close
Jump to content

Texinfo

From ArchWiki


Related articles

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 (Unix) Info (used for Info pages), PDF, HTML, DVI, LaTex, EPUB, XML, DocBook, PostScript, and plain text. The project name is a combination of the Tex typesetting engine, used for printed documentation, and the info pages online documentation.

The three topics that will be discussed in the article are:

Installation

To follow the guide, install the texinfo package, which provides both the info documentation system and the texi2any Texinfo processor.

Source file

A source file is a plain text file augmented with @-command instructions for the Texinfo processor. This section explains the structure.

Filename convention

The file should be named with the desired name of the output, except when either @setfilename command is used in the source file itself or the --output filename option is used with the makeinfo command. In both of these cases, the default filename will be replaced.

It is recommended that the file ends with the .texi extension, although any or no extension can be used.

Basic structure

Everything is written between \input texinfo and @bye. This allows for the use of @-command commands: 

\input texinfo

@bye

Comments

Comments in Texinfo are lines which start with @c or @comment, followed by space and contain a string which is ignored by the processor. It is useful for adding notes.

Texinfo does not have multiline comments. Instead one should use: 

 
@c  This 
@c   is a
@     multiline
@c     comment.

Preamble

Everything from the start to the first command that renders actual content on the info page is called the preamble.

Output filename

The @setfilename filename command can explicitly set the name of the output file. If this command is omitted, the name of the input will be used for the output file.

Tip The @setfilename command should be placed immediately after \input texinfo
Note

Despite that @setfilename filename overrides the default behavior of using the input file name for the output file, the --output filename option of the makeinfo utility has the biggest priority.

For the output filename, it is recommended that it has an extension matching its type. For example .info for info format, .html for html format, etc.

Note This section only has effect in #Output formats format.

The @settitle title command above adds title to use in a header or footer in the case of printed output. Nothing will be shown in info format. It is recommended to be written right after the @setfilename command if present. See #Output filename.

Note The header and footer title is distinct from the title that will be shown on the title page in printed output.
Directory commands

Directory commands are used for (optionally) #Integrating .info files into the Info system. They link the file into the info system's dir node, the main node of the info system, from which all other nodes can be accessed, and the existing categories.

To integrate the info page, one or more @direntry commands should be specified for one or more @dircategory categories.

These categories and their entries will be added to the * Menu section of the dir node; see also menus.

The syntax is the following: 

@dircategory CATEGORY

@direntry

* NAME-IN-THE-CATEGORY: (TARGET-DOCUMENT) SECTION-OR-SUBNODE-optional. DESCRIPTION

@end direntry
Warning All directory commands must be placed before the first @node command, or install-info would not parse them.

For the category, one can choose either from the already existing categories, or they can specify a new one. The following list shows some of the predefined categories:

  • Interface
  • Internet applications
  • Live communications
  • Localization
  • Mathematics
  • Music
  • Network applications
  • Printing
  • Security
  • Science
  • Software development
  • Software libraries
Note To see all predefined categories, use the info texinfo -n "Directory Category" command in the terminal.

After the page is embedded in the info system, and the dir node is opened with info dir in the terminal, one should see a similar output: 

$ info dir

 

Lines omitted for clarity.

...
* Menu:

CATEGORY:
* NAME-IN-THE-CATEGORY:(TARGET-DOCUMENT)SECTION-OR-SUBNODE-optional.             DESCRIPTION

...

Lines omitted for clarity.
Copying information
Note This section only has effect in printed format.

It is important for editors to add copying information, especially when they plan on making the Texinfo documents publicly accessible.

Copying information can be added with: 

@copying
 COPYRIGHT-INFORMATION-IS-WRITTEN-HERE
@end copying

@copyright{} adds the copyright symbol (©).

Note @copying does not display anything by itself. It will be displayed using @titlepage; see #Title page and copyright page metadata.
Title page and copyright page metadata
Note This section only has effect in printed format.

@titlepage adds and prints metadata for the title page, like document title, subtitle(s), and author(s), and information for the copyright page, like publication information.

Copying information can be inserted in the copyright page using @insertcopying in the @titlepage block. 

@titlepage

@title NAME-OF-MANUAL-WHEN-PRINTED
@subtitle SUBTITLE1
@subtitle SUBTITLE2
@author AUTHOR1
@author AUTHOR2

@page
@vskip 0pt plus 1filll

PPUBLICATION-INFORMATION-optional

@insertcopying

@end titlepage

There must be only a single @title, but there can be one or more @subtitle and @author lines.

