Re: Using tbl(1) for structure definitions

[Alejandro Colomar]

Improved an v2 using T{...T} in combination with column modifiers and 
removing .nf/.fi for the table, fixing a misplaced .PD, and .BR instead 
of \fB...\fP:



open_how.2type: ffix

Format structures with tbl(1) to improve alignment in 
proportional-width font text.


Reported-by: "G. Branden Robinson" 
Signed-off-by: Alejandro Colomar 

diff --git a/man2type/open_how.2type b/man2type/open_how.2type
index e058c08dc..edc4d8a3b 100644
--- a/man2type/open_how.2type
+++ b/man2type/open_how.2type
@@ -13,9 +13,26 @@ Linux kernel headers
 .B #include 
 .PP
 .B struct open_how {
-.BR "u64  flags;" "/* " O_ "* flags */"
-.BR "u64  mode;" " /* Mode for " O_ { CREAT , TMPFILE "} */"
-.BR "u64  resolve;" "  /* " RESOLVE_ "* flags */"
+.fi
+.PD 0
+.TS
+l lB lB l1 lX.
+\& u64 flags;  /*  T{
+.BR O_ *
+flags */
+T}
+\& u64 mode;   /*  T{
+Mode for
+.BR O_ { CREAT , TMPFILE }
+*/
+T}
+\& u64 resolve;/*  T{
+.BR RESOLVE_ *
+flags */
+T}
+.TE
+.PD
+.nf
 /* ... */
 .B };
 .fi


--
Alejandro Colomar



OpenPGP_signature
Description: OpenPGP digital signature

Re: Using tbl(1) for structure definitions

[Alejandro Colomar]

I must say that the source code is really ugly (ugly as in, someone 
reading it will probably have a hard time modifying it, without reading 
tbl(1)).


But at the same time, the result is beautiful, and the syntax is really 
great.  You can express exactly what you want.


Cheers,

Alex

On 7/26/22 22:07, Alejandro Colomar wrote:
Improved an v2 using T{...T} in combination with column modifiers and 
removing .nf/.fi for the table, fixing a misplaced .PD, and .BR instead 
of \fB...\fP:



     open_how.2type: ffix

     Format structures with tbl(1) to improve alignment in 
proportional-width font text.


     Reported-by: "G. Branden Robinson" 
     Signed-off-by: Alejandro Colomar 

diff --git a/man2type/open_how.2type b/man2type/open_how.2type
index e058c08dc..edc4d8a3b 100644
--- a/man2type/open_how.2type
+++ b/man2type/open_how.2type
@@ -13,9 +13,26 @@ Linux kernel headers
  .B #include 
  .PP
  .B struct open_how {
-.BR "    u64  flags;" "    /* " O_ "* flags */"
-.BR "    u64  mode;" " /* Mode for " O_ { CREAT , TMPFILE "} */"
-.BR "    u64  resolve;" "  /* " RESOLVE_ "* flags */"
+.fi
+.PD 0
+.TS
+l lB lB l1 lX.
+\& u64 flags;  /*  T{
+.BR O_ *
+flags */
+T}
+\& u64 mode;   /*  T{
+Mode for
+.BR O_ { CREAT , TMPFILE }
+*/
+T}
+\& u64 resolve;    /*  T{
+.BR RESOLVE_ *
+flags */
+T}
+.TE
+.PD
+.nf
  /* ... */
  .B };
  .fi




--
Alejandro Colomar



OpenPGP_signature
Description: OpenPGP digital signature

Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

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?

> 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!"

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

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.

https://savannah.gnu.org/bugs/index.php?62471
https://savannah.gnu.org/bugs/index.php?62265

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

https://savannah.gnu.org/bugs/index.php?49390

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

https://savannah.gnu.org/bugs/index.php?43637

And it isn't just boxes that are affected.

https://savannah.gnu.org/bugs/index.php?43636

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.

> diff --git a/man2type/open_how.2type b/man2type/open_how.2type
> index e

Re: Using tbl(1) for structure definitions

[Ralph Corderoy]

Hi Alex,

> +.TS
> +l lB lB l1 lX.
> +\& 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.

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

-- 
Cheers, Ralph.

Re: Using tbl(1) for structure definitions

