Re: Using tbl(1) for structure definitions

[Ingo Schwarze]

Hi Alejandro,

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.

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.

> But at the same time, the result is beautiful,

Only in PDF and PostScript output.

Did we really learn nothing collectively from the "do not abuse
tables for layout purposes" drama that raged for decades among HTML
authors and HTML standard developers?  Exactly the same applies to
manual pages.

In fact, the same arguments so very familiar from HTML apply to manual
pages even more. HTML tables can at least be imbued with some semantic
capabilities by using CSS, whereas tbl(1) tables are so deeply entrenched
in the "markup is presentational markup only" camp that they can never
hope to convey any semantic function at all.

> and the syntax is really great.
> You can express exactly what you want.

I think you need to revert all that madness of abusing tbl(1)
for alignment of structures.

Just say something like (caution, the following code contains
literal ASCII tab characters):

.nf
struct open_how {
        u64     flags;          /* O_* flags */
        u64     mode;           /* Mode for O_CREAT, O_TMPFILE */
        u64     resolve;        /* RESOLVE_* flags */
        /* ... */
};
.fi

There is no need to use bold or italic donts in the structure
display.  Making all the C code bold merely makes the whole
display look heavy and ugly and provides no additional
information.  Making the comments use mixed font looks even
more ugly and is also redundant because the constants are
hopefully already more fully documented elsewhere.

Just use the same indentation conventions as you would
in a *.c or *.h file.

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.
Formatters that don't support .ta will just ignore it,
so it causes no harm, and groff and mandoc do support it.

Yours,
  Ingo