man > info

Posted Dec 18, 2014 16:50 UTC (Thu) by perlwolf (guest, #46060)
In reply to: man > info by ldo
Parent article: Emacs and changing documentation formats

Exactly.

The main drawback to info format is that it can only be read by the info program with its own nonsensical (to me) key bindings. Whereas man uses whichever pager *I* chose for all of my viewing of long texts with the key bindings I already know. A learning curve of zero wins by a factor of infinity.

Every time I am forced to go to info to read documentation, I spend ten times as much time trying to figure out how to make it work than I do in reading actual documentation. So, I only use info as a absolute last resort. I've never, in all the time since the first info docs came available (yes, I've been using Unix systems that long) used info enough time to actually learn its command line. I've always considered the single fact of required a special program with its own random keystrokes to do a simple task as being an extremely arrogant act in the GNU choice of using info.

man > info

Posted Dec 21, 2014 6:50 UTC (Sun) by madscientist (subscriber, #16861) [Link] (3 responses)

The main drawback to info format is that it can only be read by the info program with its own nonsensical (to me) key bindings.

I really cannot understand this. I've seen many posts similar to this in this thread and I'm still stumped. Hardly any of the criticisms seem accurate to me.

You want to page through the entire manual as a single document? SPC/DEL (like less/more) will page down and back, and at the end of the page they automatically go to the next/previous page, just as you'd expect. Also PgUp/PgDown work the same way. Also arrow keys work the same way.

You want to search the entire document? "s" does that. So does "/" (a la less or vi).

You can't remember a key? "h" gives a quick key reference. So does "?".

These are all the common keys that I would try in any reader program, that work just as I'd expect them to work, and for which I wouldn't need to read any documentation first. I see lots of generic expressions of frustration, but no one is saying exactly what is missing.

Of course there are more advanced operations which don't have direct analogs in other programs... because info has more capabilities than those programs. Things like "i" for searching the index, or "n" (next section), "p" (previous section), "u" (up to parent section), "m" (choose menu item), "t" (top of manual), or "d" (directory of manuals). But if you don't know about these you don't have to use them.

Just about the only common navigation keys not supported by info are vi's hjkl.

So what, pray tell, are these magical keys that everyone expects info to support and are so frustrated when it doesn't, and take ten times as long to discover as it does to read the documentation?

Regarding man pages vs. texinfo manuals; I will definitely agree that man pages are better for some sorts of documentation and that in general, the GNU project does a disservice when they produce anemic man pages that say little more than "read the texinfo manual". Some things are better documented via man pages. However, man pages are reference documentation: that is, they work best when you already have a basic idea of what command you want to use and more or less how it works, but need a refresher on the details. Texinfo documentation is user documentation. Reworking the GNU Emacs manual, for example, into a man page (or even a huge set of man pages) would be excruciating and ridiculous.

As I said in my first reply, I won't pretend texinfo is the greatest markup ever but anyone wanting to move to something else should first ensure that the something else has at least all the capabilities of info. My suspicion is it would take less effort overall to keep texinfo as a markup and fix up the problematic output formats... the HTML output for example could be significantly improved: maybe having a floating menu that followed as you scroll and contained next/previous/up/top/directory buttons and search and index search boxes, plus providing info-like keybindings for keyboard control.

Scrolling

Posted Dec 25, 2014 13:47 UTC (Thu) by DigitalBrains (subscriber, #60188) [Link]

While reading a text, I don't scroll with PgUp/PgDn; I scroll with the arrow keys. The more fluid motion of one line at a time helps me keep my orientation, I think. I only use PgUp/PgDn for skipping text, as a poor man's search for the next piece I'm interested in when I can't be bothered to think of a search term or genuinely don't know one.

I think the biggest problem with info I had quite some years ago before I discovered 'pinfo' was simply related to scrolling. Using the arrow keys to scroll is so much in my muscle memory that I felt like a stranger in an unfamiliar, not very friendly environment when it did not work. I was focusing my attention on the text, and kept getting drawn back to having to think about navigation halfway through a paragraph.

Trying info for the first time in years just now, it does indeed support one-line scrolling with the arrow keys, and there's the very helpful "Press 'h' for help" message. It would be nice if scrolling from one chapter to the next were fluid, though. Now it behaves like PgUp/PgDn at the boundaries. And it does so before I have finished reading the last chapter, whisking away the text I'm reading. The scroll-behaviour=Page Only option mentioned by mchapman is preferable to me now.

By the way, my 'less' does not have Del for PgUp; its help mentions b, ^B, Esc-v and w. The unmentioned PgUp works as well.

man > info

Posted Jan 21, 2015 11:38 UTC (Wed) by bmur (guest, #52954) [Link] (1 responses)

I am also someone who is utterly frustrated by info and I hope all info documents die a horrible firey death.

For comparison, I just did a "man ls" and "info ls".

The man page gives me a nice short description of the command, a synopsis of the syntax, and jumps into the options. Very unix.

Info tells me that ls lists directory content and quickly sends me down a rabbithole. It gets pedantic about files vs directories, locales, and gives me a full paragraph telling me this command has a lot of options. (duh) Maybe all of these details are important. But for me, seeing the command line options are my goal and the edge cases about ls output sorting behavior can be put at the end of the manual.

Pressing the arrow key to scroll down doesn't move the page down. I have to take my focus off of the document and figure out why the down key didn't work. Oh, there is a cursor moving in-page on a read-only document... that seems useless. So I hold the down key to get a page full of keystrokes hoping to find the command line options. At such point the command description disappears and the options start like a new document. My expected behavior was to see it as a continuation of the documentation.

But oh wait, my down key isn't moving the page down anymore. The cursor starts moving from the top and needs another 30 presses to get to the bottom.

If you want to review something you read a few seconds ago, you need 30 up keypresses to move the page up a single line.

This is the hell of using the info command.

If I decide I want to skip a full page ahead, I press the space bar because that is what most standard unix utilities use. Sometimes it was moving me down a page and sometimes I get a blank screen (I have no idea why).

I am curious how info ends the ls manual so hit space a few more times. Before I know it, I'm in the middle of the "cp" info page. ls is gone.

All of these minor things add up to a horrible experience. Imagine if instead of ls, I was trying to get info about a command I was less familiar with. The frustration would be immense.

man > info

Posted Jan 21, 2015 11:55 UTC (Wed) by mpr22 (subscriber, #60784) [Link]

I am curious how info ends the ls manual so hit space a few more times. Before I know it, I'm in the middle of the "cp" info page. ls is gone.

This is because GNU ls is a component of the GNU coreutils suite, and whoever wrote the documentation for GNU coreutils made the IMO completely misguided decision that there should be a single info document covering all the disparate components of coreutils. I'd never noticed this before because I've never used the info documentation for coreutils because every Linux distribution I've ever used has a man page for the programs in coreutils.

Some other info documents (such as the manuals for GCC, Flex, and Bison; if you tell me any of those should be a single man page each, or even a farm of man pages, I will laugh like a hyena and refer you to the reply in the case of Arkell v. Pressdram (1971)) are more sensible.