Re: .TQ to replace .PD 0

[G. Branden Robinson]

Hi Alex!

At 2022-05-21T16:46:51+0200, Alejandro Colomar wrote:
> For the following existing usage of the deprecated .PD 0 I tried to
> use .TQ in a way that I'm not sure if it's correct by just reading
> groff_man(7):
> 
> [
> .PD 0
> .TP
> tag1
> Some text here.
> .TP
> tag2
> Some more text.
> .PD
> ]
> 
> The above produces:
> 
> [
> tag1   Some text here.
> tag2   Some more text.
> ]
> 
> I (succesfully) tried the following:
> 
> [
> .TP
> tag1
> Some text here.
> .TQ
> Some more text.
> ]
> 
> But I didn't see the manual documenting this kind of usage for .TQ.
> The manual page seems to imply that there should be no text between
> .TP and the successive .TQ tags

Well, no text that isn't part of the paragraph tag, right.

> (as that is probably thew most common use case for it; or not
> necessarily the most common, but the most specific to it, since it's
> hard to replicate it with other macros).  Am I using some undefined
> behavior that happens to behave as one (I?) would expect?  Or is it an
> intended but misdocumented feature?

I can't speak to the intentions of the implementor of TQ, as I wasn't
around when the work was done.

> Is it portable across systems that have TQ?

As far as I know, groff's and mandoc's implementations of it are the
only ones that exist.

> I read mandoc_roff(7), as Ingo usually points me to it and usually has
> exactly what I'm looking for, and once again it seems to bring light:
> 
>        TQ   Like TP, except that no vertical spacing is inserted
>             before the paragraph.  This is  a  non‐standard  GNU
>             extension  and  very  rarely used even in GNU manual
>             pages.

Yes, the above description of the macro is broader; at one point I seem
to recall Ingo sneaking a patch into the groff source tree that (ab)used
TQ in this way.

I think such abuse is tempting because (1) we tell man page authors not
to use *roff requests in man page sources and (2) the man(7) language
exposes no macro that simply breaks a line and does nothing else.

I can't remember now if I patched out Ingo's trick or left it in place;
I sympathize with the temptation to use it, since there is a design gap
here.

> This one makes it clear that it can be used for what I did.  I think
> groff_man(7) is missing this basic description of TQ.

The reason for that is that I think it's an abuse of the macro.  TQ has
semantic value: it means "here's another paragraph tag".  And you can't
use it as a general break macro because it sets an input trap to consume
the next line and typeset it as a paragraph tag.

> BTW, how much unportable is TQ?

I don't know how to answer that.  It's rarely used, true, but it's been
in an-ext.tmac for well over a decade, and that file is permissively
licensed so there's no telling whence it has spread.  People using
an-ext.tmac might have chopped out the macros they thought they didn't
need, or kept them all out of laziness or to give themselves future
flexibility.

> I guess it's still preferable to PD.

I would say so.  PD has a meaning, too: "change the inter-paragraph
spacing".

> mandoc(1) seems to produce the same output on my Debian as groff(1). And
> neither groff(1) 1.23 nor mandoc complain about it:
> 
> $ cat ./tq.7
> .TH TQ 7 2022-05-21 alx experiments
> .SH No blank lines between tagged paragraphs
> .TP
> tag1
> Some text here.
> .TQ
> tag2
> Some more text.
> $ groff -man -t -rCHECKSTYLE=3 -ww -z ./tq.7
> $ mandoc -man -Tlint ./tq.7
> $

I don't have an idea off the top of my head how to write a style check
to complain about this.  Since TQ is so seldom used, it is necessarily
seldom _ab_used.  And the style-check warnings are designed to catch
abuse, whether intentional or inadvertent.  A good example of the latter
is getting macro argument counts wrong.

The implementation of TQ is quite simple.

.\" Continuation line for .TP header.
.de TQ
.  br
.  ns
.  TP \\$1\" no doublequotes around argument!
..

It breaks the line, turns on no-space mode (which shuts itself off as
soon as further output has been formatted), and calls TP.

In groff(7), I'm piloting "begin list" and "end list" macros to provide
a path out of the elaborate page-private macro system that the page has
used for many years.  They are even simpler than TQ.

https://git.savannah.gnu.org/cgit/groff.git/tree/man/groff.7.man#n225

Pretty much the only thing people ever use "PD" to do is to set the
inter-paragraph distance zero, and restore it to its previous value.  It
therefore doesn't need an argument to process.  Further, if people _try_
to set the inter-paragraph distance to something larger than 1 line in
nroff mode, man-db man(1) will strip the extra lines out.

There is thus not much use case for anything but
  .PD 0
and
  .PD
.

And, from what I've seen, pretty much the only reason people ever want
to change the inter-paragraph distance in the first place is to do the
above: to compactly present an itemized or enumerated list.

This idea, along with one or two other mild man(7) reforms, is something
I've put on the shelf until after we get groff 1.23.0 out.

And, as John Gardner and Ingo have recently reminded me, I may be facing
a bloody, unpleasant fight with people who use UTF-8 terminal emulators
but wish to see only ASCII code points, don't want to learn any special
character escape sequences (despite their provenance all the way back to
1976) and care nothing for man page output to typesetter devices (like
PDF).

  https://savannah.gnu.org/bugs/?62494

I expect to get back to my reforms at some point in the future after
I've been on metaphorical iron supplements for a while.  And submitted
patches to some tools that automatically generate terrible man(7)
source.  :P

Since the list has been quiet, I'll also add that I got sucked back into
build system stuff because I decided to see how groff's Debian source
package build dependencies will need to be updated for 1.23, and
discovered some interesting things when building in a chroot.  Fixes for
those and the usual documentation improvements will be in my next push.

Regards,
Branden

signature.asc
Description: PGP signature