Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

Hi Alex,

At 2022-07-27T14:23:44+0200, Alejandro Colomar (man-pages) wrote:
> Yeah, it seems that everything that I used was well documented (I
> could find the way to use it).  I didn't notice any other issues.
> 
> Of course, there are things that I didn't pay much attention and
> didn't fully understand when reading them, but then while
> experimenting, I realized I wanted a feature, and then looking at the
> page again I reread it and it was what I wanted.  But that's expected
> of something so new for me.  Nothing painful.

Good.  Keep me posted!

> > > I haven't seen any mention to tables having a leading blank line,
> > > yet I couldn't get rid of it without resorting to .PD.
> > 
> > You've turned over an ugly groff rock.
> > 
> > The extra line comes from groff man(7)'s `TS` macro.
> > 
> > .\" Start table.
> > .de1 TS
> > .  \" If continuous rendering, tell tbl not to use keeps.
> > .  ie \\n[cR] .nr 3usekeeps 0
> > .  el         .nr 3usekeeps 1
> > .  sp \\n[PD]u
> > .  if \\n[an-is-output-html] \{\
> > .    nr an-TS-ll \\n[.l]
> > .    ll 1000n
> > .  \}
> > .  HTML-IMAGE
> > ..
> > 
> > Your first instinct might be to say, "Hey!  Get out of here with
> > that `sp` request!"

I have good news about this.  I wrongly conflated this issue with the
one about lines/rules eating character cells on terminal devices.

Both issues are true, but they are _not_ linked.  The `sp` request above
_can_ in fact be removed without damage to man pages, and that in turn
gives the page author control over whether any vertical spacing appears
prior to the table.

There was already no spacing after the able being injected by man(7).

I have changes in my working tree in preparation for my next push.

I have _not_ yet checked whether removing this request from groff
1.22.4's an-old.tmac file does any harm to man pages; what I can say is
that it doesn't cause any problems with groff man pages, be they boxed
or not, are already preceded by paragraphing macros, or have horizontal
rules drawn at their tops.  The spacing request has been there for 20
years.

> I'll reread that with more time.  I didn't yet get it.
[...]
> I'll also reread that with more time.

No urgency.  Except for the issue below, which is very long-standing, it
won't affect you much.

[78-column limit]
> Oh yes, I noticed that while experimenting with the filling.  I was
> going to tell you, actually.  I had to leave a minimum of 2 spaces at
> the right margin, or groff would break the line and fill.  Heh!

> I noticed it.  IIRC, in the man-pages we use the exact opposite, and
> it serves me a purpose: upper B and upper I correlate with .B and .I.
> 
> since l or L doesn't correspond with anything else, this style is more
> of my likes, I think.

Fair enough.

> 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.

> 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.

> 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.

> 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?

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

Regards,
Branden

signature.asc
Description: PGP signature