Re: [groff] mom manpage

[Morten Bo Johansen]

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.

> If getting rid of the section entirely is too radical,
> macrolist.html could be converted to man markup and inserted in its
> place, although I can't see how it would be useful.  Mom macros
> really need the documentation that's in the html/pdf docs.  It's
> enough for the manpage to give the entry points, IMO.

It is useful, because it is a quick reference in itself and
because access to a man page is right in your fingertips.

> Since groff_mom(7) isn't actually my baby, I'm asking for opinions
> before I go ahead.

Just my 2 cents ;)

 Morten