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:
>>> +@display >>> +@file{/usr/share/doc/groff-base/html/mom/toc.html} >>> +@end display >>[...] >>> +@display >>> +@file{/usr/share/doc/groff-base/pdf/mom-pdf.pdf} >>> +@end 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