After the upgrade of the groff packages from 1.23.0-10 to 1.24.1-1,
the output with the use of IP can be incorrect. This affects the
perlfunc(1) man page for 4-letter functions without an argument,
such as "fork" (this man page uses an indentation of 4 spaces).

Simple testcase:

With 1.23.0 (correct):

$ printf ".TH\n.SH D\n.IP fork 4\ntext\n" | nroff -mandoc
()                                                                          ()

D
       fork
           text

                                                                            ()

But with 1.24.1 (incorrect as there is no space between "fork" and "text"):

$ printf ".TH\n.SH D\n.IP fork 4\ntext\n" | nroff -mandoc
()                                                                            ()

D
     forktext

                                                                              ()

More generally, this is incorrect when the length of the mark is equal
to the indentation.

(removing the upstream tag because this will not change back upstream)

This also affects the Fvwm2Cpp(1) man page of fvwm:

     VERSIONThe X11 version.

     RELEASEThe X server release number.

     OPTIONSSome combination of SHAPE, XPM, NO_SAVEUNDERS, and Cpp, as  defined
            in configure.h at compile time.

As said on https://savannah.gnu.org/bugs/?68271 by G. Branden Robinson,
this was a deliberate change in groff 1.24.0, announced in the "NEWS"
file:

*  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`.

Until the various man pages are updated, G. Branden Robinson suggests
a change in "/etc/groff/man.local":

$ diff -u ~/groff-{1.24.1,HEAD}/share/groff/site-tmac/man.local
--- /home/branden/groff-1.24.1/share/groff/site-tmac/man.local  2026-04-23 21:40:05.057962304 -0500
+++ /home/branden/groff-HEAD/share/groff/site-tmac/man.local    2026-04-23 21:54:12.666452538 -0500
@@ -22,6 +22,9 @@
 .\" Set this register to configure which the `MR` macro uses.
 .\" .nr an*MR-URL-format 1
 .\"
+.am1 an*break-paragraph
+.  nr an*enforce-tag-separation 1
+..
 .\" Local Variables:
 .\" mode: nroff
 .\" fill-column: 72

Re-adding perl-doc.

Hi Vincent,

https://github.com/rra/podlators/commit/e099fdf3fa07014e3df6a476242e2484b577c3d1

Background:
https://github.com/rra/podlators/issues/43
https://github.com/Perl/perl5/issues/21239

Regards,
Branden

But it is not on CPAN yet. Then it would to have to go into perl,
then the Debian perl package would need to be updated.

Control: affects -1 src:dpkg

I had seen this problem as well with many dpkg man pages, but did not
have the time to check what might have regressed, now found this report.
After reading it, and checking further I guess this can happen as well
to any pod2man generated man page, for example as(1), or perl itself
in for example perlrun(1).

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?)

I tried my system pod2man with PERL5LIB pointing to the Pod modules from
git, and that didn't fix anything, so it appears like this is not fixed
yet (and might have never been reported upstream?), but maybe I botched
my testing process. I didn't see anything obvious related to .IP in
«git log» (besides the justification fixes).

So I think it would be nice to apply the man.local workaround posted in
this report to the Debian groff package, until at least pod2man has been
fixed and included as part of a Perl release in Debian? What do you
think Colin?

Thanks,
Guillem

[CCing Russ because a question about pod2man's generation of man(7) has
come up]

At 2026-06-19T03:07:34+0200, Guillem Jover wrote:

Yes, likely, until an updated version of pod2man percolates into Debian
unstable.

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.

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`.

(That text is already in this Debian bug's log as message #10 by Vincent
Lefevre.)

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.

NEWS:

*  The an (man) package offers new macros to ease the formatting of
   lists.  Enclose paragraphing macros between `LS` and `LE` to identify
   them as list items.  Doing so can mark them as "compact", ease
   management of their indentation, and supply hints to the output
   driver to improve their rendering (as with HTML).  Lists can be
   nested.  (Sub)sectioning macro calls, and the end of the document,
   close all open lists.  See groff_man(7) for details, and
   groff_man_style(7) for an example.

   Because these macros format no text, documents employing them risk no
   damage to their content if the formatter does not support them.  A
   man(7) document author can choose either to transition to these
   macros, to manage list "compactness" and item indentation with
   existing man(7) package facilities, or to employ both approaches.

