Re: [groff] groff as the basis for comprehensive documentation?

[Ingo Schwarze]

Hi Ralph,

Ralph Corderoy wrote on Wed, Apr 25, 2018 at 05:00:01PM +0100:
> Ingo Schwarze wrote:

>> I work on mdoc(7) manual pages a lot, and i almost never look at any
>> kind of output to see whether the final formatting comes out in the
>> desired visual form.  While writing, i exclusively think about the
>> logical structure of the text and the semantic function of each word
>> and symbol.  (I do periodically check the rendered console output,
>> though - but only because finding typos is easier in the rendered form
>> than in the source code.)  I certainly never look at HTML or
>> PDF/PostScript output to see whether it comes out right.  I just
>> *know* it will - or if it won't then that's a bug in the formatter
>> which i have to fix.

> Don't you ever forget to `\&' after a `.' that's not the end of
> sentence,

That problem is much less common than one might think because of
the "new sentence, new line" rule - basically, only dots at the
end of an input line that are not full stops need the escaping,
and that situation occurs quite rarely.

> for example, and not notice because it fortunately falls where
> it doesn't matter on the TTY but stands out when viewed in a
> higher-resolution format?

It almost always stands out on the terminal, too, because -Tascii
inserts two blanks after the end of a sentence, so the problem
is clearly visible unless the dot also happens to be at the end
of an output line.  But the latter can happen in PostScript or PDF
output, too.

> I find looking at the PostScript/PDF valuable precisely because
> it's a different rendering and thus shows problems hidden by the
> rendering used when writing.

I think in theory, you are right - there are formatting oversights
that are invisible in ASCII output but may affect typeset output.
The fact the your example is not very convincing is not a coincidence,
though.  Such issues are relatively uncommon and many people regard
them as somewhat arcane.  The most common such problem is probably
confusion of the input characters "-", "\-", "\(mi", and "\(en"
which is invisible in -Tascii - but can be seen in -Tutf8 if you
look closely.  The next one is confusing "\(lq", "\(rq", and "\(dq"
- again, invisible in -Tascii, visible in -Tutf8.  Same for "\(oq",
"\(cq", and "\(aq".  Confusing "\ ", "\~", and "\0" is even more
arcane, invisible in -Tutf8 and easy to miss even in typeset output.
There may be a few other points, but i expect them all to be
relatively rare and minor.

Besides, in stark contrast to man(7), mdoc(7) rarely requires using
these characters by hand (with the exception of "-", "\-", and
"\(en"), because you use .Qq, .Dq, .Sq, and .Ql, which cannot go
wrong.  Besides, we don't harass manual page authors over errors
of this kind, so scrutinizing my own work for them would be
considerable effort for minor benefit - after all, these kinds of
issues are not easy to see even in PDF output.

In principle, you are right, different output formats allow bugs
that only show in some or even only in one of them.  But the standard
process of writing manuals with mdoc(7) is deliberately set up in
a way to make this effect in practice almost irrelevant.  It's a
*feature* that authors almost never need to worry about all that
and can concentrate on the content and logic.

Yours,
  Ingo