This is texinfo, produced by makeinfo version 4.2 from texinfo.txi.

This manual is for GNU Texinfo (version 4.2, 28 March 2002), a
documentation system that can produce both online information and a
printed manual from a single source.

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

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being "A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     "GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: "You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by
     the Free Software Foundation raise funds for GNU development."
  
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Update info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
* texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
* makeinfo: (texinfo)Invoking makeinfo.         Translate Texinfo source.
END-INFO-DIR-ENTRY


File: texinfo,  Node: Preparing for TeX,  Next: Overfull hboxes,  Prev: Requirements Summary,  Up: Hardcopy

Preparing for TeX
=================

  TeX needs to know where to find the `texinfo.tex' file that the
`\input texinfo' command on the first line reads.  The `texinfo.tex'
file tells TeX how to handle @-commands; it is included in all standard
GNU distributions.

  Usually, the installer has put the `texinfo.tex' file in the default
directory that contains TeX macros when GNU Texinfo, Emacs or other GNU
software is installed.  In this case, TeX will find the file and you do
not need to do anything special.  If this has not been done, 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', if it is not already installed
from another distribution.  More details are at the end of the
description of the `@image' command (*note Images::).

  Likewise for `pdfcolor.tex', if it is not already installed and you
use pdftex.

  Optionally, you may create an additional `texinfo.cnf', and install
it as well.  This file is read by TeX when the `@setfilename' command
is executed (*note `@setfilename': setfilename.).  You can put any
commands you like there, according to local site-wide conventions.  They
will be read by TeX when processing any Texinfo document.  For example,
if `texinfo.cnf' contains the 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

  On MS-DOS/MS-Windows, you would say it like this(1) (*note Preparing
for TeX-Footnote-1::):

     set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros

It is customary for DOS/Windows users to put such commands in the
`autoexec.bat' file, or in the Windows Registry.

These settings 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
`/usr/lib/tex/macros'.

  Finally, you may wish to dump a `.fmt' file (*note Memory dumps:
(web2c)Memory dumps.) so that TeX can load Texinfo faster.  (The
disadvantage is that then updating `texinfo.tex' requires redumping.)
You can do this by running this command, assuming `epsf.tex' is
findable by TeX:

     initex texinfo @dump

  (`dump' is a TeX primitive.)  Then, move `texinfo.fmt' to wherever
your `.fmt' files are found; typically, this will be in the
subdirectory `web2c' of your TeX installation.


File: texinfo,  Node: Preparing for TeX-Footnotes,  Up: Preparing for TeX

  (1) Note the use of the `;' character, instead of `:', as directory
separator on these systems.


File: texinfo,  Node: Overfull hboxes,  Next: smallbook,  Prev: Preparing for TeX,  Up: 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".
`@hbox' is a TeX primitive not needed in the Texinfo language.)

  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
considered hyphenation.  *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.

  If you have many overfull boxes and/or an antipathy to rewriting, you
can coerce TeX into greatly increasing the allowable interword spacing,
thus (if you're lucky) avoiding many of the bad line breaks, like this:

     @tex
     \global\emergencystretch = .9\hsize
     @end tex

(You should adjust the fraction as needed.)  This huge value for
`\emergencystretch' cannot be the default, since then the typeset
output would generally be of noticeably lower quality; the default is
`.15\hsize'.  `\hsize' is the TeX dimension containing the current line
width.

  For what overfull boxes you have, however, TeX will print a large,
ugly, black rectangle beside the line that contains the overfull hbox
unless told otherwise.  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: texinfo,  Node: smallbook,  Next: A4 Paper,  Prev: Overfull hboxes,  Up: 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 many books are 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::).

  *Note small::, for information about commands that make it easier to
produce examples for a smaller manual.

  *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing
for TeX, for other ways to format with `@smallbook' that do not require
changing the source file.


File: texinfo,  Node: A4 Paper,  Next: pagesizes,  Prev: smallbook,  Up: Hardcopy

Printing on A4 Paper
====================

  You can tell TeX to format a document for printing on European size
A4 paper (or A5) with the `@afourpaper' (or `@afivepaper') command.
Write the command on a line by itself 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
     @afourpaper
     @c %**end of header

  *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing
