Go to the first, previous, next, last section, table of contents.
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 section Installing an Info File.
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.
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.)
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
@set var in the Texinfo file (see section @set, @clear, and @value).
--error-limit=limit
makeinfo will report
before exiting (on the assumption that continuing would be useless);
default 100.
--fill-column=width
--footnote-style=style
@footnotestyle command (see section 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
--help
-I dir
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
--no-split
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
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
--no-number-footnotes
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
@setfilename command found in the
Texinfo source (see section @setfilename). If file is `-', output
goes to standard output and `--no-split' is implied.
-P dir
dir to the directory search list for @include.
See `-I' for more details.
--paragraph-indent=indent
@paragraphindent command (see section Paragraph Indenting). The value
of indent is interpreted as follows:
--reference-limit=limit
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
@clear var in the Texinfo file (see section @set, @clear, and @value).
--verbose
makeinfo to display messages saying what it is doing.
Normally, makeinfo only outputs messages if there are errors or
warnings.
--version
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:
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.
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 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.
makeinfo job created by
makeinfo-region or makeinfo-buffer.
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.
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.
texinfo-format-region
texinfo-format-buffer
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).
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 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.)
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.