Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

At 2022-07-27T07:41:05+0100, Ralph Corderoy wrote:
> > +.TS
> > +l lB lB l1 lX.

Alex, I think your contributors will be happier if you limit the number
of table columns to the number of syntactical items that they can
perceive in the structure body: the data type, element identifier, and
(an optional) comment.

I noted that you didn't want to right-align the data type field, so you
could bracket the TS/TE table in an RS/RE region to indent it.  That
would eliminate the first dummy column you have above.

The second dummy column, "l1", you don't need because you can apply
multiple modifiers to column descriptors.

Thus, try

.B struct open_how {
.RS
.TS
lB lB1 lX.
u64→flags→T{
/*
.BR O_ *
flags */
T}
u64→mode→T{
/* Mode for
.BR O_ { CREAT , TMPFILE }
*/
T}
.TE
.RE

You could also add a column width "1" modifier to the first column
descriptor; I think this would conceal the use of tbl(1) at all from
most _readers_ of the man page.

> > +\&     u64     flags;  /*      T{
> > +.BR O_ *
> > +flags */
> > +T}
> > +\&     u64     mode;   /*      T{
> > +Mode for
> > +.BR O_ { CREAT , TMPFILE }
> > +*/
> > +T}
> 
> The inline font escapes, \fB...\fP, were much more readable because I
> could still see, and check, the structure of the C source code.

It amazes me that anyone thinks "\fBfoo\fP" is more readable than ".B
foo" but I admit that it seems to be the case nevertheless.  I would
further note, as I have before, that the macro syntax is easier for
spell checkers to handle, since they don't need to know how to parse
roff(7).  (That being said, a private dictionary including many standard
and commonly used C identifiers seems like it would be necessary for
truly effective Linux man-pages spell checking.)

However I would point out that in the above, no C syntax is being
obscured by macro calls--only the interior of comments is affected.  So
what C syntax remains in a structure definition, a simple pairing of a
data type and a structure member name--neither of which permit
expressions in the language grammar--is easy to see.

I therefore find this argument inflated.

> tbl(1) could well be overkill here; tabs may do.

This claim, however, is plausible to me.  I remain ready to produce
functionality in man(7) to support this use case if it would prove
convenient.

Regards,
Branden

signature.asc
Description: PGP signature