Re: [groff] mom manpage

[Ingo Schwarze]

Hi,

all of the below seems very well said to me.

I managed to delay my reply to Peter's thorough explanation of his
design of mom and its documentation sufficently to let the thread
become somewhat stale.  As Branden alluded in his other mail, some
degree of arguing past each other may also be involved.

All that said, it is plain enough that Peter is not planning to switch
mom documentation to manual pages any time soon.  That being a fact,
i agree that misleading information (like lists focussing on the
wrong kinds of things) are better removed from the manual page.
Even if some type of information in the manual page is merely
unmaintained - that is, currrently accurate but running a high
risk of getting outdated in the future - it might better be replaced
by a pointer to the authoritative information.

At this point, i think the full cleanup Peter intends to do is
better delayed until after release.

A small patch clarifying, within the manual page itself, what the manual
page is, and what it is not, as far as Peter thinks that is useful and
currently lacking, would be OK before release, i think, because a
small patch to a manual page is unlikely to cause a distraction to
release preparation work and almost certainly won't break the build
or introduce a bug.

Yours,
  Ingo


G. Branden Robinson wrote on Tue, Dec 11, 2018 at 09:42:35AM -0500:
> 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.