Jump to content

Texinfo/Info

From ArchWiki

Related articles

An Info page can be opened and browsed using the info utility, included in the texinfo package.

It is a document, written in the Texinfo markup language, used for description and reference of the purpose, operation and syntax of software utilities, system and library calls, file formats and conventions, and other objects of interest. Info pages are similar to man pages, but introduce additional features for fast navigation, better searching and document organization. Notably, the info utility can be used to read and navigate man pages as well.

This article focusses on accessing, searching and navigating the Info documentation system, as well as the basic steps to write an info page. See #Info pages vs man pages for a comparison to manual pages.

Accessing info pages

Note

If an .info file from the same directory is specified for opening with info, then it will be opened, however if there is both a local file and a globally accessible page with the same name, the latter will be opened. Similarly, if a package provides both an Info and a manual page, the Info page will be opened. If there is no Info page for a package, an available manual page will be accessed.

What to access Command
The top node of a page info info-page
The dir node 
$ info
or
$ info dir
An index in a page info info-page --index-search=index name
A node in a page 
$ info info-page --node=node-name
or
$ info info-page node-name
All matching pages info package name --all
Note

For info package name --all:

  • With no other flags, the command opens a dynamically created info page, called Info File Index which contains a menu with all the search results. To show that page at any time, one can use Ctrl+x+f by default.
  • If the --where flag is set, info will only print the filepaths of all matching pages.

Searching for info pages

Unlike the man utility, info does not have tools like whatis(1) and apropos(1). Instead one can search through all the indices in all local Info documents: 

$ info --apropos=regular-expression

or 

$ info -k=regular-expression

Finding paths of info pages

To display where an Info page, matching the current command and its flags, is located, one can use: 

$ info --where info-page
Note All of the key bindings shown are the default ones. All of them can be overridden with the ~/.infokey file.
Keybinding Function
arrow keys Moves cursor by one position
Ctrl+p, Ctrl+n, Ctrl+b and Ctrl+f
Space and Shift+Space Scrolling by the height of the page
b and e Go to the beginning or end of a node
Enter Jump to a node or reference.
< and > Go to the first or end of a node
t Go to the top node, the main node in an info page.
d Go the the dir node, the main node in the Info system, from which most of the info pages can be accessed.
u Go to the node that is one level up the hierarchy.
n and p Move to next or previous node on the same hierarchical level. If one reaches the last node in the level, they should move one level up to continue.
[ and ] Move to next or previous node globally.
/ or s Forward search (after the cursor)
? Backward search (before the cursor)
{ (Ctrl+x+p) and } (Ctrl+x+n) Makes the cursor jump to the previous or next match
g Prompts the user for a node name where to redirect the user. Tab is used for autocompletion.
m Prompts the user for a local menu item name to jump to.
1 to 9 Jumps to the menu entry with the specified index.
l Moves the user to the last node, they were at.
Ctrl+x Ctrl+b Opens an info page, with menu entires of the currently visited nodes.
Ctrl+x+b Prompts the user to type the name of an already visited node.
i Prompts the user to type the name of an index in the document.

Custom shortcuts

One can override the default shortcuts, by editing the ~/.infokey file. For more information on that, one can run info info -n "infokey".

Writing an info page

Info pages are written in the Texinfo markup language. Texinfo source files commonly have the .texi extension.

Texinfo#Source file explains the basic Texinfo syntax used to create a functional info page.

The minimal requirements are:

The source file can be easily converted into .info files using one of the tools of the texinfo package (preferably texi2any).

Once created, an info page can be accessed from the directory in which it is located. To be able to access the info page globally, one should integrate the .info file into the Info system.

Note All Info pages included by Arch Linux packages are automatically integrated.

Info pages vs man pages

Advantages of using info pages

Info pages provide several advantages over man pages. They allow the user to:

Feature Description
Nodes Info pages can be divided into smaller logical "sub-pages", called "nodes".
Xrefs References to other nodes or specific places within a node (chapter, section, subsection, paragraph, introduced term, etc.) can be created, called "xrefs".
Menus Each node can contain one or more menus, containing links to other nodes. Menus can be nested as well.
Indices Info pages can contain index tables comprised of indices. Indices can note terms, definitions, functions or other useful information that the user might want to access fast. The most popular index types are:
Complex data types Texinfo provides predefined commands for almost any type of data, like: email, author, code block, file, key binding, definitions, citations, URLs. See info texinfo "Marking Text" for information.
Information thoroughness Info pages often contain much more information than man pages and make it more organized.

Because of that it is often easier to sue info pages not only for reference but for in-depth learning.

Fast navigation There are keybindings for navigating the document. One can move between nodes, jump to indices, follow references, etc.
Custom key bindings All key bindings in the info system can be reconfigured in the ~/.keyinfo file.
Man page fallback Although most GNU tools have an info page, some utilities only have a man page.

If Info does not find the specified info page, it will fallback to the man page with the same name, if there is one.

Advantages of using man pages

The following are viable use cases where man pages might be the better option:

Feature Description
Fast reference Because man pages are often shorter and more concise, it can be easier to use them as a syntax reference.

Troubleshooting info pages

Problem What to do
Unchanging result Exit the Info system, and check if any warnings or errors appear in the shell. More information on Texinfo file syntax can be found at Texinfo#Source file.
Page can not be accessed globally, but locally Check the INFOPATH environment variable for possible misconfiguration. See also Texinfo#Custom special directories.
Page can not be accessed from the dir node, but globally Check: