This is Info file ../info/texinfo.info, produced by Makeinfo-1.63 from
the input file texinfo.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, 1995 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: texinfo.info,  Node: makeinfo options,  Next: Pointer Validation,  Prev: Invoking makeinfo,  Up: Create an Info File

Options for `makeinfo'
======================

  The `makeinfo' command takes a number of options.  Most often,
options are used to set the value of the fill column and specify the
footnote style.  Each command line option is a word preceded by `--'(1)
(*note makeinfo options-Footnotes::) 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'
     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.  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'.


File: texinfo.info,  Node: makeinfo options-Footnotes,  Up: makeinfo options

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


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

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

  If you do not suppress pointer-validation, `makeinfo' will check the
validity of the final Info file.  Mostly, this means ensuring that
nodes you have referenced really exist.  Here is a complete list of what
is checked:

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

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

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

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

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


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

Running `makeinfo' inside Emacs
===============================

  You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
`makeinfo-region' or the `makeinfo-buffer' commands.  In Texinfo mode,
the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.

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

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

  When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
prompts for a file name, offering the name of the visited file as the
default.  You can edit the default file name in the minibuffer if you
wish, before 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 current running `makeinfo' job created by
     `makeinfo-region' or `makeinfo-buffer'.

`C-c C-m C-l'
`M-x makeinfo-recenter-output-buffer'
     Redisplay the `makeinfo' shell buffer to display its most recent
     output.

(Note that the parallel commands for killing and recentering a TeX job
are `C-c C-t C-k' and `C-c C-t C-l'.  *Note Texinfo Mode Printing::.)

  You can specify options for `makeinfo' by setting the
`makeinfo-options' variable with either the `M-x edit-options' or the
`M-x set-variable' command, or by setting the variable in your `.emacs'
initialization file.

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

     (setq makeinfo-options
           "--paragraph-indent=0 --no-split
            --fill-column=70 --verbose")

For more information, see
*Note Editing Variable Values: (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.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::.).


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

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

  You can format Texinfo files for Info using `batch-texinfo-format'
and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
including a shell inside of Emacs.  (*Note Command Line Switches and
Arguments: (emacs)Command Switches.)

  Here is the command to format all the files that end in `.texinfo' in
the current directory (where `%' is the shell prompt):

     % 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.info,  Node: Tag and Split Files,  Prev: Batch Formatting,  Up: Create an Info File

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

  If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
automatically creates a tag table for its Info file;  `makeinfo' always
creates a tag table.  With a "tag table", Info can jump to new nodes
more quickly than it can otherwise.

  In addition, if the Texinfo file contains more than about 70,000
bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
into shorter "indirect" subfiles of about 50,000 bytes each.  Big files
are split into smaller files so that Emacs does not need to make a
large buffer to hold the whole of a large Info file; instead, Emacs
allocates just enough memory for the small, split off file that is
needed at the time.  This way, Emacs avoids wasting memory when you run
Info.  (Before splitting was implemented, Info files were always kept
short and "include files" were designed as a way to create a single,
large printed manual out of the smaller Info files.  *Note Include
Files::, for more information.  Include files are still used for very
large documents, such as `The 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 `test-texinfo' and that file looked like this:

     Info file: test-texinfo,    -*-Text-*-
     produced by texinfo-format-buffer
     from file: new-texinfo-manual.texinfo
     
     ^_
     Indirect:
     test-texinfo-1: 102
     test-texinfo-2: 50422
     test-texinfo-3: 101300
     ^_^L
     Tag table:
     (Indirect)
     Node: overview^?104
     Node: info file^?1271
     Node: printed manual^?4853
     Node: conventions^?6855
     ...

(But `test-texinfo' had far more nodes than are shown here.)  Each of
the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
`test-texinfo-3', is listed in this file after the line that says
`Indirect:'.  The tag table is listed after the line that says `Tag
table:'.

  In the list of indirect files, the number following the file name
records the cumulative number of bytes in the preceding indirect files,
not counting the file list itself, the tag table, or the permissions
text in each file.  In the tag table, the number following the node name
records the location of the beginning of the node, in bytes from the
beginning.

  If you are using `texinfo-format-buffer' to create Info files, you
may want to run the `Info-validate' command.  (The `makeinfo' command
does such a good job on its own, you do not need `Info-validate'.)
However, you cannot run the `M-x Info-validate' node-checking command
on indirect files.  For information on how to prevent files from being
split and how to validate the structure of the nodes, see *Note Using
Info-validate::.


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

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

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

* Menu:

* Directory file::              The top level menu for all Info files.
* New Info File::               Listing a new info file.
* Other Info Directories::      How to specify Info files that are
                                  located in other directories.


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

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

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

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

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

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

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

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

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

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


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

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

  To add a new Info file to your system, write a menu entry for it in
the menu in the `dir' file in the `info' directory.  Also, move the new
Info file itself to 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.

  Conventionally, the name of an Info file has a `.info' extension.
Thus, you might list the name of the file like this:

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

However, Info will look for a file with a `.info' extension if it does
not find the file under the name given in the menu.  This means that
you can refer to the file `gdb.info' as `gdb', as shown in the first
example.  This looks better.


File: texinfo.info,  Node: Other Info Directories,  Prev: New Info File,  Up: Install an Info File

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

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

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

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

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

   * Specify the `info' directory name in an 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 `~bob/manuals' directory,
you could add an entry like this to the menu in the `dir' file:

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

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

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

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

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

  Finally, you can tell Info where to look by setting the `INFOPATH'
environment variable in your `.cshrc' or `.profile' file.

  If you use `sh' or `bash' for your shell command interpreter, you
must set the `INFOPATH' environment variable in the `.profile'
initialization file; but if you use `csh', you must set the variable in
the `.cshrc' initialization file.  The two files require slightly
different command formats.

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

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

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

          INFOPATH=.:~bob/manuals:/usr/local/emacs/info
          export INFOPATH

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