for TeX, for other ways to format for different paper sizes that do not
require changing the source file.

  You may or may not prefer the formatting that results from the command
`@afourlatex'.  There's also `@afourwide' for A4 paper in wide format.


File: texinfo,  Node: pagesizes,  Next: Cropmarks and Magnification,  Prev: A4 Paper,  Up: Hardcopy

`@pagesizes' [WIDTH][, HEIGHT]: Custom page sizes
=================================================

  You can explicitly specify the height and (optionally) width of the
main text area on the page with the `@pagesizes' command.  Write this
on a line by itself near the beginning of the Texinfo file, before the
title page.  The height comes first, then the width if desired,
separated by a comma.  Examples:

     @pagesizes 200mm,150mm
   and
     @pagesizes 11.5in

  This would be reasonable for printing on B5-size paper.  To emphasize,
this command specifies the size of the _text area_, not the size of the
paper (which is 250mm by 177mm for B5, 14in by 8.5in for legal).

  To make more elaborate changes, such as changing any of the page
margins, you must define a new command in `texinfo.tex' (or
`texinfo.cnf', *note Preparing for TeX: Preparing for TeX.).

  *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing
for TeX, for other ways to specify `@pagesizes' that do not require
changing the source file.

  `@pagesizes' is ignored by `makeinfo'.


File: texinfo,  Node: Cropmarks and Magnification,  Next: PDF Output,  Prev: pagesizes,  Up: 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
`texinfo.tex'.

  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 giving a larger-than-normal master to
your print shop.  They do the reduction, thus effectively increasing the
resolution.

  Depending on your system, DVI files prepared with a
nonstandard-`\mag' may not print or may print only with certain
magnifications.  Be prepared to experiment.


File: texinfo,  Node: PDF Output,  Prev: Cropmarks and Magnification,  Up: Hardcopy

PDF Output
==========

  You can generate a PDF output file from Texinfo source by using the
`pdftex' program to process your file instead of plain `tex'.  Just run
`pdftex foo.texi' instead of `tex foo.texi', or give the `--pdf' option
to `texi2dvi'.

  "PDF" stands for `Portable Document Format'. It was invented by Adobe
Systems some years ago for document interchange, based on their
PostScript language.  A PDF reader (http://www.foolabs.com/xpdf/) for
the X window system is freely available, as is the definition of the
file format (http://partners.adobe.com/asn/developer/technotes/).
Since PDF is a binary format, there are no `@ifpdf' or `@pdf' commands
as with the other output formats.

  Despite the `portable' in the name, PDF files are nowhere near as
portable in practice as the plain ASCII formats (Info, HTML) that
Texinfo supports (DVI portability is arguable).  They also tend to be
much larger and do not support the bitmap fonts used by TeX (by
default) very well.  Nevertheless, a PDF file does preserve an actual
printed document on a screen as faithfully as possible, so it has its
place.

  PDF support in Texinfo is fairly rudimentary.


File: texinfo,  Node: Creating and Installing Info Files,  Next: Command List,  Prev: Hardcopy,  Up: Top

Creating and Installing Info Files
**********************************

  This chapter describes how to create and install Info files.  *Note
Info Files::, for general information about the file format itself.

* Menu:

* Creating an Info File::
* Installing an Info File::


File: texinfo,  Node: Creating an Info File,  Next: Installing an Info File,  Up: Creating and Installing Info Files

Creating an Info File
=====================

  `makeinfo' is a program that converts a Texinfo file into an Info
file, HTML file, or plain text.  `texinfo-format-region' and
`texinfo-format-buffer' are GNU Emacs functions that convert Texinfo to
Info.

  For information on installing the Info file in the Info system, *note
Installing 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.
* makeinfo html::               Generating HTML output.


File: texinfo,  Node: makeinfo advantages,  Next: Invoking makeinfo,  Up: Creating 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 the `C-c C-m C-r' or the `C-c C-m C-b' 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: texinfo,  Node: Invoking makeinfo,  Next: makeinfo options,  Prev: makeinfo advantages,  Up: Creating 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:

     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: texinfo,  Node: makeinfo options,  Next: Pointer Validation,  Prev: Invoking makeinfo,  Up: Creating 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::).

`--commands-in-node-names'
     Allow `@'-commands in node names.  This is not recommended, as it
     can probably never be implemented in TeX.  It also makes
     `makeinfo' much slower.  Also, this option is ignored when
     `--no-validate' is used.  *Note Pointer Validation::, for more
     details.

`--docbook'
     Generate DocBook output rather than Info.

`--error-limit=LIMIT'
`-e 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'
`-f 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.  Ignored with `--html'.

`--footnote-style=STYLE'
`-s 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.  Ignored with `--html'.

`--force'
`-F'
     Ordinarily, if the input file has errors, the output files are not
     created.  With this option, they are preserved.

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

`--html'
     Generate HTML output rather than Info.  *Note makeinfo html::.  By
     default, the HTML output is split into one output file per source
     node, and the split output is written into a subdirectory with the
     name of the top-level info file.

`-I DIR'
     Append DIR to the directory search list for finding files that are
     included using the `@include' command.  By default, `makeinfo'
     searches only the current directory.  If DIR is not given, the
     current directory `.' is appended.  Note that DIR can actually be
     a list of several directories separated by the usual path
     separator character (`:' on Unix, `;' on MS-DOS/MS-Windows).

