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.
dannyobrien 171 days ago [-]
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/
rc00 171 days ago [-]
[flagged]
homebrewer 171 days ago [-]
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"?
rc00 171 days ago [-]
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?
kouteiheika 171 days ago [-]
> 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?
fsckboy 171 days ago [-]
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
LtWorf 171 days ago [-]
You are of course entirely wrong.
I understand not knowing what lwn is… but why insist?
pm215 171 days ago [-]
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).
arccy 171 days ago [-]
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.
fsckboy 171 days ago [-]
I like the flags documentation, there are too many other words. I also used to like the examples at the bottom.
necovek 171 days ago [-]
--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.
setopt 171 days ago [-]
> 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.
setopt 171 days ago [-]
If you like examples, you might like the “tldr” command.
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.
fsckboy 171 days ago [-]
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
Rediscover 171 days ago [-]
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.
petee 171 days ago [-]
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
LtWorf 170 days ago [-]
git diff
nkrisc 171 days ago [-]
This gave me a chuckle thinking about every time a beginner was told to “read the man page” in response to a question.
hulitu 169 days ago [-]
There are good written man pages.
LtWorf 171 days ago [-]
> the LWN documentation project
LWN is not a documentation project. It's a news outlet.
rc00 171 days ago [-]
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.
homebrewer 171 days ago [-]
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".
rc00 171 days ago [-]
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.
encom 171 days ago [-]
>The Verge
>unbiased
immibis 170 days ago [-]
So... A news outlet.
biorach 174 days ago [-]
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
oneshtein 171 days ago [-]
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.
setopt 171 days ago [-]
Pandoc can convert MarkDown to Man pages so in that sense we’re halfway there. (But I agree that native support would be nice.)
tristan957 171 days ago [-]
scdoc is similar to markdown.
immibis 170 days ago [-]
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.
jbaber 168 days ago [-]
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.
setopt 172 days ago [-]
Sounds like a one man project?
locococo 171 days ago [-]
It's one of those low reward high impact jobs.
Companies should fall over themselves to fund projects like this
endgame 171 days ago [-]
This isn't reddit.
Dalewyn 171 days ago [-]
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.
Y_Y 171 days ago [-]
If you make better posts then they'll be black.
froh 172 days ago [-]
life is roff out there.
Brian_K_White 171 days ago [-]
more or less
jeifneioka 171 days ago [-]
Please guys, pun threads are not apropos on HN.
171 days ago [-]
nindalf 171 days ago [-]
Apropos means “with reference to”. Maybe you meant “appropriate”?
isThereClarity 171 days ago [-]
Perhaps, but there’s a light hearted moment going on.
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.
kevin_thibedeau 171 days ago [-]
man apropos.
dtgriscom 171 days ago [-]
owwwww.....
janandonly 174 days ago [-]
[flagged]
gnoack 172 days ago [-]
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.
immibis 170 days ago [-]
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.
ranger_danger 172 days ago [-]
Why do you assume there would even be too much G in the first place?
transpute 172 days ago [-]
Nth time that AI can repackage human creative labor that was funded by other humans.
not_your_vase 171 days ago [-]
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).
chipdart 171 days ago [-]
> 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.
not_your_vase 171 days ago [-]
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.
jon-wood 171 days ago [-]
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.
homarp 171 days ago [-]
in the comment of the article, he wrote
'Actually, I had added a sentence in my email signatures for almost a year:
does that qualify as 'looking for some sort of employment' ?
not_your_vase 171 days ago [-]
> 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'?
homarp 171 days ago [-]
Sorry, I am missing context. Where does that come from?
not_your_vase 170 days ago [-]
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.
170 days ago [-]
SOLAR_FIELDS 171 days ago [-]
Couldn’t said requestors to transfer maintenance have forked it? What would preclude that?
not_your_vase 171 days ago [-]
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.
SOLAR_FIELDS 171 days ago [-]
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.
shkkmo 171 days ago [-]
> 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'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?
I understand not knowing what lwn is… but why insist?
"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).
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.
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.
https://tldr.sh/
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.
I dread Linux man pages
LWN is not a documentation project. It's a news outlet.
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.
>unbiased
Companies should fall over themselves to fund projects like this
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
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).
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.
'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' ?
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.
Common sense.
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.