The foregoing are completely optional extensions and can't break
anything (except document that already define their own page-local `LS`
and `LE`, macros--but I've never seen one that did that I didn't write).

An unscheduled future enhancement is to enable "automatic tagging" (in
the hypertext sense) of paragraph tags.  If all goes according to plan,
that feature, which should require no new macros or revision of any
man(7) document, will pay off the promise of the `IX` macro and enable
precise hyperlinking within such documents.  That is, at a granularity
finer than (sub)section headings.

For a glimpse of what is already possible, see
<https://lists.gnu.org/archive/html/groff/2026-07/msg00001.html>.

I don't have a good reference for the automatic tagging plans, as I
haven't come up with a précis for the feature yet.  Once I do I'll make
a Savannah ticket out of it.  For background, albeit one preoccuped with
groff internals and a spirited suggestion that groff not bother
implementing this feature because mandoc(1) already has it, see
<https://lists.gnu.org/archive/html/groff/2025-01/msg00082.html>.

In case it's not clear, I think that's a fine idea, having written the
workaround myself.  ;-)

As a GNU project, groff has no influence over pod2man's release
schedule, nor Debian's for staging transitions into its unstable suite.

I _do_ hope to release groff 1.25.0 this calendar month, but Colin knows
how (un)reliable I am at precisely hitting planned release dates, so my
estimate should be taken with a grain of salt.

Here are my most recent status updates.

https://lists.gnu.org/archive/html/groff/2026-06/msg00017.html
https://lists.gnu.org/archive/html/groff/2026-07/msg00001.html

If I'm not too far off this time, coalescing that patch with the 1.25.0
packaging work might mean fewer context switches on the human side.

Regards,
Branden

Hi!

Ah, sorry, indeed by "upstream" I was referring here to podlators.

Checking briefly now, I see multiple instances of «.IP». For example for
dpkg.pod, the source is:

,---
=head2 Package selection states

=over

=item B<install>

The package is selected for installation.

=item B<hold>

A package marked to be on B<hold> is kept on the same version, that is,
no automatic new installs, upgrades or removals will be performed on them,
unless these actions are requested explicitly, or are permitted to be done
automatically with the B<--force-hold> option.

=item B<deinstall>

[…]
`---

And the generated troff is:

,---
.SS "Package selection states"
.IX Subsection "Package selection states"
.IP \fBinstall\fR 4
.IX Item "install"
The package is selected for installation.
.IP \fBhold\fR 4
.IX Item "hold"
A package marked to be on \fBhold\fR is kept on the same version, that is,
no automatic new installs, upgrades or removals will be performed on them,
unless these actions are requested explicitly, or are permitted to be done
automatically with the \fB\-\-force\-hold\fR option.
.IP \fBdeinstall\fR 4
.IX Item "deinstall"
[…]
`---

With the rendered output from man being:

,---
   Package selection states
     install
         The package is selected for installation.

     holdA package marked to be on hold is kept on the same version, that is,
         no automatic new installs, upgrades or removals will be performed on
         them, unless these actions are requested explicitly, or are permitted
         to be done automatically with the --force-hold option.

     deinstall
