Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.bugs.dist > #1301235 > unrolled thread

Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages

Back to article view | Back to linux.debian.bugs.dist

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages "G. Branden Robinson" <g.branden.robinson@gmail.com> - 2026-07-09 17:40 +0200
    Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Guillem Jover <guillem@debian.org> - 2026-07-10 00:40 +0200
      Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages "G. Branden Robinson" <g.branden.robinson@gmail.com> - 2026-07-10 09:50 +0200
        Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Russ Allbery <rra@debian.org> - 2026-07-11 18:20 +0200
    Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Russ Allbery <rra@debian.org> - 2026-07-11 18:10 +0200
      Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Russ Allbery <rra@debian.org> - 2026-07-12 05:20 +0200
        Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Russ Allbery <eagle@eyrie.org> - 2026-07-12 21:20 +0200
          Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages "G. Branden Robinson" <g.branden.robinson@gmail.com> - 2026-07-12 22:30 +0200
            Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Russ Allbery <eagle@eyrie.org> - 2026-07-13 01:20 +0200
              Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages "G. Branden Robinson" <g.branden.robinson@gmail.com> - 2026-07-13 13:10 +0200
                Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Russ Allbery <eagle@eyrie.org> - 2026-07-14 04:50 +0200
                  Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages "G. Branden Robinson" <g.branden.robinson@gmail.com> - 2026-07-18 14:50 +0200
          Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Guillem Jover <guillem@debian.org> - 2026-07-13 04:30 +0200
            Bug#1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages Russ Allbery <eagle@eyrie.org> - 2026-07-20 06:50 +0200

#1301235 — Bug#1134776: Bug #1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages

[Multipart message — attachments visible in raw view] — view raw

[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:
> Control: affects -1 src:dpkg
> 
> On Thu, 2026-04-30 at 00:18:12 -0500, G. Branden Robinson wrote:
> > > Control: affects -1 fvwm perl-doc
> > > 
> > > Re-adding perl-doc.
> 
> 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).

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

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

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

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

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.

> What do you think Colin?

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

[toc] | [next] | [standalone]

#1301272

Hi!

On Thu, 2026-07-09 at 10:29:27 -0500, G. Branden Robinson wrote:
> At 2026-06-19T03:07:34+0200, Guillem Jover wrote:
> > 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).

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

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

[toc] | [prev] | [next] | [standalone]

#1301297

[Multipart message — attachments visible in raw view] — view raw

Hi Guillem,

At 2026-07-10T00:30:58+0200, Guillem Jover wrote:
> On Thu, 2026-07-09 at 10:29:27 -0500, G. Branden Robinson wrote:
> > At 2026-06-19T03:07:34+0200, Guillem Jover wrote:
> > > 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).
> 
> > 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.
> 
> 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:).

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.

> .IP \fBinstall\fR 4
> .IP \fBhold\fR 4
> .IP \fBdeinstall\fR 4

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

[toc] | [prev] | [next] | [standalone]

#1301418

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

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

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.

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

-- 
Russ Allbery (rra@debian.org)              <https://www.eyrie.org/~eagle/>

[toc] | [prev] | [next] | [standalone]

#1301416

"G. Branden Robinson" <g.branden.robinson@gmail.com> 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.
This is the first that I've heard of this backwards-incompatible change in
groff.

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

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

-- 
Russ Allbery (rra@debian.org)              <https://www.eyrie.org/~eagle/>

[toc] | [prev] | [next] | [standalone]

#1301451

"G. Branden Robinson" <g.branden.robinson@gmail.com> 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 (rra@debian.org)              <https://www.eyrie.org/~eagle/>

[toc] | [prev] | [next] | [standalone]

#1301559

Russ Allbery <rra@debian.org> writes:

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

-- 
Russ Allbery (eagle@eyrie.org)             <https://www.eyrie.org/~eagle/>

[toc] | [prev] | [next] | [standalone]

#1301572

[Multipart message — attachments visible in raw view] — view raw

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

[toc] | [prev] | [next] | [standalone]

#1301592

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

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

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.

> I don't share your assessment that it's "very common".

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.

-- 
Russ Allbery (eagle@eyrie.org)             <https://www.eyrie.org/~eagle/>

[toc] | [prev] | [next] | [standalone]

#1301652

[Multipart message — attachments visible in raw view] — view raw

Hi Russ,

At 2026-07-12T16:12:21-0700, Russ Allbery wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> > 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?
> 
> 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.

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

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

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

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

True.  Turns out, they're not the only things that are 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.

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

> > > 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".
> 
> It's certainly common in POD documents that I have written.

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

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

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:
> All of groff's semantics are ultimately about rendering and
> formatting. That is literally the only reason why anyone uses the
> software.

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

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

No, that's a mischaracterization.  I simply grepped the sampled
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

> None of my decisions would change based on whether it is statistically
> common,

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

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

...has not been productive, and wasted our time.

> since it's a pattern I want to support in pod2man.

Can you be more specific about _which_ pattern you want to support in
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.)

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

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

[toc] | [prev] | [next] | [standalone]

#1301739

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

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

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.

-- 
Russ Allbery (eagle@eyrie.org)             <https://www.eyrie.org/~eagle/>

[toc] | [prev] | [next] | [standalone]

#1302248

[Multipart message — attachments visible in raw view] — view raw

Hi Russ,

At 2026-07-13T19:44:32-0700, Russ Allbery wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> 
> > 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]
> 
> I don't think you understand why we keep having these conversations.

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

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

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.

> (b) My users noticed way before I did and reported that to me as a
>     bug.

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

> (c) I reached out to you to try to figure out what's going on and how
>     to fix it.

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

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

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.

> You think this is me being jealous of stylesheet-level issues or not
> wanting *readers* fooling with them?

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.

> I have been using the new version of groff for months and didn't even
> notice the change.

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

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.

> Don't blame me for your users not liking your changes, let alone imply
> it's some sort of power trip on my part.

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

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

> If you would stop doing things that people notice

...indeed.

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

> and consider broken, I would literally never notice and we would not
> be having these extended discussions.

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

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

I do strive for precision in my communications.

> You would make an excellent copy editor (meant sincerely, and
> complimentarily).

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

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

I understand.  Your time is yours to manage.

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

Thank you!

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

Acknowledged.

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

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.

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

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

[toc] | [prev] | [next] | [standalone]

#1301603

Hi!

On Sun, 2026-07-12 at 12:02:45 -0700, Russ Allbery wrote:
> Russ Allbery <rra@debian.org> writes:
> > 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 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

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.

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

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

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

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

[toc] | [prev] | [next] | [standalone]

#1302390 — Bug#1134776: groff-base: IP mark can directly abut paragraph text in groff 1.24+, breaking several man pages

Guillem Jover <guillem@debian.org> writes:

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

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.

-- 
Russ Allbery (eagle@eyrie.org)             <https://www.eyrie.org/~eagle/>

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.bugs.dist

csiph-web