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

On Mon, Aug 3, 2026 at 12:09=E2=80=AFPM G. Branden Robinson
<[email protected]> wrote:
>
> [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 <[email protected]>
> > > 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>.

the crazy part is that it was an _empty_ file until i made it just
#include <string.h>:
https://android-review.googlesource.com/c/platform/bionic/+/52171

i can't explain that (it was originally checked in as an empty file,
so the history is no help).

i _can_ explain why i made it match glibc rather than just deleting it
though: i didn't want to break existing code that was [harmlessly]
including an empty file, and i wanted to increase the amount of the
code from other libcs that would "just work". (and note that ios/macos
have a <memory.h> that's just a #include <string.h> too.)

> 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=C3=ABnvisioning 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