How to use Python well?

[Roy Smith]

But you can't seriously say that authoring HTML is effective.

By hand? No of course not. That's why we have things like wikis and
CMS's, markup languages like ReST, TeX-to-HTML converters, and so on.

But, we're getting way off topic for a Python forum. The original
question was along the lines of "How do I write good Python?". I think
we're all in agreement that somewhere in the answer to that has to be,
"Provide documentation which is useful to your users, and keep it
updated as the code changes". Beyond that, I think we need to move this
to comp.text.religion.

 

[Cameron Simpson]

| In article <[email protected]>,
|
| > 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.

But HTML is just presentation. There are _plenty_ of manual page
renderers that write HTML. (Example: http://www.FreeBSD.org/cgi/man.cgi)
Complete with clickable links to other manual pages etc. That can all
be done automatically. And has _nothing_ to do with the source being in
nroff format. And the source needn't be in nroff format, either. I have
a bunch of man pages in POD format, which renders to an assortment of
formats including nroff output.

Your argument above is a fine argument for saying that HTML is a very
valuable presentation format, especially if well cross referenced.
But it is irrelevant to the usefulness of man pages.

| 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.

Any yet I (and others, based on stuff I've seen) find info to be a
disaster. Why?

- it forces the reader to use a non-standard pager to look
at info, typically the utterly weird one that comes with the info
command. The user using a terminal _should_ get to use their own pager
because their fingers know how to drive it. Info, in its tiny pieces
of text linked to other tiny pieces of text form, does not lend itself
to this and the browser it does offer on a terminal is arcane.

But see below (*).

- the info pages end up as a scattering of tiny cross linked (if
you're lucky) pieces with little information on one place/page.
So you can't, for example, stand at the top of the doco page and
search for a term.

Frankly, info is usually a step backward, speaking as a reader.

* I grew enraged at the prevalence of "GNU" unix tools with only info
for doco, and no manual pages or manual pages that said "we don't put
anything useful here, go read the info pages, the stuff here may not
even be maintained" (I'm serious - see the bottom of a lot of the
rather trite manual pages that ship with GNU this/that/the-other).

So enraged that I wrote a couple of tools called info2pod and
info2man that read postcompiled info output (the
binary-mixed-with-text stuff info files ship as, post install)
and join it all up again into a single flat text output that _can_ be
paged and searched. And a modified "man" command that can include info
dirs in the $MANPATH and thus present info as a man page. It is a
little ugly, but at least it clubs info into usability.
Example:

% man screen
1: /usr/share/man/man1/screen.1.bz2
2: /usr/share/info/screen.info-2.bz2
3: /usr/share/info/screen.info-4.bz2
4: /usr/share/info/screen.info-5.bz2
5: /usr/share/info/screen.info-1.bz2
6: /usr/share/info/screen.info-3.bz2
7: /usr/share/info/screen.info.bz2
which entry?

Choosing (1) gets you "man screen" as usual, choosing (7) gets you the
whole screen info stuff flattened and presented as a single page, where
you can _search_ for what you want.

URL: http://www.cskk.ezoshosting.com/cs/css/#key-doc

| 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.

Hard for you, maybe. As someone whole consistently finds well written
(terse yet complete) man pages _much_ more useful than many other supposed
documentation, I find it hard to imagine lack of man pages as other than
a failure.

There are exceptions of course. The python doco at python.org is pretty
good. Wikipedia is often very good. But many wikis and other "rich and
easy to author" systems are awful. Incomplete and badly fragmented.
A lot of that can be laid to "documentation as an afterthought"
mentality, but I also feel that having a manual page as a _single_ item
contributes a lot to getting it all down.

Writing man pages in nroff is a bit tedious (though actually not all
that hard). Generating man pages from POD or some other similarly friendly
format is easy and desirable.

| Except possibly as the automated output of some multi-target
| documentation system which produces them as a by-product of producing
| other, richer, formats.

Tick.

Cheers,

 

[Chris Jones]

On Sat, Feb 19, 2011 at 05:27:24PM EST, Cameron Simpson wrote:

[..]

Any yet I (and others, based on stuff I've seen) find info to be a
disaster. Why?

- it forces the reader to use a non-standard pager to look
at info, typically the utterly weird one that comes with the info
command.

On the rare occcasions I used it, navigation was such an uphill battle
that I often forgot what I was looking for in the first place.

The user using a terminal _should_ get to use their own pager
because their fingers know how to drive it.

I stumbled into this some time ago and never looked back:

https://alioth.debian.org/projects/pinfo/

It was love at first sight since it actually has the good taste to use
by default the same vi-like navigation key bindings I have set up for
myself in the ELinks web browser, which I tend to favor over GUIs
browsers when I'm reading html docs.

When you need to do brutal force searches, you could also take a look at
the vim ‘info’ plugin. On debian distributions, it is part of the
‘vim-scripts’ package and can be invoked by the ‘:Info’ Ex-mode command.
You can then use the ‘:helpgrep’ command to create a list of matches
that you can navigate in the same user-friendly way as you would use for
the Vim help files. In a nutshell, instead of getting cross-eyed trying
to locate the highlighted area on the screen to find the current match
and hit some ‘find next’ button (or use any functionally similar
mechanism) repeatedly, you are presented with a list of all your matches
in their context. It is then just a matter of navigating to the one(s)
that looks more promising and just hit enter to open the corresponding
doc page in another Vim sub-window.

Info, in its tiny pieces of text linked to other tiny pieces of
text form, does not lend itself to this and the browser it does
offer on a terminal is arcane.

That also happens with html docs, with the single page vs. chunked
formats. I have been rather enraged myself when researching something or
other and felt I'd hit the jackpot when I found the perfect document
online, only to have to read through the whole thing anyway because only
the chunked format was available, and save from downloading all the bits
and pieces and somehow recreating the single page version, there was no
way I could run a global search.

My main criticism of the man format is that it does not provide both.

Here's an example. Since I don't write bash scripts on a regular basis,
I often have to refer to the bash documentation. If I use man, I can
search for instance for ‘SHELL BUILTIN’ alright, but the trouble is that
there are about a dozen matches in this giant man page before I actually
get to the ‘SHELL BUILTINS’ section. The info format, on the other hand,
provides and index of the builtins, where I quickly find precisely what
I am looking for.

Generally speaking, I find that man pages are fine for anything that's,
well.. about one page and that I can display on one screen (that's 92
lines on my display) have has major limitations for anything much
longer.

But see below (*).

- the info pages end up as a scattering of tiny cross linked (if
you're lucky) pieces with little information on one place/page.
So you can't, for example, stand at the top of the doco page and
search for a term.

Not sure which particular info manual(s) you are referring to.

There are also info documents that are nicely structured.. with a table
of contents, an index, and sections of manageable proportions that
provided you don't use the ridiculous ‘info’ viewer, make on-screen
reading a pleasure, especially when you have decided to read the manual
cover to cover. GNU/screen is a good example. The gdb manual is another.

Perhaps it's also a matter of who wrote the doc, how good he is at
writing doc, and how much effort he put in designing and writing the
doc. And tools that automate the conversion from man to info and back
may also have something to do with this sorry state of affairs.

Frankly, info is usually a step backward, speaking as a reader.

I am also speaking as a reader and I find that both the man and the info
format (and html as well, for that matter) have their merits, and it's
a question of choosing the right format, depending on the circumstances
and what you are trying to do.

* I grew enraged at the prevalence of "GNU" unix tools with only info
for doco, and no manual pages or manual pages that said "we don't put
anything useful here, go read the info pages, the stuff here may not
even be maintained" (I'm serious - see the bottom of a lot of the
rather trite manual pages that ship with GNU this/that/the-other).

Same here... Especially when adding insult to injury, your favorite
distribution ships a man page that directs you to the info manual, but
does not ship the info version due to licensing disagreements, and you
have to download the info version from gnu.org, create your own debian
package.. etc. etc. Depending on the particular info manual, this can be
quite tricky, since the procedure is not well-documented and rather
buggy.

So enraged that I wrote a couple of tools called info2pod and
info2man that read postcompiled info output (the
binary-mixed-with-text stuff info files ship as, post install) and
join it all up again into a single flat text output that _can_ be
paged and searched. And a modified "man" command that can include
info dirs in the $MANPATH and thus present info as a man page. It is
a little ugly, but at least it clubs info into usability. Example:

% man screen
1: /usr/share/man/man1/screen.1.bz2
2: /usr/share/info/screen.info-2.bz2
3: /usr/share/info/screen.info-4.bz2
4: /usr/share/info/screen.info-5.bz2
5: /usr/share/info/screen.info-1.bz2
6: /usr/share/info/screen.info-3.bz2
7: /usr/share/info/screen.info.bz2
which entry?

Choosing (1) gets you "man screen" as usual, choosing (7) gets you the
whole screen info stuff flattened and presented as a single page, where
you can _search_ for what you want.

URL: http://www.cskk.ezoshosting.com/cs/css/#key-doc

Sounds more mature than my own messy ‘solutions’ to this problem.

| 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.

Hard for you, maybe. As someone whole consistently finds well written
(terse yet complete) man pages _much_ more useful than many other
supposed documentation, I find it hard to imagine lack of man pages as
other than a failure.

In an ideal doc world and where ‘program’ is a non-trivial piece of
software, I would like to be able to think of ‘program --help’ as the
condensed reference card, ‘man program’ as the detailed reference card,
and.. something like info, html, etc. as the user guide, and depending
on what I am doing, the bases would be covered.

There are exceptions of course. The python doco at python.org is
pretty good. Wikipedia is often very good. But many wikis and other
"rich and easy to author" systems are awful. Incomplete and badly
fragmented. A lot of that can be laid to "documentation as an
afterthought" mentality, but I also feel that having a manual page as
a _single_ item contributes a lot to getting it all down.

Apples and oranges.. In the same spirit as Westley Martínez nicely put
it a few posts back in this thread, my personal experience has led me to
regard wiki's as just a tiny step up from having to google mailing
list's archives and.. many steps backward from man or info.

Writing man pages in nroff is a bit tedious (though actually not all
that hard). Generating man pages from POD or some other similarly
friendly format is easy and desirable.

Nothing as nice as man pages written from scratch, but I've had good
results with ‘help2man’.

cj

 

[Grant Edwards]

On Sat, Feb 19, 2011 at 05:27:24PM EST, Cameron Simpson wrote:

[..]

Any yet I (and others, based on stuff I've seen) find info to be a
disaster. Why?

- it forces the reader to use a non-standard pager to look
at info, typically the utterly weird one that comes with the info
command.

On the rare occcasions I used it, navigation was such an uphill battle
that I often forgot what I was looking for in the first place.

I've lost track of how many times I've tried to learn to use the Gnu
"info" command and gave up in frustration. I've never seen a program
with a more difficult to use UI. Breaking up the manuals into
uselessly small chunks is just the icing on top of the mud cake.

 

[Anssi Saari]

I've lost track of how many times I've tried to learn to use the Gnu
"info" command and gave up in frustration. I've never seen a program
with a more difficult to use UI.

As I recall, there are other info viewers like tkinfo for example. But
really, how hard is the basic info? Enter to go down a topic, u or l
to back, s for search? Seems simple enough for me.

What's really annoying is when the man page for a program finishes
with a boilerplate announcement that the info version of the
documentation is more complete. And yet, all the info version is, is
the same manual page, including the same boilerplate...