This commit was generated by cvs2svn to compensate for changes in r6453,

[chise/xemacs-chise.git.1] / info / texinfo.info-8

This is Info file ../info/texinfo.info, produced by Makeinfo version
1.68 from the input file texinfo.texi.

INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi.      Printing Texinfo documentation.
* texindex: (texinfo)Format with tex/texindex.  Sorting Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred.        Translate Texinfo source.
END-INFO-DIR-ENTRY

  This file documents Texinfo, a documentation system that can produce
both on-line information and a printed manual from a single source file.

  Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
Foundation, Inc.

  This edition is for Texinfo version 3.12.

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

\1f
File: texinfo.info,  Node: Invoking Macros,  Prev: Defining Macros,  Up: Macros

Invoking Macros
===============

  After a macro is defined (see the previous section), you can use
("invoke") it in your document like this:

     @MACRO-NAME {ARG1, ARG2, ...}

and the result will be just as if you typed the body of MACRO-NAME at
that spot.  For example:

     @macro foo {p, q}
     Together: \p\ & \q\.
     @end macro
     @foo{a, b}

produces:

     Together: a & b.

  Thus, the arguments and parameters are separated by commas and
delimited by braces; any whitespace after (but not before) a comma is
ignored.  To insert a comma, brace, or backslash in an argument,
prepend a backslash, as in

     @MACRO-NAME {\\\{\}\,}

which will pass the (almost certainly error-producing) argument `\{},'
to MACRO-NAME.

  If the macro is defined to take a single argument, and is invoked
without any braces, the entire rest of the line after the macro name is
supplied as the argument.  For example:

     @macro bar {p}
     Twice: \p\, \p\.
     @end macro
     @bar aah

produces:

     Twice: aah, aah.

\1f
File: texinfo.info,  Node: Format/Print Hardcopy,  Next: Create an Info File,  Prev: Macros,  Up: Top

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.

* Menu:

* Use TeX::                     Use TeX to format for hardcopy.
* Format with tex/texindex::    How to format in a shell.
* Format with texi2dvi::        A simpler way to use the shell.
* Print with lpr::              How to print.
* Within Emacs::                How to format and print from an Emacs shell.
* Texinfo Mode Printing::       How to format and print in Texinfo mode.
* Compile-Command::             How to print using Emacs's compile command.
* Requirements Summary::        TeX formatting requirements summary.
* Preparing for TeX::           What you need to do to use TeX.
* Overfull hboxes::             What are and what to do with overfull hboxes.
* smallbook::                   How to print small format books and manuals.
* A4 Paper::                    How to print on European A4 paper.
* Cropmarks and Magnification::  How to print marks to indicate the size
                                of pages and how to print scaled up output.

\1f
File: texinfo.info,  Node: Use TeX,  Next: Format with tex/texindex,  Prev: Format/Print Hardcopy,  Up: Format/Print Hardcopy

Use TeX
=======

  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.  (*Note How to Obtain TeX: Obtaining
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 *Note Create an
Info File::.

\1f
File: texinfo.info,  Node: Format with tex/texindex,  Next: Format with texi2dvi,  Prev: Use TeX,  Up: Format/Print Hardcopy

Format using `tex' and `texindex'
=================================

  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 *Note Format using `texi2dvi':
Format with 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, *note tex invocation: (web2c)tex invocation.)
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 (*note
Printing Indices & Menus::.).  `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:

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

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

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

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

\1f
File: texinfo.info,  Node: Format with texi2dvi,  Next: Print with lpr,  Prev: Format with tex/texindex,  Up: Format/Print Hardcopy

Format using `texi2dvi'
=======================

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

     prompt$ texi2dvi FILENAME...

  For a list of options, run `texi2dvi --help'.

\1f
File: texinfo.info,  Node: Print with lpr,  Next: Within Emacs,  Prev: Format with texi2dvi,  Up: Format/Print Hardcopy

Shell Print Using `lpr -d'
==========================

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

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

  Using the `texi2dvi' shell script, you simply need type:

     texi2dvi bison.texinfo
     lpr -d bison.dvi

