Re: [groff] mom manpage

[G. Branden Robinson]

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