Re: [groff] mom manpage

[G. Branden Robinson]

At 2018-11-29T21:57:27-0500, 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.
> 
> 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.
> 
> Since groff_mom(7) isn't actually my baby, I'm asking for opinions
> before I go ahead.

I think it's important to _have_ a man page for each of our macro
packages (several are crammed inappropriately into groff_tmac(5)), but
beyond that the page should contain only what material we're
collectively willing to maintain.

I don't think there is any greater expert on mom than you.  In my
fantasies it would be nice to have a quick reference like we have in
groff_me(7), which acknowledges its incompleteness but is still useful,
but I completely understand if you find it infeasible to subset the
corpus of mom macros in any coherent, useful way without an undue
effort.

If macrolist.html is how you prefer to maintain the index of mom macros,
then my view is that you should keep in that format.

I'm happy to aid with the maintenance of groff_mom(7), as my
predilections and neuroses seem to have led me to stumble into an
unofficial role as a groff man page editor, but a synoptic view of mom
is beyond my current competence.

I want good man pages for "everything", but sometimes a man page has to
acknowledge its limitations and defer to other documents.  I have a
historical perspective to offer along these lines but I'll leave that
for a different subthread.

Regards,
Branden

signature.asc
Description: PGP signature