I'm not sure what the purview of the LWN documentation project is (in terms of, are those the man pages I look at when I'm using Fedora?) but I really don't like what has been happening to man pages. They're becoming bloated and beginner-y and not terse and dense technical descriptions of what I need to know.
I think you knew this, but for clarity: the man project is being reported on by Linux Weekly News (LWN), but it's not run by them. They're just the news outlet. And an excellent one, that you should totally support and subscribe: https://lwn.net/subscribe/
The exact same thing can be said about "folio bias", or "bcachefs bias", or "git bias", or "RCU bias", or anything else that's really important for the development of the Linux kernel. I don't have strong opinions about Rust (either for or against it), and, having read the site since about 2016, don't see anything out of the ordinary. Its primary target audience always were Linux kernel developers, and Rust is becoming increasingly important for them whether they like it or not. Would ignoring its integration into the kernel be an example of "unbiased reporting"?
This is going to spin out but Rust is not a fit for kernel development. It is a language fueled by what feels like a perpetual hype cycle. To say that there is nothing out of the ordinary means you haven't compared the site before and after. Out of all the languages and actual things for kernel developers to become increasingly concerned with, Rust is not one of them. To ignore this practicality and suggest that having the Rust agenda carried forward is incorrect. The current experimentation with Rust will end and what will you say when that happens? Many already falsely claim the kernel ships with Rust when it does not. How does that not indicate that a bias is leading to the spread of misinformation? Why is this okay for Rust but maybe not in other areas? Would you feel the same if it were AI articles instead?
you're half right, i thought otherwise, but not firmly, and when i followed the link to the site and found a discussion that looked like a project discussion, it dispelled my doubt, which turns out was a righteous doubt
AIUI the "Linux man-pages project" does provide the manpages you're reading, but only some of them. Specifically, its readme describes the scope as:
"The manual pages in this project document primarily the Linux kernel and the GNU C library, but also consider relevant differences in other kernels or C libraries. These pages are most of the section 2, 3, 4, 5, 7 man pages for GNU/Linux. A few pages are provided in sections 1 and 8 for commands that are not documented in other packages, and there are a few pages in sections 5 and 8 for the timezone utilities."
Most manpages for individual command line programs are written and shipped by the projects or authors of those programs. And if there are manpages for functions in non-libc libraries those are generally provided and shipped by the authors of those libraries.
The wide range of origins for manpages means there isn't going to be a single consistent style over every manpage in a Linux system (and of course "don't ship a manpage at all" remains a popular choice).
Terse was fine when you had 10 tools with 5 options each. Now we have so many more tools and each has grown a large number of flags. Nobody can remember them all so the docs need to say more. Plus the more niche flags need more explanations.
--help should give you basic docs for GNU utilities. Manpages should be more extensive (examples included).
As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed, so I guess most of that content is slowly moving over to manpages now.
> As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed
I think the only community where it kind of succeeded is the Emacs community, thanks to the built-in info reader and that a lot of Emacs docs got written in info.
Can you give a before/after example of this happening? My impression has been that man pages don't change all that much aside from adding new features.
i'll be happy to hit ^R a few times and see if it coughs up some man pages i looked at that left me disappointed... I use a number of different boxes so could take me some time to visit them all
It is not a news outlet. At least, not in the general sense of what makes for a good news outlet. Good news outlets don't have bias. It is a personal blog purporting to be news at this point.
I would be honestly interested to learn about one or two unbiased news outlets, because I don't know any, tech news or otherwise. What is usually meant by "unbiased" is "biased in the same way as I am".
Assuming this statement was made in good faith, there are many depending on the area of focus. For general tech, there's CNET, The Verge, TechCrunch, Ars Technica, Tom's Hardware, etc. For Linux, there's Phoronix, Linuxiac, Linux Journal, DistroWatch, etc.
What I mean by "unbiased" is neutral coverage on actual news, meaning just the facts. If you pay attention to the coverage at LWN, there is an inherent Rust bias that dominates regular news. Just try to go more than a few days without new articles being published with a pro-Rust stance. Actual data with stories and coverage over the years would illuminate this easily.
Man pages maintainer Alejandro Colomar announced in September that he was suspending his work due to a lack of support. He has now let it be known that funding has been found for the next year at least
It would be nice for man pages to support Markdown format natively: easy formatting, links, tables, tooling, number of ready to use pages shipped with projects.
I do not understand HN's obsession with Markdown. It's fundamentally a poorly specified, ambiguous, very limited format. And no, formalizing a single parsing algorithm for such a format doesn't solve the issues apart from different rendering in different viewer applications.
I just like it because it's a rough standard. Not the one I'd choose and, as you point out, ambiguous. But I can expect support in all kinds of random places.
If corporate were to ask me to find differences, I honestly couldn't tell them other than that one is White and Red while the other one is Orange and Gray.
I find this an offensive comment. The GIGO principle applies to documentation, and we would be in a much worse place if we didn't have the man page documentation written and reviewed by humans.
If you're offended by the idea of a computer generating output from input you should reconsider that attitude. That's what they're for. This use of AI would be similar to a (poor quality) compiler, but for documentation.
Unfortunately I couldn't help noticing however that when the maintainer announced that he is about to stop working on the project, he ignored all questions and requests about transferring the maintenance duties to someone else. Somehow I feel the project was held as a hostage, waiting for a ransom (which was paid eventually).
> Somehow I feel the project was held as a hostage, waiting for a ransom (which was paid eventually).
This situation only happens when you hand the responsibility of managing a critical domain to a single person, and you forget about it for ages.
This is hardly a "hostage" situation, specially when the reason flagged is lack of support. I mean, this scenario only happens due to lack of support to begin with.
But in my opinion if you want to earn money, then you should look for some sort of employment, and not be a volunteer in a project that's very famous about being built by volunteers, and demand to be paid (or else). If you don't want to be an unpaid volunteer anymore (which is a very fair thing to do), there are much more graceful ways to achieve that.
I don't think Linux has been primarily built by volunteers for decades, Red Hat, Canonical, IBM, and a great many other companies employ people to work on it because it's a product that they sell.
> A: Hey man, how is it going?
> B: Not good, have been without a job for over a year :(
> A: Aww... what happened? Did recruiters stop using LinkedIn? Or you made your profile private?
> B: Nah, I have no LinkedIn profile...
> A: Gotcha, M$ is a pest. The how many CVs have you sent?
> B: 0. I don't believe in that.
> A: Then what did you do? Did you try to look for a job at all?
> B: Of course! I put a new signature in my emails. And then I barely sent an email to anyone.
> A: That's 1 sentence, with a dead link.
> B: That's what I'm talking about, exactly. Even with the dead link, I still can't find any jobs...
What do you say? Does that qualify as 'looking for some sort of employment'?
You asked if putting a single sentence with a dead link in an email signature counts as job searching (putting that signature in emails by a person who barely sends emails, by his own admission).
What would preclude one from forking the kernel source, maintaining the man-pages separately, and expecting it to reach a similar adoption as the mainline?
Interesting - why would you have to fork the kernel source here? Why couldn’t you just fork the man pages only, demonstrate to the kernel maintainers the man pages project is essentially unmaintained, then ask the kernel maintainers to make your fork the source of truth? I would think if the man pages project is actually unmaintained this would not be a problem.
> Instead of stopping maintenance looking for a sponsor, wouldn't be better to hand it off to other contributors that have already established some trust? Some people may have more time available to be active maintainers. I see activity from other contributors in the git history of the project.
Is responded to with:
> Such contributors almost certainly don't exist. "Activity" from other contibutors != someone who has the time, energy, and ability to be a potential maintainer. In more than 15 years of maintaining the project, Alex was the only person that appeared who could seriously take over the maintainership. He's done a great job, but there's only so much a volunteer can do.
There is nothing being "held hostage". Expecting a volunteer to train new contributors while still managing the project is unrealistic. It is unlikely that any of these new volunteers will step into his role for free.
Thus the realistic options were to let the project die and other orgs take on the works themselves, or fund the guy who has been doing the work for free for 15 years. People values the project enough to do the later.
I'm not sure what the purview of the LWN documentation project is (in terms of, are those the man pages I look at when I'm using Fedora?) but I really don't like what has been happening to man pages. They're becoming bloated and beginner-y and not terse and dense technical descriptions of what I need to know.
I think you knew this, but for clarity: the man project is being reported on by Linux Weekly News (LWN), but it's not run by them. They're just the news outlet. And an excellent one, that you should totally support and subscribe: https://lwn.net/subscribe/
[flagged]
The exact same thing can be said about "folio bias", or "bcachefs bias", or "git bias", or "RCU bias", or anything else that's really important for the development of the Linux kernel. I don't have strong opinions about Rust (either for or against it), and, having read the site since about 2016, don't see anything out of the ordinary. Its primary target audience always were Linux kernel developers, and Rust is becoming increasingly important for them whether they like it or not. Would ignoring its integration into the kernel be an example of "unbiased reporting"?
This is going to spin out but Rust is not a fit for kernel development. It is a language fueled by what feels like a perpetual hype cycle. To say that there is nothing out of the ordinary means you haven't compared the site before and after. Out of all the languages and actual things for kernel developers to become increasingly concerned with, Rust is not one of them. To ignore this practicality and suggest that having the Rust agenda carried forward is incorrect. The current experimentation with Rust will end and what will you say when that happens? Many already falsely claim the kernel ships with Rust when it does not. How does that not indicate that a bias is leading to the spread of misinformation? Why is this okay for Rust but maybe not in other areas? Would you feel the same if it were AI articles instead?
> This is going to spin out but Rust is not a fit for kernel development.
I'll bite. Genuine question. Why?
> It is a language fueled by what feels like a perpetual hype cycle.
So just because it's hyped it shouldn't be used? Or are you saying that it's a bad language and people only use it because of the hype?
you're half right, i thought otherwise, but not firmly, and when i followed the link to the site and found a discussion that looked like a project discussion, it dispelled my doubt, which turns out was a righteous doubt
You are of course entirely wrong.
I understand not knowing what lwn is… but why insist?
AIUI the "Linux man-pages project" does provide the manpages you're reading, but only some of them. Specifically, its readme describes the scope as:
"The manual pages in this project document primarily the Linux kernel and the GNU C library, but also consider relevant differences in other kernels or C libraries. These pages are most of the section 2, 3, 4, 5, 7 man pages for GNU/Linux. A few pages are provided in sections 1 and 8 for commands that are not documented in other packages, and there are a few pages in sections 5 and 8 for the timezone utilities."
Most manpages for individual command line programs are written and shipped by the projects or authors of those programs. And if there are manpages for functions in non-libc libraries those are generally provided and shipped by the authors of those libraries.
The wide range of origins for manpages means there isn't going to be a single consistent style over every manpage in a Linux system (and of course "don't ship a manpage at all" remains a popular choice).
Terse was fine when you had 10 tools with 5 options each. Now we have so many more tools and each has grown a large number of flags. Nobody can remember them all so the docs need to say more. Plus the more niche flags need more explanations.
I like the flags documentation, there are too many other words. I also used to like the examples at the bottom.
--help should give you basic docs for GNU utilities. Manpages should be more extensive (examples included).
As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed, so I guess most of that content is slowly moving over to manpages now.
> As far as GNU tools go, their attempt to move docs to (tex)info format for better interactivity has largely failed
I think the only community where it kind of succeeded is the Emacs community, thanks to the built-in info reader and that a lot of Emacs docs got written in info.
If you like examples, you might like the “tldr” command.
https://tldr.sh/
Can you give a before/after example of this happening? My impression has been that man pages don't change all that much aside from adding new features.
i'll be happy to hit ^R a few times and see if it coughs up some man pages i looked at that left me disappointed... I use a number of different boxes so could take me some time to visit them all
Try comparing OpenBSD (or Solaris or ...) man pages to those on Linux?
The one for traceroute(8) has some great commentaries on the sample output ("God only knows what's going on with 12."). It's a personal favorite.
Anytime I've had an issue with an OpenBSD man page (rarely) I take 5 minutes to go play in Linux to remember just how terrible it could be
I dread Linux man pages
git diff
This gave me a chuckle thinking about every time a beginner was told to “read the man page” in response to a question.
There are good written man pages.
> the LWN documentation project
LWN is not a documentation project. It's a news outlet.
It is not a news outlet. At least, not in the general sense of what makes for a good news outlet. Good news outlets don't have bias. It is a personal blog purporting to be news at this point.
I would be honestly interested to learn about one or two unbiased news outlets, because I don't know any, tech news or otherwise. What is usually meant by "unbiased" is "biased in the same way as I am".
Assuming this statement was made in good faith, there are many depending on the area of focus. For general tech, there's CNET, The Verge, TechCrunch, Ars Technica, Tom's Hardware, etc. For Linux, there's Phoronix, Linuxiac, Linux Journal, DistroWatch, etc.
What I mean by "unbiased" is neutral coverage on actual news, meaning just the facts. If you pay attention to the coverage at LWN, there is an inherent Rust bias that dominates regular news. Just try to go more than a few days without new articles being published with a pro-Rust stance. Actual data with stories and coverage over the years would illuminate this easily.
>The Verge
>unbiased
So... A news outlet.
Man pages maintainer Alejandro Colomar announced in September that he was suspending his work due to a lack of support. He has now let it be known that funding has been found for the next year at least
It would be nice for man pages to support Markdown format natively: easy formatting, links, tables, tooling, number of ready to use pages shipped with projects.
Pandoc can convert MarkDown to Man pages so in that sense we’re halfway there. (But I agree that native support would be nice.)
scdoc is similar to markdown.
I do not understand HN's obsession with Markdown. It's fundamentally a poorly specified, ambiguous, very limited format. And no, formalizing a single parsing algorithm for such a format doesn't solve the issues apart from different rendering in different viewer applications.
I just like it because it's a rough standard. Not the one I'd choose and, as you point out, ambiguous. But I can expect support in all kinds of random places.
Sounds like a one man project?
It's one of those low reward high impact jobs.
Companies should fall over themselves to fund projects like this
This isn't reddit.
If corporate were to ask me to find differences, I honestly couldn't tell them other than that one is White and Red while the other one is Orange and Gray.
If you make better posts then they'll be black.
life is roff out there.
more or less
Please guys, pun threads are not apropos on HN.
Apropos means “with reference to”. Maybe you meant “appropriate”?
Perhaps, but there’s a light hearted moment going on.
Context
- https://www.man7.org/linux/man-pages/man7/roff.7.html
- https://man7.org/linux/man-pages/man1/more.1.html
- https://man7.org/linux/man-pages/man1/less.1.html
- https://man7.org/linux/man-pages/man1/apropos.1.html
That's only when used as a preposition. When used as an adjective it is more or less a synonym for "appropriate" and works fine in this context.
man apropos.
owwwww.....
[flagged]
I find this an offensive comment. The GIGO principle applies to documentation, and we would be in a much worse place if we didn't have the man page documentation written and reviewed by humans.
If you're offended by the idea of a computer generating output from input you should reconsider that attitude. That's what they're for. This use of AI would be similar to a (poor quality) compiler, but for documentation.
Why do you assume there would even be too much G in the first place?
Nth time that AI can repackage human creative labor that was funded by other humans.
Cool.
Unfortunately I couldn't help noticing however that when the maintainer announced that he is about to stop working on the project, he ignored all questions and requests about transferring the maintenance duties to someone else. Somehow I feel the project was held as a hostage, waiting for a ransom (which was paid eventually).
> Somehow I feel the project was held as a hostage, waiting for a ransom (which was paid eventually).
This situation only happens when you hand the responsibility of managing a critical domain to a single person, and you forget about it for ages.
This is hardly a "hostage" situation, specially when the reason flagged is lack of support. I mean, this scenario only happens due to lack of support to begin with.
Well, that's definitely a valid point of view.
But in my opinion if you want to earn money, then you should look for some sort of employment, and not be a volunteer in a project that's very famous about being built by volunteers, and demand to be paid (or else). If you don't want to be an unpaid volunteer anymore (which is a very fair thing to do), there are much more graceful ways to achieve that.
I don't think Linux has been primarily built by volunteers for decades, Red Hat, Canonical, IBM, and a great many other companies employ people to work on it because it's a product that they sell.
in the comment of the article, he wrote
'Actually, I had added a sentence in my email signatures for almost a year:
``` -- <https://www.alejandro-colomar.es/> Looking for a remote C programming job at the moment. ``` (e.g.: <https://lore.kernel.org/linux-man/ZgifHQoTaDEiga0W@debian...>) '
does that qualify as 'looking for some sort of employment' ?
Sorry, I am missing context. Where does that come from?
Are we not having the same conversation?
You asked if putting a single sentence with a dead link in an email signature counts as job searching (putting that signature in emails by a person who barely sends emails, by his own admission).
And my answer was "are you kidding me"?
I hope this helps.
Couldn’t said requestors to transfer maintenance have forked it? What would preclude that?
What would preclude one from forking the kernel source, maintaining the man-pages separately, and expecting it to reach a similar adoption as the mainline?
Common sense.
Interesting - why would you have to fork the kernel source here? Why couldn’t you just fork the man pages only, demonstrate to the kernel maintainers the man pages project is essentially unmaintained, then ask the kernel maintainers to make your fork the source of truth? I would think if the man pages project is actually unmaintained this would not be a problem.
> Instead of stopping maintenance looking for a sponsor, wouldn't be better to hand it off to other contributors that have already established some trust? Some people may have more time available to be active maintainers. I see activity from other contributors in the git history of the project.
Is responded to with:
> Such contributors almost certainly don't exist. "Activity" from other contibutors != someone who has the time, energy, and ability to be a potential maintainer. In more than 15 years of maintaining the project, Alex was the only person that appeared who could seriously take over the maintainership. He's done a great job, but there's only so much a volunteer can do.
There is nothing being "held hostage". Expecting a volunteer to train new contributors while still managing the project is unrealistic. It is unlikely that any of these new volunteers will step into his role for free.
Thus the realistic options were to let the project die and other orgs take on the works themselves, or fund the guy who has been doing the work for free for 15 years. People values the project enough to do the later.
Yeah the principal here is mutual aid not charity
Why is it his problem what you all do afterwards?