Hi Peter, Peter Schaffter wrote on Fri, Sep 26, 2014 at 08:26:45PM -0400: > 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. Thank your for your patch. It definitely got me going. I don't think it is quite ideal, though, since with your patch, you not only have duplicate code in Makefile.sub, but actually end up installing HTML documentation twice when all supporting programs are available. Here is a simpler patch doing the job only once: ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 ----- commit 0dfb63b0fbfa440d491f9ed3aeb90ccce89c6e56 Author: Ingo Schwarze <schwa...@openbsd.org> Date: Wed Oct 15 00:58:56 2014 +0200 always install mom documentation diff --git a/contrib/mom/Makefile.sub b/contrib/mom/Makefile.sub index 04fc501..dd91e7b 100644 --- a/contrib/mom/Makefile.sub +++ b/contrib/mom/Makefile.sub @@ -134,8 +134,8 @@ examples/stamp: touch $@ install_data: install_always \ - $(make_install_pdfdoc) $(make_install_htmldoc) \ - $(make_install_examples) + $(make_install_pdfdoc) install_htmldoc \ + install_examples install_always: stamp-strip $(NORMALFILES) -test -d $(DESTDIR)$(tmacdir) || $(mkinstalldirs) $(DESTDIR)$(tmacdir) @@ -192,8 +192,8 @@ stamp-strip: $(STRIPFILES) touch $@ uninstall_sub: uninstall_always \ - $(make_uninstall_pdfdoc) $(make_uninstall_htmldoc) \ - $(make_uninstall_examples) + $(make_uninstall_pdfdoc) uninstall_htmldoc \ + uninstall_examples uninstall_always: -for f in $(NORMALFILES) $(STRIPFILES); do \ ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 ----- I'm quite sure replacing "$(make_install_htmldoc)" with "install_htmldoc" is OK. This part certainly needs no prerequisites. While replacing "$(make_install_examples)" with "install_examples" seems useful to get mom-pdf.pdf installed - which is documentation, not an example - i'm not sure making this unconditional in possible. Building this PDF file runs pdfmom(1), and m4/groff.m4 says: # To produce PDF docs, we need both awk and ghostscript. However, i'm not sure that is quite true, either. Neither the gropdf(1) nor the pdfmom(1) manual seem to mention that they call gs(1) - do they, actually? So much for the impotant part, it seems like you still have a bit of time to evalute and maybe commit this or something similar before release... It seems a bit unfortunate how the build system is conflating aspects together. The --with-doc option is intended to say "the admin wants documentation in that output format". Whether the tools are available to convert files to those formats is a completely different question. The proper logic would be: 1. If --with-doc requests a particular format and the required tools are available run the tools to build output files. 2. If --with-doc requests a particular format, install the files having this format already contained in the distribution tarball, plus any files built in step 1. Since ./configure deletes formats from --with-doc when the tools for building these formats are missing, nothing gets installed in step 2 in that case, not even the files already contained in the distribution tarball. Another instance of conflating different things is that mom-pdf.pdf is handled by the "examples" targets. I think it should be controlled by --with-doc=pdf, not by --with-doc=examples. Regarding my rant about HTML documentation: >> 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. You have a point here. Then again, it is hardly ever done. I see very little semantic markup in contrib/mom/momdoc/typesetting.html. Probably, it wouldn't even be a good idea to try because there is no standard way to do HTML semantic markup in documentation. It would be different for each software package, which leads us to criterion 6... > 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. :) It is true that the ASCII terminal is not the most powerful output medium in the 21st century. Then again, if people are used to how man(1) does markup on the terminal, the mom HTML will definitely be unfamiliar and require getting used to. Besides, manuals - in particular mdoc(7) - can be meaningfully rendered to HTML, potentially better exploiting semantic markup than it is usually done today. There is some work to do establishing standard ways to do just that, and i hope to contribute to that... > 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. Yes. While manuals already allow HTML rendering providing exactly that - http://mdocml.bsd.lv/cgi-bin/man.cgi - there is still a lot to do in that respect. What i'm driving at is that we should aim at getting *all* the aspects right, instead of sacrificing some for others. Hand-written HTML documentation will never satify all seven quality criteria - even though you correctly point out that it might satisfy *parts* of the latter four. > Some programs aren't suited for manpages, esp. those whose > documentation benefits from a table of contents, indices, and > extensive cross-linking. The following manual does exactly that, i don't think it's so bad: http://mdocml.bsd.lv/man/mdoc.7.html > 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. Heh, i'm using fvwm right as i'm typing here. It just works. I guess i used the manual once, when i wrote my fvwm config file from scratch, and i don't remember any issues with it. Oh, by the way, here it is: http://mdocml.bsd.lv/cgi-bin/man.cgi/?query=fvwm The main reason that's not so pretty is that it is old-fashioned man(7), hence no semantic markup and no crosslinking. Apart from that, it's just fine. I simple tool like that really doesn't need a tuturial. You just look up what you need, which is not difficult even if the manual is a bit long, and are done with it for the next few years. For a tool like mom, of course, the situation is completely different. That clearly needs a tutorial-style component in its documentation. > 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. I'd rather attack the problem from the other side. Write the documentation as manual pages so they are available everywhere, then leverage groff and mandoc to get nice typeset PDF versions and semantically marked-up and crosslinked HTML versions from the same manual pages. That way, even the PDF and HTML versions will follow a uniform style that you don't have to re-adapt to for each new software package you use. > 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"? Well, proper reference documentation should certainly be there, but nothing prevents adding user-manual-style man pages to a package. Perl, for example, has some of those: perlopentut(1) is one i have used very often, and there are many more. > 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? You don't need to install less(1) if your system doesn't have it by default; more(1) is part of POSIX. Yours, Ingo