How to use Python well?

[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