[Alejandro Colomar (man-pages)]

Hi Ralph,

On 7/27/22 08:41, Ralph Corderoy wrote:

Hi Alex,


+.TS
+l lB lB l1 lX.
+\& 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.


Yeah, I think I agree.



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



Since this example is easy, tbl(1) would be overkill here.  In other 
examples with type names of very different lengths (int vs struct foo) 
tabs would not work nicely.  And I want to keep a consistent way of 
formatting all types, so I think tbl(1) will win.


Regards,

Alex
--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Using tbl(1) for structure definitions

[Alejandro Colomar (man-pages)]

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

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

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.

https://savannah.gnu.org/bugs/index.php?62471
https://savannah.gnu.org/bugs/index.php?62265

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

https://savannah.gnu.org/bugs/index.php?49390



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.

https://savannah.gnu.org/bugs/index.php?43637

And it isn't just boxes that are affected.

https://savannah.gnu.org/bugs/index.php?43636

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 

Re: Using tbl(1) for structure definitions

[Ralph Corderoy]

Hi Alex,

> > .\" 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
> > ..
>
> I'll tell you what I understand from that macro definition, so that
> you have an idea of how little groff(7) I know:

CSTR 54 is short and a first read will get you a long way in getting the
gist of what's going on.  It also has summary tables early on.
https://troff.org/54.pdf

In the above, they're all mnemonic.

.de  define a macro
.ie  start an if-else
.el  the else part
.nr  set a number register
.sp  add vertical space or move vertically to a place
.if  an if-else with no .el  :-)
.ll  set the line length
\nx  the value of number register x

-- 
Cheers, Ralph.

Re: Using tbl(1) for structure definitions

[Heinz-Jürgen Oertel]

Am Dienstag, 26. Juli 2022, 21:33:07 CEST schrieb Alejandro Colomar:
> Hi Branden,
> 
> I've already read all that was relevant to me from tbl(1) regarding what 
> I had in mind: documenting structures.
> 
> 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.
> 
> Let me know if I'm doing something wrong, or if you would improve 
> anything.  I come up with the following code.
> 
> Cheers,
> 
> Alex
> 


Hi Alex,
did you look at the dformat preprocessor for pic?

https://noxz.tech/guides/groff/papers/dformat_--_a_program_for_typesetting_data_formats__142.pdf

Heinz

example.pdf
Description: Adobe PDF document

Re: Using tbl(1) for structure definitions

[Alejandro Colomar]

On 7/29/22 10:13, Heinz-Jürgen Oertel wrote:> Hi Alex,

did you look at the dformat preprocessor for pic?


Hi Heinz,

I think tbl(1) is more suited for this.


https://noxz.tech/guides/groff/papers/dformat_--_a_program_for_typesetting_data_formats__142.pdf



But thanks for that.  I didn't know about it.

Cheers,

Alex

--
Alejandro Colomar



OpenPGP_signature
Description: OpenPGP digital signature

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

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

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



OpenPGP_signature
Description: OpenPGP digital signature

Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

Hi Alex!

At 2022-07-29T17:26:10+0200, Alejandro Colomar wrote:
> On 7/29/22 15:52, G. Branden Robinson wrote:
> > 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.

Mmm, so it would be nice to overcome that line intersection problem in
grotty(1).  Maybe for groff 1.24...

> Sure; compare:
> 
> 
>u64  mode; /* Mode  for
>  O_{CREAT,TMPFILE}
>  */
> 
>u64  mode; /* Mode  for
>   O_{CREAT,TMPFILE}
>   */

Ah, you want the comments to wrap extra-attractively.  Let me counter by
suggesting that most of the time, the comments should fit on the same
ouput line anyway.

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

The fix should be in my next push; I merely got caught in a yak shave
called groff_mm(7).

Regards,
Branden


signature.asc
Description: PGP signature

Re: Using tbl(1) for structure definitions

[Alejandro Colomar]

Hi Branden,

On 7/29/22 23:08, G. Branden Robinson wrote:

Hi Alex!

At 2022-07-29T17:26:10+0200, Alejandro Colomar wrote:

On 7/29/22 15:52, G. Branden Robinson wrote:

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.


