Re: [groff] mom manpage

[Peter Schaffter]

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