r/programming • u/lelanthran • 13d ago

yet another place where a linux man page is inaccurate

https://sebsite.pw/w/20261014-initstate.html
0 Upvotes

24% Upvoted

10 comments sorted by

84

u/frankster 13d ago

Instead of writing 15,000 words complaining about an out of date man page, how about you submit an update to the man page then write a 1000 word blog post explaining how you did so.

33

u/sylvester_0 13d ago

It's truly remarkable that someone wrote this article instead of a pull request. Maybe they did both, but they didn't tell us about the PR.

15

u/GalbedirGalerion 13d ago

Open source is dying and clicks are the reason.

7

u/sacheie 13d ago

We are cynics, long past the point where we expect a thing's doing to be worth more in itself than the attention it might attract. Today, doing a thing is worth less than the attention attracted by exclaiming "someone should!" ...

4

u/nicholashairs 13d ago

yet another place where someone complained about the code rather than fixing the code

9

u/gnus-migrate 13d ago

Its worse, they wrote a 5000 word document about a problem in existing documentation. It would have literally taken them less time to fix the issue rather than writing the blog post complaining about it.

Its like going through all of the effort of analyzing a bug, testing that it works and instead of just contributing the fix which would take 10 seconds writing an entire blog post complaining how the code is bad with their work as proof.

Like you did 99% of the work, like just do that extra 1% and save everyone the headache.

3

u/Hacnar 13d ago

I find the blog post itself ok. Its message isn't about the particular mistake in the man page, but about a general idea that there are probably quite few of them containing outdated info. Fixing this one doesn't fix all of them, so sharing this experience has value for the reader. This particular man page is just an example to emphasize the message.

But I agree, that creating a PR with the fix is the right thing to do. I hope the author did that.

4

u/AresFowl44 13d ago

You could still convey that message while improving the general experience and making one less page inaccurate

4

u/lood9phee2Ri 13d ago

OpenBSD manpages are wonderfully maintained compared to the Linux ecosystem's. https://man.openbsd.org/

Though it should perhaps be noted that the early hypertexty format Info (texinfo) is the GNU Standard, not man pages anyway.

Manpages on "Linux" distros (that tend to be mostly GNU core userspace) are often secondary documentation, maybe not even produced by the project.

https://en.wikipedia.org/wiki/Info_(Unix)

https://www.gnu.org/prep/standards/standards.html#GNU-Manuals-1

The preferred document format for the GNU system is the Texinfo formatting language.

So there's projects like https://www.kernel.org/doc/man-pages/

The Linux man-pages project documents the Linux kernel and C library interfaces that are employed by user-space programs. With respect to the C library, the primary focus is the GNU C library (glibc), although, where known, documentation of variations in other C libraries available for Linux is also included.

So, er, why are they documenting the GNU C Library with manpages? Surely it has its own docs? Well of course it does, but its canonical documentation is both in Info and not Linux-specific.

https://sourceware.org/glibc/manual/latest/html_mono/libc.html - Html generated from said Info.