Those weird info documentations

If you read man pages of free software a lot, you might have stumbled upon a remark such as this:

The full documentation for ls is maintained as a Texinfo manual. If the info and ls programs are properly installed at your site, the command

info coreutils 'ls invocation'

should give you access to the complete manual.

Some free software – mostly¹ just that of the GNU Project – maintains the bulk of its official documentation in a form one may read with a tool called info. If you are like me, you might once have followed a suggestion like the above – only to land in an idiosyncratic hypertext system that frustrated you too much to bother.

Which is a pity, since there is some good documentation to be found that way – often much more comprehensive than what you'll find in the man page pointing you there. Just compare the man page quoted above² with the HTML-ified online version of that "Texinfo manual" it promotes. Often, man pages are mere reference sheets, to quickly look up the names of command line options. The manuals you can read with info are supposed to introduce and explain things in depth.

The info tool is a browser for Info files. These are files of a format optimized for hypertextual documentation of software: documents structured as text that contains internal and external links, which the user may follow to jump around within and between documents. In other words: Info files are like websites.

The Info format predates HTML and the World Wide Web. It's still used in some niches that grew up with, and around it – most notably the GNU and Emacs world. Any manual you can find as an Info file, you most certainly also can find as HTML nowadays. The main advantages of Info files over the HTML versions are:

• they are probably installed on your local system, whereas you might have to search online for the HTML versions
• browsing them with a tool like info may fit into your workflow if you prefer working with terminals and the command line
• browsing them is well-integrated into the Emacs environment, which may come in handy if you're one of those who rarely leave it

The typical Info file sports a .info suffix to its name, and is generated from a source file written in the Texinfo markup language (files of which typically sport .texi suffixes to their names). Texinfo is also easily converted to PDF and HTML, among other target formats. The GNU Project creates most of its documentation in the Texinfo format, packages Info files derived from that with its software releases, and puts HTML variants online.

Texinfo files and Info files derived from them don't look all that different: both contain mostly the same plain text prose. In addition, Texinfo files contain some markup and navigation hints code, which turns into non-printing control characters in the Info files. Both types of files can be browsed as linear text with common plain text pagers (such as less) or editors (such as nano) if one tolerates a few control characters or markup directives scattered throughout. That is obviously not how they are supposed to be read, but it may be sufficient if you don't want to learn special software just to skim a manual.

On Unix systems, Info files are usually installed into a directory such as /usr/share/info/, often compressed (with a .gz suffix to the .info suffix of the filename). A directory of Info files is supposed to contain an Info file named dir or dir.info that contains links to all the other Info files of the directory. Like a web browser that would point to the index.html file of a website's directory by default, an Info browser would point to the dir file as an entrance to the available documents.

Info files are divided into nodes: sections of text that may link to each other. Each Info file starts with a Top node that is supposed to link to the file's other nodes – either directly, or indirectly by linking to nodes that link to other nodes.

Nodes may contain link lists called menus that are supposed³ to link to other nodes as the linking node's children. This creates a hierarchy of nodes: The Top node is parent to a number of child nodes, which themselves are parents to some more nodes, etc. It mirrors the hierarchical structure of books with chapters that have sub-chapters, with each menu node a top-level table of contents for the document section beneath it.

Nodes may also contain non-menu, non-hierarchical links to other nodes, which are called cross-references. They may point to anywhere in the node tree, and even to specific positions in nodes.

Finally, authors may indicate lines in their documentation as explaining specific keywords, concepts etc. From the collection of such markings, indices are auto-generated that link keywords, concept-describing phrases etc. to the respective lines in the nodes of the documentation. An Info file may have different indices for different purposes, such as one for general concepts, one for function names, and one for variable names.

Originally, Info files evolved for, and were browsed by, the text editing environment Emacs. They were – and still are – part of its internal documentation system. A special Emacs "mode" exists to browse Info files. GNU's info tool is a stand-alone variant of that mode for the peripheral demographic of people that do not live and breathe Emacs. In Linux distributions, info is usually available as part of a package called info or texinfo, and probably comes pre-installed.

If you start info without argument, it will display a composite of all dir Info files found in its search path (which combines a built-in default directory, usually /usr/share/info/, with the environment variable INFOPATH). These should link to the Top nodes of other Info files.

You can also point info to a specific Info file by providing that as argument – either by its full or relative path, or (if it is linked to by one of the dir files in info's search path) by its mere name (with or without suffixes). Furthermore, you can point info to start into a specific node by adding a node name to the argument sequence. Thus, the following opens the "ls invocation" node of the coreutils Info file found at /usr/share/info/coreutils.info.gz:

$ info coreutils 'ls invocation'

Inside info, the top and the bottom of the terminal view are dedicated to navigation and metadata bars. These bars should be mostly self-explanatory, but if they are not, feel free to ignore them. The minimum you must know to read and navigate Info files with info is these keybindings:

• arrow keys: move cursor (and move view, if moving against the view's edges)
• Return: follow link under cursor
• u: move to parent node
• l: move backward in sequence of visited nodes (like a web browser's "back" button)

Moving the cursor beyond the start or end of a node's text will move the view into the node that precedes or follows the current node. The meaning of "preceding" and "following" here is quite specific: Nodes may follow each other by their sequence in the Info file, i.e. node B follows node A if node B is defined right below node A in the file text. That is the order of nodes that scrolling through the Info file with arrow keys reproduces.

This sequential order of nodes must not be confused with the order implied by the Prev and Next pointers in the navigation bar on top of the info screen: Just like the Up pointer in the same bar, they indicate family-tree-like relationships. Whereas Up (followed by the u key) points to a parent node, Prev (followed by the p key) and Next (followed by the n key) point to sibling nodes, i.e. nodes that share the parent with the current node. These might be equal to the nodes preceding and following the current node in the internal node sequence of the Info file. But moving to the "following" node by arrow key might just as well hit a node that is the current node's child, or its parent's or grand-parent's next sibling.

I also found these keybindings pretty useful:

• Page up and Page down: move cursor up or down a screenful
• Tab and Shift+Tab: move cursor to next or previous link
• / (Forward slash): find next match in Info file for a regex you will be prompted for
• { and } (curly braces): continue search for strings summoned by the Forward slash key up or down
• q: quit info

The h key will pop up (and close again) a list of many more keybindings. You might find some of these useful too. One prominent feature documented here that I rarely use are the indices (which to me are made mostly redundant by the full-text search), available via:

• i: prompt for an index entry name (with tab-completion available) to follow
• I: prompt for a string, and generate a menu of index entries whose names contain that string