path: root/gnu/usr.bin/texinfo/info-files/texi.info-7

This is Info file texi.info, produced by Makeinfo-1.55 from the input
file texi.texi.

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

   Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
Inc.

   This is the second edition of the Texinfo documentation,
and is consistent with version 2 of `texinfo.tex'.

   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.


File: texi.info,  Node: Footnotes,  Next: Conditionals,  Prev: Definition Commands,  Up: Top

Footnotes
*********

   A "footnote" is for a reference that documents or elucidates the
primary text.(1)

   In Texinfo, footnotes are created with the `@footnote' command.
This command is followed immediately by a left brace, then by the text
of the footnote, and then by a terminating right brace.  The template
is:

     @footnote{TEXT}

   Footnotes may be of any length, but are usually short.

   For example, this clause is followed by a sample footnote(2); in the
Texinfo source, it looks like this:

     ...a sample footnote @footnote{Here is the sample
     footnote.}; in the Texinfo source...

   In a printed manual or book, the reference mark for a footnote is a
small, superscripted number; the text of the footnote is written at the
bottom of the page, below a horizontal line.

   In Info, the reference mark for a footnote is a pair of parentheses
with the footnote number between them, like this: `(1)'.

   Info has two footnote styles, which determine where the text of the
footnote is located:

   * In the `End' node style, all the footnotes for a single node are
     placed at the end of that node.  The footnotes are separated from
     the rest of the node by a line of dashes with the word `Footnotes'
     within it.  Each footnote begins with an `(N)' reference mark.

     Here is an example of a single footnote in the end of node style:

           --------- Footnotes ---------
          
          (1)  Here is a sample footnote.

   * In the `Separate' node style, all the footnotes for a single node
     are placed in an automatically constructed node of their own.  In
     this style, a "footnote reference" follows each `(N)' reference
     mark in the body of the node.  The footnote reference is actually
     a cross reference which you use to reach the footnote node.

     The name of the node containing the footnotes is constructed by
     appending `-Footnotes' to the name of the node that contains the
     footnotes. (Consequently, the footnotes' node for the `Footnotes'
     node is `Footnotes-Footnotes'!)  The footnotes' node has an `Up'
     node pointer that leads back to its parent node.

     Here is how the first footnote in this manual looks after being
     formatted for Info in the separate node style:

          File: texinfo.info  Node: Overview-Footnotes, Up: Overview
          
          (1) Note that the first syllable of "Texinfo" is
          pronounced like "speck", not "hex". ...

   A Texinfo file may be formatted into an Info file with either
footnote style.

   Use the `@footnotestyle' command to specify an Info file's footnote
style.  Write this command at the beginning of a line followed by an
argument, either `end' for the end node style or `separate' for the
separate node style.

   For example,

     @footnotestyle end

or
     @footnotestyle separate

   Write an `@footnotestyle' command before or shortly after the
end-of-header line at the beginning of a Texinfo file.  (If you include
the `@footnotestyle' command between the start-of-header and
end-of-header lines, the region formatting commands will format
footnotes as specified.)

   If you do not specify a footnote style, the formatting commands use
their default style.  Currently, `makeinfo' uses the `end' style, while
`texinfo-format-buffer' and `texinfo-format-region' use the `separate'
style.

   This chapter contains two footnotes.

   ---------- Footnotes ----------

   (1)  A footnote should complement or expand upon the primary text,
but a reader should not need to read a footnote to understand the
primary text.  For a thorough discussion of footnotes, see `The Chicago
Manual of Style', which is published by the University of Chicago Press.

   (2)  Here is the sample footnote.


File: texi.info,  Node: Conditionals,  Next: Format/Print Hardcopy,  Prev: Footnotes,  Up: Top

Conditionally Visible Text
**************************

   Sometimes it is good to use different text for a printed manual and
its corresponding Info file.  In this case, you can use the
"conditional commands" to specify which text is for the printed manual
and which is for the Info file.

* Menu:

* Conditional Commands::        How to specify text for Info or TeX.
* Using Ordinary TeX Commands::  You can use any and all TeX commands.
* set clear value::             How to designate which text to format (for
                                  both Info and TeX); and how to set a
                                  flag to a string that you can insert.


File: texi.info,  Node: Conditional Commands,  Next: Using Ordinary TeX Commands,  Up: Conditionals

Using `@ifinfo' and `@iftex'
============================

   `@ifinfo' begins segments of text that should be ignored by TeX when
it typesets the printed manual.  The segment of text appears only in
the Info file.  The `@ifinfo' command should appear on a line by
itself;  end the Info-only text with a line containing `@end ifinfo' by
itself.  At the beginning of a Texinfo file, the Info permissions are
contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
Info Summary and Permissions::.)

   The `@iftex' and `@end iftex' commands are similar to the `@ifinfo'
and `@end ifinfo' commands, except that they specify text that will
appear in the printed manual but not in the Info file.

   For example,

     @iftex
     This text will appear only in the printed manual.
     @end iftex
     
     @ifinfo
     However, this text will appear only in Info.
     @end ifinfo