\1f
File: texinfo.info,  Node: Within Emacs,  Next: Texinfo Mode Printing,  Prev: Print with lpr,  Up: Format/Print Hardcopy

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.  *Note Format and Print
Hardcopy: Format/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:

     texi2dvi gcc.texinfo
     lpr -d gcc.dvi

  *Note Texinfo Mode Printing::, for more information about formatting
and printing in Texinfo mode.

\1f
File: texinfo.info,  Node: Texinfo Mode Printing,  Next: Compile-Command,  Prev: Within Emacs,  Up: Format/Print Hardcopy

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

     C-c C-t C-b             Run `texi2dvi' on 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 `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:

          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 (*note Editing Variable Values: (xemacs)Edit
Options.), with the `M-x set-variable' command (*note Examining and
Setting Variables: (xemacs)Examining.), or with your `.emacs'
initialization file (*note Init File: (xemacs)Init File.).

\1f
File: texinfo.info,  Node: Compile-Command,  Next: Requirements Summary,  Prev: Texinfo Mode Printing,  Up: Format/Print Hardcopy

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' 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 *Note Compilation: (xemacs)Compilation.

\1f
File: texinfo.info,  Node: Requirements Summary,  Next: Preparing for TeX,  Prev: Compile-Command,  Up: Format/Print Hardcopy

TeX Formatting Requirements Summary
===================================

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

For more information, see
*Note `@settitle': settitle,
*Note `@setchapternewpage': setchapternewpage,
*Note Page Headings: Headings,
*Note Titlepage & Copyright Page::,
*Note Printing Indices & Menus::, and
*Note Contents::.

\1f
File: texinfo.info,  Node: Preparing for TeX,  Next: Overfull hboxes,  Prev: Requirements Summary,  Up: Format/Print Hardcopy

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; 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
(*note Images::.).

  Optionally, you may create an additional `texinfo.cnf', and install
it as well.  This file is read by TeX at the `@setfilename' command
(*note `@setfilename': 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' (*note 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.

\1f
File: texinfo.info,  Node: Overfull hboxes,  Next: smallbook,  Prev: Preparing for TeX,  Up: Format/Print Hardcopy

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.  *Note Catching Errors with TeX
Formatting: Debugging with TeX, 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:

     @finalout

\1f
File: texinfo.info,  Node: smallbook,  Next: A4 Paper,  Prev: Overfull hboxes,  Up: Format/Print Hardcopy

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
(*note Start of Header::.).

  The Free Software Foundation distributes printed copies of `The GNU
Emacs Manual' and other manuals in the "small" book size.  *Note
`@smallexample' and `@smalllisp': smallexample & 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 (*note Format with
texi2dvi::.), and supply `-t @smallbook' as an argument.  Then other
people do not have to change the document source file to format it
differently.

\1f
File: texinfo.info,  Node: A4 Paper,  Next: Cropmarks and Magnification,  Prev: smallbook,  Up: Format/Print Hardcopy

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

  Alternatively, to avoid embedding this physical paper size in your
document, use `texi2dvi' to format your document (*note Format with
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.

\1f
File: texinfo.info,  Node: Cropmarks and Magnification,  Prev: A4 Paper,  Up: Format/Print Hardcopy

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 plain
TeX command that is prefixed with a backslash.  You have to write this
command between `@tex' and `@end tex' (*note 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.

\1f
File: texinfo.info,  Node: Create an Info File,  Next: Install an Info File,  Prev: Format/Print Hardcopy,  Up: Top

Creating an Info File
*********************

  `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
*Note Install an Info File::.

* Menu:

* makeinfo advantages::         `makeinfo' provides better error checking.
* Invoking makeinfo::           How to run `makeinfo' from a shell.
* makeinfo options::            Specify fill-column and other options.
* Pointer Validation::          How to check that pointers point somewhere.
* makeinfo in Emacs::           How to run `makeinfo' from Emacs.
* texinfo-format commands::     Two Info formatting commands written
                                  in Emacs Lisp are an alternative
                                  to `makeinfo'.
* Batch Formatting::            How to format for Info in Emacs Batch mode.
* Tag and Split Files::         How tagged and split files help Info
                                  to run better.

\1f
File: texinfo.info,  Node: makeinfo advantages,  Next: Invoking makeinfo,  Prev: Create an Info File,  Up: Create an Info File

`makeinfo' Preferred
====================

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

