Hi Russ, I'm replying to your more recent message now, as you've committed code and that seems more urgent to respond to (though I have no urgent observations to make).
At 2026-07-12T12:02:45-0700, Russ Allbery wrote: > I have merged code to the main branch of podlators to hopefully work > around this change and produce the same output with both older and > newer groff. Testing would be very much welcome; there are a lot of > subtleties here and I am not certain that I got all of them correct. > Code is available from either: > > https://git.eyrie.org/git/perl/podlators.git > https://github.com/rra/podlators I've read over commit fb2736d0672dc7b3ff546fde1d31ed180a0760ad and see nothing incorrect or (freshly) discomfiting. +++ b/lib/Pod/Man.pm -.\\" and register settings are required by groff 1.23.0 and later. +.\\" and register settings are required by groff 1.23.0 and later. Changing +.\\" tag separation back to 1n is required by groff 1.24.0 and later. .if n .ds AD l .if n .ad l .nr HY 0 +.nr TS 1n This change is too bad, as it defeats the _user_-configurability of `TP` tag spacing from its paragraph--but as with adjustment and hyphenation, POD's policy is that the _reader_ of a man page is not permitted to alter these--two horses have already bolted, so what's a third? I looked carefully at each of the changes to "*.groff" model documents and all the changes look idiomatic to me as generated output goes. Is it excessively sunny of me to assess the following as improvements to readability? -.IP """" 3 +.TP 3 +" -.IP """foo""" 4 +.TP 4 +"foo" .IX Item """foo""" .PD 0 -.IP \fBbar\fR 4 +.TP 4 +\&\fBbar\fR .IX Item "bar" -.ie n .IP """baz""" 4 -.el .IP \f(CRbaz\fR 4 +.TP 4 +\&\f(CR\*(C`baz\*(C'\fR AT&T-compatible quoting of double quotes in macro call arguments is pretty mind-twisting. > Colin, for the purposes of this groff bug, I think adding the local > configuration specified early in this bug is correct but insufficient. > groff_man(7) is now also wrong, since it claims that .IP doesn't > enforce tag separation but, with that change, I assume it does. (I > haven't tested the change myself.) That's true. I'm attaching a patch to the man page against stock groff 1.24.1. > In addition, groff 1.24 also broke .TP formatting in a more minor way > by increasing the tag separation from 1n to 2n, which will likely > cause unintended tag spilling onto a separate line in the cases where > the indent was carefully chosen to leave just enough room for the tag > and a single space. This pattern is very common in POD documents; > those are unaffected, of course, since pod2man has always used .IP, > but from that I would conclude that it's probably also common in > hand-written documents. I don't share your assessment that it's "very common". My impression is that man(7) documents directly composed by humans tend either to (1) not give `IP` an argument at all, or (2) select a value and use it uniformly throughout the whole document. Machine-generated man(7) documents also tend strongly to pattern (2). POD sometimes doubles the indentation of an IP paragraph from 4n to 8n, so it's not _strictly_ "uniform"...but it's close. To test that impression, I took a quick statistical sample of ~0.1% of the man pages installed on my Debian(-ish) box, I observe the following. $ find /usr/share/man/man* -type f > ALLMANS $ wc -l ALLMANS 12431 ALLMANS $ shuf -n 13 ALLMANS >|SAMPLE $ vi $(< SAMPLE) To characterize the results, let me add a few "patterns" or notes. (0) no use of macro at all (P) POD-generated page (H) help2man-generated page (D) "Man page generated from reStructuredText." (docutils?) Findings on IP macro calls: /usr/share/man/man1/perltooc.1.gz 0, P /usr/share/man/man1/autoscan-dickey.1.gz 1, H /usr/share/man/man3/rpc_gss_get_principal_name.3t.gz 0 /usr/share/man/man1/ansible-playbook.1.gz 0, D /usr/share/man/man2/msgop.2.gz 2 (2n; \(bu) /usr/share/man/man1/skill.1.gz 0 /usr/share/man/man3/XkbBell.3.gz 2 (5n; \(bu) /usr/share/man/man3/Sys::Hostname::Long.3pm.gz 2, P (4n, 8n) /usr/share/man/man3/XMLRPC::Test.3pm.gz 0, P /usr/share/man/man3/XmScaleGetValue.3.gz 0 (10n; semantic) /usr/share/man/man3/Glib::OptionGroup.3pm.gz 2, P (4n, 8n; \(bu) /usr/share/man/man3/ExtUtils::MM_QNX.3perl.gz 0, P /usr/share/man/man1/irssi.1.gz 0 Oh. Having just written that up, I see you were talking about `TP`, not `IP`. Okay, well, I can make another pass over the same files. Findings on TP macro calls: /usr/share/man/man1/perltooc.1.gz 0, P /usr/share/man/man1/autoscan-dickey.1.gz 1, H /usr/share/man/man3/rpc_gss_get_principal_name.3t.gz 0 /usr/share/man/man1/ansible-playbook.1.gz 1, D /usr/share/man/man2/msgop.2.gz 1 /usr/share/man/man1/skill.1.gz 1 /usr/share/man/man3/XkbBell.3.gz 1 /usr/share/man/man3/Sys::Hostname::Long.3pm.gz 0, P /usr/share/man/man3/XMLRPC::Test.3pm.gz 0, P /usr/share/man/man3/XmScaleGetValue.3.gz 0 /usr/share/man/man3/Glib::OptionGroup.3pm.gz 0, P /usr/share/man/man3/ExtUtils::MM_QNX.3perl.gz 0, P /usr/share/man/man1/irssi.1.gz 1 The coupling of "0, P" is of course not a surprise given your observation earlier in the thread that podlators has, to date, never used the `TP` macro call. I seldom have to use statistics in anger, so I recognize that the margin of error here may be on the order of 25% or something. But even with that amount of slop, a hit rate of 0 explicit uses of an indentation argument with the `TP` macro in this sample suggests that your conclusion that it's probably also common in hand-written documents is not well-founded. Let me know if you'd like me to set aside some time to do larger, and more rigorous, statistical sampling. > I think you should therefore also override the TS register to set it > to 1n, thus restoring backward compatibility with previous versions of > groff. If the Debian package does this, it should update the man page accordingly. Regards, Branden
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index a617d7803..af0444f95 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -1010,10 +1010,12 @@ .SS "Paragraphing macros" .I mark argument to .B IP -cannot `include' a macro call, -and the tag separation amount stored in the -.B TS -register is not enforced. +cannot `include' a macro call. +.\" cannot `include' a macro call, +.\" NOTE: The behavior is reverted by Debian. +.\" and the tag separation amount stored in the +.\" .B TS +.\" register is not enforced. . . _ifstyle()dnl
signature.asc
Description: PGP signature
