[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 (man-pages)
Subject: Re: Using tbl(1) for structure definitions
Date: Wed, 27 Jul 2022 14:23:44 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.8.1

HI Branden,

On 7/27/22 02:12, G. Branden Robinson wrote:
Hi Alex,

At 2022-07-26T21:33:07+0200, Alejandro Colomar wrote:
I've already read all that was relevant to me from tbl(1) regarding
what I had in mind: documenting structures.

Okay.  Apart from those two nits I didn't get any other feedback from
you, did you find the document clear and satisfactory?

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.

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

Your first instinct might be to say, "Hey!  Get out of here with that
`sp` request!"

My first instinct is to say, "Hey!  Do you write macros in chinese?" :p
I'll tell you what I understand from that macro definition, so that you have an idea of how little groff(7) I know:

.de1 TS    \" de1 is C's #define.  TS is the macro to be defined.
yadayadayada much chinese.
.  if  ... \{\  \" okay, I guess that if means... if.  That's universal.
                \" I don't understand the condition, though.
                \" From the obvious name, it seems like if (html) {
yadayadayada more chinese
.  \}           \" end of conditional
yada yada yada
..               \" End of macro definition.

:-)  (does that have any groff meaning? It should :P

Your instinct will leave you unhappy the first time you render a boxed
table to a terminal.  The line at the top of the table will overlap the
glyphs on the line of text _above_ the table.

The macro package doesn't have anyway of knowing whether the table is
boxed or not.  Though it does occur to me, we could add a register for

But this is just a symptom of a bigger architectural issue with tbl(1)
as implemented by groff.  It assumes that all rules, horizontal and
vertical,  are (practically) zero-width.  For typesetter devices this is
true.  But for terminals they eat an entire character cell, which is
_huge_, relatively speaking.

This causes all sorts of grief that I have catalogued in Savannah.

There's also an older report that hints at trouble.

I'll reread that with more time.  I didn't yet get it.

Some time back I had an exchange with you and/or Michael about the
origin of the 78-column rendering limit in man pages.  (In other words,
why not 80?)

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 have since found out what it really was--apparently, a
workaround for groff tbl behavior.  And maybe other tbl programs, too.
tbl relies on the output driver to handle the drawing of intersections
between lines, like the corners of table boxes.  On typesetters this is
trivial: you just draw the lines.  On terminals, you have to do
collision detection!  You have to determine that a horizontal rule is
overlapping a vertical rule, and replace that character cell's contents
with a glyph indicating the intersection (and a lookup table for whether
to imply that the lines continue to the next cell).  This is a big pain
in the ass and supporting intersection of double lines, with themselves
and with single lines, would only make it worse, which is why doublebox
tables are not implemented on terminal devices.

And it isn't just boxes that are affected.

If you ask tbl to draw a horizontal rule across a table that is exactly
78n wide, you will get a 79n rule.  (See attachment.)  tbl deliberately
overdraws it because it makes the collision detection done by grotty(1)
feasible in more complicated cases.

I want to fix this.  Lord, I do.  But to date, the source of tbl, along
with that of the various pieces of grothml, have proven the most
challenging to my understanding.  It may happen, but likely not soon.

Let me know if I'm doing something wrong, or if you would improve
anything.  I come up with the following code.

I despair of the fact that you're going to get BLITZED with CHECKSTYLE
warnings, which I know you use, due to your leverage of `PD`.  I
therefore think I would rather alter tbl(1) to set a register indicating
that the table is boxed and will therefore need an extra vee of space at
the top and bottom on terminal devices.  an.tmac can straightforwardly
test this.  `TB` sounds like a name that might already be employed by
user documents, so I'm thinking `T_`, to suggest a horizontal line
having to to with tbl(1).

(It _appears_ to me, having done some quick experimentation with the
attachment, that horizontally-ruled table rows, while they are too wide,
do not cause vertical space accounting issues.)

That would enable a workaround.  And it need not be a temporary hack,
even if I deeply alter the architecture of tbl as I think is necessary
to resolve those Savannah tickets: this information might be useful for
macro packages in general.  They might want to similarly adjust vertical
spacing before a table depending on whether it's boxed.  Even documents
for other full-service macro packages rendering to typesetters might
want to take advantage of this.  (ms(7), however, manages different
registers for display distance and paragraph distance.)  If they don't,
nothing changes and nothing is lost, except a weird register name
employed by the tbl preprocessor.  Two others, `T.` and `#T`, spent 30
years undocumented until my tbl(1) page rewrite.

I'll also reread that with more time.

diff --git a/man2type/open_how.2type b/man2type/open_how.2type
index e058c08dc..f7b0aea42 100644
--- a/man2type/open_how.2type
+++ b/man2type/open_how.2type
@@ -13,9 +13,14 @@ Linux kernel headers
  .B #include <linux/openat2.h>
  .B struct open_how {
-.BR "    u64  flags;" "    /* " O_ "* flags */"
-.BR "    u64  mode;" "     /* Mode for " O_ { CREAT , TMPFILE "} */"
-.BR "    u64  resolve;" "  /* " RESOLVE_ "* flags */"
+.PD 0
+l lB lB l.

I take it you didn't care for my convention, shown in the man page, of
using capitals for the column classifier and lowercase for modifiers...

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.

+\&     u64     flags;  /* \fBO_\fP* flags */
+\&     u64     mode;   /* Mode for \fBO_\fP{\fBCREAT\fP,\fBTMPFILE\fP} */
+\&     u64     resolve;        /* \fBRESOLVE_\fP* flags */

I sure do wince at all those font escapes.  You don't _have_ to use
them, you know.  You could make the comment fields text blocks.  This
would enable you to use man(7) font macros, and, perhaps even more
importantly, this will make them flexible to different terminal line
lengths, and adaptable to contributors that get carried away with
excessively long comments.  They will degrade cleanly, heightening the
row (and even aligning with themselves!) instead of overrunning the
right margin or terminal width.

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.
I fear that I may be abusing tbl(1) too much for a SYNOPSIS.

Let's wait for more voices to review v3.

Let me also suggest that you can right-align the column with the data

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.

My proposal, forgetting about the vertical space issue discussed at
length above, is as follows.  Tabs are indicated in this email with →.

Rb Lb L.
.BR O_ *
flags */
/* Mode for
flags */

Yes, that's mostly my v3. I had some .nf/.fi things that I realized are unnecessary, so I'll remove them for v4.

I also put the opening /* in a separate field, to better align texts.

I've also attached the file I used to experiment with horizontal rule
placement and the "box" option.




Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

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