Re: Using tbl(1) for structure definitions

[Alejandro Colomar]

Hi Branden,

On 7/29/22 15:52, G. Branden Robinson wrote:
> > Oh, I used text blocks and .BR, in v2.  In part, I like it; in part I
> > hate it.
> >
> > So, text blocks are definitely better.
> >
> > I'm not convinced about changing the escapes by macros; it makes it
> > quite hard for inexperienced contributors to imagine the C source
> > code.
>
> It's the same markup they would use if "O_* flags" or
> "O_{CREAT,TMPFILE}" were occurring in a paragraph of the description.  I
> propose that this consistency has some benefit.
>
> You would know better than I how common it is that you'll need some kind
> of metsyntactic markup in the data type or structure element identifiers
> themselves.  My _guess_ from mere exposure to the pages is that it's
> rare.

Yeah, I think you have a point (actually, several):

- automatic tools
- consistency

> > I fear that I may be abusing tbl(1) too much for a SYNOPSIS.
>
> I don't think you're abusing it but you are employing some heavy
> machinery that brings some limitations with it.  The worst from my
> perspective is that using tbl(1) in man pages limits your flexibility in
> terms of line length.  Terminal windows can be all kinds of crazy sizes.

Oh, didn't the Mesopotamians already know about the standard tablet size 
of 80x24?  :D

"Thou shalt set your tablet size to 80x24 or larger, but never smaller; 
or thou shalt not report a bug if the formatting becomes unreadable.
Thou shalt not assume your neighbor has a tablet wider than 80 
characters, so thou shalt not write past it."

I think that's what the famous tablets said.

> > In this case, yes we can.  In the more general case where types may
> > vary in length, I want to left-align them; so for consistency, I'll
> > left-align them here too.  That will make it more obvious for
> > contributors to know what they need to do.
>
> Okay.  As noted in my previous mail, I'd use RS/RE to get the
> initial indentation in this case instead of using a dummy column.  You
> can give `RS` an argument (in ens by default) to control the amount.

Done.  I like it.

> > I also put the opening /* in a separate field, to better align texts.
>
> I don't understand why that's necessary.  "/*" will always start at a
> tab stop (table column) and it will always be the same glyphs, so the
> width will always be consistent.  Am I misunderstanding?  Do you have an
> example of bad alignment I can look at?

Sure; compare:


           u64  mode;     /* Mode          for
                             O_{CREAT,TMPFILE}
                             */

           u64  mode;     /* Mode          for
                          O_{CREAT,TMPFILE}
                          */



> I'm really looking forward to killing off another application of `PD`.

Ok.  T think I'll remove .PD, and leave the extra blank line until .TS 
is fixed.  A blank line will not hurt too much.

> Regards,
> Branden

Will send v4 soon.

Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature