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
signature.asc
Description: PGP signature