In article <878vxcbudn....@benfinney.id.au>, Ben Finney <ben+pyt...@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.
-- http://mail.python.org/mailman/listinfo/python-list