Comment by coldtea
8 years ago
>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
You clearly don't understand core Unix philosophy[1]. It's this that drives commands like man, that have been around since 3rd edition Unix.
You're failing to understand who the main users of Unix were (Bell, a telecoms company. Academics didn't start using Unix in anger until the late 70s, by which point Unix had been established for about 3-7 years within AT&T/Bell depending on whether you count Berkeley and Illinois's initial use as academia, or it's more widespread adoption following the release of the BSD distribution and V7/V32).
Before you start complaining about man pages, consider that in order to access them on your shiny new computer that it simulates a 1970s era virtual terminal, which itself emulates an advanced 1960s era teletype terminal to display it.
The problem isn't man pages. They do their job generally well. The problem is that you want man pages to do something they aren't designed for, and will not change to. Use /usr/share/docs or info instead. That's what these things are there for.
[1] - https://en.wikipedia.org/wiki/Unix_philosophy
2 replies →