man(7) DS and DE macros (was: [PATCH 4/5] tm.3type: describe tm_zone, tm_gmtoff)

[G. Branden Robinson]

[dropped наб from CC list; added groff@]

At 2022-07-22T12:57:53+0200, Alejandro Colomar (man-pages) wrote:
> You answered all that I thought you would, and even more.  As always,
> you surprise me with great knowledge that I didn't even know I could
> ask for, and that's the main reason I tend to not try to direct your
> answers.  They're always welcome (although sometimes the knowledge is
> too much for me, a novice groff(7) user, to understand it; but I try
> to).

Aww, shucks.  Well, never hesitate to correct or challenge me; the best
knowledge is tested knowledge.

> On 7/22/22 05:33, G. Branden Robinson wrote:
> > Oh, bother.  Bash autocompletion for "man" on my Debian bullseye is
> > too dumb to recognize this new man page suffix.  I trust someone
> > reading this is aware of the problem and is fixing it for the next
> > Debian release.  (Has someone filed this as a bug with the Debian
> > BTS?)
> 
> I don't think it's been reported.  I've detected some unpleasantness,
> but since I also had some unpleasantness with pages in the main
> sections, I didn't know if there was even more of it with subsections.
> 
> Was it trying to read a manual page from a relative path?

Yup.  I was "man -l"-ing inside my Git checkout of man-pages.

> That's where I find a lot of problems, and that's why I always `sudo
> make install` the pages, then read them from the system as usual.
> That makes it easier.  I improved the Makefile to make that loop
> experience something nice.
> 
> Anyway, would you mind reporting the bug you notice and CCing me?

If I work up the gumption to report it, I will CC you, yes.

> > Hmmm.  I'm attaching a screenshot of Okular's rendering of the
> > current state of tm(3type) in the Linux man-pages Git repository to
> > PostScript.
> 
> I only see a black 180 bytes image.  Probably not what you expected to
> send?

No indeed.  My Logitech thumb-operated trackball hates me, as does the
company--they don't even sell a corded version anymore.  Due to some
diabolical collusion with the alkaline cartel, their devices refuse to
operate reliably after a fresh battery has been installed for more than
about 71 seconds.

> Anyway, I used pdfman()[1] to read the page in PDF, and I get your
> point.

I'm trying the attachment again for the benefit of list readers.

> > Synopses in man pages, whether for section [168] commands or section
> > [23] C function calls or data types, are not typically set in a
> > monospaced typeface, nor do I think they should be.  A proportional
> > typeface generally looks better.
> > 
> > The price of that improved appearance is that the use of sequences
> > of spaces to get columnar alignment breaks as soon as there is
> > variation in the content.
> 
> I know.  And I tend to agree that proportional typeface is nicer for
> SYNOPSIS.

Yeah, I don't want to give that up.  Also I seem to remember that in the
Linux man-pages, some function declarations are already nearing or
exceeding the line limit.  Switching to Courier would make this happen
to more of them.

> I'm generally a tab user, so you won't find resistance from me to use
> them, especially if they improve the situation.

When I started to contributing to groff, I didn't think they had a place
in man pages outside of tbl(1) tables, but my resolve is softening.

> > There are a few ways to address this issue.
> > 
> > A. Don't worry about it and let HTML/PostScript/PDF output look ugly.
> 
> I'd prefer to help them if I can.
> 
> > B. Stick synopses, at least for section 2 and 3 man pages, in EX/EE
> >     blocks [...].  My recollection is that Michael Kerrisk opposed
> >     this practice.  I too don't think it's a great idea; the average
> >     glyph width is lower in proportional fonts, so using it, you can
> >     fit more content on an output line.
> 
> It would be an easy fix, if nothing else works nicely.  We can
> restrict it to type pages, where there is an objective reason to do
> that, and let function pages continue using proportinal typeface.

After a bit of pondering today, I had an idea--see below.

> > C. Use tabs anyway.  For results that will actually get what you
> >    want, you will need to set the tab stops to ensure they're wide
> >    enough to achieve the desired alignment.  The use of custom tab
> >    stops requires invoking the `ta` request, and this is warned
> >    against in the "Portability" section of groff_man(7) (to be part
> >    of groff_man_style(7) in groff 1.23).  But by invoking the `nf`
> >    and `fi` requests for other reasons, this project's pages have
> >    already crossed that bridge.
> 
> That will be my first attempt.  But I won't try setting the width,
> since you've shown in the below explanations how brittle and difficult
> it is.  So, if the defaults work nicely (maybe using double tabs at
> some places), I'll use tabs.  Otherwise, I'm probably going to
> fallback to .EX/.EE.  What's your opinion on this?  Or do you prefer
> going directly to .EX/.EE for 3type/2type pages?

