On Sat, Dec 24, 2011 at 10:08:31AM EST, Bill Gradwohl wrote:
[..]
> The man page is written the way Robbie the Robot used to speak in the old
> black and white TV days¹. Short, cryptic and in many cases unintelligible IN
> THE DETAILS. Alternatively, one might snicker that some lawyer wrote it to
> purposely make it difficult to understand. As with most of the
> documentation I've seen in the Linux community, it's awful.
[..]
I find it rather ironical that your rant should amount to a clumsy
rewording of section 6.1, GNU Manuals, from the GNU Coding Standards:
http://www.gnu.org/prep/standards/html_node/GNU-Manuals.html#GNU-Manuals
In particular:
‘Don’t use Unix man pages as a model for how to write GNU documentation;
most of them are terse, badly structured, and give inadequate
explanation of the underlying concepts.’
CJ
¹ Actually, regarding form rather than content, man pages go back
considerably farther than Robbie the Robot and black and white TV...
some 2,000 years or so... See wiki articles, re: ‘scrolls’ and ‘codex’
for the details.