Comment by scaryclam
8 years ago
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.
Which might have been good for late 70s -- and the main users being academics and the designers of the system itself, but might not be as good for late 2010s.
Besides, we already have the Examples section, would it be too much to ask to have it better (or at least somewhat) utilized in all manpages?
We could even have different sections, shown with flags, and keep regular output as it is.
man --examples foocommand
3 replies →