Comment by _b8r0
8 years ago
> 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
>You clearly don't understand core Unix philosophy[1].
That's because it's trite cargo cult. And even worse, it's totally unapplicable to our discussion, as it pertains to program design, not how to write or what to include in a man page. man, the program, would still just be a simple manpage showing program.
Besides it, and other basic unix core utils and userland programs, have adopted 10,000s of flags and new functionality over the years, to the point that shooting down my --examples suggestion for "breaking the unix philosophy" is total BS.
Heck, Emacs includes everything AND the kitchen sync, but it's a much beloved part of Unix tradition.
>It's this that drives commands like man, that have been around since 3rd edition Unix.
Tradition doesn't make it right. Where's the science? How about some actual measurements of levels of head-banging of users between different approaches?
Also note that I started on Sun OS, when Solaris was a new unstable OS, and have used HPUX, IRIX and other such flavors in workstations of the time (and actual VT terminals). I'm not some teenager that got into Linux with the latest Ubuntu.
>The problem is that you want man pages to do something they aren't designed for, and will not change to.
Sorry, you've already lost that battle. Lots of manpages already have EXAMPLES sections. It's just that not enough attention has been paid to their content.
1 reply →