"G. Branden Robinson" <[email protected]> writes: > At 2026-07-11T08:58:35-0700, Russ Allbery wrote:
>> This is the first that I've heard of this backwards-incompatible >> change in groff. > I see. Tracking upstream changes across high-volume development > channels--and the groff-commit list is surely that--can challenge > downstream maintainers. This change percolated in groff's Git "master" > branch for two years, followed by four public release candidates, and > then the final 1.24.0 release announcement, without drawing comment. Yes, the groff mailing list is considerably higher traffic than I have time to read. Unfortunately, so are the release announcements for groff, which are so verbose, detailed, and full of technical jargon that doubtless makes sense to heavy *roff users but that is opaque to me that I'm afraid I have given up on trying to absorb them. I note that this change was not even listed under "Noteworthy incompatible changes," even though from my perspective it is a noteworthy incompatible change. One would have to read well into the section on macros to spot it, and indeed I did not do that. > What notification channels do you suggest are more appropriate for a > tool generating input for groff? My objection here is not primarily about notification, it's about the existence of the change at all. This is the type of backwards-incompatible change that I would hope that the maintainer of a package like groff for which backwards compatibility is so critical would not make. The contract that I would hope for is that existing documents that currently format correctly would not stop formatting correctly because I did not closely track the groff release notes, at least as long as they didn't rely on rather obscure edge cases. > 1. It relieves man(7) authors of having to undertake hacks to > "backspace" over the tag separation when they didn't want it, which > can (heretofore) be achieved only by inlining horizontal motion > escape sequences like `\h'1n'` or embedded ASCII BS (\010) > characters in the text stream, an obscure feature. > I noticed this problem in groff's own man pages; historically, it > appears in gropdf(1) and grops(1). (I didn't put it there.) I admit to being astonished that anyone would want their hanging tags to directly abut the paragraph text. In any event, in the tiny percentage of cases where people truly don't want any separating whitespace between the tag and the paragraph, *roff did already offer alternatives. I certainly wouldn't object to the an macros offering more, nicer alternatives. But this formatting change seems obviously incorrect for the vast majority of pages that it affects. > 2. It gives the `IP` and `TP` macros different reasons for existing > from a semantic perspective, a distinction that has been lacking in > the man(7) language. I understand the motivation for this change but I don't understand why it requires changing the formatting of .IP. >> Nothing about the handling of .IP has changed in podlators since 2001 >> and I don't remember encountering this problem before. It seems >> strictly worse than the previous behavior? > What's worse about it? You truly don't see what's worse about the output examples shown at the beginning of this bug? I find that difficult to believe. I consider those to be unacceptably mangled formatting. > No one is saying you have to do it. If Debian applies the workaround I > suggested and which Vincent passed along in comment #10, Debian's users > will never be exposed to the change. > https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1134776#10 > In your upstream capacity, you can point other distributors to the same > workaround, and/or advise users to raise their concerns on the groff > discussion list, where they'll be heard, as noted, co-equally with > everyone else. I'm responding here as the pod2man maintainer, not just for Debian. One of the design goals of pod2man has always been that the output function correctly as manual pages across a wide variety of systems. I didn't write or maintain the software specifically for Debian. (I have been maintaining it for considerably longer than I have been involved in Debian.) Yes, I could try to organize a collective reconfiguration of groff to undo this decision. This is something that I most certainly do not have time for, given that I've been struggling to put out podlators releases at all due to a large number of reasons too tedious to get into. I did consider putting an irritated note in the pod2man documentation and not otherwise changing its behavior, but while that would be somewhat emotionally satisfying, it wouldn't help any user and I'd probably feel bad about it in six months or so. > You can find the design sketch and discussion in the GNU coreutils > discussion list, whence it arose organically in response to a technique > involving the `PD` macro that Pádraig Brady was using to achieve > "compact list rendering", and which I had seen other seasoned man(7) > authors, like Chet Ramey, use. The `PD` technique is tedious and > error-prone. pod2man also uses .PD to collapse vertical whitespace for multiple consecutive item tags, which is important for clear formatting of many POD documents. That support has been present since October of 2000. Hopefully your mention that you are discouraging it does not mean that you are thinking about breaking it in some future version. If that happened, I would be quite irate. > I'd say it's not a semantic change because `IP` hasn't had a semantic > value to change, or impart. In applying your desired new semantic meaning, you changed the existing semantic meaning that authors were relying on. This is what the groff_man(7) documentation stated: .IP [tag] [indentation] Set an indented paragraph with an optional tag. The tag and indentation arguments, if present, are handled as with .TP, with the exception that the tag argument to .IP cannot include a macro call. .IP was clearly and explicitly defined in the groff documentation for authors as equivalent to .TP except for the restriction on macro calls. This is what the groff_man(7) documentation now says: .IP [mark [indentation]] Set an indented paragraph with an optional mark. Arguments, if present, are handled as with TP, except that the mark argument to IP cannot include a macro call, and the tag separation amount stored in the TS register is not enforced. .IP is now not equivalent to .TP and produces unacceptable formatting in the common case for nroff when the length of the tag is equal to the indent. This broke the formatting of a large number of documents. That is a semantically incompatible backwards change to the meaning of the .IP macro by any definition of those words that I recognize. You made the semantic change of making it no longer equivalent to .TP. > The change that prompted this Debian bug report is to > rendering/formatting. That is the entire raison d'etre of groff. All of groff's semantics are ultimately about rendering and formatting. That is literally the only reason why anyone uses the software. > What alternative do you propose? Adding yet another new macro seems > like a non-starter; we already have two for _almost_ the same purpose. > (Similarly, I find the presence of 3 synonymous paragraphing macros, > `LP`, `PP`, and `P`, an annoyance.) A new macro meaning "semantic tag > here" faces an immensely strong headwind: text discard by renderers that > have no definition for it. Yes, this is a good point; it's a hard problem. As someone who does *not* maintain a *roff to HTML converter, my preference is for a new macro. In my ideal world, someone would contribute pod2man support for various new macros that are already in groff, along with the necessary backwards-compatibility code in the preamble to define those macros if they aren't present on the local system. For example, I know the groff an macro set now has a way of correctly representing links to URLs, something that is defined semantically in POD but which is effectively discarded by pod2man right now because I have not had time to figure out how to use it in a way that maintains the current status quo for other *roff implementations. I would be very happy to review such changes. I realize, though, that this is not ideal for *roff to HTML converter maintainers since presumably no one or next to no one writes a full *roff language implementation. Instead, I assume most of them rely on ad hoc parsers that recognize known macros, and adding new macros in that way therefore runs the risk of breaking them rather badly. So I can understand why that approach may not always be appealing. My attitude towards this is heavily skewed by how I found out about it. If I try to discard that, I see the problem that you're trying to solve and I see the bind that you're in. If you had not changed the formatting of .IP, I don't think I'd have any fundamental objections. > Do you expect to ever stop emitting `IX` calls in podlators's man(7) > output? Why or why not? I have considered doing so multiple times, because so far as I'm aware no one is using them. I place an extremely high value on backwards compatibility, though (as you can probably tell), so I've stubbornly refused to remove them as long as they aren't actively causing any problems. I don't test that support except in the most superficial way, though, and I'm sure the semantics have bit-rotted because I don't think anyone is really trying to use them in earnest. Perhaps someone still is in the Perl community and I just don't know about it, though, which is also why I try not to break things unless I have a very good reason. A lot of people use Perl precisely because it is very stable and their existing code and workflows are very likely to keep working. I ignited quite the firestorm when I bumped the minimum required Perl version in podlators to a version of Perl released in 2010 from a version of Perl released in 2002. I thought (and still think) that I had a reasonably good justification for that change, but it brought home how cautious I should be as a Perl core package maintainer. > Again, as I noted, POD already tried, and apparently succeeded, at > solving this problem with all those `IX` calls No, definitely not. The very best that you can say about .IX is that at one point in the past it sort of worked for a very specific thing that Tom Christiansen was attempting to do, and I have kept the support on life support without knowing whether the results are still useful. In summary, my position is that the backwards-incompatible change to the formatting of .IP (and .TP, for that matter, although I have no current stake in that myself) should be reverted in the next release of groff. I don't believe this would interfere with your other goal of adding a semantic difference between .TP and .IP, whatever the merits of that goal. Past experience tells me this will probably not happen, plus there are released versions of groff for which pod2man output formatting is now broken. Therefore, I probably have to fix this whether I am grumpy about it or not. I see that in addition to changing from .IP to .TP, I also need to override the the TS register to restore the previous formatting behavior, since apparently that *also* changed in a backwards-incompatible way. That was immediately obvious when I tried to format the Pod::Man documentation with a patched pod2man that used .TP and got incorrect results. Is the TS register another one of these magic registers that I have to set after .TH because it gets reset every time .TH is processed, and therefore cannot be meaningfully set in the pod2man preamble? I hope that, at some point in the future, working around backward-incompatible changes in groff will be less of the work of maintaining podlators. I would love to collaborate on using new macros in a safe way and making other, more positive-looking changes, and not feeling grumpy and out of sorts because I'm picking up podlators just to get back to the previous status quo rather than improving it. -- Russ Allbery ([email protected]) <https://www.eyrie.org/~eagle/>
