On Fri, Nov 30, 2018, Morten Bo Johansen wrote: > On 2018-11-30 Peter Schaffter wrote: > > > I revisited groff_mom(7) recently. I didn't write it and I've > > always felt it was there for the sake of completeness. I'd > > like to revise it, scrapping the alphabetic listing of macros > > and strings entirely. All it does is partially duplicate the > > mom Quick Reference Guide (macrolist.html) and arranges it by > > alphabet, which isn't an improvement. > > A man page does not have to be an improvement over more exhaustive > documentation. IMO, a man page should always describe the use and > options of its subject in an adequate fashion, but not necessarily > in an exhaustive fashion. And since the subject here is a groff > MACRO package, omitting the listing and short description of the > macros, makes the man page quite pointless, IMHO.
My phrasing is at fault. By "isn't an improvement," I meant to convey that alpabetic arrangement of the macros diminishes the usefulness of such a list, which benefits from being grouped into categories. The problem with listing mom macros in a manpage is twofold: there are over 500 user-space macro definitions in om.tmac, and a number of them have enough options to warrant their own manpage. Does one prune the list? If so, using what criteria? The authors of groff_mom(7) restricted themselves to the presentational macros, which seriously misrepresents mom. And what should be done about macros whose concise description could lead to misunderstanding and incorrect usage? DOC_LEAD, for example. It can't be used promiscuously and requires understanding what is meant by "adjusted leading." Or .T_MARGIN and .B_MARGIN, which have different meanings depending on whether one is creating a strictly presentational document or using semantic markup for document processing. Debates over manpages have persisted for years, what they should contain and how they should be formatted. However, the one thing everyone agrees on is that they should contain useful information. An overlong (or incomplete), partially-documented and potentially misleading list of mom macros isn't useful. An adequate description of mom's scope, along with a pointer to the categorized, indexed, hyperlinked documetation is. Mom is not -ms or -me, with their tidy but somewhat limited macros that can be described in a few words. > Just my 2 cents ;) Thanks. -- Peter Schaffter http://www.schaffter.ca