The preceding example produces the following line:

   However, this text will appear only in Info.

Note how you only see one of the two lines, depending on whether you
are reading the Info version or the printed version of this manual.

   The `@titlepage' command is a special variant of `@iftex' that is
used for making the title and copyright pages of the printed manual.
(*Note `@titlepage': titlepage.)


File: texi.info,  Node: Using Ordinary TeX Commands,  Next: set clear value,  Prev: Conditional Commands,  Up: Conditionals

Using Ordinary TeX Commands
===========================

   Inside a region delineated by `@iftex' and `@end iftex', you can
embed some PlainTeX commands.  Info will ignore these commands since
they are only in that part of the file which is seen by TeX.  You can
write the TeX commands as you would write them in a normal TeX file,
except that you must replace the `\' used by TeX with an `@'.  For
example, in the `@titlepage' section of a Texinfo file, you can use the
TeX command `@vskip' to format the copyright page.  (The `@titlepage'
command causes Info to ignore the region automatically, as it does with
the `@iftex' command.)

   However, many features of PlainTeX will not work, as they are
overridden by features of Texinfo.

   You can enter PlainTeX completely, and use `\' in the TeX commands,
by delineating a region with the `@tex' and `@end tex' commands.  (The
`@tex' command also causes Info to ignore the region, like the `@iftex'
command.)

   For example, here is a mathematical expression written in PlainTeX:

     @tex
     $$ \chi^2 = \sum_{i=1}^N
               \left (y_i - (a + b x_i)
               \over \sigma_i\right)^2 $$
     @end tex

The output of this example will appear only in a printed manual.  If
you are reading this in Info, you will not see anything after this
paragraph.


File: texi.info,  Node: set clear value,  Prev: Using Ordinary TeX Commands,  Up: Conditionals

`@set', `@clear', and `@value'
==============================

   You can direct the Texinfo formatting commands to format or ignore
parts of a Texinfo file with the `@set', `@clear', `@ifset', and
`@ifclear' commands.

   In addition, you can use the `@set FLAG' command to set the value of
FLAG to a string of characters; and use `@value{FLAG}' to insert that
string.  You can use `@set', for example, to set a date and use
`@value' to insert the date in several places in the Texinfo file.

* Menu:

* ifset ifclear::               Format a region if a flag is set.
* value::                       Replace a flag with a string.
* value Example::               An easy way to update edition information.


File: texi.info,  Node: ifset ifclear,  Next: value,  Up: set clear value

`@ifset' and `@ifclear'
-----------------------

   When a FLAG is set, the Texinfo formatting commands format text
between subsequent pairs of `@ifset FLAG' and `@end ifset' commands.
When the FLAG is cleared, the Texinfo formatting commands do *not*
format the text.

   Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
can be any single word.  The format for the command looks like this:

     @set FLAG

   Write the conditionally formatted text between `@ifset FLAG' and
`@end ifset' commands, like this:

     @ifset FLAG
     CONDITIONAL-TEXT
     @end ifset

   For example, you can create one document that has two variants, such
as a manual for a `large' and `small' model:

     You can use this machine to dig up shrubs
     without hurting them.
     
     @set large
     
     @ifset large
     It can also dig up fully grown trees.
     @end ifset
     
     Remember to replant promptly ...

In the example, the formatting commands will format the text between
`@ifset large' and `@end ifset' because the `large' flag is set.

   Use the `@clear FLAG' command to turn off, or "clear", a flag.
Clearing a flag is the opposite of setting a flag.  The command looks
like this:

     @clear FLAG

Write the command on a line of its own.

   When FLAG is cleared, the Texinfo formatting commands do *not*
format the text between `@ifset FLAG' and `@end ifset'; that text is
ignored and does not appear in either printed or Info output.

   For example, if you clear the flag of the preceding example by