Mmm, so it would be nice to overcome that line intersection problem in
grotty(1).  Maybe for groff 1.24...


Sure; compare:


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

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


Ah, you want the comments to wrap extra-attractively.  Let me counter by
suggesting that most of the time, the comments should fit on the same
ouput line anyway.


Hmm, considering that the amount of multiline comments with 80-char 
terminals is still non-negligible (not in this page, but in all type 
pages), I think I prefer to consistently support them, even when I don't 
need.  That will have 2 side effects: contributors will experience a 
more consistent syntax; and I will support smaller terminals with 
extra-attractive comments.


I'll send a v5 with another page, to show that tabs are not good enough.
And I'll try to not forget CCing groff@.




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.


The fix should be in my next push; I merely got caught in a yak shave
called groff_mm(7).


Nice.  Still, I woudn't make use of it so fast, if the side effect in 
old groff(1) versions was something more than a blank line.  Poor 
contributors are unlikely to have latest groff for git HEAD :)


Regards,

Alex

--
Alejandro Colomar



OpenPGP_signature
Description: OpenPGP digital signature

Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

Hi Alex,

At 2022-07-30T00:38:13+0200, Alejandro Colomar wrote:
> On 7/29/22 23:08, G. Branden Robinson wrote:
> > At 2022-07-29T17:26:10+0200, Alejandro Colomar wrote:

> Hmm, considering that the amount of multiline comments with 80-char
> terminals is still non-negligible (not in this page, but in all type
> pages), I think I prefer to consistently support them, even when I
> don't need.  That will have 2 side effects: contributors will
> experience a more consistent syntax; and I will support smaller
> terminals with extra-attractive comments.

Okay.  If you trust your contributors to understand that column just for
the comment leader, then I trust you.  :)

> I'll send a v5 with another page, to show that tabs are not good
> enough.  And I'll try to not forget CCing groff@.

It'll be good to have a look.

> > > > 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.
> > 
> > The fix should be in my next push; I merely got caught in a yak
> > shave called groff_mm(7).
> 
> Nice.  Still, I woudn't make use of it so fast, if the side effect in
> old groff(1) versions was something more than a blank line.

It wasn't.  I was confusing this issue with Savannah #49390.

https://savannah.gnu.org/bugs/index.php?49390

Savannah #43637 is also pretty gross.

https://savannah.gnu.org/bugs/index.php?43637

I rendered all the groff man pages from Git HEAD with groff 1.22.4, with
the `sp` request deleted from the `TS` definition and a fallback
definition of `MR` (just like the one I presented in arguments with
Ingo) in man.local, and observed no pertinent layout problems.

> Poor contributors are unlikely to have latest groff for git HEAD :)

Don't I know it.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Using tbl(1) for structure definitions

[Alejandro Colomar]

Hi Branden,

On 7/30/22 01:56, G. Branden Robinson wrote:

Hi Alex,

At 2022-07-30T00:38:13+0200, Alejandro Colomar wrote:

On 7/29/22 23:08, G. Branden Robinson wrote:

At 2022-07-29T17:26:10+0200, Alejandro Colomar wrote:



Hmm, considering that the amount of multiline comments with 80-char
terminals is still non-negligible (not in this page, but in all type
pages), I think I prefer to consistently support them, even when I
don't need.  That will have 2 side effects: contributors will
experience a more consistent syntax; and I will support smaller
terminals with extra-attractive comments.


Okay.  If you trust your contributors to understand that column just for
the comment leader, then I trust you.  :)


Heh!  I'll try.




I'll send a v5 with another page, to show that tabs are not good
enough.  And I'll try to not forget CCing groff@.


It'll be good to have a look.


Oh, it's already in your mailbox, isn't it?



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.


The fix should be in my next push; I merely got caught in a yak
shave called groff_mm(7).


Nice.  Still, I woudn't make use of it so fast, if the side effect in
old groff(1) versions was something more than a blank line.


It wasn't.  I was confusing this issue with Savannah #49390.

https://savannah.gnu.org/bugs/index.php?49390

Savannah #43637 is also pretty gross.

https://savannah.gnu.org/bugs/index.php?43637

