Re: Using tbl(1) for structure definitions

[Ingo Schwarze]

G. Branden Robinson wrote on Thu, Aug 11, 2022 at 04:46:12PM -0500:
> At 2022-08-11T15:47:38+0200, Ingo Schwarze wrote:
>> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 10:09:44PM +0200:

>>> I must say that the source code is really ugly (ugly as in,
>>> someone reading it will probably have a hard time modifying it,
>>> without reading tbl(1)).

>> Completely true, but that's not the worst aspect of it.

> I disagree with Ingo's priorities here.  The readability of the
> source is more important for document maintainability.

True, both readability of the source code and rendering quality
matter, and discussing which one matters more in the case at hand
feels moot.

> As we shall see, tbl(1) need not discard as much as Ingo suggests,
> and even if it does (at present), I don't perceive quite the semantic
> damage he does.

I cannot imagine worse damage than reading an alt="" text containing
a non-descriptive filename to a blind reader.  Even with mandoc,
the damage of rendering a structure display as a <table> is very
severe for a blind reader.

>> In a nutshell, you are making it impossible to decently render
>> the manual page to HTML or to convert it to other formats in
>> any sensible way.
>> 
>> If esr@ (of doclifter fame) were still around, he would be screaming
>> in pain and disgust.

> We have an open bug report requesting a feature to have tbl emit HTML.
> 
> https://savannah.gnu.org/bugs/index.php?60052
> 
> Maybe someone would like to work on this.  The "troffcvt" suite already
> did this many years ago.

An argument that groff -T html could possibly support <table> output
from tbl(1) input if somebody did the work is hardly a justification
that manual page authors should behave as if it did *right now*.

Also, you ignored my observiation that even the mandoc -T html output
from a structure display using tbl(1) is very bad for accessibility,
and groff could hardly do better.  The reason is not that mandoc
tbl(7) to HTML conversion is bad but that a structure display *is
not tabular data*.

I really think this is a point we should try to find a consensus on
because using tbl(1) for structure display is such egregiously and
unambiguously bad advice that it would be very detrimental if even
part of the groff developers would continue promoting it.

[...]
>>> But at the same time, the result is beautiful,

>> Only in PDF and PostScript output.

> These output formats are _how typesetting is done_ in the modern era.
> 
> I know mandoc doesn't want to dirty its hands with such matters, but
> your militance about the unimportance of typesetting blinkers your
> perspective.

I don't think that is fair.  My argument here is only that a very
minor advantage for PDF and Postscript is not worth completely ruining
HTML output *for manual pages*.  (Besides, there is likely additional
fragility with processors without tbl(1) support, or with incomplete
tbl(1) support.)

I'm not talking about general-purpose typesetting here.

> groff cannot share that perspective.
> 
> "As the most widely deployed implementation of troff in use today, groff
> holds an important place in the Unix universe.  Frequently and
> erroneously dismissed as a legacy program for formatting Unix manuals
> (manpages), groff is in fact a sophisticated system for producing
> high-quality typeset material, from business correspondence to complex
> technical reports and plate-ready books." -- groff Mission Statement,
> 2014
> 
> https://www.gnu.org/software/groff/groff-mission-statement.html

Yes.  It is important that groff provides high-quality typesetting.

But that doesn't mean manual pages authors should go out of their
way to optimize typesetting quality and disregard considerations
for any other output format, or for portability and robustness.

[...]
> .TS
> tab(@);
> Lg(type) Lg(identifier) Lg(descriptive-comment).
> int@nflag;@/* ??? */
> .TE

Please don't abuse hypothetical language extensions to justify
using fancy features in manual pages that cause severe trouble
with currently existing software.

[...]
> Yet I would hasten to point out that a synopsis that presents something
> that is nowhere discussed later in the man page makes the document
> deficient.  So if you have semantic markup of all relevant content
> _after_ the synopsis, of which a well-written mdoc(7) page will surely
> boast, then little or nothing is lost in the domains of  searchability
> and discoverability.