`--macro-expand=FILE'
`-E FILE'
     Output the Texinfo source with all the macros expanded to the named
     file.  Normally, the results of macro expansion are used
     internally by `makeinfo' and then discarded.  This option is used
     by `texi2dvi' if you are using an old version of `texinfo.tex'
     that does not support `@macro'.

`--no-headers'
     For Info output, do not include menus or node separator lines in
     the output.  This results in a simple plain text file that you can
     (for example) send in email without complications, or include in a
     distribution (as in an `INSTALL' file).

     For HTML output, likewise omit menus.  And if `--no-split' is also
     specified, do not include a navigation links at the top of each
     node (these are never included in the default case of split
     output).  *Note makeinfo html::.

     In both cases, write to standard output by default (can still be
     overridden by `-o').

`--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.  For Info output, each one is approximately
     50k bytes.  For HTML output, each file contains one node (*note
     makeinfo html::).

`--no-pointer-validate'
`--no-validate'
     Suppress the pointer-validation phase of `makeinfo'.  This can also
     be done with the `@novalidate' command (*note Use TeX: Use TeX.).
     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.

`--number-sections'
     Output chapter, section, and appendix numbers as in printed
     manuals.

`--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.  For split HTML
     output, FILE is the name for the directory into which all HTML
     nodes are written (*note makeinfo html::).

`-P DIR'
     Prepend DIR to the directory search list for `@include'.  If DIR
     is not given, the current directory `.' is prepended.  See `-I'
     for more details.

`--paragraph-indent=INDENT'
`-p 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 NUM spaces.

`--reference-limit=LIMIT'
`-r 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'
`-V'
     Print the version number, then exit successfully.

`--xml'
     Generate XML output rather than Info.


File: texinfo,  Node: Pointer Validation,  Next: makeinfo in Emacs,  Prev: makeinfo options,  Up: Creating an Info File

Pointer Validation
------------------

  If you do not suppress pointer validation with the `--no-validate'
option or the `@novalidate' command in the source file (*note Use TeX:
Use TeX.), `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 node pointed to by the `Previous' field must have a
     `Next' field which points back to this node.

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

  4. The node referenced by an `Up' pointer must itself reference the
     current node through a menu item, unless the node referenced by
     `Up' has the form `(FILE)'.

  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.

  6. Every node except `Top' should be referenced by at least one other
     node, either via the `Previous' or `Next' links, or via a menu or a
     cross-reference.

  Some Texinfo documents might fail during the validation phase because
they use commands like `@value' and `@definfoenclose' in node
definitions and cross-references inconsistently.  Consider the
following example:

     @set nodename Node 1
     
     @node @value{nodename}, Node 2, Top, Top
     
     This is node 1.
     
     @node Node 2, , Node 1, Top
     
     This is node 2.

Here, the node "Node 1" was referenced both verbatim and through
`@value'.

  By default, `makeinfo' fails such cases, because node names are not
fully expanded until they are written to the output file.  You should
always try to reference nodes consistently; e.g., in the above example,
the second `@node' line should have also used `@value'.  However, if,
for some reason, you _must_ reference node names inconsistently, and
`makeinfo' fails to validate the file, you can use the
`--commands-in-node-names' option to force `makeinfo' to perform the
expensive expansion of all node names it finds in the document.  This
might considerably slow down the program, though; twofold increase in
conversion time was measured for large documents such as the Jargon
file.

  The support for `@'-commands in `@node' directives is not general
enough to be freely used.  For example, if the example above redefined
`nodename' somewhere in the document, `makeinfo' will fail to convert
it, even if invoked with the `--commands-in-node-names' option.

  `--commands-in-node-names' has no effect if the `--no-validate'
option is given.


File: texinfo,  Node: makeinfo in Emacs,  Next: texinfo-format commands,  Prev: Pointer Validation,  Up: Creating 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: (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 current running `makeinfo' job (from `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: texinfo,  Node: texinfo-format commands,  Next: Batch Formatting,  Prev: makeinfo in Emacs,  Up: Creating 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::).


File: texinfo,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Creating 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: (emacs)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.)


