Hi Russ, At 2026-07-13T19:44:32-0700, Russ Allbery wrote: > "G. Branden Robinson" <[email protected]> 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
signature.asc
Description: PGP signature
