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.
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. This command produces a formatted
DVI file as well as several auxiliary files containing indices,
cross references, etc. The DVI file (for DeVice Independent
file) can be printed on a wide variety of printers.
tex formatting command itself does not sort the indices; it
writes an output file of unsorted index data. This is a misfeature of
texi2dvi command automatically generates indices;
see section Format using
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 GNU distribution and is usually installed when Emacs is
tex formatting command outputs unsorted index files under
names that obey a standard convention. These names are the name of
your main input file to the
tex formatting command, with
everything after the first period thrown away, and the two letter
names of indices added at the end. 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
Or else, you can use `??' as "wild-cards" and give the command in this form:
This command will run
texindex on all the unsorted index files,
including any that you have defined yourself using
@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
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.
texindex does not alter the raw index output file.
After you have sorted the indices, you need to rerun the
formatting command on the Texinfo file. This regenerates a formatted
DVI file with up-to-date index entries.(11)
To summarize, this is a three step process:
texformatting command on the Texinfo file. This generates the formatted DVI file as well as the raw index files with two letter extensions.
texindexon the raw index files to sort them. This creates the corresponding sorted index files.
texformatting command on the Texinfo file. This regenerates a formatted DVI file with the index entries in the correct order. This second run also corrects the page numbers for the cross references. (The tables of contents are always correct.)
You need not run
texindex each time after you run the
tex formatting. If you do not, on the next run, the
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.
texi2dvi command is a shell script that automatically runs
texindex as many times as necessary to
produce a DVI file with up-to-date, sorted indices. It simplifies
tex sequence described in the
The syntax for
texi2dvi is like this (where `prompt$' is the
prompt$ texi2dvi filename...
You can print a DVI file with the DVI print command. The precise printing command to use depends on your system; `lpr -d' is common. The DVI print command may require a file name without any extension or with a `.dvi' extension.
The following commands, for example, sort the indices, format, and print the Bison Manual (where `%' is the shell prompt):
% tex bison.texinfo % texindex bison.?? % tex bison.texinfo % lpr -d bison.dvi
(Remember that the shell commands may be different at your site; but these are commonly used versions.)
texi2dvi shell script, you simply need type:
% texi2dvi bison.texinfo % lpr -d bison.dvi
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
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 (where `%' is the shell
% texi2dvi gcc.texinfo % lpr -d gcc.dvi
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.
texi2dvion the current buffer.
texinfo-tex-buffer, or any other process running in the Texinfo shell buffer.
Thus, the usual sequence of commands for formatting a buffer is as follows (with comments to the right):
C-c C-t C-b Run
texi2dvion the buffer. C-c C-t C-p Print the DVI file. C-c C-t C-q Display the printer queue.
The Texinfo mode TeX formatting commands start a subshell in Emacs
called the `*tex-shell*'. The
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:
Variable Default value texinfo-texi2dvi-command "texi2dvi" texinfo-tex-command "tex" texinfo-texindex-command "texindex" texinfo-delete-from-print-queue-command "lprm" texinfo-tex-trailer "@bye" tex-start-of-header "%**start" tex-end-of-header "%**end" tex-dvi-print-command "lpr -d" tex-show-queue-command "lpq"
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
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:
@c Local Variables: @c compile-command: "texi2dvi gdb.texinfo" @c 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 and
\input texinfo @setfilename arg-not-used-by-TeX @settitle name-of-manual
The first command instructs TeX to load the macros it needs to process a Texinfo file, the second command opens auxiliary files, and the third specifies the title of printed manual.
Every Texinfo file must end with a line that terminates TeX processing and forces out unfinished pages:
Strictly speaking, these four lines are all a Texinfo file needs for
TeX, besides the body. (The
@setfilename line is the only
line that a Texinfo file needs for Info formatting.)
Usually, the file's first line contains an `@c -*-texinfo-*-'
comment that causes Emacs to switch to Texinfo mode when you edit the
file. In addition, the beginning usually includes 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.
For more information, see
section Page Headings,
section The Title and Copyright Pages,
section Index Menus and Printing an Index, and
section Generating a Table of Contents.
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. (`texinfo.tex' is included in the standard GNU distributions.)
Usually, the `texinfo.tex' file is put in the default directory that contains TeX macros (the `/usr/lib/tex/macros' directory) 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 directory in which the Texinfo source file is located, and TeX will find it there.
However, you may want to specify the location of the
yourself. One way to do this is to write the complete path for the file
\input command. Another way is to set the
TEXINPUTS environment variable in your `.cshrc' or
`.profile' file. The
TEXINPUTS environment variable will tell
TeX where to find the `texinfo.tex' file and any other file that
you might want TeX to use.
Whether you use a `.cshrc' or `.profile' file depends on
whether you use
bash for your shell
command interpreter. When you use
csh, it looks to the
`.cshrc' file for initialization information, and when you use
bash, it looks to the `.profile' file.
In a `.cshrc' file, you could use the following
setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros
In a `.profile' file, you could use the following
TEXINPUTS=.:/usr/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 the system library.
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,
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:
(Since regular sized books are often about 7 by 9.25 inches, this
command might better have been called the
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.
@smalllisp, for information about commands that make it easier
to produce examples for a smaller manual.
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
@end iftex lines near
the beginning of the Texinfo file, before the title page:
For example, this is how you would write the header for this manual:
\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename texinfo @settitle Texinfo @syncodeindex vr fn @iftex @afourpaper @end iftex @c %**end of header
You can attempt to direct TeX to print cropmarks at the corners of
pages with the
@cropmarks command. Write the
command on a line by itself between
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
(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
(see section Using Ordinary TeX Commands).
\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.
Go to the first, previous, next, last section, table of contents.