\1f
File: texinfo.info,  Node: Invoking makeinfo,  Next: makeinfo options,  Prev: makeinfo advantages,  Up: Create an Info File

Running `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'.)

  Sometimes you will want to specify options.  For example, if you wish
to discover which version of `makeinfo' you are using, type:

     makeinfo --version

  *Note makeinfo options::, for more information.

\1f
File: texinfo.info,  Node: makeinfo options,  Next: Pointer Validation,  Prev: Invoking makeinfo,  Up: Create an Info File

Options for `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'
     Cause the variable VAR to be defined.  This is equivalent to `@set
     VAR' in the Texinfo file (*note set clear value::.).

`--error-limit=LIMIT'
     Set the maximum number of errors that `makeinfo' will report
     before exiting (on the assumption that continuing would be
     useless); default 100.

`--fill-column=WIDTH'
     Specify the maximum number of columns in a line; this is the
     right-hand edge of a line.  Paragraphs that are filled will be
     filled to this width.  (Filling is the process of breaking up and
     connecting lines so that lines are the same length as or shorter
     than the number specified as the fill column.  Lines are broken
     between words.) The default value is 72.

`--footnote-style=STYLE'
     Set the footnote style to STYLE, either `end' for the end node
     style (the default) or `separate' for the separate node style.
     The value set by this option overrides the value set in a Texinfo
     file by an `@footnotestyle' command (*note 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'
     Ordinarily, if the input file has errors, the output files are not
     created.  With this option, they are preserved.

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`-I DIR'
     Add `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'
     Do not include menus or node lines in the output.  This results in
     an ASCII file that you cannot read in Info since it does not
     contain the requisite nodes or menus. It is primarily useful to
     extract certain pieces of a manual into separate files to be
     included in a distribution, such as `INSTALL' files.

`--no-split'
     Suppress the splitting stage of `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'
     Suppress the pointer-validation phase of `makeinfo'.  Normally,
     after a Texinfo file is processed, some consistency checks are
     made to ensure that cross references can be resolved, etc.  *Note
     Pointer Validation::.

`--no-warn'
     Suppress warning messages (but *not* error messages).  You might
     want this if the file you are creating has examples of Texinfo
     cross references within it, and the nodes that are referenced do
     not actually exist.

`--no-number-footnotes'
     Suppress automatic footnote numbering.  By default, `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'
     Specify that the output should be directed to FILE and not to the
     file name specified in the `@setfilename' command found in the
     Texinfo source (*note setfilename::.).  If FILE is `-', output
     goes to standard output and `--no-split' is implied.

`-P DIR'
     Prepend `dir' to the directory search list for `@include'.  See
     `-I' for more details.

`--paragraph-indent=INDENT'
     Set the paragraph indentation style to INDENT.  The value set by
     this option overrides the value set in a Texinfo file by an
     `@paragraphindent' command (*note paragraphindent::.).  The value
     of INDENT is interpreted as follows:

    `asis'
          Preserve any existing indentation at the starts of paragraphs.

    `0' or `none'
          Delete any existing indentation.

    NUM
          Indent each paragraph by that number of spaces.

`--reference-limit=LIMIT'
     Set the value of the number of references to a node that
     `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'
     Cause VAR to be undefined.  This is equivalent to `@clear VAR' in
     the Texinfo file (*note set clear value::.).

`--verbose'
     Cause `makeinfo' to display messages saying what it is doing.
     Normally, `makeinfo' only outputs messages if there are errors or
     warnings.

`--version'
     Print the version number, then exit successfully.

\1f
File: texinfo.info,  Node: Pointer Validation,  Next: makeinfo in Emacs,  Prev: makeinfo options,  Up: Create an Info File

Pointer Validation
==================

  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:

  1. If a `Next', `Previous', or `Up' node reference is a reference to a
     node in the current file and is not an external reference such as
     to `(dir)', then the referenced node must exist.

  2. In every node, if the `Previous' node is different from the `Up'
     node, then the `Previous' node must also be pointed to by a `Next'
     node.

  3. Every node except the `Top' node must have an `Up' pointer.

  4. The node referenced by an `Up' pointer must contain a reference to
     the current node in some manner other than through a `Next'
     reference.  This includes menu entries and cross references.

  5. If the `Next' reference of a node is not the same as the `Next'
     reference of the `Up' reference, then the node referenced by the
     `Next' pointer must have a `Previous' pointer that points back to
     the current node.  This rule allows the last node in a section to
     point to the first node of the next chapter.

