.TQ to replace .PD 0
Hi, Branden! 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 (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? Is it portable across systems that have TQ? 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. 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. BTW, how much unportable is TQ? I guess it's still preferable to PD. 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 $ Cheers, Alex -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Re: .TQ to replace .PD 0
On 5/21/22 16:46, Alejandro Colomar wrote: I (succesfully) tried the following: [ .TP tag1 Some text here. .TQ I missed here "tag2" Some more text. ] -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Re: .TQ to replace .PD 0
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 o
Re: .TQ to replace .PD 0
Hi Branden, On 5/21/22 17:21, G. Branden Robinson wrote: 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 I recommend naming them LS/LE (list start, list end), for symmetry with RS/RE (and slightly with others such as UR/UE. LS also happens to be a nice name for list. 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 . Does .PD 0 suffer from the reasons that led to the deprecation of .PD? Or is .PD 0 safe from that and can be used portably for compacting in HTML or PDF output? 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. Yes. I haven't seen in a different context yet. 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. Do you have an idea of when that can be (1.23.0)? Regards, Alex -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Re: .TQ to replace .PD 0
Hi, Alex!
At 2022-05-21T23:58:57+0200, Alejandro Colomar wrote:
> On 5/21/22 17:21, G. Branden Robinson wrote:
> > 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
>
> I recommend naming them LS/LE (list start, list end), for symmetry
> with RS/RE (and slightly with others such as UR/UE. LS also happens
> to be a nice name for list.
That's a good idea. I like it. Any other votes or suggestions from the
mailing list?
> > 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
> > .
>
> Does .PD 0 suffer from the reasons that led to the deprecation of .PD?
Yes, I think so. As I understand it, the HTML devices ("html" and
"xhtml") _are_ the problem in this regard. Or they once were. A quick
experiment reveals that `.PD 0` and `.PD` work fine at least for simple
cases in HTML output. See attachment.
> Or is .PD 0 safe from that and can be used portably for compacting in
> HTML or PDF output?
It should be widely portable. The sin of the `PD` macro isn't its
portability, but its "presentationality", if you will. Almost every
semantic text markup system I've seen, and several presentational ones,
like the Markdown family, has a notion of a "list". man(7) is something
of an outlier in lacking it. By adding one we make the jobs of those
who write tools for interconverting these formats easier.
> > 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.
>
> Do you have an idea of when that can be (1.23.0)?
We're pretty close. Ingo Schwarze and John Gardner have been helpful in
finding portability problems that crept into the build/test procedure.
We've had very recent successful build and "make check" reports on
GNU/Linux, macOS, NetBSD, and OpenBSD.
Bertrand Garrigues, our release manager and official maintainer, has
returned back, which is hugely helpful. He has the knowledge and
permissions to roll out a release to the GNU infrastructure.
I need to write release notes for 1.23.0(.rc2)--I think not having them
for rc1 might account for the near-zero level of feedback we got on that
snapshot. I'd like to go to final as soon as after that as is
reasonable, depending on the severity of reported issues, and then
schedule a point release for 6 months after that.
I strongly prefer time-based releases to feature-based ones. I have a
hard time thinking of things as "done".
Regards,
Branden
signature.asc
Description: PGP signature
Re: .TQ to replace .PD 0
At 2022-05-21T22:41:58-0500, G. Branden Robinson wrote:
> Yes, I think so. As I understand it, the HTML devices ("html" and
> "xhtml") _are_ the problem in this regard. Or they once were. A quick
> experiment reveals that `.PD 0` and `.PD` work fine at least for simple
> cases in HTML output. See attachment.
As usually happens, I forgot the attachment.
Trying again.
PD.man
Description: PD.man
signature.asc
Description: PGP signature
