Re: [groff] mom manpage

[Mike Bianchi]

> ... scrapping the alphabetic listing of macros and strings entirely.  All it
> does is partially duplicate the mom Quick Reference Guide (macrolist.html) 
>       :

IMHO   One complete, up-to-date, easily-acquired reference is preferable to
        duplicates.

        The exception is when the duplicated information is from a single
        source so all duplicates always contain the same information.

Long ago I was part of a team that built both the documentation and the 
code from a single source file so both always spoke a single truth.

The one improvement on _that_ idea was another development group which
managed to close the loop.  There were two documents (alphabetical and
by-concept written in nroff with comments) plus two forms of code (PL/I
and IMS database declaration, with comments) that were interlocked by
UNIX shell scripts.

If you needed to make a change or addition, you could do it in _any_
one of the 4 forms and then generate the other 3.  They were laughed at
for being obsessive but never had that form of consistency bug in the
long-lived project.

((Bless you Leon Levy, where ever you are.))

On Thu, Nov 29, 2018 at 09:57:27PM -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.
> 
> -- 
> Peter Schaffter
> http://www.schaffter.ca

-- 
 Mike Bianchi