Texinfo/Info - ArchWiki

Jump to content

# Texinfo/Info

From ArchWiki
< Texinfo

Related articles

- Man page
- Texinfo

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

## Navigating info pages

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:

- A preamble as shown in Texinfo#Preamble boilerplate code
- At least a Top node in the body.

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: concept indices function indices variable indices user-defined index types See info texinfo "Predefined Indices" for more.
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: If one plans to edit the `dir` node `.info` file manually, see Texinfo#Dir node. If one plans to use install-info tool, see Texinfo#install-info.

Categories:

- Document markup languages
- Command-line

Texinfo/Info
Add topic