There are three major shell commands for making a printed manual from a
Texinfo file: one for converting the Texinfo file into a file that will be
printed, a second for sorting indices, and a third for printing the
formatted document. When you use the shell commands, you can either
work directly in the operating system shell or work within a shell
inside GNU Emacs.

If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands. In addition to the three commands to
format a file, sort the indices, and print the result, Texinfo mode
offers key bindings for commands to recenter the output buffer, show the
print queue, and delete a job from the print queue.

The typesetting program called TeX is used for formatting a Texinfo
file. TeX is a very powerful typesetting program and, if used right,
does an exceptionally good job. (See section How to Obtain TeX, for information on how to obtain TeX.)

The makeinfo, texinfo-format-region, and
texinfo-format-buffer commands read the very same @-commands
in the Texinfo file as does TeX, but process them differently to
make an Info file; see section Creating an Info File.

Format the Texinfo file with the shell command tex followed by
the name of the Texinfo file. For example:

tex foo.texi

TeX will produce a DVI file as well as several auxiliary
files containing information for indices, cross references, etc. The
DVI file (for DeVice Independent file) can be printed on virtually
any printe (see the following sections).

The tex formatting command itself does not sort the indices; it
writes an output file of unsorted index data. (The texi2dvi
command automatically generates indices; see section Format using texi2dvi.) To generate a printed index after
running the tex command, you first need a sorted index to work
from. The texindex command sorts indices. (The source file
`texindex.c' comes as part of the standard Texinfo distribution,
among other places.)

The tex formatting command outputs unsorted index files under
names that obey a standard convention: the name of your main input file
with any `.tex' (or similar, see section `tex invocation' in Web2c) extension removed, followed by the two letter names of indices.
For example, the raw index output files for the input file
`foo.texinfo' would be `foo.cp', `foo.vr', `foo.fn',
`foo.tp', `foo.pg' and `foo.ky'. Those are exactly the
arguments to give to texindex.

Instead of specifying all the unsorted index file names explicitly, you
can use `??' as shell wildcards and give the command in this
form:

texindex foo.??

This command will run texindex on all the unsorted index files,
including any that you have defined yourself using @defindex
or @defcodeindex. (You may execute `texindex foo.??'
even if there are similarly named files with two letter extensions
that are not index files, such as `foo.el'. The texindex
command reports but otherwise ignores such files.)

For each file specified, texindex generates a sorted index file
whose name is made by appending `s' to the input file name. The
@printindex command knows to look for a file of that name
(see section Index Menus and Printing an Index). texindex does not alter the
raw index output file.

After you have sorted the indices, you need to rerun the tex
formatting command on the Texinfo file. This regenerates the DVI file,
this time with up-to-date index entries.

Finally, you may need to run tex one more time, to get the page
numbers in the cross-references correct.

To summarize, this is a four step process:

Run tex on your Texinfo file. This generates a DVI file (with
undefined cross-references and no indices), and the raw index files
(with two letter extensions).

Run texindex on the raw index files. This creates the
corresponding sorted index files (with three letter extensions).

Run tex again on your Texinfo file. This regenerates the DVI
file, this time with indices and defined cross-references, but with page
numbers for the cross-references from last time, generally incorrect.

Run tex one last time. This time the correct page numbers are
written for the cross-references.

Alternatively, it's a one-step process: run texi2dvi.

You need not run texindex each time after you run tex. If
you do not, on the next run, the tex formatting command will use
whatever sorted index files happen to exist from the previous use of
texindex. This is usually ok while you are
debugging.

The texi2dvi command automatically runs both tex and
texindex as many times as necessary to produce a DVI file with
up-to-date, sorted indices. It simplifies the
tex---texindex---tex sequence described in the
previous section.

The syntax for texi2dvi is like this (where `prompt$' is your
shell prompt):