I rendered all the groff man pages from Git HEAD with groff 1.22.4, with
the `sp` request deleted from the `TS` definition and a fallback
definition of `MR` (just like the one I presented in arguments with
Ingo) in man.local, and observed no pertinent layout problems.


But reallistically, how many people will fix their TS in man.local?  Are 
we asking Debian [old]stable to backport that fix?  :)





Poor contributors are unlikely to have latest groff for git HEAD :)


Don't I know it.

Regards,
Branden


Cheers,

Alex

--
Alejandro Colomar



OpenPGP_signature
Description: OpenPGP digital signature

Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

Hi Alex,

At 2022-07-30T02:04:39+0200, Alejandro Colomar wrote:
> On 7/30/22 01:56, G. Branden Robinson wrote:
> > It'll be good to have a look.
> 
> Oh, it's already in your mailbox, isn't it?

I think I just responded to it.  :)

> But reallistically, how many people will fix their TS in man.local?
> Are we asking Debian [old]stable to backport that fix?  :)

I think we must be talking about different things.  There is no need to
modify the groff 1.22.4 and earlier man(7) `TS` macro.  It will put a
blank line before all tables (except, if not continuously rendering, at
the tops of pages or anyplace else no-space mode is on).

And, in fact, I did not change the 1.22.4 `TS` macro in any way.  I
contrived an ersatz `.cp` register via a hack and implemented a
substitute `MR` macro so that groff Git HEAD man pages would render
without warnings.

What I thought you were asking me was whether this `TS` change (removing
the `sp` request) needed to roll out before you could safely use tbl(1)
to lay out synopses of structs in the Linux man-pages.  I say "no",
because at worst, rendering with groff 1.22.4 and earlier, you'll get a
spurious blank line like this:

struct foo {

int bar;
}

...but not with groff Git HEAD, of course.  I was worried about ugly
overprinting scenarios like that documented in Savannah #49390.

Does this clear things up?

Regards,
Branden


signature.asc
Description: PGP signature

Re: Using tbl(1) for structure definitions

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 10:09:44PM +0200:

> I must say that the source code is really ugly (ugly as in,
> someone reading it will probably have a hard time modifying it,
> without reading tbl(1)).

Completely true, but that's not the worst aspect of it.

In a nutshell, you are making it impossible to decently render
the manual page to HTML or to convert it to other formats in
any sensible way.

If esr@ (of doclifter fame) were still around, he would be screaming
in pain and disgust.

> But at the same time, the result is beautiful,

Only in PDF and PostScript output.

Did we really learn nothing collectively from the "do not abuse
tables for layout purposes" drama that raged for decades among HTML
authors and HTML standard developers?  Exactly the same applies to
manual pages.

In fact, the same arguments so very familiar from HTML apply to manual
pages even more. HTML tables can at least be imbued with some semantic
capabilities by using CSS, whereas tbl(1) tables are so deeply entrenched
in the "markup is presentational markup only" camp that they can never
hope to convey any semantic function at all.

> and the syntax is really great.
> You can express exactly what you want.

I think you need to revert all that madness of abusing tbl(1)
for alignment of structures.

Just say something like (caution, the following code contains
literal ASCII tab characters):

.nf
struct open_how {
u64 flags;  /* O_* flags */
u64 mode;   /* Mode for O_CREAT, O_TMPFILE */
u64 resolve;/* RESOLVE_* flags */
/* ... */
};
.fi

There is no need to use bold or italic donts in the structure
display.  Making all the C code bold merely makes the whole
display look heavy and ugly and provides no additional
information.  Making the comments use mixed font looks even
more ugly and is also redundant because the constants are
hopefully already more fully documented elsewhere.

Just use the same indentation conventions as you would
in a *.c or *.h file.

I don't think you need to worry that the alignment might
vary on different output devices.  If you worry anyway,
you can use an explicit roff(7) .ta request before the
display and reset it with .DT after the display.
Formatters that don't support .ta will just ignore it,
so it causes no harm, and groff and mandoc do support it.

Yours,
  Ingo

Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

At 2022-08-11T15:47:38+0200, Ingo Schwarze wrote:
> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 10:09:44PM +0200:
> > I must say that the source code is really ugly (ugly as in,
> > someone reading it will probably have a hard time modifying it,
> > without reading tbl(1)).
> 
> Completely true, but that's not the worst aspect of it.

