Comment by coldtea
8 years ago
>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.
>Man pages are manual pages, not howto pages.
Isn't that a made-up distinction though?
Who said manuals can't have representative examples for how to do certain tasks?
Product manuals (including software product manuals) almost always do. They don't just enumerate features and flags.
> Who said manuals can't have representative examples for how to do certain tasks?
Dennis Ritchie defined what goes into the manual in the 3rd edition of UNIX, at the behest of Doug McEllroy. Ken Thompson also did some work on man pages, and I believe Lorinda Cherry was involved too. As I understand it (and I could be wrong though) the terseness of man pages was Ritchie's design, with input from Thompson.
4 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.