`---

Branden I guess you are in a getter position to file a bug to podlators
upstream, having more details and knowledge on the matter, but if you
are short on time, I could try to concoct some report (where I'll need
to read about the fine details about this I guess, which I've kind of
skipped up to now O:).

Thanks,
Guillem

Hi Guillem,

At 2026-07-10T00:30:58+0200, Guillem Jover wrote:

Right.  I'll await guidance from Russ for the time being, but I have
some really good news.

perlpod already applies semantic analysis (DWIM) to the argument of its
`=item` command/directive/declarator.

     "=over indentlevel"
     "=item stuff..."
     "=back"
         Item, over, and back require a little more explanation:
         "=over" starts a region specifically for the generation of a
         list using "=item" commands, or for indenting (groups of)
         normal paragraphs.  At the end of your list, use "=back" to end
         it. ...  In the stuff in "=item stuff...", you may use
         formatting codes, as seen here:

           =item Using C<$|> to Control Buffering

         Such commands are explained in the "Formatting Codes" section,
         below.

         Note also that there are some basic rules to using "=over" ...
         "=back" regions:

...
         •   And perhaps most importantly, keep the items consistent:
             either use "=item *" for all of them, to produce bullets;
             or use "=item 1.", "=item 2.", etc., to produce numbered
             lists; or use "=item foo", "=item bar", etc.--namely,
             things that look nothing like bullets or numbers.  (If you
             have a list that contains both: 1) things that don’t look
             like bullets nor numbers,  plus 2) things that do, you
             should preface the bullet- or number‐like items with "Z<>".
             See Z<> below for an example.)

So despite the fact that I'm a bad person and didn't dig deeply into
perlpod before making the change to groff man(7)'s `IP` behavior,
this is a striking case of convergent evolution--I suspect because
typography has strong, stable, and longevous conventions.

perlpod _already_ parses the argument to `=item` for a "type": ordered/
enumerated, unordered/marked, or definitional.  This trichotomy maps
perfectly to HTML, of course, and to the forthcoming groff 1.25's new
"advisory" `LS`/`LE` macros.  The original man(7) language of 1979 did
not employ the same trichotomy, but, blissfully, organized a dichotomy
such that ordered/enumerated and unordered/marked lists were not
distinguished--I suspect because there was no point, as the macro
package did not maintain registers to manage list enumerators.  McIlroy
might have thought it unnecessary for man(7) (and indeed you don't often
see it), even though such a feature was present in ms(7) at least as
early as Sixth Edition Unix (1975).

Schematically:

IP
+-- ordered/enumerated list item (HTML: <OL><LI>)
+-- unordered/marked list item (HTML: <UL><LI>)

TP
+-- definition list item (HTML: <DL><LI>)

Further, it was straightforward, before the advent of "man2html" tools
that reconceptualized man(7) as a declarative or markup language rather
than a layer of macros atop a Turing-complete language, to "punch
through the floor" and use raw *roff requests to set up registers to
automatically increment the marks of an enumerated list oneself.

Thus, if my analysis is correct, the groff 1.24 change to man(7)'s `IP`
macro indentation does not require _much_ of a change to perlpod
interpreters--indeed, if we take the foregoing as a specification, an
implementation might already be producing man(7) documents in the manner
I recommend.  Because `TP` is strictly more flexible than `IP`, I can
imagine a perlpod interpreter that never generates `IP` calls at all.

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.

One of the possibilities we've discussed on the groff list is supporting
a rendering-time option so as to generate a ctags(1)-compatible tags
file when rendering man pages.  A man(1) program could then pass that
tags file's name to less(1)'s `-T` option.

https://lists.gnu.org/archive/html/groff/2025-01/msg00108.html

Anyway, my suggested prescription for perlpod interpreters is simple:

If perlpod decides the `item` is bulleted or numbered, generate an `IP`
call; otherwise generate a `TP` call.

As seen above, pod2man (or some module it uses) already explicitly
declares a paragraph indentation.

For enumerated and marked lists, 4 ens should be plenty.  I've never
seen a man page that had more than 99 items in an enumerated list (which
is 3n wide including a trailing dot), or used a mark wider than 2n (an
em dash on a terminal).

I'm hopeful that Russ can correct any misconceptions I've stated above.

Regards,
Branden

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

I have not made any changes in podlators in Git related to the .IP macro.
This is the first that I've heard of this backwards-incompatible change in
groff.

What was the motivation for making this change? 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?

I suppose I can do this if I have to, 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.

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

[citation needed]

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.
It's of course possible that I have missed something along the way.

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 appreciate why you want to do this, but I'm not particularly enthused
about helping. It seems like a hack. I have been headed in the opposite
direction in general in pod2man from hard-won experience: removing
attempts to guess at the user's meaning by imposing semantics where there
were no semantics in the original input, and accepting the limitations of
the input method.

Hi Russ,

At 2026-07-11T08:58:35-0700, Russ Allbery wrote:

Acknowledged.

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.

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.

What's worse about it?

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 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.

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

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".

No, not in this case.  Just a point of evolution.

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.

Okay.

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.

Do you expect to ever stop emitting `IX` calls in podlators's man(7)
output?  Why or why not?

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.

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

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

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.

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.

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.

I understand the motivation for this change but I don't understand why it
requires changing the formatting of .IP.

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.

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.

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.

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.

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.

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.

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.

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 <rra@debian.org> writes:

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

The timing for the upcoming Perl release is as bad as it possibly could
be, which is my fault for sitting on a new release for too long. (I'm
sorry about that, Guillem; I did see your bug report but didn't have a
chance to address it until now.) I am hesitant to make a release today
without some confirmation that the fix appears to be correct, but I will
try to make one very soon since there are a large number of other
accumulated fixes that I have been sitting on.

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.)

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 think
you should therefore also override the TS register to set it to 1n, thus
restoring backward compatibility with previous versions of groff.

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'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.

That's true.  I'm attaching a patch to the man page against stock groff
1.24.1.
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.

If the Debian package does this, it should update the man page
accordingly.

Regards,
Branden

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

Yeah, you shot yourself in the foot with that one, and I don't see an easy
way for you to repair the damage given that groff 1.24 is already out in
the wild. If you had not chosen to change the default tag separation for
.TP, I wouldn't have needed to override it, and thus your reader
configuration desire could have been achieved. I would be happy to support
user configuration, but not at the cost of backward compatibility.

(As we've previously discussed, hyphenation and adjustment are a harder
problem because in those cases pod2man already had a long-standing
practice of changing the default back when end-user configuration was not
supported, and finding a way to support both, and all of the
already-released versions of groff, is complex.)

Perhaps a lesson for the future is that if you want to make something
user-adjustable, it is crucial that you not also change the default at the
same time and thus leave document authors no choice but to ignore
groff_man(7) and override the default if they want to preserve the
existing rendering of their document as the default.

It's certainly common in POD documents that I have written. I did indeed
not check to see if other people followed me in that and perhaps they do
not anywhere near as much as I thought. I will note that this change broke
the formatting of literally the first POD document I looked at (Pod::Man's
own manual page), but of course that document was one I wrote.

Your search methodology would not have caught this because it uses tags of
three characters with an indent of four.

None of my decisions would change based on whether it is statistically
common, since it's a pattern I want to support in pod2man. Colin can
certainly make an independent decision about whether this is relevant to
the configuration of the Debian groff package; my belief that it is common
is just guesswork, and perhaps most cases of this are via POD documents.

Hi!

Great, thank you! I've built the dpkg man pages using podlator's HEAD,
and the =item issues have disappeared now. I checked also for items with
bullets and numbers and they look good to me. Also for =over with
different indent levels (2 and 4). I did a quick scan over a couple of
man pages and didn't see anything obviously wrong, but I didn't do a
detailed rendered diff against a previously working groff version.

Hey, no problem! I know how that is. :)

I can perform more checks tomorrow, if that would be more reassuring,
but I'm not sure I'd be covering all the tricky details you might be
concerned about.


I also have to say I found it a bit surprising that these breaking
changes went into groff, when from what I think I've seen in other
instances, behavior from very ancient and no longer supported historic
version of roff/troff seem sometimes to be used as rationale for current
suboptimal behavior (?).

In any case, thanks Russ for fixing the fallout, even if you perceive
you are otherwise not making other progress. This is still highly
appreciated!

Thanks,
Guillem

Hi Russ,

At 2026-07-12T16:12:21-0700, Russ Allbery wrote:

Hmm.  F*** me, then, eh?

I saw "too many" man pages where a tagged paragraph (`TP`) was
indistinguishable from a hanging paragraph (`HP`) because, if the tag is
just the right size, exactly one space separates the first word from
the rest of the paragraph.

One might point out that by also un-deprecating the original 1979 man(7)
`HP` macro, which groff_man(7) had discouraged users from using for
about 15 years, I was needlessly entangling those issues, and should
have left `HP` deprecated for another release, or N years, or so.

But `HP` turns out to be useful if you want to set a command or function
synopsis and also not to embrace the groff_man(7) extensions for doing
so, `SY`, and `YS`.  (Because your man pages need to be portable to
Solaris 10, for example.)

I had a user who was actually communicating with me and was expressing a
historically consistent use case I wanted to support.

https://lists.gnu.org/archive/html/bug-findutils/2025-12/msg00009.html

True.  Turns out, they're not the only things that are complex.

That's one potential lesson.  Another is that maintainers of
man(7)-generation tools are jealous of "stylesheet"-level issues, and
don't want readers of man pages fooling with them.  I imagine that
highly paid web site designers feel the same way about Stylus...[1]

For context in the next point, I'll need to restore some quoted
material from comment #82...

I'm confused because what I was replying to was your statement that "POD
documents are unaffected, since pod2man has always used .IP".

This bug report is about groff's `IP` macro changing to _not honor tag
separation_.  How did the tag separation _amount_ change break
Pod::Man?

As you noted, there were multiple changes here:

* The tag separation became user-customizable via the `TS` register;
* `TP` imposes the amount in `TS` as a minimal separation between its
  "tag" and the paragraph indentation;
* `IP` does not enforce "tag separation" (because its "mark" argument is
  not a "tag"), but historically did enforce what we might call a "mark
  separation" of 1n; and
* I changed the tag separation amount from 1n to 2n.

All of these, I documented in the "NEWS" file--but, as we've
established, people won't type "/man" in their pager to see if any
changes affect the man(7) package, even if they consider themselves a
man(7) stakeholder.  It seems I have to flag something as a "Noteworthy
incompatible change" to get their attention.  But that, as it turns out,
is pointless:

As you said in comment #77 to this bug:

...so all changes that affect output _in any way_ are "noteworthy
incompatible changes", and we're back to the problem of people having
too much to read, and skipping it, effectively boycotting the feedback
process that release candidates are made to stimulate.

I have my own classification scheme that I apply to groff, since it's a
complex system of several component parts. It also implements a
Turing-complete language (*roff itself) and multiple other language
substrates: eqn(1), pic(1), and the macro languages of several macro
packages, one of which, mdoc(7), implements its own macro processor on
to top of *roff's.

You can find that classification scheme on the GNU Savannah site.

https://savannah.gnu.org/bugs/admin/field_values.php?group_id=273&field=bug_group_id&list_value=1

As shown there, I distinguish "Incorrect behavio(u)r", where a component
violates _documented_ norms, from "Feature changes" which warrant "NEWS"
items, and both of these from "Rendering/cosmetics" issues where "output
... is ugly ... but not incorrect and not misrendered such that
comprehension is defeated."

I observe that permitting confusion of `HP` with `TP` paragraphs _does_
risk defeating comprehension.
documents for `IP` and `TP` calls, with complete indifference to their
arguments or the width of their "marks" or "tags".  I'm attaching those
raw results for your edification.

I produced them with:
$ zgrep '^\.[IT]P' $(<ATTIC/SAMPLE ) > /tmp/sample-ip-tp.txt

Okay.  Then I suggest that the popularity-based argument you pursued in
comment #82:

...has not been productive, and wasted our time.
pod2man?  Are you concerned more with the selection of man(7) macros and
the sizes of tag separations in ens, or are you concerned more with:

* distinguishing "marks" (paragraph annotations that don't get `IX`
  calls emitted for them) from "tags" (ones that do, and have semantic
  value because they're things like syntax keywords that people want to
  look up);
* keeping marks from abutting paragraph text;
* permitting marks to abut paragraph text where desired; and
* ensuring that tags are always separated from paragraph text?

Attend to the phrasing of my question: I present not an all-or-nothing
dilemma, but an invitation to express preference or priority.

(I include the third item for completeness; I note that you already
assigned it zero weight, with astonishment, in comment #77, though you
there said "tags".  Under my nomenclature, I agree regarding "tags" but
not regarding "marks", since I saw "abutting marks" in the wild,
employed in groff's own man pages years before I ever contributed to
that project.)

Well, if you change your mind about the worth of more rigorously
sampling the space of actually existing documents to discern real-world
usage patterns, I shall remain

Your humble servant,
Branden

[1] https://chromewebstore.google.com/detail/stylus/clngdbkpkpeebahjckkjfobafhncgmne?pli=1

Hi Guillem,

At 2026-07-13T04:20:00+0200, Guillem Jover wrote:

I pursue several goals that don't always militate action in the same
direction:

* I seek consistent language syntax and semantics.
* I seek not to alter the behavior or rendering of documents relying
  upon _documented_ interfaces and/or behavior.
* I seek to solve problems that have historically gone unsolved by *roff
  systems, increasing the appeal and utility of the system to existing
  and (potentially) new users.

Here are examples from the forthcoming groff 1.25 release that
highlight how these objectives can be in tension.

(For what it's worth, I don't expect these to affect any documents in
the global corpus of man pages.)

*  GNU troff, the formatter, now employs the unusual Roman numerals "W"
   and "Z" of AT&T troff only in compatibility mode.

*  The `dt` request, when given invalid arguments, now does nothing
   instead of removing any existing diversion trap.  This change is
   inconsistent with AT&T troff but more consistent with general *roff
   syntax; as a rule, requests given invalid arguments (and that don't
   process a list of similar objects, as `rm` and `rr` do) perform no
   operation.

*  The `dt` and `wh` requests now enforce their requirement of space
   between their arguments.  While consistent with GNU troff input
   syntax, [said enforcement] is not consistent with AT&T troff.  We did
   not add support in groff's AT&T troff compatibility mode because
   we're aware of no legacy documents that require it.  Example:
   `.wh9i+.5+\n(xxuPT` is, while validly planting a trap for the `PT`
   macro in AT&T troff, an input considerably more cryptic than any
   specimens known to us.

I've never seen a man page that assigned a Roman numeral format to a
register, though I'd bet that a few exist.  I'd bet money, though, that
they don't use such registers to represent magnitudes greater than 3,999
decimal.  My supposition is that the Bell Labs CSRC innovated these
additional Roman numerals so that they could represent the full range of
values of the PDP-11's 16-bit machine registers (to which troff's
registers ultimately mapped) without having to perform a range check if
the troff register's format was Roman.

Similarly, I've yet to encounter a man(7) document that messes with
diversion traps (`dt`) or setting up its own page location traps.
man(7) authors don't tend to (directly) employ diversions at all, and
employing page location traps when a full-service macro package like
man(7) already handles them can be a tricky business--one that requires
awareness of that package's internals.

I strive to make groff operate consistently with AT&T troff behavior and
especially to avoid crashing or abandoning rendering when a concrete
ancient document of which we have a specimen does something surprising.
Our development team intentionally evolves novelties like PDF,
hyperlink, and OSC 8 terminal escape sequences to improve the user
experience.  Usually these two goals are not in conflict.  Sometimes,
however, friction arises when their implementations come into contact.

I feel certain you've faced such challenges in maintaining dpkg.

To get back to broader concerns, balancing the competing pressures of
the goals I've selected for my groff work is a matter of judgment.
Being a human of finite intelligence and insight, my judgment is
reliably going to differ from that of others from time to time.

As I said earlier, I've been as transparent with changes to groff as I
know how to be.  I ask users who care about what groff does and who are
sensitive to change to pay attention and engage our development
community where they feel intervention is warranted.

For general edification, I'm attaching a 2-page PDF of the original
man(7) macro package "spec"--the original man(7) page by McIlroy from
Volume 1 of the Seventh Edition Unix Programmer's Manual.

groff_man(7)'s specification of package behavior is far more detailed.

Regards,
Branden

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

I don't think you understand why we keep having these conversations.

Apart from one thing I noticed while I was still reading the groff list,
and which you convinced me didn't affect as many man pages as I had
thought, every time we've had one of these chats, it's because the
following sequence of events have happened:

(a) You made some change to how man pages are rendered that broke
    something people cared about.
(b) My users noticed way before I did and reported that to me as a bug.
(c) I reached out to you to try to figure out what's going on and how to
    fix it.

This *keeps happening*, which is why you're getting a more and more blunt
version of me each time it happens.

You think this is me being jealous of stylesheet-level issues or not
wanting *readers* fooling with them? I have been using the new version of
groff for months and didn't even notice the change. I got involved because
it broke things for other people who use pod2man, who then reported it to
me. Those are the writers and readers of the documents your software is
formatting, go argue with them. Don't blame me for your users not liking
your changes, let alone imply it's some sort of power trip on my part.

I am not objecting to *readers* of man pages fooling with them, I am
objecting to *you* fooling with the rendering in ways that my users
consider to be bugs. If you would stop doing things that people notice and
consider broken, I would literally never notice and we would not be having
these extended discussions.


In any case, we've now reached the point where I can either argue with you
in detail or maintain podlators but I literally don't have enough hours in
the day to do both.

I honestly regret that because, despite my tone, I do like these
conversations, at least in part. Every time we have one, I learn
something, and in the right mood it's sort of enjoyable to play the game
of "can I write a message phrased carefully enough that Branden can't find
sloppy wording to object to." You would make an excellent copy editor
(meant sincerely, and complimentarily). But every one of these discussions
takes me at least ten hours, and right now I simply do not have another
ten hours to spend.

So, here's what I'm going to do:

I'm reverting the change to podlators to override the TS register and
changing the relevant block in the Pod::Man documentation to =over 5 for
several reasons:

1. As a gesture of good will because I really don't want to be fighting
   with you, and I do want you to feel like I respect your technical
   judgement (because I do!).

2. After looking at the rendering of perlfunc, I see your point about
   hanging paragraphs and agree that it's at least arguable that the
   current approach is *too* cuddled.

3. None of my users have complained to me about this yet (because they've
   not been exposed to the new behavior yet). It's just something I
   noticed while switching from .IP to .TP, so I am in that sense
   borrowing trouble, and I don't want to do that.

The tag spilling is minor and arguably more correct in at least some
cases, so I'll document this in the Changes and see if anyone notices or
objects. If no one does, great! If they do, I'll decide then whether the
right thing for me to do is to override the default or do something else.

After I get done with that, I'll release the new version of podlators and
then see about getting it into Perl. I don't know when that will happen,
and when that version of Perl will get into Debian, so that doesn't
immediately resolve this bug. But that's all that I can do, at least at
the moment, to try to push it towards a resolution.

Hi Russ,

At 2026-07-13T19:44:32-0700, Russ Allbery wrote:

I think you underestimate me, but I guess third parties will have to
judge the issue.

s/broke/changed/

There's no need to put a thumb on the scale here.  Users will notice
differences/changes.  Those changes aren't always "breakage".  Sometimes
the question of "breakage" is arguable and sometimes it isn't.

However, people tend not to go out of their way to thank developers for
implementing a noticeable change that is a bug fix, except sometimes
when they were involved with reporting the bug in the first place.

Right.  I think it's premature to assume the presence of a _defect_ at
that point.

Right.  But when reaching out, you often seem to me sufficiently
aggrieved by the tax levied on your limited time for dealing with
podlators issues that you prejudge any _change_ your users notice in
_man_(7) rendering as a _defect_.

Gradualism is not necessary with me.  Be completely frank with me from
day one.  If you're furious and hide it, I'm unlikely to calibrate my
response in a manner that you find satisfactory.

(I could still fail to calibrate sufficiently _anyway_, but the fault
would be more mine than yours.)

I regret that Debian's social culture has programmed its participants to
favor passive aggression and superficial performances of decorum.  These
practices promote the confusion and commingling of subjective emotional
matters with empirically measurable phenomena, and drive a stake into
the heart of egoless programming.

I hereby pledge not to report you to the Community Team for being blunt.

Well, _someone_ is.  Your users, I guess.  Consider the possibility that
their interests are not 100% aligned with yours.  That's a problem all
maintainers have.  Not all of our users want mutually compatible things
from the software system.

That's valuable information!  Certainly to me, but I suggest that it
could be to you, too.  That datum can inform the weight you give the
matter.

I'd say it's more your responsibility to direct people complaining about
groff issues in poldators forums to groff than it is mine to hunt them
down and confront them.

Moreover, I expect to practice reciprocity here; if a person
discontented with a pod2man(1)-generated man(7) page complains to the
groff list or our Savannah bug tracker, and upon investigation I find
that podlators is doing something bizarre or unsupported, I'll write up
a technical summary and do the meatspace/upstream equivalent of
"reassigning" the bug to podlators.

Likewise, don't feel compelled to adopt the irritated affect of your
users when they become cross with changes that are of sufficiently low
impact that you didn't notice them yourself.

Here's an example of a groff man(7) change in 1.24.0 that _could_ have
drawn annoyed comment by people who expect byte-precise immutability of
terminal rendering from groff release to release.

*  The an (man) and doc (mdoc) macro packages now support a `BP`
   register to configure the ("base") paragraph inset amount; that is
   the amount used by man(7) for paragraphs not within an `RS`/`RE`
   relative inset, and in mdoc(7) for all paragraphs.  Formerly, the
   `IN` register configured this amount with other indentation and inset
   amount parameters used by man(7).  (In mdoc(7), it had no other
   purpose.)  The base paragraph indentation default is now 5n,
   corresponding to that used by historical man(7) and mdoc(7)
   implementations going back to Unix Version 7 (1979) and 4.3BSD-Reno
   (1990), respectively.

Since this change affects _every rendered man page_, if one regards it
as a defect, it must be a critical one.  (And yet one would not apply
that same reasoning to James Clark's decision circa 1989 to implement a
different base paragraph inset amount from every other man(7)
implementation then in existence, including the SunOS system upon which
he modeled his reimplementation's behavior.  Some groff maintainers get
to make changes, it seems, and some don't.)

Fortunately, except for mandoc(1)'s test suite, which was crafted when
groff development was nearly moribund and gambled on its
stagnation[1]--the plan was to utterly displace groff as a man page
renderer after all[2]--no one has proven that hypersensitive.

Yet.  Knock wood.

I recommend that you shove such issues off your plate as quickly as
possible.  It is not necessary to appoint yourself your users' attorney.
You can say something as simple as:

"I checked, and the difference in output is not the result of any change
in podlators.  I see you're using groff to render man pages.  Please
take your concern to the groff mailing list or its bug tracker."

...indeed.

Your advice rhymes with that of the God Entity from _Futurama_.  ;-)

Then let _me_ have that discussion with them.  You might have noticed
that I tend to document my rationales for changes I make.  It's
reasonable to expect me to be prepared to defend my changes to your
users.  If I can't, then they've caught me out, and I might have to
revert or update the change I've made so as to better reflect users'
environments or their needs.

When your users report a problem to you that is not your responsibility,
_take the opportunity to disintermediate yourself_.

I sympathize with the feeling of being stretched thin.  I've been
burning much oil trying to get issues knocked out so I can tag groff
1.25.0.rc1.

I do strive for precision in my communications.

Every time I start to think so, I find errors in my own output that
restore my humility.

I understand.  Your time is yours to manage.

Thank you!

Acknowledged.

Completely fair.  Consider the groff list a resource for consultation;
from what I've seen, people are pretty good about honoring requests to
be CCed.  I'm very far from the sole authority there--we have
participants who are trained and experienced typographers.  I'm just a
Unix nerd.

Yes.  All you can do is build it.  How quickly the people arrive to
enjoy it depends on how high Kevin Costner's star is in the celebrity
firmament from day to day.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2026-02/msg00067.html
[2] https://www.openbsd.org/papers/bsdcan15-mandoc.pdf

Guillem Jover <guillem@debian.org> writes:

Thank you very much for the testing!

I have finally found a few hours to turn the release crank, and podlators
v6.1.0 is now out. I've notified perl5-porters for integration into Perl
core.