> ... 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
