Hi Russ, At 2026-07-11T08:58:35-0700, Russ Allbery wrote: > "G. Branden Robinson" <[email protected]> writes: > > At 2026-06-19T03:07:34+0200, Guillem Jover wrote: > > >> Hmm, this seems unrelated though? Or I don't understand the > >> relation between CW/CR and .IP? (Just in case, I tried to call > >> pod2man with --fixed=CR but that did not seem to fix this problem?) > > > There are multiple changes queued up in pod2man. Yes, the font name > > selection issue is separate from the indentation applied to > > paragraphs populated with the `IP` man(7) macro. > > I have not made any changes in podlators in Git related to the .IP > macro.
Acknowledged. > 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. https://lists.gnu.org/archive/html/groff-commit/2024-01/msg00148.html https://lists.gnu.org/archive/html/info-groff/2026-01/msg00000.html https://lists.gnu.org/archive/html/info-groff/2026-01/msg00001.html https://lists.gnu.org/archive/html/info-groff/2026-02/msg00000.html https://lists.gnu.org/archive/html/info-groff/2026-02/msg00001.html https://lists.gnu.org/archive/html/info-groff/2026-02/msg00002.html What notification channels do you suggest are more appropriate for a tool generating input for groff? An approach I am keen to avoid, but with which we are both familiar, is building a private, solicited, closed circle of "trusted" downstream maintainers and/or "stakeholders" who expect the groff maintainer to quietly seek their approval before making behavioral changes. While stratified governance models are common in FLOSS projects, the groff project does not operate that way. The groff discussion list has maintained a flat community of co-equal participants since May 1999. It is, I think, a proud tradition--one that I aim to preserve. Changes are debated openly, and all participants are heard on an equitable footing. > > The change in `IP` handling is known in _groff_ upstream, and > > documented in the groff 1.24.0 release notes. > > > NEWS: > > > * The an (man) macro package's `IP` macro no longer honors the > > formerly hard-coded 1n tag separation noted in the previous item. > > This means that the first argument to the `IP` macro can abut the > > text of the paragraph with no intervening space. If you use a > > word instead of punctuation or a list enumerator for `IP`'s first > > argument, consider migrating to `TP`. > > What was the motivation for making this change? 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.) 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. Any paragraph mark that one might use, such as `*`, `-`, `+`, or `(1)`, could be simply an item mark, or could have semantic meaning, with the former examples being especially common in documentation of programming languages or any tool that can evaluate arithmetic expressions. To date, in man(7), there has been no way at the lexical level to distinguish these. I admit I don't know how POD solves this problem for its own purposes when faced with `=over` and then `=item`, and the first item is a symbol that _looks_ like an enumerator or unordered list mark. Maybe you could tell me. If you expect the POD author to say `=item C<*>` instead of `=item *` to begin a list of language operators, then you are asking that author for the same semantic hint that I am. > 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? > > If by "upstream" you meant pod2man, it's worth exploring whether that > > tool is generating `TP` macros for things like definition lists, or > > `IP`. `TP` is a better choice and it is going to become increasingly > > important given changes expected in groff 1.25 and planned for the > > future. > > I suppose I can do this if I have to, 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. > but to say that I'm annoyed at being asked to change something that > was working fine because groff decided to break existing manual pages > is putting it mildly. I'm sorry to hear that. I've stated the objectives above. Ah, I see that you took note of them in a subsequent follow-up. I'll go ahead and quote that now. >> Schematically: > >> IP >> +-- ordered/enumerated list item (HTML: <OL><LI>) >> +-- unordered/marked list item (HTML: <UL><LI>) > >> TP >> +-- definition list item (HTML: <DL><LI>) > > [citation needed] The foregoing translation to HTML is not yet implemented, because grohtml(1) has proven challenging to work on. I hope to land the change in time for groff 1.26, scheduled for December of this year. The progress of this work is tracked in Savannah #68335. https://savannah.gnu.org/bugs/?68335 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. https://lists.gnu.org/r/coreutils/2026-05/msg00021.html > I have not seen any indication that the difference between .TP and .IP > has any semantic meaning in the documentation that I have previously > reason. That's because no such distinction has heretofore existed. There's been no way to express "this blob of text has inherent semantics and should be indexed and/or 'tagged' as a potential hyperlink destination". > It's of course possible that I have missed something along the way. No, not in this case. Just a point of evolution. > pod2man has used .IP exclusively since Tom Christansen's original > version in the 1990s, so the corpus of man pages that a semantic > change to .IP will break is not small. I'd say it's not a semantic change because `IP` hasn't had a semantic value to change, or impart. The change that prompted this Debian bug report is to rendering/formatting. > > On the bright side, I know of no man(7) generator that is so > > militant, so, with a _little_ adaptation on their part, we can more > > strongly semantically distinguish the purposes of `IP` and `TP`, and > > potentially reap rich rewards in improving the searchability and > > navigability of man(7) documents. > > I appreciate why you want to do this, but I'm not particularly > enthused about helping. Okay. > It seems like a hack. 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. > I have been headed in the opposite direction in general in pod2man > from hard-won experience: Do you expect to ever stop emitting `IX` calls in podlators's man(7) output? Why or why not? > removing attempts to guess at the user's meaning by imposing semantics > where there were no semantics in the original input, That's what this change attempts to do; by corraling non-semantic paragraph marks within the `IP` pen, and "meaningful" paragraph marks in the `TP` pen, groff man(7) encourages the author to _express_ what had previously been implicit and unreliably guessable. * This is a multiplication operator. * This is a paragraph bullet. > and accepting the limitations of the input method. People have been unwilling to accept the limitations of the man(7) format in this respect since approximately 1990, with 4.3BSD-Reno's mdoc(7) package. Sadly, for a variety of reasons, alternatives have failed to reach "critical mass". https://lore.kernel.org/linux-man/alFWqYWKJkQQxtJ6@devuan/T/#m9fda91ba28ca257c67d4595f81d38b32c5c9c937 Among the deepest of those reasons, one that has to date defeated any technology or tooling thrown at the problem, is that it's a huge challenge to get hackers to think in terms of semantic categories when they write documentation. "Vibe coding"--pattern-driven composition of program code--is not new, but an old phenomenon newly accelerated by LLM assistance. Asking hackers to apply semantic categories to the conceptual lexicon embodied by the code they've written is like asking them to red-team their own design. (Back when I worked at Progeny, developing our Debian-based distro, my friend and colleague Tim Ottinger labelled me "the lexicon guy" because I was always asking for meaningful labels we could apply to the notions our programming team came up with while prototyping.) One thing hackers _can_ do pretty reliably, though, is distinguish a "literal" from a "non-literal". Or, in this context, a "non-semantic" paragraph mark that is simply a bullet splat or list enumerator versus a semantically loaded integer like '128' or a multiplication operator that happens to be graphically represented by a bullet splat. Thus, from one digital bit of information--`IP` or `TP`?--we can leverage an advantage in semantic interconnect and document navigation. Again, as I noted, POD already tried, and apparently succeeded, at solving this problem with all those `IX` calls--but only for its own ecosystem, and not in a way that was generally leveragable via man(1) and the pager. I think the problem _can_ be solved at that level, and would like to do so. You do not have to help in this effort. POD already has something that works. But I think, with only a modest effort, non-POD man pages can enjoy the semantic advantage of POD's `IX` calls--and more. Regards, Branden
signature.asc
Description: PGP signature
