Creating an Info File

Next: Installing an Info File  Prev: Format and Print Hardcopy

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 contain 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 Install an Info File.

makeinfo Preferred

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 to the shell: is the prompt):

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

Sometimes you will want to specify options. For example, if you wish to discover which version of makeinfo you are using, type:

makeinfo --version
See makeinfo options, for more information.

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 `--' or a letter preceded by `-'. You can use abbreviations for the long option names as long as they are unique.

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

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.

The options are:

-D var
Cause the variable var to be defined. This is equivalent to @set var in the Texinfo file (See set clear value).

--error-limit=limit
Set the maximum number of errors that makeinfo will report before exiting (on the assumption that continuing would be useless); default 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 is 72.

--footnote-style=style
Set the footnote style to style, either `end' for the end node style (the default) 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 (See Footnotes). 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.

--force
Ordinarily, if the input file has errors, the output files are not created. With this option, they are preserved.

--help
Print a usage message listing all available options, then exit successfully.

-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. It is primarily useful to extract certain pieces of a manual into separate files to be included in a distribution, such as `INSTALL' files.

--no-split
Suppress the splitting stage of makeinfo. By default, large output files (where the size is greater than 70k bytes) are split into smaller subfiles, each one approximately 50k bytes.

--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 Pointer Validation.

--no-warn
Suppress warning messages (but not error messages). 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 (See setfilename). If file is `-', output goes to standard output and `--no-split' is implied.

-P dir
Prepend dir to the directory search list for @include. See `-I' for more details.

--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 (See paragraphindent). The value of indent is interpreted as follows:

`asis'
Preserve any existing indentation at the starts of paragraphs.

`0' or `none'
Delete any existing indentation.

num
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. The default is 1000.

-U var
Cause var to be undefined. This is equivalent to @clear var in the Texinfo file (See set clear value).

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

--version
Print the version number, then exit successfully.

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:

  1. 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.

  2. 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.

  3. Every node except the `Top' node must have an `Up' pointer.

  4. 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.

  5. 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 pressing <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 emacs:Compilation, Running make or Compilers Generally, 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 Texinfo Mode Printing.)

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
emacs:Edit Options, Editing Variable Values,
emacs:Examining, Examining and Setting Variables,
emacs:Init File, and
Options for makeinfo.

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 Catching Mistakes. However, the makeinfo program is often faster and provides better error checking (See makeinfo in 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 emacs:Command Switches, Command Line Switches and Arguments.)

Here is a shell command to format all the files that end in `.texinfo' in the current directory:

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 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 Using Info-validate.