How to use Python well?
roy at panix.com
Sat Feb 19 04:28:08 CET 2011
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.
More information about the Python-list