Re: [Groff] The future redux

[Federico Lucifredi]

On Feb 26, 2014, at 8:19 AM, Ralph Corderoy <address@hidden> wrote:

> Hi Walter,
> 
>> Man pages are not tutorials or complete manuals
> 
> Yes they are, or should be.  They used to be.  I learnt Perl 4 from
> perl(1).  Back then it was a single long man page, well-written by an
> experienced Unix hand, Larry Wall.

Notwithstanding the height of perl (1), Man pages are not meant to be 
treatises. They are meant to be quickly accessed, searchable reference.

There is a very big difference from reading 200 pages sequentially, and 
skimming 10 pages or less looking for a synopsis of what a command does, why, 
and what options it provides, or illustrating examples of how to use something.

While there is a lot to be learned in man pages (or, at least, I would like to 
think so given the time I spent on the topic), that does not make them books on 
the subject.  Many of the longest man pages are not very readable, as the 
terminal is not a comfortable medium to read a very long article.  People also 
tend to search for the relevant option, and very verbose pages backfire on them.

> There was _The Unix Programming Environment_
> which, coming from K&R, was how I learnt Unix existed.

Indeed. And there is a difference between expecting K&R in a man page, or 
reference for printf (3).  I would not want to read K&R in man (1), no matter 
how fond I am of that tool.

Best -F


_________________________________________
-- "'Problem' is a bleak word for challenge" - Richard Fish
(Federico L. Lucifredi) - flucifredi at acm.org - GnuPG 0x4A73884C