on project management (was: the Linux man-pages as an educational tool)

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 9536 bytes --]

[looping in groff list because toward the end of this mail I present
some philosophy that I have applied to my work on that project]

Hi Alex,

At 2026-08-03T01:37:26+0200, Alejandro Colomar wrote:
> > Date: 2026-08-02 16:27:21-0700
> > From: Collin Funk <collin.funk1@gmail.com>
> > I can't help but wonder of what happens in WG 14 rejects this
> > controversial, as obvious by this thread, change. Will the man-pages
> > changes be reverted? Or will we slowly watch them document personal
> > preferences instead of existing standards?
> 
> This patch set is quite independent of the standard.  It documents a
> header file that has been provided since forever in glibc and most
> other POSIX-ish systems,

Just yesterday while watching an ncurses build scroll by on my tablet, I
had occasion to notice that Bionic libc provides a "memory.h" header.
Curious, I checked it out.

It's a thin wrapper for <string.h>.

I endorse your reformist attitude because every technological success
story begins ossifying as soon as its market position can be milked for
economic rent.  As the old Demotivator poster said of consulting: "If
you're not a part of the solution, there's good money to be made in
prolonging the problem."[1]

Thus trigraphs.  Thus K&R function declarations.  Thus "wastebasket
taxon" header files.

> so changes to the standard are unlikely to have any effects.  I've
> clarified this extensively.  If you want to discourage me from
> applying the change, you should rather bring up technical reasons.

I don't think Collin's totally off base.

What is the overall mission of the Linux man-pages project as you
conceive it?

Take some time to draft one, if you haven't already and I missed it.
Here are some points you might consider.

*  Is delivery of factual information more or less important than
   advocacy of correct methods and accepted idioms?

*  If the foregoing are equally important, are you _sure_ they need to
   be?  Can you escape dilemmas that frustrate day-to-day stewardship
   work by favoring one over the other?

*  If you maintain that the two are equally important, nevertheless, how
   do you resolve conflict?  Disclose the principles you employ to
   decide such issues, and write them down where people can find them.
   That way they can better understand why you reason the way you do,
   and you bind yourself to those principles, so that you and others are
   less seduced by the urge to "shift the goalposts" in a dispute.

> This passive-aggressive message is not something that will have the
> desired effects you could possibly reach with technical arguments.

I'd say less that it was a passive-aggressive message than that it was a
deployment of a slippery-slope argument.  Fallaciously?  I don't know.

But it is also true that people are pushing back on your proposals
regarding reënvisioning of libc's memory buffer and string APIs from two
fronts.  Only one is technical.  The other is managerial.

As a maintainer, your role is to serve your community.  This is a
privilege and a responsibility.  Generally, one is accepted in that role
because one has demonstrated a high level of expertise and sufficient
resources to carry out the tasks the role requires.

Someone earlier in the thread made reference to the personage of past
glibc maintainer Ulrich Drepper, whose maintainership of glibc came to
an unhappy end.  Anyone who'd deny that Drepper was a world-class domain
expert or diligently applied himself to his work, I would not take
seriously.  Apart from glibc maintenance, he wrote some excellent papers
on dynamic shared objects and on the nature of the memory abstraction in
Unix and Unix-like systems.  (Since the latter paper got so deep into
the topic of cache memory architecture, I'd venture it applies more
broadly still.)

I reiterate: world-class.  Any engineer in this space who doesn't read
Drepper disserves themselves professionally.  His stuff is up there with
Goldberg's 1991 paper on floating-point arithmetic, in my opinion.  Even
if you don't 100% digest what these people have to say, they'll improve
your thinking, because you'll become more familiar with the problem
domain.  (And if you disagree with them and can back up your claims,
start writing a paper of your own.  That's where the confidence one
manifests in the Google interview or break room evaporates.)

So how does a guy like that get himself into trouble as a maintainer?

By persistently failing to attend to the demands/needs of the community
they serve.

Listen to your users.  Even if they're "wrong".

