Re: [groff] mom manpage

[Ingo Schwarze]

Hi Peter,

Peter Schaffter wrote on Fri, Dec 07, 2018 at 11:18:32AM -0500:
> On Fri, Dec 07, 2018, Colin Watson wrote:
>> On Thu, Dec 06, 2018 at 06:38:40PM -0500, Peter Schaffter wrote:

>>> address@hidden
>>> address@hidden/usr/share/doc/groff-base/html/mom/toc.html}
>>> address@hidden display
>>[...]
>>> address@hidden
>>> address@hidden/usr/share/doc/groff-base/pdf/mom-pdf.pdf}
>>> address@hidden display
>>[...]
>>> I'm not sure whether it's okay for entry points to local files to
>>> have literal paths or whether they need to be rendered symbolically
>>> for build/install purposes, so I won't commit without your go-ahead.

>> These paths are *very* Debian-and-derivatives-specific (even leaving
>> aside the hardcoded /usr/share/doc prefix, the split between groff-base
>> and groff is a Debianism), so they can't be committed upstream like
>> that.

> That's what I thought.
 
>> Either the local references will need to be omitted, or we'll
>> need some kind of arrangement along the lines of the existing
>> @HTMLDOCDIR@ and @PDFDOCDIR@ in groff's man pages (I'm not sure how
>> practical that is in texinfo).

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

> Bertrand, how do you feel about omitting the local docs, leaving
> just the pointer to the online docs?  If you're agreeable, I can
> commit the change.

This is part of the kind of trouble i meant when saying "harder to
access": even developers feel quite lost trying to figure out how
to tell users where to look.

You wrote earlier:

> Harder to access?  Marginally at best.
>
>   man groff_mom
>   w3m <docdir>/macrolist.html

There are numerous problems are right there:

 * How do i know the documentation is in HTML format in the first place?
   I have seen software documented in PDF, in PostScript,
   in various dialects of markdown, in plain text, ...
 * Of course, each of these require starting a different
   program and typing a different file name extension.
 * How do i know the file name to start with is "macrolist"?
   For some HTML documentation i have seen, the author at least
   chose to call the starting page "index.html", which is clearly
   better, but still only one of several possibilities.

 * How do i know what to insert for <docdir>?

   /usr/local/share/doc/bzip2/manual.html
   /usr/local/share/doc/libxml2/html/FAQ.html
   /usr/local/share/doc/libxml2/html/index.html
   /usr/local/share/doc/libxml2/html/tutorial/index.html
   /usr/local/share/doc/lynx/lynx_help/lynx_help_main.html
   /usr/local/share/doc/groff/html/mom/macrolist.html
   /usr/local/share/doc/pcre/html/index.html
   /usr/local/share/gtk-doc/html/glib/api-index-full.html
   /usr/local/share/gtk-doc/html/cairo/index.html
   /usr/local/share/heirloom-doctools/font/devps/MustRead.html
   /usr/local/share/ghostscript/9.07/doc/index.html
   /usr/local/share/enscript/afm/MustRead.html
   /usr/local/share/texmf-dist/doc/latex/koma-script/koma-script.html

   Don't you agree that's a total mess?
   And that's on a system where packagers take exceptional care
   to package stuff as uniformly as possible.  Elsewehere, there
   will be more variations, including /usr/local/<package>/whatever,
   /usr/share/whatever, /opt/whatever, and so on and so forth.

   Of course, as a developer, *you* know where the software you
   maintain installs on *your* system (not so much on other systems,
   though, see above), and what the format of the documentation is,
   and what the filenames are.  Even for a very experienced user,
   finding it is a pain.  When packages don't have proper manual
   pages, i regularly end up typing "pkg_info -L <packagename>" to
   show the list of files installed by the package and look through
   the list of files to locate any that might possibly be documentation.
   Often, it takes more than one try to find the actual starting
   page.

   Should i look at a stub manual page merely to find the location
   of the real documentation?  Maybe.  But often enough, even that
   only tells me the file name, not the directory name, for exactly
   the reason you are just suffering from: upstream simply cannot
   know, and the person building the package may not be aware of
   the need to fix up path names in some manual page.  So it is not
   unusual that i type "man foo" to look for the filename of the
   documentation, then "locate foo_help.html" to see where it is
   installed, then cut and paste the result into the address bar
   of a graphical browser with a mouse - because HTML documentation
   tends to use pictures and often don't work well in lynx(1).
   Harder to access?  Marginally at best.

 * "apropos mom" won't find it.

     $ man -k any=PT_SIZE any=SHIFT_LIST any=CHAPTER_TITLE
    man: nothing appropriate

     $ man -akO tag=unfilled any=unfilled
    opens the manual page right at the place where "-unfilled"
    is defined, and if i then hit the single key "t", i get right
    to the place where the same option is defined in a *different*
    manual page - mdoc(7) vs. groff_mdoc(7).

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

I'm sorry i'm not very constructive today, but i don't know how to
fix the texinfo problem either.  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.

Yours,
  Ingo