Re: [Groff] Documentation for -mom

[Ingo Schwarze]

Hi Peter,

Peter Schaffter wrote on Sun, Sep 21, 2014 at 09:39:17PM -0400:

> Sorry not to get back on this right away.  I've been away for a
> couple of days--work and computer free!

No problem.  Unless a software project will be abondoned soon,
a few days delay really don't matter.

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

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

>> we end up in a situation where some groff installations
>> do not include full mom documentation.

> However, I'm going to have a look at the
> situation of disabling building html when support software is
> missing.  The mom docs require no special build tools, hence there's
> no reason not to include the docs in every installation.

In that case, disabling the build of grohtml(1) when gs(1) or
pnmcut(1) are missing would indeed be wrong.  It the build system
maybe mixing up build and run dependencies here?

*Building* something should be disabled if it requires linking
against an external library that is not installed - since the build
would fail otherwise.  If something merely needs an additional
external tool *at run time*, that should not disable the build,
because it's completely legitimate to build first and maybe install
the dependency later when you actually need the functionality.  This
holds even more when the dependency is only needed for a subset of
the functionality.  All this becomes even more important when talking
about packaging, where the distinction of build and run dependencies
is absolutely crucial - but a packaging system is out of luck of
having something as a pure run dependency if the configure script
already spoils the show and turns it into a needless build dependency.

I have no idea what the situation with grohtml(1) is, that is, what
that beast needs for building, and what it needs for which run-time
functionality - i never used it.  But it sounds good that you want
to look into that.

>> To mitigate that situation, i think it would help a bit to include
>> a link to http://www.schaffter.ca/mom/mom-04.html (that file name
>> seems a bit awkward; is it stable?) in contrib/mom/groff_mom.man
>> below SEE ALSO.

> Yes, that would help.  I'll get onto it.

Great, thanks for doing that.  Your commit looks fine to me,
it definitely makes finding the HTML docs easier.

> Something else that would help, too, would be converting the docs
> to pdf.

Hell, *NO*.  That's even worse than HTML.

 4. ease of access: complete failure, now you suddenly need
    xpdf(1) to even read the docs?!
 5. semantic markup: even worse than HTML; in HTML, you can
    do semantic markup if you want to (mandoc -Thml does), even
    though it's not much use because it's completely non-standard;
    in PDF, you can't at all.
 criteria 6 and 7: not much of a change

So, there are two downsides to PDF but no benefit.

Yours,
  Ingo