This is a digression.  I would argue that the SYNOPSIS should
usually not contain structure displays.  Then again, this is a
page documenting a type, which we both consider a bad idea IIRC.
But none of that is related to the question whether using tbl(1)
for a structure display is a good idea.  If nothing is lost by
the structure not rendering at all, that's an argument for
deleting it, not for using tbl(1).

Let's stick to the point of how to best mark up a structure.

>> I don't think you need to worry that the alignment might vary on
>> different output devices.  If you worry anyway, you can use an
>> explicit roff(7) .ta request before the display and reset it with .DT
>> after the display.

> "If esr@ (of doclifter fame) were still around, he would be screaming in
> pain and disgust."
> 
>   commit 26e827e36a4d98e9a9403bcc73b4afb116495407
>   Author:     Eric S. Raymond <esr@thyrsus.com>
>   AuthorDate: Sat Feb 3 11:54:41 2007 +0000
> 
>       Added portability advice.
> 
>   diff --git a/tmac/groff_man.man b/tmac/groff_man.man
>   index e314cd8f6..057f9f9d4 100644
>   --- a/tmac/groff_man.man
>   +++ b/tmac/groff_man.man
> [...]
>   +.\" -----------------------------------------------------------------
>   +.
>   +.SH "PORTABILITY AND TROFF REQUESTS"
>   +.
>   +Since the
>   +.B man
>   +macros consist of groups of
>   +.I groff
>   +requests, one can, in principle, supplement the functionality of the
>   +.B man
>   +macros with individual
>   +.I groff
>   +requests where necessary.  See the
>   +.I groff
>   +info pages for a complete reference of all requests.
>   +.LP
>   +Note, however, that using raw troff requests is likely to make your page
>   +render poorly on the (increasingly common) class of viewers that
>   +render it to HTML.  Troff requests make implicit assumptions about
>   +things like character and page sizes that may break in an HTML
>   +environment; also, many of these viewers don't interpret the full
>   +troff vocabulary, a problem which can lead to portions of your
>   +text being silently dropped.
>   +.LP
>   +For portability to modern viewers, it is best to write your page
>   +entirely in the requests described on this page. Further, it is best
>   +to completely avoid those we have described as 'presentation-level'
>   +.RB ( HP ,
>   +.BR PD ,
>   +and
>   +.BR DT ).
> 
> The above has undergone some recasting but the basic thrust is intact.
> We can dial back its stridency in a considered way, if you like.  Shall
> we discuss it?

The above is just fine.

But there is a difference between:

 (1) Adding a low-level roff(7) request that does little harm when
     completely ignored, like .ta in this case.
     That's merely somewhat ugly but not a particularly serious problem.

 (2) Using non-semantic, fragile markup that causes the complete
     content to become unsusable in some output modes.
     That's a major disaster.

> It seems like all three of us have some reservations about employing
> tbl(1) to this end, but we have not aligned on the best alternative.

I think there are many acceptable possibilities.  Another one might be
using a spaces for indentation in a fixed-with font in non-breaking
mode.  I don't care that much which of the reasonable ones you pick
for recommendation.  But tbl(1) is not a serious contender; can't we
at least agree on that?

>> Formatters that don't support .ta will just ignore it, so it causes
>> no harm, and groff and mandoc do support it.

> Exactly what I had in mind for `KS` and `KE`, so that we can have
> keeps in man pages.  :D

Practical experience in mdoc(7), which provides the .Bk macro to
implement keeps, is that it is almost never needed, so i'd rather
deprecate .Bk in mdoc(7) than adding anything similar to man(7).
Then again, you are probably right that adding a "keep" macro to
man(7) likely causes less disruption than some other macros you added
because even the naive way to do it is trivially backward-compatible.
But that is unrelated to the question of tbl(1) for structure displays.

Yours,
  Ingo