Here's how I apply the foregoing mode of analysis to my own work.

I've occasionally ruffled feathers by changing defaults in groff.[2]  I
_think_ that I have kept myself from being deposed by the sans-culottes
by going well out of my way to ensure that configuration knobs are
available to override those defaults, to document not just their
substance but their rationale, and to present examples in a
configuration file in /etc/groff so that all people have to do is
uncomment something to override my contemptible idiocy.  (Eventually,
some learn the hard way why I made my choice.)

Frequently, I pitch potentially disruptive changes--stuff that we'd
report in the "NEWS" file--as an email to the groff list with
"Proposed:" in the Subject line.  More often than not, what I suggest
involves such an esoteric detail of formatter behavior that I get no
feedback at all.  Few have mastered such oddities as diversion trap
management, to name an example of something that's moving a little bit
in groff 1.25 and might, theoretically,[3] break some old AT&T troff
documents (but none written targeting GNU troff itself).

But I also have a counterexample.

2 release cycles in a row, in anticipation of groff 1.24 and 1.25, I've
pitched a small redesign of GNU troff such that the configured
hyphenation language--basically, the set of patterns used for automatic
hyphenation of words, which are locale-specific (English, French,
German)--is a property of the environment, like all other hyphenation
configuration parameters, rather than a global one.

Twice in a row, one person has spoken against the change--it _would_
require changes to some macro packages.  That person is Peter Schaffter,
author of mom(7), a macro package that shows off GNU troff's
capabilities as a typesetting system better than any other.

I haven't yet managed to make a concrete case to him strongly enough to
persuade him that the objective is worth the candle.

Now, I'm dead certain that my proposal is the correct course from a
software design perspective.  It's a Yourdon/Constantine "cohesion"
no-brainer.

But, because environments are formatter-level objects, such a change's
impact is not limited to internal data design.  It affects the language,
and I have users.  So, I've interpreted Peter's objection as a
procedural veto.  Rhetorically, he hasn't been so strident.  What I
infer is that I need to spend time coming up with one or more concrete
exhibits to establish the benefit of the change.  I have an idea for
what would do it: a multi-lingual document, say an mm(7) document where
most of the body text is in English but the document uses the package's
"bottom block" `BS` and `BE` macros to present at the foot of every page
some kind of disclaimer in, for instance, French.

Just articulating the idea isn't enough.  Given the unusual resistance
on this point, and recognizing the general indulgence shown by the
community toward my madcap reformist schemes as something I'd be wise
not to squander, I've decided what I need to do is build a real document
with a real macro package, and illustrate what changes to that package
would be necessary to fulfill the promise of the redesign.

I expect the disruption level to be low and the benefit to be high--for
its applicable problem domain.  The potential impact either way is
limited because multilingual documents are simply not common.

Because groff's community is small, I interpret a single dissenting
voice as putting consensus out of reach.  It helps in this case that the
single dissenting voice is a known member of the community.  If our
mailing list suffered from anonymous drive-by trolls, I'd be in the
perilous position of bifurcating participants into a class that gets
"taken seriously" and a class that does not.  I spoke earlier in this
thread of "moral hazard".  I feel there is significant moral hazard in
making such classifications.  For one thing, sometimes anonymous
contributors make cogent points, and for another, temptation is
ever present to make the class of "people to be taken seriously"
coextensive with those who agree with, flatter, or indulge you.

Kings, presidents, executives, generals, and "BDFL"s express
mystification and confusion regarding their failures because they
mistake sycophancy for objective judgment.

Regards,
Branden

[1] https://www.reddit.com/r/Demotivational/comments/1fdyxe/consulting/

[2] The most famous example is the great hyphen-minus debacle of 2023.
    https://lwn.net/Articles/947941/

[3] And I do mean theoretically.  I surveyed a large corpus of
    historical Unix troff documents and could not find _any_ that came
    close to slipping through the "hole in the grammar" that I
    identified and closed.
    https://savannah.gnu.org/bugs/?68357#comment1

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]