Go to the first, previous, next, last section, table of contents.

Creating an Info File

makeinfo is a utility that converts a Texinfo file into an Info file; texinfo-format-region and texinfo-format-buffer are GNU Emacs functions that do the same.

A Texinfo file must possess an @setfilename line near its beginning, otherwise the Info formatting commands will fail.

For information on installing the Info file in the Info system, see section Installing an Info File.

Invoking makeinfo: How to run makeinfo from a shell.
makeinfo options: Specify fill-column and other options.
Pointer Validation: How to check that pointers point somewhere.
makeinfo in Emacs: How to run makeinfo from Emacs.
texinfo-format commands: Two Info formatting commands written in Emacs Lisp are an alternative to makeinfo.
Batch Formatting: How to format for Info in Emacs Batch mode.
Tag and Split Files: How tagged and split files help Info to run better.

The makeinfo utility creates an Info file from a Texinfo source file more quickly than either of the Emacs formatting commands and provides better error messages. We recommend it. makeinfo is a C program that is independent of Emacs. You do not need to run Emacs to use makeinfo, which means you can use makeinfo on machines that are too small to run Emacs. You can run makeinfo in any one of three ways: from an operating system shell, from a shell inside Emacs, or by typing a key command in Texinfo mode in Emacs.

The texinfo-format-region and the texinfo-format-buffer commands are useful if you cannot run makeinfo. Also, in some circumstances, they format short regions or buffers more quickly than makeinfo.

Running `makeinfo` from a Shell

