Go to the previous, next section.

Format and Print Hardcopy

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 and Print Using Shell Commands

Format the Texinfo file with the shell command tex followed by the name of the Texinfo file. This 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.

The tex formatting command itself does not sort the indices; it writes an output file of unsorted index data. This is a misfeature of TeX. Hence, to generate a printed index, 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 installed.)

The 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 texindex.

Or else, you can use `??' as "wild-cards" 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. 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 a formatted DVI file with up-to-date index entries.(10)

To summarize, this is a three step process:

  1. Run the tex formatting command on the Texinfo file. This generates the formatted DVI file as well as the raw index files with two letter extensions.

  2. Run the shell command texindex on the raw index files to sort them. This creates the corresponding sorted index files.

  3. Rerun the tex formatting 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 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.

Rather than type the tex and texindex commands yourself, you can use texi2dvi. This shell script is designed to simplify the tex---texindex---tex sequence by figuring out whether index files and DVI files are up-to-date. It runs texindex and tex only when necessary.

The syntax for texi2dvi is like this (where `%' is the shell prompt):

% texi2dvi filename...

Finally, you can print the DVI file with the DVI print command. The precise command to use depends on the 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.)

From an Emacs Shell ...

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 Using Shell Commands, 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 (where `%' is the shell prompt):

% texi2dvi gcc.texinfo
% lpr -d gcc.dvi

Formatting and Printing in Texinfo Mode

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-r
M-x texinfo-tex-region
Run TeX on the current region.

C-c C-t C-b
M-x texinfo-tex-buffer
Run TeX on the current buffer.

C-c C-t C-i
M-x texinfo-texindex
Sort the indices of a Texinfo file that have been formatted with texinfo-tex-region or texinfo-tex-buffer.

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 texinfo-show-tex-print-queue
Show the print queue.

C-c C-t C-d
M-x texinfo-delete-from-tex-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 texinfo-kill-tex-job
Kill either the currently running TeX job that has been 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-tex-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 texinfo-recenter-tex-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):

C-c C-t C-b             Run TeX on the buffer.
C-c C-t C-i             Sort the indices.
C-c C-t C-b             Rerun TeX to regenerate indices.
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 `*texinfo-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 `*texinfo-tex-shell*' buffer, and you can switch to and from and use the `*texinfo-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-tex-command                       "tex"
texinfo-texindex-command                  "texindex"
texinfo-tex-shell-cd-command              "cd"
texinfo-tex-dvi-print-command             "lpr -d"
texinfo-show-tex-queue-command            "lpq"
texinfo-delete-from-print-queue-command   "lprm"
texinfo-start-of-header                   "%**start"
texinfo-end-of-header                     "%**end"
texinfo-tex-trailer                       "@bye"

The default values of both the texinfo-tex-command and the texinfo-texindex-command variables are set in the `texnfo-tex.el' file.

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

Using the Local Variables List

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 formatting command as a compile-command and have Emacs run the TeX formatting command 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 would put the following:

@c Local Variables:
@c compile-command: "tex 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.

TeX Formatting Requirements Summary

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

\input texinfo
@settitle name-of-manual

The first command instructs TeX to load the macros it needs to process a Texinfo file and the second command specifies the title of printed manual.

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

@bye

Strictly speaking, these three 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 @setfilename for Info formatting, 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 @setchapternewpage, section Page Headings, section The Title and Copyright Pages, section Index Menus and Printing an Index, and section Generating a Table of Contents.

Preparing to Use TeX

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 \input file yourself. One way to do this is to write the complete path for the file after the \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 csh, sh, or bash for your shell command interpreter. When you use csh, it looks to the `.cshrc' file for initialization information, and when you use sh or bash, it looks to the `.profile' file.

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

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

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

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.

Overfull "hboxes"

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 overful 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:

@finalout

Printing "Small" Books

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.

Printing on A4 Paper

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:

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

Cropmarks and Magnification

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 PlainTeX command that is prefixed with a backslash. You have to write this command between @tex and @end tex (see section Using Ordinary TeX 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.

Go to the previous, next section.