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 -- http://mail.python.org/mailman/listinfo/python-list
