User:MartinMihalkov/Texinfo short

Texinfo, is a documentation system, used for producing both digital and printed information documents. A single source file can produce output in different formats, like Info (used for Info pages), PDF, HTML, DVI, LaTex, EPUB, XML, DocBook, PostScript, and plain text.

Note

The package is called texinfo because the system was originally designed to produce both printed documentation (using the Tex typesetting engine) and online documentation (like info pages from a single source file. See more at Texinfo#Output_formats.

Installation

One should install the texinfo package, which contains the Info documentation system.

Note texinfo is comprised of utilities (called Texinfo processors throughout the article) for converting a source file into an output format, the info standalone program for viewing Info pages, and the texindex utility for sorting index files generated by TeX when processing Texinfo documents.

Information about all tools can be found in the tools' respective manual or info pages.

Conversion

Texifno source files (commonly with the .texi extension) can be used to create outputs in various formats.

Online and printed output formats

Online/hypertext formats - formats for digital reading.
printed formats - the processor adds additional formatting (like page numbers, table of contents, etc.) to make the content suitable for printing.

Conversion tools

The texinfo package comes with several tools for converting files from one format to another.

texi2any (makeinfo)

texi2any or its symlink, makeinfo, is used to convert a .texi source file into all of the output formats mentioned in Texinfo#Output_formats.

The output format is determined by the flag.

Note

By default the output file name will be either the same as the input file name (if there is not a @setfilename command in the source file) or @setfilename will override it. The --output flag overwrites both the input file name and the @setfilename flag. For more information, issue info texi2any --index-search=@setfilename.

$ texi2any --output_format file_name.texi [--output=output_filename]
or
$ makeinfo --output_format file_name.texi [--output=output_filename]

Here is a list of flags:

Flag	Description
`info`	creates an info page. If no flag is specified, this is used by default.
`--html`	creates an HTML page
`--plain-text`	creates a plain-text document
`--xml`	creates an XML document
`--docbook`	creates a DocBook document
`--dvi`	creates a DVI file
`--ps`	creates a PostScript file
`--pdf`	create a PDF document

Other conversion tools

Although texi2any can be used to convert a source file to all supported output formats, there are tools for specific output formats.

Command	Description
`texi2dvi`	translates `.texi` to DVI.
`texi2pdf`	translates `.texi` to PDF.
`pdftexi2dvi`	the same as `texi2pdf`.
`pod2texi`	translates Perl Pod documentation file(s) to Texinfo.

Note More info can be found by by running info tool_name.

texindex

texindex is a utility that sorts index files generated by Tex when processing Texinfo documents.

When using texi2dvi on a .texi file, it produces raw index files (typically with extensions like .cp, .fn, .ky, .pg, .tp, .vr).

texindex reads these raw, unsorted files, sorts the entries alphabetically, and creates new files (with an added suffix, like .cps).

Then TeX runs a second time to read these sorted files and format them into the final printed index in PDF or DVI output.

For more information, one can run info texindex.

Multiple output files

Depending the length and structure of Info and HTML files, makeinfo/tex2any may generate multiple output files.

Note

Some formats, like Info and HTML, have a splitting option, while others, like PDF, DVI, PostScript don't have one.

According to the info pages for texinfo, a file is split at about every 300,000 characters for faster searching.

Each of the output files will have the same name and file extension, but will end with a different index. For example an input file test.texi may produce test.info-1, test.info-2, test.info-3, etc.

Tip

It is generally preferred for long files to be split, but if one doesn't want that behaviour, they can disable it with the --no-split option of the makeinfo/texi2any.

For more information issue this terminal command: info texinfo Split

Info pages

Info pages are information documents, created with Texinfo syntax, usually having an .info extension.

They are used to describe the operation and inner workings of a tool or technology. Info pages are utilized for both learning and reference.

Info pages vs man pages

Advantages to 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, 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 Run `info texinfo "Predefined Indices"` in the terminal to see 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. Issue `info texinfo "Marking Text"` in the terminal to see more.
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 navigationn	There are keybindings for navigating the document. One can move between nodes, jump to indices, follow references, etc. See more.
Custom key bindings	All key bindings in the info system can be reconfigured in the ~/.keyinfo file. See more.
Man page fallback	Although most GNU tools have an info page, some utils 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 to 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 consice, it can be easier to use them as a syntax reference.
Compatibility	Linux distributions], including Arch_Linux include the man-db package, but not the texinfo package out of the box.

Accessing info pages

Note

If a local file is specified for info_page, 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.

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 man, Info does not have tools like whatis(1) and apropos(1). Instead one can search through all the indices in all info documents on the system:

$ info --apropos=regular_expression
or
$ info -k=regular_expression

Finding paths of info pages

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

$ info --where

Navigating info pages

Note All of the key bindings shown are the default ones. All of them can be overridden with the ~/.infokey file (MORE ON THAT BELOW).

Keybinding	Function
`arrow keys`	Moves cursor by one position
`Ctrl+p`, `Ctrl+n`, `Ctrl+b` and `Ctrl+f`	Moves cursor by one position
`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".

Integrating .info files into the info system

Note This section is only intended for users, interested in making their local info pages, globally or partially-globally accessible with the info system. If one does not plan to use Texinfo for creating info pages, or is not interested in globalizing their info pages, can safely skip this section.

This section assumes that the reader already has .info pages that can be opened using the info command from the file's local directory.

To make the local info pages accessible from everywhere on the system the user wants, generated files (see Texinfo#Multiple_output_files), should be placed in one of several special directories.

Default special directories

These are the two main directories, info will look at when searching globally for info pages, ordered by their priority:

/usr/share/info/
/usr/local/share/info

Custom special directories

One can create a set of special directories per user by setting the INFOPATH environment variable.

By default it is empty, so the default order, shown in Texinfo#Default_special_directories is used.

Integrate info file in the dir node

If added to one of the special directories, info pages may be accessible globally, but they aren't accessible from the dir node by default.

To make the new info pages accessible, one has two options:

Edit the dir node .info file (/usr/share/info/dir) manually, by adding new menu entries in the @menu block (more information can be read by issuing info texinfo -n "Menus" in the terminal).
Use the install-info command, which automatically adds entries to the dir node by looking at the @dircategory and @direntry commands (more on that at issuing info texinfo dircategory in the terminal).

Note

The install-info command is part of the texinfo package.

install-info

The syntax of install-info is the following:

$ sudo install-info path-to-main-info-file-being-integrated path-to-dir-node-file

path-to-main-info-file-being-integrated - if one has multiple output files, they should only write the path to a file with the common name and file extension of all, but ommit the index at the end, and if the files are compressed, one may also include the .gz extension.
path-to-dir-node-file - usually this is /usr/share/info/dir, but a custom dir node file may be provided.

More information on install-info can be found by running info install-info.

Note

Sudo permissions are usually required for the install-info command, because the command should be able to edit dir node file, which may be have write access available only for the root user.

Troubleshooting info pages

Problem	What to do
Unchanging result	One should 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 can locally	One should check the `INFOPATH` environment variable for possible misconfigurations. For more info on that, the reader can check Texinfo#Custom_special_directories
Page can not be accessed from the dir node, but can globally	One should check: If one plans to edit the `dir` node `.info` file manually: If the menu entries are correctly written. More information can be found by issuing the terminal command: `info texinfo -n "Menus"` for syntax on menu entries. If one plans to use `install-info` tool: If they have set `@dircategory` and `@direntry` commands in their source file, as `install-info` depends on that. If they are using correct paths for the command arguments. If they are using sudo permissions to run the command, as the files `install-info` is trying to edit might be write-protected.