File: texinfo,  Node: Tag and Split Files,  Next: makeinfo html,  Prev: Batch Formatting,  Up: Creating 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 Emacs 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 the file `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 of the (unsplit) output.

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


File: texinfo,  Node: makeinfo html,  Prev: Tag and Split Files,  Up: Creating an Info File

Generating HTML
---------------

  Besides generating output in the Info format, you can use the
`--html' option to generate output in HTML format, for installation on
a web site (for example).  By default, the HTML output is split at node
level.

  When splitting, the HTML output files are written into a subdirectory.
The subdirectory is named according to the name from `@setfilename'
with any extension removed; for example, HTML output for `@setfilename
emacs.info' would be written into a subdirectory named `emacs'.  If
that directory cannot be created for any reason, then `.html' is
appended to the directory name, as in `emacs.html' (this is necessary
because sometimes the info file is named without an extension, e.g.,
`texinfo').  If the `NAME.html' directory can't be created either,
`makeinfo' gives up.  In any case, the top-level output file within the
directory is always named `index.html'.

  Monolithic output (`--no-split') is named according to `@setfilename'
or `--outfile'.  Cross-document node references are not supported in
monolithic HTML.

  Texinfo input marked up with the `@ifhtml' command will produce
output only with the `--html' option supplied.  Input marked up with
the `@html' is passed literally to the output (suppressing the normal
escaping of input `<', `>' and `&' characters which have special
significance in HTML).

  The `--footnote-style' option is currently ignored for HTML output;
footnotes are linked to the end of the output file.

  The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866).  The
exception is that HTML 3.2 tables are generated from the `@multitable'
command, but tagged to degrade as well as possible in browsers without
table support.  The HTML 4 `lang' attribute on the `<html>' attribute
is also used.  Please report output from an error-free run of
`makeinfo' which has browser portability problems as a bug.

  Navigation bars are inserted at the start of nodes, similarly to Info
output.  The `--no-headers' option will suppress this if used with
`--no-split'.  Header `<link>' elements in split output can support
info-like navigation with browsers like Lynx and Emacs W3 which
implement this HTML 1.0 feature.  `@xref' commands to other documents
are generated assuming the other document is available in split HTML
form, and installed in the same HTML documentation tree, at
`../<info-document>/'.


File: texinfo,  Node: Installing an Info File,  Prev: Creating an Info File,  Up: Creating and Installing Info Files

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.


File: texinfo,  Node: Directory File,  Next: New Info File,  Up: Installing an Info File

The Directory File `dir'
------------------------

  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

In this case, the `dir' file name is written in upper case letters--it
can be written in either upper or lower case.  This is not true in
general, it is a special case for `dir'.


File: texinfo,  Node: New Info File,  Next: Other Info Directories,  Prev: Directory File,  Up: Installing 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'(1) (*note New Info File-Footnote-1::); 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'.


File: texinfo,  Node: New Info File-Footnotes,  Up: New Info File

  (1) On MS-DOS/MS-Windows systems, Info will try the `.inf' extension
as well.


