[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Using tbl(1) for structure definitions

From: Alejandro Colomar
Subject: Re: Using tbl(1) for structure definitions
Date: Fri, 29 Jul 2022 17:26:10 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.0.2

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

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

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

           u64  mode;     /* Mode          for

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.


Will send v4 soon.



Alejandro Colomar

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]