How to use Python well?

[Roy Smith]

In article <878vxcbudn.fsf at benfinney.id.au>,
 Ben Finney <ben+python at benfinney.id.au> wrote:

> This collection of a great deal of documentation for the operating
> system into a single “manual” is one reason why users like man pages so
> much: we want to find anything installed on the system documented in
> that one place.

What made man pages such a great technology back in the 70's was exactly 
what Ben is saying.  Everything was on-line and instantly available for 
quick reference.  Not to mention that you could use man as just another 
cog in the unix toolset and do things like grep all of /usr/man for a 
term (or an error message which appeared and you didn't know what had 
produced it).  These were astonishing advances in usability vs. having 
printed manuals (which may or may not have been available to you).

But, today we have such better tools available.  HTML, for example.  
Whether it's a wiki or the generated output of sphinx/doxygen/etc, HTML 
provides for a much richer presentation.  Which is more convenient: 
having the signal(3) man page reference "sigaction(2)" textually, or 
having it be a clickable link that can take me right there?  HTML also 
gives you much greater formatting flexibility than what's still 
basically 35-year old nroff.

If, for whatever reason, you're still wed to plain text, even info gives 
you much better capabilities than man.  At least you get basic stuff 
like menus, document hierarchy, cross-linking, and browsing history.

I'm not saying that help text is the be-all and end-all for 
documentation.  I'm just saying that if you're going to do more than 
help text, it's hard to imagine putting any effort into producing man 
pages.  Except possibly as the automated output of some multi-target 
documentation system which produces them as a by-product of producing 
other, richer, formats.