Comment by PaulRobinson
8 years ago
Hilariously, ITT are lots of comments saying that man is awful, in response to a pot about a "simplified and community-driven" alternative.
Breaking news: man pages are community-driven already. You can make them better in your distro of choice. The BSD projects are a little better IMHO at this than Linux because each project has a dedicated team trying to raise the bar and make their docs better than the next distro.
So don't make it simplified, don't hail "community-driven", just go and start making suggested changes with the rest of your favourite OS community!
These community projects are great ways to test potential upstream changes before trying to make a bunch of upstream changes. The maintainer of the project doesn't have to field half-baked pull requests.
I think a bigger problem with man pages is not that they are badly written, it's that man itself is not user friendly:
1. I can't immediately jump to an entry for "-o", I have to use a search expression that might or might not work.
2. I can't reliably search for all references to "-o" from its definition.
3. I can't reliably jump to the definition of "-o" from any given reference.
4. I sure as hell can't search for "output" and easily find that "-o" is the option that controls the name of the output file.
5. There is no table of contents, and even if there were, there would be no way to link from an item in that table to its location in the manual.
HTML, for whatever it's deficiencies might be, is a far superior format for disseminating documentation. The Vim manual is pretty good too, due to the use of aggressive tagging and tight integration with those tags. Funny part is that manual pages can be written with semantic markup, but the semantic meaning is discarded once the manual pages rendered. It is totally backwards, and the world is in need of a better manual page renderer.
Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.
Why would you want a manpage that doesn't have the structure of a manpage? If every other manpage has one structure, you want yours to have another? What's special about yours?
The consistency is not an accident and my personal experience is that the format works well.
The point is exactly that people do not want something like a man page, so they make their own thing that's not like a man page, and the suggestion "go contribute to manpages instead" isn't a good one, because it would mean making bad man pages (or not fixing the issue people have). If aspects are useful for the man pages (e.g. to make better examples sections), they can still be pulled out and added there as well.
"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.
Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.
2 replies →
People who complain about man pages tend not to understand man pages. Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file.
OP is absolutely spot on about man pages being community driven. At least half the time someone complains to me about a man page, the man page is the wrong place to look. Usually, the answer they're looking for is in an info manual or somewhere like /usr/share/doc/.
>People who complain about man pages tend not to understand man pages.
That's their very issue with them.
>Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file.
Then people who designed man pages didn't understand what the users want first and foremost: howto examples.
Besides, whether they document "the different components of a command" and whether they have howto examples is orthogonal. They could do all the formal documentation they want and still include howto examples.
That they don't (well, most don't, some man pages are decent enough to indeed include example sections) is their failure.
I don't think it's fair to say that the originators of man pages didn't understand what their users were looking for. In most cases, the authors are the users, and when they were first created, that was pretty much the only user base they had. Man pages are manual pages, not howto pages.
If I'm looking at a man page, it's pretty much always because I want to look up one of the options, not how to use the command itself. Adding that sort of howto clutter would make it a whole lot harder to use the pages properly. Why not leave man pages alone and just focus on info pages again (http://www.troubleshooters.com/linux/info.htm)? That was always the go-to for more verbose descriptions and has much more of a howto vibe about it.
6 replies →
I pointed you directly at the correct sources of documentation: info pages (for most GNU software) and /usr/share/docs. These are the places where howtos belong, not man pages.
The issue isn't with man pages themselves. The issue is with the expectations sites, tutorials and users themselves set for man pages.
"People who complain about man pages tend not to understand man pages."
There could not be a more valid complaint. If the man pages aren't understandable, what program is supposed to explain them?
There isn't really a single program. Man pages have been built through convention by people who've taken the time to write them, at various points following guidelines from Ritchie et al. It's usually down to the OS to explain the purpose and function of man pages in their own documentation.
For some Operating Systems, man pages are exceptionally high quality (most notably the BSDs). For some, they're bilge, but such systems tend to have init managed through systemd.
Having said that, many OSes support info(1), which provides more detailed software manuals for many pieces of software.
Of course, there are actual physical locations for forms of documentation not in man format or structure. You can find out where such documentation lives on your system on most Unix-like OSes through man:
$ man hier
>So don't make it simplified, don't hail "community-driven", just go and start making suggested changes with the rest of your favourite OS community!
Good luck with getting those accepted, when there's an established man page and for 30+ years simple examples like in tldr where frowned upon in almost all of them.
https://tldr.ostera.io/tar
https://man.openbsd.org/tar#EXAMPLES
What they're covering is just the examples section of a traditional man page. What makes you think people wouldn't merge these?
It's a fundamentally different goal / structure.
`man` documents every last flag, and I generally use it for a command I know decently but need to dig into particulars. It goes to a scrollable page like `less` which is important bc it's total size spans several pages.
`tldr` is shows the 3-4 most common use cases for a command, and puts it right to stdout more like `cat` so you can refer to it as you type along. I'd generally use this for a command I do not know so well.
1 reply →
Discussion on this page at https://news.ycombinator.com/item?id=15779457 has already touched upon this.
You hit the nail on the head. If you want simple examples, send patches to your maintainers extending (or adding) the EXAMPLES section of the manual instead of looking to a project like tdlr pages.
TFA uses a “NodeJS” “client” and its members nerd out on “Gitter”. I’m not sure what the hell any of that hipster bullshit means, but to people of that ilk, if it’s not on GitHub it does not exist.