User:MartinMihalkov/Texinfo
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, independent file format DVI, LaTex, EPUB, XML, DocBook, PostScript, and text plain text.
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.
The three topics that will be discussed in the article are:
- Writing a source file in Texinfo (
.texi) format - Converting a (
.texi) file into an output format
Instalation
To follow the guide, one should install the texinfo package, which contains both the info documentation system and the texi2any Texinfo processor.
Source file
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 written for 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 of code 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 doesn't 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
@setfilename filename 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.
@setfilename command should be placed immediately after \input texinfoDespite that @setfilename filename overrides the default behavior of using the input file name for the output file, the --output filename option of the makeinfo command 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.
Header and footer title
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 recomended for that command to be written right after @setfilename
command if present. See here.
Directory commands
info format.If the user is planning to create info pages, it is recommended that they integrate their info page into the info's dir node, the main node of the info system, from which all other nodes can be accessed.
This can be done either by editing the dir info file manually (located at /usr/share/info/dir or by using the install-info command.
To integrate the info page using install-info, 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 more on menus.
The syntax is the following:
@dircategory CATEGORY @direntry * NAME-IN-THE-CATEGORY: (TARGET-DOCUMENT) SECTION-OR-SUBNODE-optional. DESCRIPTION @end direntry
@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
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 (©).
@copying does not display anything by itself. It will be displayed using @titlepage.
Title page and copyright page metadata
@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 @insetcopying 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 isn't a specialized type for publication that you can use inside the @titlepage block.
@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
@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:
| Preamble boilerplate code: |
|---|
\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 is starts right after the preamble and just before the @bye. The end of the preamble is denoted by the first element which actually displays someting on the screen.
In the Texinfo#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 on 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 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 considered part of the contents of the node. To say that one node is the top node, the @top command is written in the node's contents.
Chapters, Sections, and Subsections
In every node chapters, sections and in the sections - as many sub-sections can be written as the editor needs. @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 1.
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.
Menu
A menu is automatically generated, which 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 is starts with
— The detailed Node Listing —.
In printed output, the menu appears as table of contents and in Info output, the menu is interactive list of links, leading to other nodes in the page.
One can create a custom menu or multiple menus that will override the automatically generated one, using @menu. More can be read by running info texinfo menu command.
File inclusion
By design Texinfo uses a single source file. When creating big documents with a lots 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.
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 preffered for the author to use indices for the commands, concepts, everything, they want their users to have direct access to for 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 be put before the content they point to.
The above snippet creates the entries, but it won’t show an actual index. To print a specific index type, use:
@printindex INDEX-TYPE-ABBREVIATION
To see all predefined index type abbreviations, one can use info texinfo -s “Predefined Indices”. For example, the concept index has the “cp” abbreviation.
Multiple index tables can be created using the @printindex command several times, but it is reccomented 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, one can use 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 complext 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
infoterminal command. - HTML - produces a web page
- text Plain text
- XML - produces a markup document in XML
- DocBook - produces a markup document in DocBook
- (Unix) Info - info pages use this format and can be opened with the
- Printed/hardcopy formats - formats for reading on a physical carrier:
- independent file format DVI - Produces TeX DVI file
- PostScript - produces a markup document in PostScript
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)
texi2any or its link| 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.
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. |
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.
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.
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
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 of them.
To use the tool, one would need to install the gzip package.
To compress the files, the following terminal command should be issued:
$ gzip file1 [file2-optional] [file3-optional]
Multiple files can be compressed with one command by listing them one ofther another.
Now compressed files end with the .gz extension.
--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
.infofile, theinfocommand can be used.
- To open an
.htmlfile, a browser will be needed.
- To open a
.dvifile, 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.
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.
If the size of the info pages is big, one can compress them, using gzip and place the compressed file into a special directory.
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
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 aren't accessible from the dir node by default.
To make the new info pages accessible, one has two options:
- Edit the
dirnode.infofile (/usr/share/info/dir) manually, by adding new menu entries in the@menublock (more information can be read by issuinginfo texinfo -n "Menus"in the terminal). - Use the
install-infocommand, which automatically adds entries to the dir node by looking at the@dircategoryand@direntrycommands (more on that at issuinginfo texinfo dircategoryin the terminal).
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.gzextension.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.
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.