writing an `@clear large' command after the `@set large' command (but
before the conditional text), then the Texinfo formatting commands
ignore the text between the `@ifset large' and `@end ifset' commands.
In the formatted output, that text does not appear; in both printed and
Info output, you see only the lines that say, "You can use this machine
to dig up shrubs without hurting them.  Remember to replant promptly
...".

   If a flag is cleared with an `@clear FLAG' command, then the
formatting commands format text between subsequent pairs of `@ifclear'
and `@end ifclear' commands.  But if the flag is set with `@set FLAG',
then the formatting commands do *not* format text between an `@ifclear'
and an `@end ifclear' command; rather, they ignore that text.  An
`@ifclear' command looks like this:

     @ifclear FLAG

   In brief, the commands are:

`@set FLAG'
     Tell the Texinfo formatting commands that FLAG is set.

`@clear FLAG'
     Tell the Texinfo formatting commands that FLAG is cleared.

`@ifset FLAG'
     If FLAG is set, tell the Texinfo formatting commands to format the
     text up to the following `@end ifset' command.

     If FLAG is cleared, tell the Texinfo formatting commands to ignore
     text up to the following `@end ifset' command.

`@ifclear FLAG'
     If FLAG is set, tell the Texinfo formatting commands to ignore the
     text up to the following `@end ifclear' command.

     If FLAG is cleared, tell the Texinfo formatting commands to format
     the text up to the following `@end ifclear' command.


File: texi.info,  Node: value,  Next: value Example,  Prev: ifset ifclear,  Up: set clear value

`@value'
--------

   You can use the `@set' command to specify a value for a flag, which
is expanded by the `@value' command.  The value is a string a
characters.

   Write the `@set' command like this:

     @set foo This is a string.

This sets the value of `foo' to "This is a string."

   The Texinfo formatters replace an `@value{FLAG}' command with the
string to which FLAG is set.

   Thus, when `foo' is set as shown above, the Texinfo formatters
convert

     @value{foo}
to
     This is a string.

   You can write an `@value' command within a paragraph; but you must
write an `@set' command on a line of its own.

   If you write the `@set' command like this:

     @set foo

without specifying a string, the value of `foo' is an empty string.

   If you clear a previously set flag with an `@clear FLAG' command, a
subsequent `@value{flag}' command is invalid and the string is replaced
with an error message that says `{No value for "FLAG"}'.

   For example, if you set `foo' as follows:

     @set how-much very, very, very

then the formatters transform

     It is a @value{how-much} wet day.
into
     It is a very, very, very wet day.

   If you write

     @clear how-much

then the formatters transform

     It is a @value{how-much} wet day.
into
     It is a {No value for "how-much"} wet day.


File: texi.info,  Node: value Example,  Prev: value,  Up: set clear value

`@value' Example
----------------

   You can use the `@value' command to limit the number of places you
need to change when you record an update to a manual.  Here is how it
is done in `The GNU Make Manual':

Set the flags:

     @set EDITION 0.35 Beta
     @set VERSION 3.63 Beta
     @set UPDATED 14 August 1992
     @set UPDATE-MONTH August 1992

Write text for the first `@ifinfo' section, for people reading the
Texinfo file:

     This is Edition @value{EDITION},
     last updated @value{UPDATED},
     of @cite{The GNU Make Manual},
     for @code{make}, Version @value{VERSION}.

Write text for the title page, for people reading the printed manual:

     @title GNU Make
     @subtitle A Program for Directing Recompilation
     @subtitle Edition @value{EDITION}, ...
     @subtitle @value{UPDATE-MONTH}

(On a printed cover, a date listing the month and the year looks less
fussy than a date listing the day as well as the month and year.)

Write text for the Top node, for people reading the Info file:

     This is Edition @value{EDITION}
     of the @cite{GNU Make Manual},
     last updated @value{UPDATED}
     for @code{make} Version @value{VERSION}.

   After you format the manual, the text in the first `@ifinfo' section
looks like this:

     This is Edition 0.35 Beta, last updated 14 August 1992,
     of `The GNU Make Manual', for `make', Version 3.63 Beta.

   When you update the manual, change only the values of the flags; you
