Re: [groff] mom manpage

[Ingo Schwarze]

Hi Peter,

Peter Schaffter wrote on Sun, Dec 09, 2018 at 05:22:19PM -0500:
> On Fri, Dec 07, 2018, Ingo Schwarze wrote:
>> Peter Schaffter wrote:

>>> Neither am I.  What I know about texifo wouldn't fit in a thimble.

>> You mean it would, right?  Put it in there, and enough space will
>> probably be left to fit in my knowledge of textinfo, as well.

> Is the fact the we both mistyped 'texinfo' evidence our of shared
> disdain?

Not beyond reasonable doubt, but certainly with a preponderance of
evidence.  ;-)

>> But one thing is certain: linking to the WWW more prominantly than
>> to the local documentation, or in a way that is less likely to
>> fail for the user, is a very bad idea.  What the user finds on the
>> Web may not even correspond to the version of the software that is
>> actually installed.

> I develop mom independently of groff.  An unfortunate but inevitable
> consequence is that mom releases occur more frequently than groff
> releases.  You're quite right: the online documentation may
> not--in fact can be expected not to--correspond to the installed
> documentation.  It supersedes the installed documentation--another
> reason why an attempt to render it as a manpage is ill-advised.
> Users who install a version of mom newer than what's installed with
> groff are stuck with an out-of-date manpage until the next groff
> release.

I don't follow at all.  There is nothing wrong with releasing newer
versions of mom between groff releases, but *of course* such a mom
release doesn't make any sense unless it comes bundled with the
documentation pertaining to it, such that users automatically get
the correct documentation installed with the new code.  Like for
any other software release.

So, before installing a newer mom release, the user has an older
mom release installed (with matching older documentation), while
what is found on the web mismatches.  After installing a new mom
release, the user again has matching code and documentation, by the
very definition of what a "release" is and what "installing" means.
The result then may or may not match what is on the web.

> Taking this into account, I propose

I can't comment on textifo(1-) markup, but the content change seems
reasonable to me, given the current state of affairs.  I also think
it should be committed *before* release because it is important to
prevent user confusion.

Regarding the last sentence,

> +See also @cite{groff_mom(7)} (type @command{man groff_mom} at the
> +command line).

my impression is that wording isn't particularly helpful.  Unless
obvious, a reference below SEE ALSO should say what it is useful
for.  If i remember correctly what you said, the groff_mom(7) manual
in its current state is not really useful at all - in the sense
that everything it contains is better explained elsewhere.

Maybe something like:

  The groff_mom(7) manual page only contains a few incomplete lists
  of some of mom's features and nothing that isn't better explained
  in the HTML documentation.

Or something like that, whatever is accurate and to the point.  It
doesn't matter here that i like manual pages.  When they are defective
for some specific software, promoting the defective pages harms
users, and mentioning the drawbacks of those specific pages actually
helps users.

Yours,
  Ingo