\1f
File: texinfo.info,  Node: makeinfo in Emacs,  Next: texinfo-format commands,  Prev: Pointer Validation,  Up: Create an Info File

Running `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.

`C-c C-m C-r'
`M-x makeinfo-region'
     Format the current region for Info.

`C-c C-m C-b'
`M-x makeinfo-buffer'
     Format the current buffer for Info.

  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.  *Note Running
`make' or Compilers Generally: (xemacs)Compilation, 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.

`C-c C-m C-k'
`M-x makeinfo-kill-job'
     Kill the current running `makeinfo' job created by
     `makeinfo-region' or `makeinfo-buffer'.

`C-c C-m C-l'
`M-x makeinfo-recenter-output-buffer'
     Redisplay the `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'.  *Note Texinfo Mode Printing::.)

  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
*Note Editing Variable Values: (xemacs)Edit Options,
*Note Examining and Setting Variables: (xemacs)Examining,
*Note Init File: (xemacs)Init File, and
*Note Options for `makeinfo': makeinfo options.

\1f
File: texinfo.info,  Node: texinfo-format commands,  Next: Batch Formatting,  Prev: makeinfo in Emacs,  Up: Create an Info File

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

`C-c C-e C-r'
``texinfo-format-region''
     Format the current region for Info.

`C-c C-e C-b'
``texinfo-format-buffer''
     Format the current buffer for Info.

  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 *Note Catching Mistakes::.  However,
the `makeinfo' program is often faster and provides better error
checking (*note makeinfo in Emacs::.).

\1f
File: texinfo.info,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Create an Info File

Batch Formatting
================

  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.  (*Note Command Line Switches and
Arguments: (xemacs)Command Switches.)

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

\1f
File: texinfo.info,  Node: Tag and Split Files,  Prev: Batch Formatting,  Up: Create an Info File

Tag Files and Split Files
=========================

  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.  *Note Include
Files::, for more information.  Include files are still used for very
large documents, such as `The XEmacs 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 *Note Using
Info-validate::.

\1f
File: texinfo.info,  Node: Install an Info File,  Next: Command List,  Prev: Create an Info File,  Up: Top

Installing an Info File
***********************

  Info files are usually kept in the `info' directory.  You can read
Info files using the standalone Info program or the Info reader built
into Emacs.  (*note info: (info)Top, for an introduction to Info.)

* Menu:

* Directory file::              The top level menu for all Info files.
* New Info File::               Listing a new info file.
* Other Info Directories::      How to specify Info files that are
                                  located in other directories.
* Installing Dir Entries::      How to specify what menu entry to add
                                  to the Info directory.
* Invoking install-info::       `install-info' options.

\1f
File: texinfo.info,  Node: Directory file,  Next: New Info File,  Prev: Install an Info File,  Up: Install an Info File

The `dir' File
==============

  For Info to work, the `info' directory must contain a file that
serves as a top level directory for the Info system.  By convention,
this file is called `dir'.  (You can find the location of this file
within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
to see the pathname to the `info' directory.)

  The `dir' file is itself an Info file.  It contains the top level
menu for all the Info files in the system.  The menu looks like this:

     * Menu:
     
     * Info:    (info).     Documentation browsing system.
     * Emacs:   (emacs).    The extensible, self-documenting
                            text editor.
     * Texinfo: (texinfo).  With one source file, make
                            either a printed manual using
                            TeX or an Info file.
     ...

  Each of these menu entries points to the `Top' node of the Info file
that is named in parentheses.  (The menu entry does not need to specify
the `Top' node, since Info goes to the `Top' node if no node name is
mentioned.  *Note Nodes in Other Info Files: Other Info Files.)

  Thus, the `Info' entry points to the `Top' node of the `info' file