I disagree with Ingo's priorities here.  The readability of the source
is more important for document maintainability.  As we shall see, tbl(1)
need not discard as much as Ingo suggests, and even if it does (at
present), I don't perceive quite the semantic damage he does.

> In a nutshell, you are making it impossible to decently render
> the manual page to HTML or to convert it to other formats in
> any sensible way.
> 
> If esr@ (of doclifter fame) were still around, he would be screaming
> in pain and disgust.

We have an open bug report requesting a feature to have tbl emit HTML.

https://savannah.gnu.org/bugs/index.php?60052

Maybe someone would like to work on this.  The "troffcvt" suite already
did this many years ago.  I further note that GNU eqn(1) has already for
many years supported MathML output, and Brian Kernighan reportedly
altered pic(1) to produce SVG.  This undertaking was characterized as
"not difficult".  I imagine it was GNU pic he extended in this way,
given his statements about groff in his most recent book _Unix: A
History and Memoir_, and because GNU pic was written from the start to
support different output formats (supplanting tpic for production of TeX
pictures from pic input).

If we could knock those two projects out, summer-of-code style, we could
eliminate a lot of grohtml.  Possibly the entire pre-grohtml
preprocessor could be disposed of.

> > But at the same time, the result is beautiful,
> 
> Only in PDF and PostScript output.

These output formats are _how typesetting is done_ in the modern era.

I know mandoc doesn't want to dirty its hands with such matters, but
your militance about the unimportance of typesetting blinkers your
perspective.

groff cannot share that perspective.

"As the most widely deployed implementation of troff in use today, groff
holds an important place in the Unix universe.  Frequently and
erroneously dismissed as a legacy program for formatting Unix manuals
(manpages), groff is in fact a sophisticated system for producing
high-quality typeset material, from business correspondence to complex
technical reports and plate-ready books." -- groff Mission Statement,
2014

https://www.gnu.org/software/groff/groff-mission-statement.html

> Did we really learn nothing collectively from the "do not abuse
> tables for layout purposes" drama that raged for decades among HTML
> authors and HTML standard developers?  Exactly the same applies to
> manual pages.

Tables were abused in HTML for layout for a similar reason Alex is
tempted to use tbl here; the suggested "portable" dialect you and I both
prescribe for man(7) pages does not admit any other way for him to
achieve what he wants.  In HTML, at first CSS didn't even exist, and its
progress toward permitting the simulation of full-color typography with
pixel-precise element placements in Web pages was difficult and fitful.
I stopped messing with Web stuff before that journey was completed, if
indeed it was.  I have heard it said that the preferred way to satisfy
such demands these days is use a "canvas" element and run JavaScript on
the client side to draw it.

Anyway, what Alex wants isn't stupid or gratuitous.

> In fact, the same arguments so very familiar from HTML apply to manual
> pages even more. HTML tables can at least be imbued with some semantic
> capabilities by using CSS, whereas tbl(1) tables are so deeply
> entrenched in the "markup is presentational markup only" camp that
> they can never hope to convey any semantic function at all.

tbl could be extended to support semantic tagging easily.

We could add a column modifier, say "g", which would take a mandatory
parenthesized argument with the semantic tag to be applied to the
column.

.TS
tab(@);
Lg(type) Lg(identifier) Lg(descriptive-comment).
int@nflag;@/* ??? */
.TE

How to carry this semantic information into the output is the more
interesting question.

Yet I would hasten to point out that a synopsis that presents something
that is nowhere discussed later in the man page makes the document
deficient.  So if you have semantic markup of all relevant content
_after_ the synopsis, of which a well-written mdoc(7) page will surely
boast, then little or nothing is lost in the domains of  searchability
and discoverability.

> There is no need to use bold or italic donts in the structure
> display.  Making all the C code bold merely makes the whole
> display look heavy and ugly and provides no additional
> information.  Making the comments use mixed font looks even
> more ugly and is also redundant because the constants are
> hopefully already more fully documented elsewhere.

I'm going to invite you again to

Re: Using tbl(1) for structure definitions

[Ingo Schwarze]

