Re: [groff] mom manpage

[Peter Schaffter]

On Fri, Dec 07, 2018, Ingo Schwarze 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?

> So indexing is actually much better with manual pages, and
> searching doesn't work at all with HTML.

It could equally be said that *an* index (i.e. a categorized, linked
list of terms) is much better with html, and searching inside
displayed manpages leaves much to be desired.

The issue isn't which format is better, rather which is more apt.
Some programs are better served by documentation in a format other
manpages.  Mom is one of them.  The 1.x release documentation
addressed the issue explicitly:

 "Some mom users are sure to ask: “Why is the documentation in
  html?  If mom’s so great, why not pdfs to show her off?  And if
  groff’s so great, why not write a man page?”

  ...

  The documentation is in html because I still find it the best tool
  for navigating lengthy manuals.  Html, with its anchors and links,
  came into being precisely so people could do something they’d
  never been able to with the printed word: instantly track down
  internal and external references in a document.

  It’s essential that people reading mom’s documentation never
  have difficulty finding precisely the macro they need for a
  particular task.  Equally, when reading up on a macro, they should
  never be presented with terms or other macro names for which they
  cannot instantly find accurate explanations.  Short of having
  written the documentation in TeX for the info browser (and TeX
  bloat is one of the reasons I prefer to typeset with groff), I
  can think of no better way to achieve the kind of truly useful
  documentation I wanted than html."

> I'm sorry i'm not very constructive today, but i don't know how to
> fix the texinfo problem either.

As Betrand has pointed out, the awkwardly-named POSITIONS FROM
INSTALLATION in groff(1) takes care of the problem.

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

Taking this into account, I propose

diff --git a/doc/groff.texi b/doc/groff.texi
index a6d1260..f588d5f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4649,11 +4649,36 @@ command line).
 
 @c XXX documentation
 @c XXX this is a placeholder until we get stuff knocked into shape
-See the @cite{groff_mom(7)} man page (type @command{man groff_mom} at
-the command line), which gives a short overview and a link to its
-extensive documentation in HTML format.
+The main documentation files for the @file{mom} macros are in html
+format.  Additional, useful documentation is in pdf format.  See the
+groff(1) manpage "Collection of Installation Directories" for their
+location.
 
address@hidden @bullet
address@hidden
address@hidden
address@hidden
+Entry point to the full mom manual.
+
address@hidden
address@hidden
address@hidden
+Hyperlinked index of macros with brief descriptions, arranged by
+category.
 
address@hidden
address@hidden
address@hidden
+PDF features and usage.
address@hidden itemize
+
+The mom macros are in active development between groff releases.
+The most recent version, along with up-to-date documentation, is
+available at 
address@hidden://www.schaffter.ca/mom/mom-05.html}
+
+See also @cite{groff_mom(7)} (type @command{man groff_mom} at the
+command line).
 
 @c =====================================================================
 @c =====================================================================

If all are agreeable and my .texi formatting is acceptable, I can
commit this.

-- 
Peter Schaffter
http://www.schaffter.ca