The precise command to print a DVI file depends on your system
installation, but `lpr -d' is common. The command may require the
DVI file name without any extension or with a `.dvi'
extension. (If it is `lpr', you must include the `.dvi'.)

The following commands, for example, will (probably) suffice to sort the
indices, format, and print the Bison Manual:

You can give formatting and printing commands from a shell within GNU
Emacs. To create a shell within Emacs, type M-x shell. In this
shell, you can format and print the document. See section Format and Print Hardcopy, for details.

You can switch to and from the shell buffer while tex is
running and do other editing. If you are formatting a long document
on a slow machine, this can be very convenient.

You can also use texi2dvi from an Emacs shell. For example,
here is how to use texi2dvi to format and print Using and
Porting GNU CC from a shell within Emacs:

Texinfo mode provides several predefined key commands for TeX
formatting and printing. These include commands for sorting indices,
looking at the printer queue, killing the formatting job, and
recentering the display of the buffer in which the operations
occur.

C-c C-t C-b

M-x texinfo-tex-buffer

Run texi2dvi on the current buffer.

C-c C-t C-r

M-x texinfo-tex-region

Run TeX on the current region.

C-c C-t C-i

M-x texinfo-texindex

Sort the indices of a Texinfo file formatted with
texinfo-tex-region.

C-c C-t C-p

M-x texinfo-tex-print

Print a DVI file that was made with texinfo-tex-region or
texinfo-tex-buffer.

C-c C-t C-q

M-x tex-show-print-queue

Show the print queue.

C-c C-t C-d

M-x texinfo-delete-from-print-queue

Delete a job from the print queue; you will be prompted for the job
number shown by a preceding C-c C-t C-q command
(texinfo-show-tex-print-queue).

C-c C-t C-k

M-x tex-kill-job

Kill the currently running TeX job started by
texinfo-tex-region or texinfo-tex-buffer, or any other
process running in the Texinfo shell buffer.

C-c C-t C-x

M-x texinfo-quit-job

Quit a TeX formatting job that has stopped because of an error by
sending an x to it. When you do this, TeX preserves a record
of what it did in a `.log' file.

C-c C-t C-l

M-x tex-recenter-output-buffer

Redisplay the shell buffer in which the TeX printing and formatting
commands are run to show its most recent output.

Thus, the usual sequence of commands for formatting a buffer is as
follows (with comments to the right):

The Texinfo mode TeX formatting commands start a subshell in Emacs
called the `*tex-shell*'. The texinfo-tex-command,
texinfo-texindex-command, and tex-dvi-print-command
commands are all run in this shell.

You can watch the commands operate in the `*tex-shell*' buffer,
and you can switch to and from and use the `*tex-shell*' buffer
as you would any other shell buffer.

The formatting and print commands depend on the values of several variables.
The default values are:

You can change the values of these variables with the M-x
edit-options command (see section `Editing Variable Values' in The GNU Emacs Manual), with the M-x set-variable command
(see section `Examining and Setting Variables' in The GNU Emacs Manual), or with your `.emacs' initialization file
(see section `Init File' in The GNU Emacs Manual).

Yet another way to apply the TeX formatting command to a Texinfo file
is to put that command in a local variables list at the end of the
Texinfo file. You can then specify the tex or texi2dvi
commands as a compile-command and have Emacs run it by typing
M-x compile. This creates a special shell called the
`*compilation*' buffer in which Emacs runs the compile command.
For example, at the end of the `gdb.texinfo' file, after the
@bye, you could put the following:

Local Variables:
compile-command: "texi2dvi gdb.texinfo"
End:

This technique is most often used by programmers who also compile programs
this way; see section `Compilation' in The GNU Emacs Manual.

Every Texinfo file that is to be input to TeX must begin with a
\input command and must contain an @setfilename command:

\input texinfo
@setfilename arg-not-used-by-TeX

The first command instructs TeX to load the macros it needs to
process a Texinfo file and the second command opens auxiliary files.

Every Texinfo file must end with a line that terminates TeX's
processing and forces out unfinished pages:

@bye

Strictly speaking, these lines are all a Texinfo file needs to be
processed successfully by TeX.

Usually, however, the beginning includes an @settitle command to
define the title of the printed manual, an @setchapternewpage
command, a title page, a copyright page, and permissions. Besides an
@bye, the end of a file usually includes indices and a table of
contents. (And of course most manuals contain a body of text as well.)

TeX needs to know where to find the `texinfo.tex' file that you
have told it to input with the `\input texinfo' command at the
beginning of the first line. The `texinfo.tex' file tells TeX
how to handle @-commands; it is included in all standard GNU
distributions.

Usually, the `texinfo.tex' file is put under the default directory
that contains TeX macros
(`/usr/local/share/texmf/tex/texinfo/texinfo.tex' by default) when
GNU Emacs or other GNU software is installed. In this case, TeX will
find the file and you do not need to do anything special.
Alternatively, you can put `texinfo.tex' in the current directory
when you run TeX, and TeX will find it there.

Also, you should install `epsf.tex' in the same place as
`texinfo.tex', if it is not already installed from another
distribution. This file is needed to support the @image command
(see section Inserting Images).

Optionally, you may create an additional `texinfo.cnf', and install
it as well. This file is read by TeX at the @setfilename
command (see section @setfilename). You can put any
commands you like there according to local site-wide conventions, and
they will be read by TeX when processing any Texinfo document. For
example, if `texinfo.cnf' contains the a single line
`@afourpaper' (see section Printing on A4 Paper), then all Texinfo documents will
be processed with that page size in effect. If you have nothing to put
in `texinfo.cnf', you do not need to create it.

If neither of the above locations for these system files suffice for
you, you can specify the directories explicitly. For
`texinfo.tex', you can do this by writing the complete path for the
file after the \input command. Another way, that works for both
`texinfo.tex' and `texinfo.cnf' (and any other file TeX
might read), is to set the TEXINPUTS environment variable in your
`.cshrc' or `.profile' file.

Which you use of `.cshrc' or `.profile' depends on
whether you use a Bourne shell-compatible (sh, bash,
ksh, ...) or C shell-compatible (csh, tcsh)
command interpreter. The latter read the `.cshrc' file for
initialization information, and the former read `.profile'.

In a `.cshrc' file, you could use the following csh command
sequence:

setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros

In a `.profile' file, you could use the following sh command
sequence:

TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
export TEXINPUTS

This would cause TeX to look for `\input' file first in the current
directory, indicated by the `.', then in a hypothetical user's
`me/mylib' directory, and finally in a system directory.

TeX is sometimes unable to typeset a line without extending it into
the right margin. This can occur when TeX comes upon what it
interprets as a long word that it cannot hyphenate, such as an
electronic mail network address or a very long title. When this
happens, TeX prints an error message like this:

Overfull \hbox (20.76302pt too wide)

(In TeX, lines are in "horizontal boxes", hence the term, "hbox".
The backslash, `\', is the TeX equivalent of `@'.)

TeX also provides the line number in the Texinfo source file and
the text of the offending line, which is marked at all the places that
TeX knows how to hyphenate words.
See section Catching Errors with TeX Formatting,
for more information about typesetting errors.

If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur, or you can decide to leave it. A
small excursion into the right margin often does not matter and may not
even be noticeable.

However, unless told otherwise, TeX will print a large, ugly, black
rectangle beside the line that contains the overfull hbox. This is so
you will notice the location of the problem if you are correcting a
draft.

To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
before the @titlepage command:

By default, TeX typesets pages for printing in an 8.5 by 11 inch
format. However, you can direct TeX to typeset a document in a 7 by
9.25 inch format that is suitable for bound books by inserting the
following command on a line by itself at the beginning of the Texinfo
file, before the title page:

@smallbook

(Since regular sized books are often about 7 by 9.25 inches, this
command might better have been called the @regularbooksize
command, but it came to be called the @smallbook command by
comparison to the 8.5 by 11 inch format.)

If you write the @smallbook command between the
start-of-header and end-of-header lines, the Texinfo mode TeX
region formatting command, texinfo-tex-region, will format the
region in "small" book size (see section Start of Header).

The Free Software Foundation distributes printed copies of The GNU
Emacs Manual and other manuals in the "small" book size.
See section @smallexample and @smalllisp, for information about commands that make it easier
to produce examples for a smaller manual.

Alternatively, to avoid embedding this physical paper size in your
document, use texi2dvi to format your document (see section Format using texi2dvi), and supply `-t @smallbook' as an argument. Then
other people do not have to change the document source file to format it
differently.

You can tell TeX to typeset a document for printing on European size
A4 paper with the @afourpaper command. Write the command on a
line by itself between @iftex and @end iftex lines near
the beginning of the Texinfo file, before the title page:

Alternatively, to avoid embedding this physical paper size in your
document, use texi2dvi to format your document (see section Format using texi2dvi), and supply `-t @afourpaper' as an argument. Then
other people do not have to change the document source file to format it
differently.

Another alternative: put the @afourpaper command in the file
`texinfo.cnf' that TeX will read. (No need for @iftex
there.) This will automatically typeset all the Texinfo documents at
your site with that paper size in effect.

You can attempt to direct TeX to print cropmarks at the corners of
pages with the @cropmarks command. Write the @cropmarks
command on a line by itself between @iftex and @end
iftex lines near the beginning of the Texinfo file, before the title
page, like this:

@iftex
@cropmarks
@end iftex

This command is mainly for printers that typeset several pages on one
sheet of film; but you can attempt to use it to mark the corners of a
book set to 7 by 9.25 inches with the @smallbook command.
(Printers will not produce cropmarks for regular sized output that is
printed on regular sized paper.) Since different printing machines work
in different ways, you should explore the use of this command with a
spirit of adventure. You may have to redefine the command in the
`texinfo.tex' definitions file.

You can attempt to direct TeX to typeset pages larger or smaller than
usual with the \mag TeX command. Everything that is typeset
is scaled proportionally larger or smaller. (\mag stands for
"magnification".) This is not a Texinfo @-command, but is a
plain TeX command that is prefixed with a backslash. You have to
write this command between @tex and @end tex
(see section Raw Formatter Commands).

Follow the \mag command with an `=' and then a number that
is 1000 times the magnification you desire. For example, to print pages
at 1.2 normal size, write the following near the beginning of the
Texinfo file, before the title page:

@tex
\mag=1200
@end tex

With some printing technologies, you can print normal-sized copies that
look better than usual by using a larger-than-normal master.

Depending on your system, \mag may not work or may work only at
certain magnifications. Be prepared to experiment.