@page makes all the following content go to a new page in printed output, so that the title page is separated from the copyright page. @vskip aligns the content that follows on the copyright page.

After that, the publishing information can be added. If using @titlepage, there is not a specialized type for publication that you can use inside the @titlepage block.

Note texinfo 7.3 introduced new commands, like @publication and @documentinfo which make the document structure clearer, but since, version 7.3 was introduced in March 2026, writing documents using the new commands might introduce errors with users relying on older versions of info. More can be read by running info texinfo --index-search documentinfo in the terminal.
Table of contents
Note This section only has effect in printed format.

@contents can be used to display a table of contents of all the chapters, sections and subsections in the document in printed output. Nothing will be shown in info output.

Preamble boilerplate code

For convenience, a template boilerplate code of the preamble can be copied from here: 

\input texinfo

@setfilename filename

@settitle title

@dircategory CATEGORY

@direntry

* NAME-IN-THE-CATEGORY: (TARGET-DOCUMENT) SECTION-OR-SUBNODE-optional. DESCRIPTION

@end direntry

@copying
 COPYRIGHT-INFORMATION-IS-WRITTEN-HERE
@end copying

@titlepage

@title NAME-OF-MANUAL-WHEN-PRINTED
@subtitle SUBTITLE1
@subtitle SUBTITLE2
@author AUTHOR1
@author AUTHOR2

@page
@vskip 0pt plus 1filll

PPUBLICATION-INFORMATION-optional

@insertcopying

@end titlepage

@contents

@bye

Body

The body contains the actual content of a Texinfo document. It starts right after the preamble and ends just before the @bye command. The end of the preamble is denoted by the first element which actually displays something on the screen.

In the #Preamble boilerplate code example above, the body should start right after @contents

To have a functioning document, one should have at least one node, the top node.

Node

A node is a logically separated part of the whole document, which in itself contains chapters, sections and other sub-nodes. A node is created with the @node command.

Top node

In the info format, each node functions as a distinct, navigable page.

In printed format, although the structure looks flat, nodes act as structuring blocks, used when automatically generating the table of contents (in Printed/hardcopy format) or menu (in online/hypertext formats).

Every page has a main node, which is at the top of the document hierarchy. It is called the top node. Every document must have a Top node.

To create a top node, one should use: 

@node NAME
@top NAME-THAT-WILL-APPEAR-ON-THE-DOCUMENT

@node creates a node and everything after it, until the next @node is content of the node. The @top command distinguishes its content.

Chapters, Sections, and Subsections

In every node as many chapters, sections and sub-sections can be written as needed. @chapter name, @section name and @subsection name are used to create a structure inside each node.

Here is an example of a usage of the three commands: 

@chapter name
This is chapter 1.

  @section name
  This is section 1.1.

    @subsection name
    This is subsection 1.1.1.

    @subsection name
    This is subsection 1.1.2.

  @section name
  This is section 1.2.

@chapter name
This is chapter 2.
Note The indentations are not necessary. They are used for clarity.
Other nodes

The content can be distributed into multiple nodes. Although only one note, the Top one, is enough to create a functioning Texinfo document, it is strongly recommended that the content is distributed logically. This allows for generation of table of contents with @contents in printed format and generation of a menu in info format.

Here is an example: 

@node Top
@top Top

@node c1
@chapter Chapter 1
This is chapter 1.

@node s1
@section Section 1.1
This is section 1.1.

A menu is automatically generated, it consists of two parts:

  • a chapter menu, listing only the chapters that are separated in their own nodes.
  • a section menu, listing all the sections and subsections that are separated in different nodes. It starts with — The detailed Node Listing — .

In printed output, the menu appears as table of contents and in Info output, the menu is an interactive list of links, leading to other nodes in the page.

Note

One can create a custom menu or multiple menus that will override the automatically generated one, using @menu. More can be read by running the info texinfo menu command.

File inclusion

By design Texinfo uses a single source file. When creating big documents with a lot of content and a complex hierarchy it generally becomes difficult to manage the content. To simplify and modularize the creation and editing of large documents, one can use file inclusion.

@include 'filename.texi' is used to include a file into another one right at the place where that command is written. One inclusion file can contain on itself multiple inclusion files.

Warning

The way Texinfo includes files is by copying the content of the file being included and pasting it as it is in the file which receives the inclusion. Because of that, users should avoid using basic document functions, like \input texinfo, @bye, @titlepage, etc., in the included files, because that would effectively create a single file with duplicate commands, which is an error.

Indices

Indices or indexes, allow us to index commands, functions, concepts, etc. so that the user can go to the specific piece of information they want.