I think going ahead and using tabs as a first cut is a good idea.  I
would recommend _against_ adding supplemental adjacent tabs to manually
correct cases of misalignment.  A tab character always causes motion to
the next tab stop to the right of the current drawing position, so it
should never happen that text overrunning a tab stop will get
overprinted.

Further, in groff, by default the number of tab stops is infinite,
spaced at half-inch (~1.3 cm) intervals.

[Imagined: a new man(7) macro that would use \w to compute the widths of
its arguments, add 1n, and set a tab stop for each.]
> >      .TA char gmtoff
> > 
> >      This certainly looks much cleaner, and in fact it closely
> >      resembles Texinfo's @multitable command.  But it is just a mask
> >      over the `ta` request of frightening appearance above, not a
> >      silver bullet.
> 
> May be nice.

I'm keeping the above content as preparation for the New Idea.

> > C3. The above has the problem that it relies upon the writer to know
> >      which pieces of text between the tab stops are the longest.
> >      This sounds like an obvious thing that no one would ever screw
> >      up.  I think that assumption would be swiftly overturned.
> 
> Maybe you can set up .TA so that it takes the longest of a set of
> consecutive .TA?  That's already kind of tbl(1).  Maybe we should use
> tbl(1) for that :P.

Yes, that seems a bridge too far to me.  If its features are needed,
there is no shame in reaching for tbl(1).

> Would you recommend me using tbl(1), or .EX, or tabs (in the simple
> way)?

Start with tabs.  If that proves unsatisfactory, consider my New Idea
below, or tbl(1).  Using EX/EE for some synopses but not others feels
ugly to me.

> > D. Congratulations, you've discovered tbl(1).[1]
> 
> So it seems.

I fancy that I reconstructed the sequence of events that led Mike Lesk
to write it.  This could of course be completely wrong.  ;-)

> So no single-sided space for em dashes --such as this one--, right?
> Maybe that's a construction of my brain, trying to make them a bit
> more logic...

I haven't seen that outside of things like more(1) prompts; my few
memories of such feel decades old, probably of bespoke implementations
for 1980s micros.

Or maybe I'm thinking of NetHack.[1]

So here's the crazy idea.

Check this out from groff's an-ext.tmac file.

259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 267) .\" Start 
display.
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 268) .de DS
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 269) .  \" XXX to be 
written
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 270) ..
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 271) .
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 272) .
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 273) .\" End display.
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 274) .de DE
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 275) .  \" XXX to be 
written
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 276) ..

We've had these stub, empty definitions of display macros lying around
for over 15 years.

How about we put some life into them?

Your section 2 and 3 synopses don't use groff's SY/YS macros because
those fill the text and you don't want the text filled.  You also need
tab stops and command synopses never do.

Unfilled text is a common feature of display macros in *roff macro
packages (see groff_me(7), groff_mm(7), and groff_ms(7)).

So, we could define `DS` as an `nf` invocation and `DE` as `fi`.  This
would relieve the Linux man-pages from having to "reach down" and invoke
these requests directly.

But we can do better.

Historically, there isn't much demand in man pages for right-aligned
text or centering; means of encoding these requirements is a common
feature of "display start" macro arguments in other packages.

The macro definitions above ignore their arguments.  What if we made
`DS` accept a list of strings whose widths it would use to compute the
tab stops?  (If there are no arguments, it would do nothing with the tab
stops.)

That would make `DS` work like my straw-man `TA` above, and importantly,
would eliminate the need to un-deprecate `DT` to reset the tab stops.
The scope of your changed tab stops would end with `DE`.

Furthermore, noting the (elided from the email) concerns I had about
people rendering man pages at a different type size (as supported by the
`S` register) or the future potential to make the font family used for
the body text configurable, I think it would be valuable for this `DS`
macro to emit a warning if a tab stop thus computed exceeds the line
length.  Because this is done at formatting time, it is dynamic--it
takes into account the properties of the font being used for rendering.
So it can't be wrong, and will never be issued spuriously.[2]

This change would be less disruptive than `MR`.  `DS` and `DE` are
_already defined_, and have been in groff man(7) for 15+ years.  In the
short term you could keep the `nf` and `fi` requests within `DS` and
`DE` until groff 1.23 ages out of your support window.  groff 1.22.4 and
earlier won't render your pages any _worse_ than they are right now, but
groff 1.23 would handle them _better_.

It will be important to remember that this feature isn't as powerful as
tbl(1).  It will still rely on contributors updating the `DS` call to
contain the "longest" text appearing in each column.  This will
occasionally be overlooked and people will occasionally guess wrong.

Maybe it's not worth the trouble.

But maybe it is.  I think there is a chance that this feature would
capture as much table or tab stop functionality as most man pages
require.

Regards,
Branden

[1] https://github.com/NetHack/NetHack/blob/NetHack-3.7/doc/Guidebook.mn#L428
[2] famous last words

signature.asc
Description: PGP signature