Ingo -- On Fri, Sep 19, 2014, Ingo Schwarze wrote: > Given that the build systems disables building HTML documentation > when some support software is missing on the target system and > that the main mom documentation is (very unfortunately, but that's > the current state of affairs) HTML, we end up in a situation where > some groff installations do not include full mom documentation.
The attached patch to /contrib/mom/Makefile.sub should ensure that mom's documentation gets installed (and uninstalled) regardless of whether support software for building HTML documentation is missing. On Sun, Sep 21, 2014, Peter Schaffter wrote: >> a lot of mom users would disagree that having the documentation >> in html is unfortunate. :) > Well, what i mean is this. In my tutorial on documentation here in > Sofia i'm going to list seven quality criteria for software > documentation: > 1. correctness > 2. completeness > 3. conciseness > 4. ease of access (both regarding searching and regarding the > required tools for viewing it); ideally, all documentation > should be in one place so you cannot miss it > 5. semantic markup > 6. ease of reading; ideally, uniform display markup and style > 7. ease of writing; ideally, one simple, standard input language > > HTML flat-out fails on criteria 4-7. Respectfully disagree with "flat-out fails", though not because I'm promoting HTML as a documentation standard. Heaven forbid. 5. Well-formed css/xhtml allows for unambiguous semantic markup. 6. For ease of reading, uniform display and style are only achievable when the display and style are well-thought-out and well-rendered; a manpage at the terminal is decidedly sub-optimal in this regard, as my occasionally blurred vision will attest. :) 7. Agreed. HTML is a PITA. > Regarding 4, it's not just that people cannot see it in man(1) > where documentation is expected to be, but need to install a > browser; on top of that, apropos(1) will be completely blind to it. Regarding 4, you omitted "ease of navigation". Searching is one thing, but it doesn't include being able to click on internal links to find out what an unfamiliar term means, or how, in the case of mom, to use a macro that's referenced in the description of another macro's usage. Clickable cross-references, IOW. Some programs aren't suited for manpages, esp. those whose documentation benefits from a table of contents, indices, and extensive cross-linking. Remember the bad old days of FVWM, with its humungous, unindexed, un-cross-linked manpage? It was correct, complete, concise (despite its length), easy to access--and pure, off-putting hell to wade through. GNU tried to solve the navigation problem by foisting texinfo on everybody, but after a couple of decades I, and many others, still find info(1) a trial to use. I'd never suggest that HTML should be a standard for Unix documentation. Manpages are essential. However, when they can't furnish easily-navigable information about a program's usage, some other form of documentation is required. Furthermore, the search-only navigation and in-a-nutshell style of manpages can actually have the effect of discouraging program usage if the program is large and complex. What good is documentation that turns people off using a program, or leaves them scratching their heads saying, "I'll never make sense of all this"? In instances where a manpage is clearly the wrong format for documentation, I believe, as was for so long the case with mom, that a manpage stub pointing to the complete documentation in another format is the way to go since it prevents apropos(1) blindness and tells users correctly, completely, and concisely what they need to know, namely "go here for the documentation." As for "installing a browser", e.g. w3m(1), is that any more trouble than installing less(1) in order to browse manpages? -- Peter Schaffter http://www.schaffter.ca
diff --git a/contrib/mom/Makefile.sub b/contrib/mom/Makefile.sub index 04fc501..6afc2c1 100644 --- a/contrib/mom/Makefile.sub +++ b/contrib/mom/Makefile.sub @@ -139,6 +139,7 @@ install_data: install_always \ install_always: stamp-strip $(NORMALFILES) -test -d $(DESTDIR)$(tmacdir) || $(mkinstalldirs) $(DESTDIR)$(tmacdir) + -test -d $(DESTDIR)$(htmldocdir)/mom || $(mkinstalldirs) $(DESTDIR)$(htmldocdir)/mom for f in $(NORMALFILES); do \ $(RM) $(DESTDIR)$(tmacdir)/$$f; \ $(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(tmacdir)/$$f; \ @@ -147,6 +148,11 @@ install_always: stamp-strip $(NORMALFILES) $(RM) $(DESTDIR)$(tmacdir)/$$f; \ $(INSTALL_DATA) $$f-s $(DESTDIR)$(tmacdir)/$$f; \ done + for f in $(HTMLDOCFILES); do \ + $(RM) $(DESTDIR)$(htmldocdir)/mom/$$f; \ + cp $$f \ + $(DESTDIR)$(htmldocdir)/mom/; \ + done install_pdfdoc: # Since this uses examples/, it's in install_pdfexamples @@ -199,7 +205,12 @@ uninstall_always: -for f in $(NORMALFILES) $(STRIPFILES); do \ $(RM) $(DESTDIR)$(tmacdir)/$$f; \ done - + -for f in $(HTMLDOCFILES_); do \ + $(RM) $(DESTDIR)$(htmldocdir)/mom/$$f; \ + done + -test -d $(DESTDIR)$(htmldocdir)/mom && \ + rmdir $(DESTDIR)$(htmldocdir)/mom + uninstall_pdfdoc: uninstall_always # Since that used examples/, it's in uninstall_pdfexamples