To create an Info file from a Texinfo file, type makeinfo followed by the name of the Texinfo file. Thus, to create the Info file for Bison, type the following at the shell prompt (where `%' is the prompt):

% makeinfo bison.texinfo

(You can run a shell inside Emacs by typing M-x shell.)

Options for `makeinfo`

The makeinfo command takes a number of options. Most often, options are used to set the value of the fill column and specify the footnote style. Each command line option is a word preceded by `--'(12) or a letter preceded by `-'. You can use abbreviations for the option names as long as they are unique.

For example, you could use the following command to create an Info file for `bison.texinfo' in which each line is filled to only 68 columns (where `%' is the prompt):

% makeinfo --fill-column=68 bison.texinfo

You can write two or more options in sequence, like this:

% makeinfo --no-split --fill-column=70 ...

This would keep the Info file together as one possibly very long file and would also set the fill column to 70.

If you wish to discover which version of makeinfo you are using, type:

% makeinfo --version

The options are:

-D var

Cause var to be defined. This is equivalent to @set var in the Texinfo file.

--error-limit limit

Set the maximum number of errors that makeinfo will report before exiting (on the assumption that continuing would be useless). The default number of errors that can be reported before makeinfo gives up is 100.

--fill-column width

Specify the maximum number of columns in a line; this is the right-hand edge of a line. Paragraphs that are filled will be filled to this width. (Filling is the process of breaking up and connecting lines so that lines are the same length as or shorter than the number specified as the fill column. Lines are broken between words.) The default value for fill-column is 72.

--footnote-style style

Set the footnote style to style, either `end' for the end node style or `separate' for the separate node style. The value set by this option overrides the value set in a Texinfo file by an @footnotestyle command. When the footnote style is `separate', makeinfo makes a new node containing the footnotes found in the current node. When the footnote style is `end', makeinfo places the footnote references at the end of the current node.

-I dir

Add dir to the directory search list for finding files that are included using the @include command. By default, makeinfo searches only the current directory.

--no-headers

Do not include menus or node lines in the output. This results in an ASCII file that you cannot read in Info since it does not contain the requisite nodes or menus; but you can print such a file in a single, typewriter-like font and produce acceptable output.

--no-split

Suppress the splitting stage of makeinfo. Normally, large output files (where the size is greater than 70k bytes) are split into smaller subfiles, each one approximately 50k bytes. If you specify `--no-split', makeinfo will not split up the output file.

--no-pointer-validate

--no-validate

Suppress the pointer-validation phase of makeinfo. Normally, after a Texinfo file is processed, some consistency checks are made to ensure that cross references can be resolved, etc. See section Pointer Validation.

--no-warn

Suppress the output of warning messages. This does not suppress the output of error messages, only warnings. You might want this if the file you are creating has examples of Texinfo cross references within it, and the nodes that are referenced do not actually exist.

--no-number-footnotes

Suppress automatic footnote numbering. By default, makeinfo numbers each footnote sequentially in a single node, resetting the current footnote number to 1 at the start of each node.

--output file

-o file

Specify that the output should be directed to file and not to the file name specified in the @setfilename command found in the Texinfo source. file can be the special token `-', which specifies standard output.

--paragraph-indent indent

Set the paragraph indentation style to indent. The value set by this option overrides the value set in a Texinfo file by an @paragraphindent command. The value of indent is interpreted as follows:

If the value of indent is `asis', do not change the existing indentation at the starts of paragraphs.
If the value of indent is zero, delete any existing indentation.
If the value of indent is greater than zero, indent each paragraph by that number of spaces.

--reference-limit limit

Set the value of the number of references to a node that makeinfo will make without reporting a warning. If a node has more than this number of references in it, makeinfo will make the references but also report a warning.

-U var

Cause var to be undefined. This is equivalent to @clear var in the Texinfo file.

--verbose

Cause makeinfo to display messages saying what it is doing. Normally, makeinfo only outputs messages if there are errors or warnings.

--version

Report the version number of this copy of makeinfo.

Pointer Validation

If you do not suppress pointer-validation, makeinfo will check the validity of the final Info file. Mostly, this means ensuring that nodes you have referenced really exist. Here is a complete list of what is checked:

If a `Next', `Previous', or `Up' node reference is a reference to a node in the current file and is not an external reference such as to `(dir)', then the referenced node must exist.
In every node, if the `Previous' node is different from the `Up' node, then the `Previous' node must also be pointed to by a `Next' node.
Every node except the `Top' node must have an `Up' pointer.
The node referenced by an `Up' pointer must contain a reference to the current node in some manner other than through a `Next' reference. This includes menu entries and cross references.
If the `Next' reference of a node is not the same as the `Next' reference of the `Up' reference, then the node referenced by the `Next' pointer must have a `Previous' pointer that points back to the current node. This rule allows the last node in a section to point to the first node of the next chapter.

Running `makeinfo` inside Emacs

You can run makeinfo in GNU Emacs Texinfo mode by using either the makeinfo-region or the makeinfo-buffer commands. In Texinfo mode, the commands are bound to C-c C-m C-r and C-c C-m C-b by default.

C-c C-m C-r
M-x makeinfo-region: Format the current region for Info.
C-c C-m C-b
M-x makeinfo-buffer: Format the current buffer for Info.

When you invoke either makeinfo-region or makeinfo-buffer, Emacs prompts for a file name, offering the name of the visited file as the default. You can edit the default file name in the minibuffer if you wish, before typing RET to start the makeinfo process.

The Emacs makeinfo-region and makeinfo-buffer commands run the makeinfo program in a temporary shell buffer. If makeinfo finds any errors, Emacs displays the error messages in the temporary buffer.

You can parse the error messages by typing C-x ` (next-error). This causes Emacs to go to and position the cursor on the line in the Texinfo source that makeinfo thinks caused the error. See section `Running make or Compilers Generally' in The GNU Emacs Manual, for more information about using the next-error command.

In addition, you can kill the shell in which the makeinfo command is running or make the shell buffer display its most recent output.

C-c C-m C-k
M-x makeinfo-kill-job: Kill the current running makeinfo job created by makeinfo-region or makeinfo-buffer.
C-c C-m C-l
M-x makeinfo-recenter-output-buffer: Redisplay the makeinfo shell buffer to display its most recent output.

(Note that the parallel commands for killing and recentering a TeX job are C-c C-t C-k and C-c C-t C-l. See section Formatting and Printing in Texinfo Mode.)

You can specify options for makeinfo by setting the makeinfo-options variable with either the M-x edit-options or the M-x set-variable command, or by setting the variable in your `.emacs' initialization file.

For example, you could write the following in your `.emacs' file:

(setq makeinfo-options 
      "--paragraph-indent=0 --no-split 
       --fill-column=70 --verbose")

For more information, see section Options for makeinfo, as well as "Editing Variable Values,""Examining and Setting Variables," and "Init File" in the The GNU Emacs Manual.

The `texinfo-format...` Commands

In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo file with the texinfo-format-region command. This formats the current region and displays the formatted text in a temporary buffer called `*Info Region*'.

Similarly, you can format a buffer with the texinfo-format-buffer command. This command creates a new buffer and generates the Info file in it. Typing C-x C-s will save the Info file under the name specified by the @setfilename line which must be near the beginning of the Texinfo file.

C-c C-e C-r
texinfo-format-region: Format the current region for Info.
C-c C-e C-b
texinfo-format-buffer: Format the current buffer for Info.

The texinfo-format-region and texinfo-format-buffer commands provide you with some error checking, and other functions can provide you with further help in finding formatting errors. These procedures are described in an appendix; see section Formatting Mistakes. However, the makeinfo program is often faster and provides better error checking (see section Running makeinfo inside Emacs).

Batch Formatting

You can format Texinfo files for Info using batch-texinfo-format and Emacs Batch mode. You can run Emacs in Batch mode from any shell, including a shell inside of Emacs. (See section `Command Line Switches and Arguments' in The GNU Emacs Manual.)

Here is the command to format all the files that end in `.texinfo' in the current directory (where `%' is the shell prompt):

% emacs -batch -funcall batch-texinfo-format *.texinfo

Emacs processes all the files listed on the command line, even if an error occurs while attempting to format some of them.

Run batch-texinfo-format only with Emacs in Batch mode as shown; it is not interactive. It kills the Batch mode Emacs on completion.

batch-texinfo-format is convenient if you lack makeinfo and want to format several Texinfo files at once. When you use Batch mode, you create a new Emacs process. This frees your current Emacs, so you can continue working in it. (When you run texinfo-format-region or texinfo-format-buffer, you cannot use that Emacs for anything else until the command finishes.)

Tag Files and Split Files

If a Texinfo file has more than 30,000 bytes, texinfo-format-buffer automatically creates a tag table for its Info file; makeinfo always creates a tag table. With a tag table, Info can jump to new nodes more quickly than it can otherwise.

In addition, if the Texinfo file contains more than about 70,000 bytes, texinfo-format-buffer and makeinfo split the large Info file into shorter indirect subfiles of about 50,000 bytes each. Big files are split into smaller files so that Emacs does not need to make a large buffer to hold the whole of a large Info file; instead, Emacs allocates just enough memory for the small, split off file that is needed at the time. This way, Emacs avoids wasting memory when you run Info. (Before splitting was implemented, Info files were always kept short and include files were designed as a way to create a single, large printed manual out of the smaller Info files. See section Include Files, for more information. Include files are still used for very large documents, such as The Emacs Lisp Reference Manual, in which each chapter is a separate file.)

When a file is split, Info itself makes use of a shortened version of the original file that contains just the tag table and references to the files that were split off. The split off files are called indirect files.

The split off files have names that are created by appending `-1', `-2', `-3' and so on to the file name specified by the @setfilename command. The shortened version of the original file continues to have the name specified by @setfilename.

At one stage in writing this document, for example, the Info file was saved as `test-texinfo' and that file looked like this:

Info file: test-texinfo,    -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo

^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...

(But `test-texinfo' had far more nodes than are shown here.) Each of the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and `test-texinfo-3', is listed in this file after the line that says `Indirect:'. The tag table is listed after the line that says `Tag table:'.

In the list of indirect files, the number following the file name records the cumulative number of bytes in the preceding indirect files, not counting the file list itself, the tag table, or the permissions text in each file. In the tag table, the number following the node name records the location of the beginning of the node, in bytes from the beginning.

If you are using texinfo-format-buffer to create Info files, you may want to run the Info-validate command. (The makeinfo command does such a good job on its own, you do not need Info-validate.) However, you cannot run the M-x Info-validate node-checking command on indirect files. For information on how to prevent files from being split and how to validate the structure of the nodes, see section Running Info-validate.

Go to the first, previous, next, last section, table of contents.