It is preferred for the author to use indices for the commands, concepts, everything, they want their users to have direct access to the reference.

There are:

  • Predefined index types: concept index, function index, variable index, etc. (see more with info texinfo -s “Predefined Indices”)
  • Custom index types: indices one creates themselves (see more with info texinfo —index-search=”Defining New Indices”)

For example, to create concept index entries, one can use @cindex: 


@node c1
@chapter Chapter 1

@cindex <NAME
Concept 1 - This is the first concept

@node c2
@chapter Chapter 2

@cindex NAME
Concept 2 - This is the second concept

Indices should always precede the content they point to.

The above snippet creates the entries, but it will not show an actual index. To print a specific index type, use: 

@printindex INDEX-TYPE-ABBREVIATION
Note

To see all predefined index type abbreviations, one can use info texinfo -s “Predefined Indices”. For example, the concept index has the cp abbreviation.

Tip

Multiple index tables can be created using the @printindex command several times, but it is recommended to have a single index. To merge several indexes into one, the @synindex command can be used. More info can be shown with info texinfo synindex.

For more information about advanced indexing commands, see info texinfo "Advanced Indexing".

Additional commands

Texinfo has much more functionality than what is described here, but these are the basics for creating a functioning info page with a proper hierarchy.

If the user needs more information for the more complex features of Texinfo, it is suggested that they read the official info pages for Texinfo, using the info texinfo command in the terminal.

Output format conversion

Output formats

Once an user has a source .texi file, it can be converted into the following formats:

  • Online/hypertext formats - formats for digital reading
    • (Unix) Info - info pages use this format and can be opened with the info terminal command.
    • HTML - produces a web page
    • Plain text
    • XML - produces a markup document in XML
    • DocBook - produces a markup document in DocBook
  • Printed/hardcopy formats - formats for reading on a physical carrier:
    • DVI - Produces TeX DVI file
    • PostScript - produces a markup document in PostScript
    • PDF

For printed/hardcopy formats, the processor adds additional formatting to make the content suitable for printing. Some of those additional formatting includes adding page numbers, table of contents, headers and footers.

Conversion tools

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

texi2any (makeinfo)

The texi2any utility or its symlink, makeinfo, is used to convert a .texi source file into all of the output formats mentioned in #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 text plain-text document
--xml creates an XML document
--docbook creates a DocBook document
--dvi creates a independent file format 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, execute info texindex.

Multiple output files

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

Note

Some formats, like Info and HTML, have a splitting option, while others, like PDF, DVI, PostScript do not 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 does not want that behaviour, it can be disableed with the --no-split option of the makeinfo/texi2any tools.

For more information issue the info texinfo Split command.

Compression

For output files in the info format, a user can reduce the size of the output files by compressing them using the gzip tool.

If an user decides to compress the output file(s) and has multiple files, it is recommended to compress all of them or none.

To use the tool, install the gzip package and compress the files: 

$ gzip file1 [file2-optional] [file3-optional]

The compressed files end with the .gz extension.

Note To decompress a file, one can use the --decompress flag of gzip and list the compressed .gz files the same way to decompress it in one command.

Opening an output file

Depending on the file format of the output file, a different tool will be needed to open the file. For example:

  • To open an .info file, the info command can be used.
  • To open an .html file, a browser will be needed.
  • To open a .dvi file, a DVI viewer will be needed.

If in the previous step, multiple output files have been generated, the user can open the whole document by only specifying the common name of all the output files and omitting the index. For example: if one has test.info-1, test.info-2, test.info-3, they can open the whole document using a command like info test.info.

Integrating .info files into the Info system

This section assumes that the reader already has .info pages that can be opened using the info command from the file's local directory. They can (optionally) be made available with the system's Info system.

To make the local info pages accessible system-wide, the generated files (see #Multiple output files), should be placed in one of several special directories.

Tip

If the size of the info pages is big, one can compress them.

Default special directories

These are the two main directories, the info utility will search, 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 #Default special directories is used.

Integrate info file in the dir node

dir node

The dir node is the main node of the whole Info system, just as the top node is the main node of a single document. From the dir node, one can access almost all info pages installed on the system.

Integration

If added to one of the special directories, info pages may be accessible globally, but they are not 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).

install-info

The syntax of install-info is the following: 

# 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, only the path to the file with the common name and file extension is used, omitting the index at the end. For compressed files, 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 the install-info tool 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.

See also

Retrieved from "https://wiki.archlinux.org/index.php?title=Texinfo&oldid=883549"