and the `Emacs' entry points to the `Top' node of the `emacs' file.

  In each of the Info files, the `Up' pointer of the `Top' node refers
back to the `dir' file.  For example, the line for the `Top' node of
the Emacs manual looks like this in Info:

     File: emacs  Node: Top, Up: (DIR), Next: Distrib

(Note that in this case, the `dir' file name is written in upper case
letters--it can be written in either upper or lower case.  Info has a
feature that it will change the case of the file name to lower case if
it cannot find the name as written.)

\1f
File: texinfo.info,  Node: New Info File,  Next: Other Info Directories,  Prev: Directory file,  Up: Install an Info File

Listing a New Info File
=======================

  To add a new Info file to your system, you must write a menu entry to
add to the menu in the `dir' file in the `info' directory.  For
example, if you were adding documentation for GDB, you would write the
following new entry:

     * GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a
colon.  The second part is the name of the Info file, in parentheses,
followed by a period.  The third part is the description.

  The name of an Info file often has a `.info' extension.  Thus, the
Info file for GDB might be called either `gdb' or `gdb.info'.  The Info
reader programs automatically try the file name both with and without
`.info'; so it is better to avoid clutter and not to write `.info'
explicitly in the menu entry.  For example, the GDB menu entry should
use just `gdb' for the file name, not `gdb.info'.

\1f
File: texinfo.info,  Node: Other Info Directories,  Next: Installing Dir Entries,  Prev: New Info File,  Up: Install an Info File

Info Files in Other Directories
===============================

  If an Info file is not in the `info' directory, there are three ways
to specify its location:

   * Write the pathname in the `dir' file as the second part of the
     menu.

   * If you are using Emacs, list the name of the file in a second `dir'
     file, in its directory; and then add the name of that directory to
     the `Info-directory-list' variable in your personal or site
     initialization file.

     This tells Emacs where to look for `dir' files.  Emacs merges the
     files named `dir' from each of the listed directories.  (In Emacs
     version 18, you can set the `Info-directory' variable to the name
     of only one directory.)

   * Specify the Info directory name in the `INFOPATH' environment
     variable in your `.profile' or `.cshrc' initialization file.
     (Only you and others who set this environment variable will be
     able to find Info files whose location is specified this way.)

  For example, to reach a test file in the `/home/bob/manuals'
directory, you could add an entry like this to the menu in the `dir'
file:

     * Test: (/home/bob/manuals/info-test).  Bob's own test file.

In this case, the absolute file name of the `info-test' file is written
as the second part of the menu entry.

  Alternatively, you could write the following in your `.emacs' file:

     (setq Info-directory-list
           '("/home/bob/manuals"
             "/usr/local/info"))

  This tells Emacs to merge the `dir' file from the `/home/bob/manuals'
directory with the `dir' file from the `/usr/local/info' directory.
Info will list the `/home/bob/manuals/info-test' file as a menu entry
in the `/home/bob/manuals/dir' file.

  Finally, you can tell Info where to look by setting the `INFOPATH'
environment variable in your `.cshrc' or `.profile' file.  If you use a
Bourne-compatible shell such as `sh' or `bash' for your shell command
interpreter, you set the `INFOPATH' environment variable in the
`.profile' initialization file; but if you use `csh' or `tcsh', you
must set the variable in the `.cshrc' initialization file.  The two
types of shells use different syntax.

   * In a `.cshrc' file, you could set the `INFOPATH' variable as
     follows:

          setenv INFOPATH .:~/manuals:/usr/local/emacs/info

   * In a `.profile' file, you would achieve the same effect by writing:

          INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
          export INFOPATH

The `.' indicates the current directory as usual.  Emacs uses the
`INFOPATH' environment variable to initialize the value of Emacs's own
`Info-directory-list' variable.

  However you set `INFOPATH', if its last character is a colon, this is
replaced by the default (compiled-in) path.  This gives you a way to
augment the default path with new directories without having to list all
the standard places.  For example (using `sh' syntax:

     INFOPATH=/local/info:
     export INFOPATH

will search `/local/info' first, then the standard directories.
Leading or doubled colons are not treated specially.