Re: [Groff] Documentation for -mom

[Ingo Schwarze]

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 <address@hidden>
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