Nobody who removed the joke said they were offended by it, they just said that they didn't believe it was the sort of thing that belonged in technical documentation. If anyone is offended, it is RMS, in the sense that he seems personally affronted that he doesn't carry the line-item veto power he thinks he had over all of GNU and people did not ask him before removing something he added 25 years ago.
Not everyone who disagrees with something is offended by the thing they disagree with. Shall I say that someone who prefers writing documentation in man pages instead of Markdown is offended by Markdown? Is Project Zero offended by buffer overflows?
Technical documentation isn't the place for a joke full stop. Documentation is for people who are typically busy, uncertain and potentially dealing with something that is going wrong.
They want clear, concise and accessible help. They don't want or need tasteless jokes. It is disrespectful to their time to include random garbage.
This is supposed to be read by people who need it, not people who know what is going on and want to enjoy a good laugh.
For what it's worth, at least one member of the glibc steering committee appears to agree:
"I agree with removing this joke. A bit of humor is fine - indeed, the manual could use a bit more than it has - but this attempt at humor does not work. The manual should be high-quality, and that includes high-quality jokes."
"your technical documentation should have a consistent tone"
I appreciate light-hearted asides in documentation. But more if I expect it than when it's unexpected. Like you wouldn't want to end up confusing some ESL programmer who goes ask a lawyer whether they should be worried about this?
Or if you're really ambitious, make all your docs super funny! But if you mix the tone it's disorienting and maybe bad writing.
I would even go so far as to say that Why's (Poignant) Guide to Ruby directly contributed a great deal to Ruby's popularity because of the witty content alone.
Leaving aside the question of the nature of its jokes, the TeXBook is the sort of thing you read straight through. It's a narrative about how some code came to be. It's not the same sort of reference as the glibc manual, and I think a narrative form of documentation benefits from a casual tone and a four-sentence standalone reference about a function (especially where one of those sentences is "Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt") benefits from a terse tone.
Knuth has a great sense of humor in his books and exercices. I also like Stallman's jokes, but I can concede that they are sligthly less funny than Knuth's.
I'm not that hardcore about it, but I still agree this really shouldn't be in the official docs. Maybe in a tutorial or a set of slides.
I do agree with some professionalism in things that want to be taken seriously. I don't even really like the "Apt with super cow powers."
I do agree this isn't about political correctness. At one time GNU tools were just a bunch of devs trying to write open source tooling for fun or to learn. But with it being such a huge part of our industry now, it does need to grow up.
If you're working on your own small open source projects, have fun with the docs and comments. But don't be like Stallman. Realize if your tools are really successful, those quips might get cut out one day. c'est la vie
My feeling is that most of GNU manuals in texinfo format are borderline useless because the structure is simply wrong, the random jokes are somewhat tangential issue.
I Don't know if we're talking about the same thing but I've found the format of man pages to be absolutely useless for me. Maybe I'm too dumb/noob to understand them, but then what's left for the folk who just switched to linux and wamts to learn about commands.
> "Notably, man is not available as an output format from the standard Texinfo tools. While Texinfo is used for writing the documentation of GNU software, which typically is used in Unix-like environments such as GNU/Linux, where man pages are the traditional format for documentation, the rationale for this is that man pages have a strict conventional format, used traditionally as quick reference guides, whereas typical Texinfo applications are for tutorials as well as reference manuals. As such, no benefit is seen in expressing Texinfo content in man page format. Moreover, many GNU projects eschew man pages almost completely, referring the reader of the provided man page (which often describes itself as seldom maintained) to the Info document."
They can take some getting used to if you're not familiar with them, but given how much documentation is available in these formats, it's worth taking a few hours to become accustomed to them. A lot of it is duplicated online as well, so you can often use your favorite search engine.
It's wonderful to use in emacs, and back before I started using emacs ISTR that pinfo was a great way to read info.
I used to hate how GNU manpages would point me at the info docs, but honestly nowadays I prefer info. It really is nice — like a pre-CSS, pre-JavaScript HTML, only it can be beautifully typeset too.
Yeah, I hate info, but the problem is info(1), not the entire texinfo stack. The html output is pretty good and I already know how to navigate it, so I usually use that
If you genuinely believe that these are comparable situations (and you're not just making a strained comparison to argue in favor of the side you favor), I'm not sure how to explain my position to you.
Although I think I would start by saying this: where "spam" and "eggs" is used in Python, it is in the place of any other word, usually a nonsense word like "foo" or "bar", and its presence does not distract. I doubt anyone thinks of actual SPAM or actual eggs when they run across it, and I seriously doubt the documentation authors intended or expected anyone to.
The (so-called) joke in this glibc discussion is a) essentially a pun on the name of the function, i.e., introducing mental confusion; b) a political subject; c) an ill-explained reference to a political subject (did you know it's about the global gag rule? do you know what the global gag rule is?); d) intended to make you think about that subject instead of tuning it out.
Python's use of "spam" and "eggs" adds some character, that's about it. (Python's insistence on "eggs" and "wheels" and "cheeseshop", on the other hand... I find the names cute but if you wanted to get rid of them all in favor of slightly more descriptive words, I'd honestly be in favor.) This joke serves no purpose other than, at best, to distract the attention of the person looking up documentation onto a completely different subject.
I think that's a little different. Even with the fun variable names, the Python docs are pretty damn professional.
They haven't always been that way. The Python docs back around 2000 were not that great. A lot of work has been put in by people in the community to get them to the state they're in.
Not the same thing. "spam" & "eggs" are very neutral. If they used politically charged terms, and inserted example code like "if brains(republicans) == 0 # always true!" then the situation would be similar. The difference is between neutral light-heartedness and non-neutral political message.
In any case that question seems wildly unrelated to the question at hand, which is about a joke that's intended to be a present-day political reference.
The early days of computing was very informal and full of jokes. Didn't stop people from creating some of the most long-lasting and technically successful tools.
A well-constructed joke can make documentation more useful. I can't think of an example off the top of my head, but there've been plenty of times that something made me laugh and go "NOW I get it!" to the technical material.
This isn't a well-constructed joke in that sense - it's likely to cause confusion, not increased understanding.
> they just said that they didn't believe it was the sort of thing that belonged in technical documentation
I've been dreading the day OSS projects became as soulless and boring as corporate ones. If we can't have jokes in technical documentation then it seems that day has come.
Next the FOSS HR department will be asking them to rename the abort function.
There's certainly something lost here, I won't deny that.
But glibc, and huge other parts of the FOSS ecosystem, has been a corporate project for years. Maintenance comes from stodgy companies like Red Hat who install glibc on the sort of extremely stodgy companies who are Red Hat customers.
And for those of us whose day jobs involve using glibc and reading its documentation, we deserve the benefits of free software as much as everyone else. If it is an ethical imperative (as RMS says!) for all software to be free and for proprietary software to die, it follows that the primary battleground is the servers of soulless, boring corporations. Your hobbyist laptop is important, too, because everyone deserves free software. But if free software weren't around, you would have installed a pirated copy of Windows with a keygen with some hentai as its background image and enjoyed the non-HR-compliance of the process, and Microsoft would have been quite okay with it because you would be locked into their proprietary software.
If free software is an ethical imperative - or even if it's not, but even if open source is simply a better way to develop software - then everyone who wants a job in software engineering and is qualified for it should be able to have a job in writing and maintaining FOSS. Human society has determined that if we want everyone to participate in an activity, things work better if everyone agrees to uphold a few norms. They don't have to be the same norms as boring corporations uphold (and you can quite easily argue that the norms of boring corporations aren't that good, actually, at making sure everyone is welcome to participate on equal terms). But the fact that we open our shared infrastructural work to accountability and public judgment is sort of how civilization works.
Hobbyist projects are still as possible as ever. Twenty years ago, you wouldn't have been able to get inappropriate jokes in the technical documentation for Solaris libc, or into MSDN, or whatever, but you could work on some upstart free software project with your friends and do whatever you want. You can still do that. If you want to be the young, upstart libc with some off-color political jokes that's being an alternative to the boring corporate libc, more power to you. Not everyone will participate, but that's what you want. Meanwhile, the libc whose goal in life was to displace the corporate libcs has won - and needs to step into its role.
I think you're looking at the wrong axis. This isn't an order-vs-chaos question, it's one of constructive vs destructive. This particular joke makes the manual worse, not better, at being a manual. Cut it and move on, and always keep an eye out for places it could be improved, whether that be through better descriptive prose or a good, understanding-building joke.
The main justification for why it shouldn't be there is that it was offensive. The idea that software should not be political is, in fact, itself just as offensive to the community of campaigners who've joined the calls to have this removed as this joke is. The last big controversy I saw was the entire console jailbreaking community being declared a bunch of bigots because someone mocked the idea that code could have views on LGBTQ rights.
> The main justification for why it shouldn't be there is that it was offensive.
This is simply untrue; you can look at the patch's commit message and the review thread. The primary justification was that it wasn't appropriate, and the secondary one is that it wasn't actually funny and was tasteless. Nobody said "offensive". You can read the thread yourself.
(The April history shows the conversation between maintainers regarding the patch itself; if you want to see RMS' reply, go to the May index. RMS and Alexandre Oliva, the two people defending the joke, brought up the concept of "offense", and people repeatedly say in reply that they're not offended. Oliva later says he's offended by other people in the discussion.)
Of course, you're also welcome to believe that everyone who disagrees with you must be offended; you're entitled to your opinions.
Not everyone who disagrees with something is offended by the thing they disagree with. Shall I say that someone who prefers writing documentation in man pages instead of Markdown is offended by Markdown? Is Project Zero offended by buffer overflows?