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/
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.
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.
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 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.
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.
> 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.
[+] [-] fsckboy|1 year ago|reply
[+] [-] dannyobrien|1 year ago|reply
[+] [-] pm215|1 year ago|reply
"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).
[+] [-] arccy|1 year ago|reply
[+] [-] dooglius|1 year ago|reply
[+] [-] nkrisc|1 year ago|reply
[+] [-] LtWorf|1 year ago|reply
LWN is not a documentation project. It's a news outlet.
[+] [-] biorach|1 year ago|reply
[+] [-] oneshtein|1 year ago|reply
[+] [-] setopt|1 year ago|reply
[+] [-] tristan957|1 year ago|reply
[+] [-] immibis|1 year ago|reply
[+] [-] setopt|1 year ago|reply
[+] [-] locococo|1 year ago|reply
Companies should fall over themselves to fund projects like this
[+] [-] endgame|1 year ago|reply
[+] [-] froh|1 year ago|reply
[+] [-] janandonly|1 year ago|reply
[deleted]
[+] [-] gnoack|1 year ago|reply
[+] [-] transpute|1 year ago|reply
[+] [-] not_your_vase|1 year ago|reply
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).
[+] [-] chipdart|1 year ago|reply
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.
[+] [-] SOLAR_FIELDS|1 year ago|reply
[+] [-] shkkmo|1 year ago|reply
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.
[+] [-] unknown|1 year ago|reply
[deleted]
[+] [-] 2OEH8eoCRo0|1 year ago|reply