do not need to rewrite the three sections.


File: texi.info,  Node: Format/Print Hardcopy,  Next: Create an Info File,  Prev: Conditionals,  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.
* Shell Format & Print::        How to format and print a hardcopy manual
                                 with shell commands.
* 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.


File: texi.info,  Node: Use TeX,  Next: Shell Format & Print,  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::.


File: texi.info,  Node: Shell Format & Print,  Next: Within Emacs,  Prev: Use TeX,  Up: Format/Print Hardcopy

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

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

   ---------- Footnotes ----------

   (1)  If you use more than one index and have cross references to an
index other than the first, you must run `tex' *three times* to get
correct output: once to generate raw index data; again (after
`texindex') to output the text of the indices and determine their true
page numbers; and a third time to output correct page numbers in cross
references to them.  However, cross references to indices are rare.


File: texi.info,  Node: Within Emacs,  Next: Texinfo Mode Printing,  Prev: Shell Format & Print,  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 How to Format and
Print Using Shell Commands: Shell Format & Print, 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

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


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


File: texi.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 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 *Note Compilation: (emacs)Compilation.


File: texi.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 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
*Note `@setchapternewpage': setchapternewpage,
*Note Page Headings: Headings,
*Note Titlepage & Copyright Page::,
*Note Printing Indices & Menus::, and
*Note Contents::.


File: texi.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.  (`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.


File: texi.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 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


File: texi.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.


File: texi.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


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


File: texi.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 possess 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.


File: texi.info,  Node: makeinfo advantages,  Next: Invoking makeinfo,  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'.


File: texi.info,  Node: Invoking makeinfo,  Next: makeinfo options,  Prev: makeinfo advantages,  Up: Create an Info File

Invoking `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 at the shell prompt (where `%' 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.


File: texi.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 `--'(1)
or a letter preceded by `-'.  You can use abbreviations for the option
names as long as they are unique.

   For example, you could use the following command to create an Info
file for `bison.texinfo' in which each line is filled to only 68
columns (where `%' is the prompt):

     % 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 VAR to be defined.  This is equivalent to `@set VAR' in the
     Texinfo file.

`--error-limit LIMIT'
     Set the maximum number of errors that `makeinfo' will report
     before exiting (on the assumption that continuing would be
     useless).  The default number of errors that can be reported before
     `makeinfo' gives up is 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 for `fill-column' is 72.

`--footnote-style STYLE'
     Set the footnote style to STYLE, either `end' for the end node
     style 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.  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.

`-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; but you can print such a
     file in a single, typewriter-like font and produce acceptable
     output.

`--no-split'
     Suppress the splitting stage of `makeinfo'.  Normally, large
     output files (where the size is greater than 70k bytes) are split
     into smaller subfiles, each one approximately 50k bytes.  If you
     specify `--no-split', `makeinfo' will not split up the output file.

`--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 the output of warning messages.  This does *not* suppress
     the output of error messages, only warnings.  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'
     Supress 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.  FILE can be the special token `-', which specifies
     standard output.

`--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.  The value of INDENT is interpreted as
     follows:

        * If the value of INDENT is `asis', do not change the existing
          indentation at the starts of paragraphs.

        * If the value of INDENT is zero, delete any existing
          indentation.

        * If the value of INDENT is greater than zero, 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.

`-U VAR'
     Cause VAR to be undefined.  This is equivalent to `@clear VAR' in
     the Texinfo file.

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

`--version'
     Report the version number of this copy of `makeinfo'.

   ---------- Footnotes ----------

   (1)  `--' has replaced `+', the old introductory character, to
maintain POSIX.2 compatibility without losing long-named options.


File: texi.info,  Node: Pointer Validation,  Next: makeinfo in Emacs,  Prev: makeinfo options,  Up: Create an Info File

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

   `makeinfo' will check the validity of the final Info file unless you
suppress pointer-validation by using the `--no-pointer-validation'
option.  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.


File: texi.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 typing 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: (emacs)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 currently running 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: (emacs)Edit Options,
*Note Examining and Setting Variables: (emacs)Examining,
*Note Init File: (emacs)Init File, and
*Note Options for `makeinfo': makeinfo options.


File: texi.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::.).