File: texinfo,  Node: Other Info Directories,  Next: Installing Dir Entries,  Prev: New Info File,  Up: Installing 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:

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

  2. 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 variable tells Emacs where to look for `dir' files (the files
     must be named `dir').  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.)

  3. 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/info' directory,
you could add an entry like this to the menu in the standard `dir' file:

     * Test: (/home/bob/info/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:

     (require 'info)
     (setq Info-directory-list
       (cons (expand-file-name "/home/bob/info")
             Info-directory-list))

  This tells Emacs to merge the system `dir' file with the `dir' file
in `/home/bob/info'.  Thus, Info will list the
`/home/bob/info/info-test' file as a menu entry in the
`/home/bob/info/dir' file.  Emacs does the merging only when `M-x info'
is first run, so if you want to set `Info-directory-list' in an Emacs
session where you've already run `info', you must `(setq
Info-dir-contents nil)' to force Emacs to recompose the `dir' file.

  Finally, you can tell Info where to look by setting the `INFOPATH'
environment variable in your shell startup file, such as `.cshrc',
`.profile' or `autoexec.bat'.  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 set the variable in the `.cshrc'
initialization file.  On MS-DOS/MS-Windows systems, you must set
`INFOPATH' in your `autoexec.bat' file or in the Registry.  Each type
of shell uses a different syntax.

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

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

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

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

   * In a `autoexec.bat' file, you write this command(1) (*note Other
     Info Directories-Footnote-1::):

          set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info

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.  The stand-alone Info reader merges any
files named `dir' in any directory listed in the `INFOPATH' variable
into a single menu presented to you in the node called `(dir)Top'.

  However you set `INFOPATH', if its last character is a colon(2)
(*note Other Info Directories-Footnote-2::), 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.

  When you create your own `dir' file for use with
`Info-directory-list' or `INFOPATH', it's easiest to start by copying
an existing `dir' file and replace all the text after the `* Menu:'
with your desired entries.  That way, the punctuation and special
CTRL-_ characters that Info needs will be present.


File: texinfo,  Node: Other Info Directories-Footnotes,  Up: Other Info Directories

  (1) Note the use of `;' as the directory separator, and a different
syntax for using values of other environment variables.

  (2) On MS-DOS/MS-Windows systems, use semi-colon instead.


File: texinfo,  Node: Installing Dir Entries,  Next: Invoking install-info,  Prev: Other Info Directories,  Up: Installing an Info File

Installing Info Directory Files
-------------------------------

  When you install an Info file onto your system, you can use the
program `install-info' to update the Info directory file `dir'.
Normally the makefile for the package runs `install-info', just after
copying the Info file into its proper installed location.

  In order for the Info file to work with `install-info', you include
the commands `@dircategory' and `@direntry'...`@end direntry' in the
Texinfo source file.  Use `@direntry' to specify the menu entries to
add to the Info directory file, and use `@dircategory' to specify which
part of the Info directory to put it in.  Here is how these commands
are used in this manual:

     @dircategory Texinfo documentation system
     @direntry
     * Texinfo: (texinfo).           The GNU documentation format.
     * install-info: (texinfo)Invoking install-info. ...
     ...
     @end direntry

  Here's what this produces in the Info file:

     INFO-DIR-SECTION Texinfo documentation system
     START-INFO-DIR-ENTRY
     * Texinfo: (texinfo).           The GNU documentation format.
     * install-info: (texinfo)Invoking install-info. ...
     ...
     END-INFO-DIR-ENTRY

The `install-info' program sees these lines in the Info file, and that
is how it knows what to do.

  Always use the `@direntry' and `@dircategory' commands near the
beginning of the Texinfo input, before the first `@node' command.  If
you use them later on in the input, `install-info' will not notice them.

  If you use `@dircategory' more than once in the Texinfo source, each
usage specifies the `current' category; any subsequent `@direntry'
commands will add to that category.

  Here are some recommended `@dircategory' categories:

     GNU packages
     GNU programming tools
     GNU programming documentation
     GNU Emacs Lisp
     GNU libraries
     TeX
     Individual utilities

  The idea is to include the `Invoking' node for every program installed
by a package under `Individual utilities', and an entry for the manual
as a whole in the appropriate other category.

