makeinfo is a utility that converts a Texinfo file into an Info
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.
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
makeinfo, which means you can use
makeinfo on machines
that are too small to run Emacs. You can run
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.
texinfo-format-region and the
commands are useful if you cannot run
makeinfo. Also, in some
circumstances, they format short regions or buffers more quickly than
makeinfofrom a Shell
To create an Info file from a Texinfo file, type
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.)
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
you are using, type:
% makeinfo --version
The options are:
@set varin the Texinfo file.
makeinfowill report before exiting (on the assumption that continuing would be useless). The default number of errors that can be reported before
makeinfogives up is 100.
@footnotestylecommand. When the footnote style is `separate',
makeinfomakes a new node containing the footnotes found in the current node. When the footnote style is `end',
makeinfoplaces the footnote references at the end of the current node.
dirto the directory search list for finding files that are included using the
@includecommand. By default,
makeinfosearches only the current directory.
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',
makeinfowill not split up the output file.
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.
makeinfonumbers each footnote sequentially in a single node, resetting the current footnote number to 1 at the start of each node.
@setfilenamecommand found in the Texinfo source. file can be the special token `-', which specifies standard output.
@paragraphindentcommand. The value of indent is interpreted as follows:
makeinfowill make without reporting a warning. If a node has more than this number of references in it,
makeinfowill make the references but also report a warning.
@clear varin the Texinfo file.
makeinfoto display messages saying what it is doing. Normally,
makeinfoonly outputs messages if there are errors or warnings.
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
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.
When you invoke either
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
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
caused the error. See section `Running
make or Compilers Generally' in The GNU Emacs Manual, for more
information about using the
In addition, you can kill the shell in which the
command is running or make the shell buffer display its most recent
makeinfojob created by
makeinfoshell 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
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
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.
makeinfo program is often faster and
provides better error checking (see section Running
makeinfo inside Emacs).
You can format Texinfo files for Info using
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.
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
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-buffer, you cannot
use that Emacs for anything else until the command finishes.)
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
In addition, if the Texinfo file contains more than about 70,000
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
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
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
Go to the first, previous, next, last section, table of contents.