G. Branden Robinson wrote on Thu, Aug 11, 2022 at 04:46:12PM -0500:
> At 2022-08-11T15:47:38+0200, Ingo Schwarze wrote:
>> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 10:09:44PM +0200:

>>> I must say that the source code is really ugly (ugly as in,
>>> someone reading it will probably have a hard time modifying it,
>>> without reading tbl(1)).

>> Completely true, but that's not the worst aspect of it.

> I disagree with Ingo's priorities here.  The readability of the
> source is more important for document maintainability.

True, both readability of the source code and rendering quality
matter, and discussing which one matters more in the case at hand
feels moot.

> As we shall see, tbl(1) need not discard as much as Ingo suggests,
> and even if it does (at present), I don't perceive quite the semantic
> damage he does.

I cannot imagine worse damage than reading an alt="" text containing
a non-descriptive filename to a blind reader.  Even with mandoc,
the damage of rendering a structure display as a  is very
severe for a blind reader.

>> In a nutshell, you are making it impossible to decently render
>> the manual page to HTML or to convert it to other formats in
>> any sensible way.
>> 
>> If esr@ (of doclifter fame) were still around, he would be screaming
>> in pain and disgust.

> We have an open bug report requesting a feature to have tbl emit HTML.
> 
> https://savannah.gnu.org/bugs/index.php?60052
> 
> Maybe someone would like to work on this.  The "troffcvt" suite already
> did this many years ago.

An argument that groff -T html could possibly support  output
from tbl(1) input if somebody did the work is hardly a justification
that manual page authors should behave as if it did *right now*.

Also, you ignored my observiation that even the mandoc -T html output
from a structure display using tbl(1) is very bad for accessibility,
and groff could hardly do better.  The reason is not that mandoc
tbl(7) to HTML conversion is bad but that a structure display *is
not tabular data*.

I really think this is a point we should try to find a consensus on
because using tbl(1) for structure display is such egregiously and
unambiguously bad advice that it would be very detrimental if even
part of the groff developers would continue promoting it.

[...]
>>> But at the same time, the result is beautiful,

>> Only in PDF and PostScript output.

> These output formats are _how typesetting is done_ in the modern era.
> 
> I know mandoc doesn't want to dirty its hands with such matters, but
> your militance about the unimportance of typesetting blinkers your
> perspective.

I don't think that is fair.  My argument here is only that a very
minor advantage for PDF and Postscript is not worth completely ruining
HTML output *for manual pages*.  (Besides, there is likely additional
fragility with processors without tbl(1) support, or with incomplete
tbl(1) support.)

I'm not talking about general-purpose typesetting here.

> groff cannot share that perspective.
> 
> "As the most widely deployed implementation of troff in use today, groff
> holds an important place in the Unix universe.  Frequently and
> erroneously dismissed as a legacy program for formatting Unix manuals
> (manpages), groff is in fact a sophisticated system for producing
> high-quality typeset material, from business correspondence to complex
> technical reports and plate-ready books." -- groff Mission Statement,
> 2014
> 
> https://www.gnu.org/software/groff/groff-mission-statement.html

Yes.  It is important that groff provides high-quality typesetting.

But that doesn't mean manual pages authors should go out of their
way to optimize typesetting quality and disregard considerations
for any other output format, or for portability and robustness.

[...]
> .TS
> tab(@);
> Lg(type) Lg(identifier) Lg(descriptive-comment).
> int@nflag;@/* ??? */
> .TE

Please don't abuse hypothetical language extensions to justify
using fancy features in manual pages that cause severe trouble
with currently existing software.

[...]
> Yet I would hasten to point out that a synopsis that presents something
> that is nowhere discussed later in the man page makes the document
> deficient.  So if you have semantic markup of all relevant content
> _after_ the synopsis, of which a well-written mdoc(7) page will surely
> boast, then little or nothing is lost in the domains of  searchability
> and discoverability.

This is a digression.  I would argue that the SYNOPSIS should
usually not contain structure displays.  Then again, this is a
page documenting a type, which we both consider a bad idea IIRC.
But none of that is related to the question whether using tbl(1)
for a structure display is a good idea.  If nothing is lost by
the structure not rendering at all, that's an argument for
deleting it, not for using tbl(1).

