groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: .TQ to replace .PD 0


From: G. Branden Robinson
Subject: Re: .TQ to replace .PD 0
Date: Tue, 24 May 2022 00:57:08 -0500

Hi, Ingo!

At 2022-05-24T04:44:21+0200, Ingo Schwarze wrote:
> Your version (with .PD) has the clear advantage that it is more
> portable: it is likely to work on any man(7) implementation,
> whereas .TQ might fail on implementations that are neither
> groff nor mandoc.

There's one wrinkle with `PD`, as noted in a thread from a couple of
weeks ago.

https://lists.gnu.org/archive/html/groff/2022-05/msg00019.html

Briefly, man-db man(1) squeezes multiple blank lines to one when using
nroff to render the page.  That caveat doesn't apply to examples shown
in this thread, but it is a limitation we don't discuss in groff_man(7)
(because we don't impose it) and it is not how historical
implementations behave.  man-db man(1) has done this for a long time; as
far back as 2001, it was calling the pager program with the "-s" flag,
but since 2015 it has done the squeezing itself.

Admittedly, that wrinkle shouldn't come up often.  You can still space
paragraphs however you want when formatting for typesetter devices, and
the most common idiom I've seen for `PD` use is the one discussed in
this thread--setting the spacing to zero and then restoring it.

> My version has the (doubious) advantage that it's a bit less
> presentation-oriented and a bit more indicative of semantics.
> How much that is worth in a language like man(7) that is almost
> entirely presentation-oriented and provides very little semantic
> markup in the first place is open for debate.

Let's not forget that `TH`, `SH`, and `SS` are all semantic, and have
paid us the tremendous benefit of being easily converted to PDF
bookmarks (and HTML anchors, though grohtml has some issues still to be
resolved).  By frequency of use these are far more important than either
`PD` or `TQ`.  Like HTML 1.0, the man(7) language mixes the
presentational and semantic domains.  They also illustrate the inertial
challenge to unscrambling the mixture, I'll grant.

> I tend to think portability is possibly more important than the fact
> that my version with .TQ looks minimally nicer.  So if somebody wrote
> a new manual page in man(7), i would probably recommend your version
> with .PD rather than mine with .TQ.

Another, as yet only potential, advantage to using `TQ` is that it is
much more amenable to indexing and tag inference.  (You could still do
it by parsing a man page and tracking enough state to see `.PD 0` and
`.PD` pairs come and go, but it would be more tedious.)  That's one
reason I embraced the macro when I learned about it.  Many people have
seen pod2man(1) litter man pages with non-standard `IX` macros.  I think
that was a poor execution of a good idea.  Certainly mandoc(1)+mdoc(7)
can boast of powerful tag recognition and search facilities.

Paragraph tags, if used as recommended by groff_man_style(7), will
practically always be the sorts of key words or phrases one wants to
search for, or see compiled into an index (of command-line options, for
instance).  The fact that `TQ` identifies a tag that should be grouped
with the previous `TP` tag allows inferences to be drawn about their
structuring for indexing or tag-relation purposes.

(By "if used as recommended", I mean that, for best results,  people
shouldn't use asterisks/bullets/list enumerators as `TP` paragraph tags.
The same effect can be achieved with the tag argument to the `IP` macro
without muddling the "tag space".)

I have ideas for leveraging this potential that I want to pursue after
the 1.23 release.

[...]
> In either case, i think the best answer to Alejandro's original
> question is: if you value portability, which you probably should,
> using .PD is better than using .TQ, the reason being that the
> gain in beauty from .TQ is small and the portability risk in
> using it is real.

Magnitudes and use cases are important.  It would be nice to know, even
approximately, which systems _don't_ support `TQ` and other groff man(7)
extensions, and how prevalent those systems are.  Without some notion of
that, we can by the same token point people to the Unix Version 7 man(7)
page and tell them to use only that and nothing else--not `TQ`, not
`UR`, not `P`, `AT`, or `UC`, and certainly not mdoc(7), which is a
decade younger, and as far as I know (maybe you do), never made it into
many commercial Unixes descended from System V at all.

That's an extreme application of your principle that I don't expect
anyone to seriously adopt.  But I think the best barrier against sliding
into it is to collect some data and apply quantitative reasoning.  Do
you have any suggestions?  Hypothetically, we could have groff's
'configure' script analyze the host system for this sort of thing.

(I trimmed some other points of yours which are well-taken.)

Regards,
Branden

Attachment: signature.asc
Description: PGP signature


reply via email to

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