At 2018-11-30T14:18:05-0500, Peter Schaffter wrote: > 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.
At the risk of being unfair to Ingo, based on my occasional disputes with him over the groff man pages generally, I would say that an alphabetical ordering of macros is useful to readers who are _really_ impatient. Too much so to type a search pattern into less(1), which we probably have to concede in 2018 is an essential part of the man page interface on the terminal. (Pagers that don't buffer their input and permit seeking backwards will cause unhappiness to all but the most diehard grognards.) My rewrite of groff_man(7) shows some of his influence, in that I introduced an alphabetically-sorted list of the non-deprecated macros in the package. I think it also has the virtue of emphasizing, for better or worse, how small a language man(7) is, even with the GNU extensions. With that established, I felt justified in reorganizing the sections of the page in an order that I think was more pedagogically useful. The first macro a man page writer needs to learn about is .TH, not .B. > 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. I did not know that, and it is distressing. Presentationalism, as a document author's mindset, has almost no place in *roff anymore--everyone who eschews semantics is going to defect from *roff to asciidoc or Markdown or whatever crude markup is the primrose path in vogue today. > 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. The groff_me(7) page somewhat meekly notes that macros whose descriptions were too hard to fit into the ASCII-collated table were simply omitted from it. But even that admission is preferable to misleading the user into thinking that the undocumented macros _don't exist_. On my lengthy to-do list is a list of those unmentioned macros for that page, so that at least the reader knows what's in the namespace and what isn't. > 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. Yes, but they then argue over the meaning of the word "useful". :) > 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. Amen. > Mom is not -ms or -me, with their tidy but somewhat limited macros > that can be described in a few words. As noted above, -me's waistline managed to stretch beyond that point. ;) Regards, Branden
signature.asc
Description: PGP signature