Let's stick to the point of how to best mark up a structure.

>> I don't think you need to worry that the alignment might vary on
>> different output devices.

Re: Using tbl(1) for structure definitions

[Alejandro Colomar]

Hi Ingo and Branden,

Since I'm not 100% convinced by any of the ways to format structure 
definitions in SYNOPSIS, I'm going to go for the status quo.  Since 
there weren't any structure definitions (at least that I know of) in 
SYNOPSIS before my introduction, I'll go for what was used in 
DESCRIPTIONs.  That is embedding them in EX/EE, which uses monospace, 
which allows me to align perfectly with spaces in any output device.


I hope nobody will consider this very harmful.

Still, I'm interested in your discussion about the best way to show 
structured data like this, and the possible 
portability/readability/accessibility issues of each alternative, so 
this is just a temporary solution until we agree on something better (if 
it exists).


Cheers,

Alex


--
Alejandro Colomar



OpenPGP_signature
Description: OpenPGP digital signature

Re: Using tbl(1) for structure definitions

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Fri, Aug 12, 2022 at 05:58:32PM +0200:

> Since I'm not 100% convinced by any of the ways to format structure 
> definitions in SYNOPSIS, I'm going to go for the status quo.  Since 
> there weren't any structure definitions (at least that I know of) in 
> SYNOPSIS before my introduction, I'll go for what was used in 
> DESCRIPTIONs.  That is embedding them in EX/EE, which uses monospace, 
> which allows me to align perfectly with spaces in any output device.

I consider that a good choice.

> I hope nobody will consider this very harmful.

While .EX may not be perfectly portable (being a v9+GNU extension),
i agree it is useful enough that using it often makes sense.
Btw., Branden sometimes asks for man(7) extensions that i do not
vilify; this is one.  :)

Besides, even if a formatter does not implement it (which won't
happen for many formatters), no content is lost.  Indentation is
lost in that case, but that's not a very serious problem because
C is not Pathon and line breaks and indentation do not matter for
C syntax and semantics.

> Still, I'm interested in your discussion about the best way to show 
> structured data like this, and the possible 
> portability/readability/accessibility issues of each alternative, so 
> this is just a temporary solution until we agree on something better (if 
> it exists).

I'm not sure whether a better way exists.  Maybe, maybe not.
Certainly tbl(1) isn't part of it.

Yours,
  Ingo

Re: Using tbl(1) for structure definitions

[James K. Lowden]

On Fri, 12 Aug 2022 17:41:40 +0200
Ingo Schwarze  wrote:

> The reason is not that mandoc tbl(7) to HTML conversion is bad but
> that a structure display *is not tabular data*.

Ingo's point is irrefutable.  Whenever a technology is used toward an
unintended end, problems inevitably arise.  (I exclude uses unforeseen
by the designer but encompassed in the design.) 

The goal of better output for structure definitions is salubrious.
What is considered problematic currently, and what is Alejandro's goal,
in terms of output?  

I've seen a lot of discussion about using tbl(1) to that end, but I
don't recall a "white paper" laying out the problem statement and
rationale for that particular solution. 

--jkl

Re: Using tbl(1) for structure definitions

[G. Branden Robinson]

At 2022-08-13T16:26:43-0400, James K. Lowden wrote:
> Ingo Schwarze  wrote:
> > The reason is not that mandoc tbl(7) to HTML conversion is bad but
> > that a structure display *is not tabular data*.
> 
> Ingo's point is irrefutable.

Oh yeah?  Prove it!  ;-)

> The goal of better output for structure definitions is salubrious.
> What is considered problematic currently, and what is Alejandro's goal,
> in terms of output?
> 
> I've seen a lot of discussion about using tbl(1) to that end, but I
> don't recall a "white paper" laying out the problem statement and
> rationale for that particular solution. 

The discussion started on the linux-man list in the course of a patch
review.

https://lore.kernel.org/linux-man/62c1b6748d2faa6263264b9fcaa064495357441b.1658195739.git.nabijaczlew...@nabijaczleweli.xyz/T/#m83835d556f7dd115590ff756305734ce5fb27a18

I presented multiple alternatives.

Regards,
Branden


signature.asc
Description: PGP signature