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: ifinfo Permissions,  Next: Titlepage Permissions,  Prev: Inserting Permissions,  Up: Sample Permissions

`ifinfo' Copying Permissions
============================

  In the `@ifinfo' section of a Texinfo file, the standard Free
Software Foundation permission notice reads as follows:

     This file documents ...
     
     Copyright 1992 Free Software Foundation, Inc.
     
     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.
     
     @ignore
     Permission is granted to process this file through TeX
     and print the results, provided the printed document
     carries a copying permission notice identical to this
     one except for the removal of this paragraph (this
     paragraph not being relevant to the printed manual).
     
     @end ignore
     Permission is granted to copy and distribute modified
     versions of this manual under the conditions for
     verbatim copying, provided also that the sections
     entitled ``Copying'' and ``GNU General Public License''
     are included exactly as in the original, and 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: Titlepage Permissions,  Prev: ifinfo Permissions,  Up: Sample Permissions

Titlepage Copying Permissions
=============================

  In the `@titlepage' section of a Texinfo file, the standard Free
Software Foundation copying permission notice follows the copyright
notice and publishing information.  The standard phrasing is as follows:

     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 also that the sections
     entitled ``Copying'' and ``GNU General Public License''
     are included exactly as in the original, and 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: Include Files,  Next: Headings,  Prev: Sample Permissions,  Up: Top

Include Files
*************

  When TeX or an Info formatting command sees an `@include' command in
a Texinfo file, it processes the contents of the file named by the
command and incorporates them into the DVI or Info file being created.
Index entries from the included file are incorporated into the indices
of the output file.

  Include files let you keep a single large document as a collection of
conveniently small parts.

* Menu:

* Using Include Files::         How to use the `@include' command.
* texinfo-multiple-files-update::  How to create and update nodes and
                                  menus when using included files.
* Include File Requirements::   What `texinfo-multiple-files-update' expects.
* Sample Include File::         A sample outer file with included files
                                  within it; and a sample included file.
* Include Files Evolution::     How use of the `@include' command
                                  has changed over time.


File: texinfo.info,  Node: Using Include Files,  Next: texinfo-multiple-files-update,  Prev: Include Files,  Up: Include Files

How to Use Include Files
========================

  To include another file within a Texinfo file, write the `@include'
command at the beginning of a line and follow it on the same line by
the name of a file to be included.  For example:

     @include buffers.texi

  An included file should simply be a segment of text that you expect to
be included as is into the overall or "outer" Texinfo file; it should
not contain the standard beginning and end parts of a Texinfo file.  In
particular, you should not start an included file with a line saying
`\input texinfo'; if you do, that phrase is inserted into the output
file as is.  Likewise, you should not end an included file with an
`@bye' command; nothing after `@bye' is formatted.

  In the past, you were required to write an `@setfilename' line at the
beginning of an included file, but no longer.  Now, it does not matter
whether you write such a line.  If an `@setfilename' line exists in an
included file, it is ignored.

  Conventionally, an included file begins with an `@node' line that is
followed by an `@chapter' line.  Each included file is one chapter.
This makes it easy to use the regular node and menu creating and
updating commands to create the node pointers and menus within the
included file.  However, the simple Emacs node and menu creating and
updating commands do not work with multiple Texinfo files.  Thus you
cannot use these commands to fill in the `Next', `Previous', and `Up'
pointers of the `@node' line that begins the included file.  Also, you
cannot use the regular commands to create a master menu for the whole
file.  Either you must insert the menus and the `Next', `Previous', and
`Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
command, `texinfo-multiple-files-update', that is designed for
`@include' files.


File: texinfo.info,  Node: texinfo-multiple-files-update,  Next: Include File Requirements,  Prev: Using Include Files,  Up: Include Files

`texinfo-multiple-files-update'
===============================

  GNU Emacs Texinfo mode provides the `texinfo-multiple-files-update'
command.  This command creates or updates `Next', `Previous', and `Up'
pointers of included files as well as those in the outer or overall
Texinfo file, and it creates or updates a main menu in the outer file.
Depending whether you call it with optional arguments, the command
updates only the pointers in the first `@node' line of the included
files or all of them:

`M-x texinfo-multiple-files-update'
     Called without any arguments:

        - Create or update the `Next', `Previous', and `Up' pointers of
          the first `@node' line in each file included in an outer or
          overall Texinfo file.

        - Create or update the `Top' level node pointers of the outer or
          overall file.

        - Create or update a main menu in the outer file.

`C-u M-x texinfo-multiple-files-update'
     Called with `C-u' as a prefix argument:

        - Create or update pointers in the first `@node' line in each
          included file.

        - Create or update the `Top' level node pointers of the outer
          file.

        - Create and insert a master menu in the outer file.  The
          master menu is made from all the menus in all the included
          files.

`C-u 8 M-x texinfo-multiple-files-update'
     Called with a numeric prefix argument, such as `C-u 8':

        - Create or update *all* the `Next', `Previous', and `Up'
          pointers of all the included files.

        - Create or update *all* the menus of all the included files.

        - Create or update the `Top' level node pointers of the outer or
          overall file.

        - And then create a master menu in the outer file.  This is
          similar to invoking `texinfo-master-menu' with an argument
          when you are working with just one file.

  Note the use of the prefix argument in interactive use: with a regular
prefix argument, just `C-u', the `texinfo-multiple-files-update'
command inserts a master menu; with a numeric prefix argument, such as
`C-u 8', the command updates *every* pointer and menu in *all* the
files and then inserts a master menu.


File: texinfo.info,  Node: Include File Requirements,  Next: Sample Include File,  Prev: texinfo-multiple-files-update,  Up: Include Files

Include File Requirements
=========================

  If you plan to use the `texinfo-multiple-files-update' command, the
outer Texinfo file that lists included files within it should contain
nothing but the beginning and end parts of a Texinfo file, and a number
of `@include' commands listing the included files.  It should not even
include indices, which should be listed in an included file of their
own.

  Moreover, each of the included files must contain exactly one highest
level node (conventionally, `@chapter' or equivalent), and this node
must be the first node in the included file.  Furthermore, each of
these highest level nodes in each included file must be at the same
hierarchical level in the file structure.  Usually, each is an
`@chapter', an `@appendix', or an `@unnumbered' node.  Thus, normally,
each included file contains one, and only one, chapter or
equivalent-level node.

  The outer file should contain only *one* node, the `Top' node.  It
should *not* contain any nodes besides the single `Top' node.  The
`texinfo-multiple-files-update' command will not process them.


File: texinfo.info,  Node: Sample Include File,  Next: Include Files Evolution,  Prev: Include File Requirements,  Up: Include Files

Sample File with `@include'
===========================

  Here is an example of a complete outer Texinfo file with `@include'
files within it before running `texinfo-multiple-files-update', which
would insert a main or master menu:

     \input texinfo @c -*-texinfo-*-
     @setfilename  include-example.info
     @settitle Include Example
     
     @setchapternewpage odd
     @titlepage
     @sp 12
     @center @titlefont{Include Example}
     @sp 2
     @center by Whom Ever
     
     @page
     @vskip 0pt plus 1filll
     Copyright @copyright{} 1990 Free Software Foundation, Inc.
     @end titlepage
     
     @ifinfo
     @node Top, First, (dir), (dir)
     @top Master Menu
     @end ifinfo
     
     @include foo.texinfo
     @include bar.texinfo
     @include concept-index.texinfo
     
     @summarycontents
     @contents
     
     @bye

  An included file, such as `foo.texinfo', might look like this:

     @node First, Second, , Top
     @chapter First Chapter
     
     Contents of first chapter ...

  The full contents of `concept-index.texinfo' might be as simple as
this:

     @node Concept Index, , Second, Top
     @unnumbered Concept Index
     
     @printindex cp

  The outer Texinfo source file for `The GNU Emacs Lisp Reference
Manual' is named `elisp.texi'.  This outer file contains a master menu
with 417 entries and a list of 41 `@include' files.


File: texinfo.info,  Node: Include Files Evolution,  Prev: Sample Include File,  Up: Include Files

Evolution of Include Files
==========================

  When Info was first created, it was customary to create many small
Info files on one subject.  Each Info file was formatted from its own
Texinfo source file.  This custom meant that Emacs did not need to make
a large buffer to hold the whole of a large Info file when someone
wanted information; instead, Emacs allocated just enough memory for the
small Info file that contained the particular information sought.  This
way, Emacs could avoid wasting memory.

  References from one file to another were made by referring to the file
name as well as the node name. (*Note Referring to Other Info Files:
Other Info Files.  Also, see *Note `@xref' with Four and Five
Arguments: Four and Five Arguments.)

  Include files were designed primarily as a way to create a single,
large printed manual out of several smaller Info files.  In a printed
manual, all the references were within the same document, so TeX could
automatically determine the references' page numbers.  The Info
formatting commands used include files only for creating joint indices;
each of the individual Texinfo files had to be formatted for Info
individually.  (Each, therefore, required its own `@setfilename' line.)

  However, because large Info files are now split automatically, it is
no longer necessary to keep them small.

  Nowadays, multiple Texinfo files are used mostly for large documents,
such as `The GNU Emacs Lisp Reference Manual', and for projects in
which several different people write different sections of a document
simultaneously.

  In addition, the Info formatting commands have been extended to work
with the `@include' command so as to create a single large Info file
that is split into smaller files if necessary.  This means that you can
write menus and cross references without naming the different Texinfo
files.


File: texinfo.info,  Node: Headings,  Next: Catching Mistakes,  Prev: Include Files,  Up: Top

Page Headings
*************

  Most printed manuals contain headings along the top of every page
except the title and copyright pages.  Some manuals also contain
footings.  (Headings and footings have no meaning to Info, which is not
paginated.)

* Menu:

* Headings Introduced::         Conventions for using page headings.
* Heading Format::              Standard page heading formats.
* Heading Choice::              How to specify the type of page heading.
* Custom Headings::             How to create your own headings and footings.


File: texinfo.info,  Node: Headings Introduced,  Next: Heading Format,  Prev: Headings,  Up: Headings

Headings Introduced
===================

  Texinfo provides standard page heading formats for manuals that are
printed on one side of each sheet of paper and for manuals that are
printed on both sides of the paper.  Usually, you will use one or other
of these formats, but you can specify your own format, if you wish.

  In addition, you can specify whether chapters should begin on a new
page, or merely continue the same page as the previous chapter; and if
chapters begin on new pages, you can specify whether they must be
odd-numbered pages.

  By convention, a book is printed on both sides of each sheet of paper.
When you open a book, the right-hand page is odd-numbered, and chapters
begin on right-hand pages--a preceding left-hand page is left blank if
necessary.  Reports, however, are often printed on just one side of
paper, and chapters begin on a fresh page immediately following the end
of the preceding chapter.  In short or informal reports, chapters often
do not begin on a new page at all, but are separated from the preceding
text by a small amount of whitespace.

  The `@setchapternewpage' command controls whether chapters begin on
new pages, and whether one of the standard heading formats is used.  In
addition, Texinfo has several heading and footing commands that you can
use to generate your own heading and footing formats.

  In Texinfo, headings and footings are single lines at the tops and
bottoms of pages; you cannot create multiline headings or footings.
Each header or footer line is divided into three parts: a left part, a
middle part, and a right part.  Any part, or a whole line, may be left
blank.  Text for the left part of a header or footer line is set
flushleft; text for the middle part is centered; and, text for the
right part is set flushright.


File: texinfo.info,  Node: Heading Format,  Next: Heading Choice,  Prev: Headings Introduced,  Up: Headings

Standard Heading Formats
========================

  Texinfo provides two standard heading formats, one for manuals printed
on one side of each sheet of paper, and the other for manuals printed
on both sides of the paper.

  By default, nothing is specified for the footing of a Texinfo file,
so the footing remains blank.

  The standard format for single-sided printing consists of a header
line in which the left-hand part contains the name of the chapter, the
central part is blank, and the right-hand part contains the page number.

  A single-sided page looks like this:

        _______________________
       |                       |
       | chapter   page number |
       |                       |
       | Start of text ...     |
       | ...                   |
       |                       |

  The standard format for two-sided printing depends on whether the page
number is even or odd.  By convention, even-numbered pages are on the
left- and odd-numbered pages are on the right.  (TeX will adjust the
widths of the left- and right-hand margins.  Usually, widths are
correct, but during double-sided printing, it is wise to check that
pages will bind properly--sometimes a printer will produce output in
which the even-numbered pages have a larger right-hand margin than the
odd-numbered pages.)

  In the standard double-sided format, the left part of the left-hand
(even-numbered) page contains the page number, the central part is
blank, and the right part contains the title (specified by the
`@settitle' command).  The left part of the right-hand (odd-numbered)
page contains the name of the chapter, the central part is blank, and
the right part contains the page number.

  Two pages, side by side as in an open book, look like this:

        _______________________     _______________________
       |                       |   |                       |
       | page number     title |   | chapter   page number |
       |                       |   |                       |
       | Start of text ...     |   | More  text ...        |
       | ...                   |   | ...                   |
       |                       |   |                       |

The chapter name is preceded by the word `Chapter', the chapter number
and a colon.  This makes it easier to keep track of where you are in
the manual.


File: texinfo.info,  Node: Heading Choice,  Next: Custom Headings,  Prev: Heading Format,  Up: Headings

Specifying the Type of Heading
==============================

  TeX does not begin to generate page headings for a standard Texinfo
file until it reaches the `@end titlepage' command.  Thus, the title
and copyright pages are not numbered.  The `@end titlepage' command
causes TeX to begin to generate page headings according to a standard
format specified by the `@setchapternewpage' command that precedes the
`@titlepage' section.

  There are four possibilities:

No `@setchapternewpage' command
     Cause TeX to specify the single-sided heading format, with chapters
     on new pages. This is the same as `@setchapternewpage on'.

`@setchapternewpage on'
     Specify the single-sided heading format, with chapters on new
     pages.

`@setchapternewpage off'
     Cause TeX to start a new chapter on the same page as the last page
     of the preceding chapter, after skipping some vertical whitespace.
     Also cause TeX to typeset for single-sided printing.  (You can
     override the headers format with the `@headings double' command;
     see *Note The `@headings' Command: headings on off.)

`@setchapternewpage odd'
     Specify the double-sided heading format, with chapters on new
     pages.

Texinfo lacks an `@setchapternewpage even' command.


File: texinfo.info,  Node: Custom Headings,  Prev: Heading Choice,  Up: Headings

How to Make Your Own Headings
=============================

  You can use the standard headings provided with Texinfo or specify
your own.

  Texinfo provides six commands for specifying headings and footings.
The `@everyheading' command and `@everyfooting' command generate page
headers and footers that are the same for both even- and odd-numbered
pages.  The `@evenheading' command and `@evenfooting' command generate
headers and footers for even-numbered (left-hand) pages; and the
`@oddheading' command and `@oddfooting' command generate headers and
footers for odd-numbered (right-hand) pages.

  Write custom heading specifications in the Texinfo file immediately
after the `@end titlepage' command.  Enclose your specifications
between `@iftex' and `@end iftex' commands since the
`texinfo-format-buffer' command may not recognize them.  Also, you must
cancel the predefined heading commands with the `@headings off' command
before defining your own specifications.

  Here is how to tell TeX to place the chapter name at the left, the
page number in the center, and the date at the right of every header
for both even- and odd-numbered pages:

     @iftex
     @headings off
     @everyheading @thischapter @| @thispage @| @today{}
     @end iftex

You need to divide the left part from the central part and the central
part from the right had part by inserting `@|' between parts.
Otherwise, the specification command will not be able to tell where the
text for one part ends and the next part begins.

  Each part can contain text or @-commands.  The text is printed as if
the part were within an ordinary paragraph in the body of the page.
The @-commands replace themselves with the page number, date, chapter
name, or whatever.

  Here are the six heading and footing commands:

`@everyheading LEFT @| CENTER @| RIGHT'
`@everyfooting LEFT @| CENTER @| RIGHT'
     The `every' commands specify the format for both even- and
     odd-numbered pages.  These commands are for documents that are
     printed on one side of each sheet of paper, or for documents in
     which you want symmetrical headers or footers.

`@evenheading LEFT @| CENTER @| RIGHT'
`@oddheading  LEFT @| CENTER @| RIGHT'
`@evenfooting LEFT @| CENTER @| RIGHT'
`@oddfooting  LEFT @| CENTER @| RIGHT'
     The `even' and `odd' commands specify the format for even-numbered
     pages and odd-numbered pages.  These commands are for books and
     manuals that are printed on both sides of each sheet of paper.

  Use the `@this...' series of @-commands to provide the names of
chapters and sections and the page number.  You can use the `@this...'
commands in the left, center, or right portions of headers and footers,
or anywhere else in a Texinfo file so long as they are between `@iftex'
and `@end iftex' commands.

  Here are the `@this...' commands:

`@thispage'
     Expands to the current page number.

`@thischaptername'
     Expands to the name of the current chapter.

`@thischapter'
     Expands to the number and name of the current chapter, in the
     format `Chapter 1: Title'.

`@thistitle'
     Expands to the name of the document, as specified by the
     `@settitle' command.

`@thisfile'
     For `@include' files only: expands to the name of the current
     `@include' file.  If the current Texinfo source file is not an
     `@include' file, this command has no effect.  This command does
     *not* provide the name of the current Texinfo source file unless
     it is an `@include' file.  (*Note Include Files::, for more
     information about `@include' files.)

You can also use the `@today{}' command, which expands to the current
date, in `1 Jan 1900' format.

  Other @-commands and text are printed in a header or footer just as
if they were in the body of a page.  It is useful to incorporate text,
particularly when you are writing drafts:

     @iftex
     @headings off
     @everyheading @emph{Draft!} @| @thispage @| @thischapter
     @everyfooting @| @| Version: 0.27: @today{}
     @end iftex

  Beware of overlong titles: they may overlap another part of the
header or footer and blot it out.


File: texinfo.info,  Node: Catching Mistakes,  Next: Refilling Paragraphs,  Prev: Headings,  Up: Top

Formatting Mistakes
*******************

  Besides mistakes in the content of your documentation, there are two
kinds of mistake you can make with Texinfo:  you can make mistakes with
@-commands, and you can make mistakes with the structure of the nodes
and chapters.

  Emacs has two tools for catching the @-command mistakes and two for
catching structuring mistakes.

  For finding problems with @-commands, you can run TeX or a region
formatting command on the region that has a problem; indeed, you can
run these commands on each region as you write it.

  For finding problems with the structure of nodes and chapters, you
can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
command and you can use the `M-x Info-validate' command.

* Menu:

* makeinfo preferred::          `makeinfo' finds errors.
* Debugging with Info::         How to catch errors with Info formatting.
* Debugging with TeX::          How to catch errors with TeX formatting.
* Using texinfo-show-structure::  How to use `texinfo-show-structure'.
* Using occur::                 How to list all lines containing a pattern.
* Running Info-Validate::       How to find badly referenced nodes.


File: texinfo.info,  Node: makeinfo preferred,  Next: Debugging with Info,  Prev: Catching Mistakes,  Up: Catching Mistakes

`makeinfo' Find Errors
======================

  The `makeinfo' program does an excellent job of catching errors and
reporting them--far better than `texinfo-format-region' or
`texinfo-format-buffer'.  In addition, the various functions for
automatically creating and updating node pointers and menus remove many
opportunities for human error.

  If you can, use the updating commands to create and insert pointers
and menus.  These prevent many errors.  Then use `makeinfo' (or its
Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
to format your file and check for other errors.  This is the best way
to work with Texinfo.  But if you cannot use `makeinfo', or your
problem is very puzzling, then you may want to use the tools described
in this appendix.


File: texinfo.info,  Node: Debugging with Info,  Next: Debugging with TeX,  Prev: makeinfo preferred,  Up: Catching Mistakes

Catching Errors with Info Formatting
====================================

  After you have written part of a Texinfo file, you can use the
`texinfo-format-region' or the `makeinfo-region' command to see whether
the region formats properly.

  Most likely, however, you are reading this section because for some
reason you cannot use the `makeinfo-region' command; therefore, the
rest of this section presumes that you are using
`texinfo-format-region'.

  If you have made a mistake with an @-command, `texinfo-format-region'
will stop processing at or after the error and display an error
message.  To see where in the buffer the error occurred, switch to the
`*Info Region*' buffer; the cursor will be in a position that is after
the location of the error.  Also, the text will not be formatted after
the place where the error occurred (or more precisely, where it was
detected).

  For example, if you accidentally end a menu with the command `@end
menus' with an `s' on the end, instead of with `@end menu', you will
see an error message that says:

     @end menus is not handled by texinfo

The cursor will stop at the point in the buffer where the error occurs,
or not long after it.  The buffer will look like this:

     ---------- Buffer: *Info Region* ----------
     * Menu:
     
     * Using texinfo-show-structure::  How to use
                                       `texinfo-show-structure'
                                       to catch mistakes.
     * Running Info-Validate::         How to check for
                                       unreferenced nodes.
     @end menus
     -!-
     ---------- Buffer: *Info Region* ----------

  The `texinfo-format-region' command sometimes provides slightly odd
error messages.  For example, the following cross reference fails to
format:

     (@xref{Catching Mistakes, for more info.)

In this case, `texinfo-format-region' detects the missing closing brace
but displays a message that says `Unbalanced parentheses' rather than
`Unbalanced braces'.  This is because the formatting command looks for
mismatches between braces as if they were parentheses.

  Sometimes `texinfo-format-region' fails to detect mistakes.  For
example, in the following, the closing brace is swapped with the
closing parenthesis:

     (@xref{Catching Mistakes), for more info.}

Formatting produces:
     (*Note for more info.: Catching Mistakes)

  The only way for you to detect this error is to realize that the
reference should have looked like this:

     (*Note Catching Mistakes::, for more info.)

  Incidentally, if you are reading this node in Info and type `f RET'
(`Info-follow-reference'), you will generate an error message that says:

     No such node: "Catching Mistakes) The only way ...

This is because Info perceives the example of the error as the first
cross reference in this node and if you type a RET immediately after
typing the Info `f' command, Info will attempt to go to the referenced
node.  If you type `f catch TAB RET', Info will complete the node name
of the correctly written example and take you to the `Catching
Mistakes' node.  (If you try this, you can return from the `Catching
Mistakes' node by typing `l' (`Info-last').)


File: texinfo.info,  Node: Debugging with TeX,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes

Catching Errors with TeX Formatting
===================================

  You can also catch mistakes when you format a file with TeX.

  Usually, you will want to do this after you have run
`texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same
file, because `texinfo-format-buffer' sometimes displays error messages
that make more sense than TeX.  (*Note Debugging with Info::, for more
information.)

  For example, TeX was run on a Texinfo file, part of which is shown
here:

     ---------- Buffer: texinfo.texi ----------
     name of the Texinfo file as an extension.  The
     @samp{??} are `wildcards' that cause the shell to
     substitute all the raw index files.  (@xref{sorting
     indices, for more information about sorting
     indices.)@refill
     ---------- Buffer: texinfo.texi ----------

(The cross reference lacks a closing brace.) TeX produced the following
output, after which it stopped:

     ---------- Buffer: *tex-shell* ----------
     Runaway argument?
     {sorting indices, for more information about sorting
     indices.) @refill @ETC.
     ! Paragraph ended before @xref was complete.
     <to be read again>
                        @par
     l.27
     
     ?
     ---------- Buffer: *tex-shell* ----------

  In this case, TeX produced an accurate and understandable error
message:

     Paragraph ended before @xref was complete.

`@par' is an internal TeX command of no relevance to Texinfo.  `l.27'
means that TeX detected the problem on line 27 of the Texinfo file.
The `?' is the prompt TeX uses in this circumstance.

  Unfortunately, TeX is not always so helpful, and sometimes you must
truly be a Sherlock Holmes to discover what went wrong.

  In any case, if you run into a problem like this, you can do one of
three things.

  1. You can tell TeX to continue running and ignore just this error by
     typing RET at the `?' prompt.

  2. You can tell TeX to continue running and to ignore all errors as
     best it can by typing `r RET' at the `?' prompt.

     This is often the best thing to do.  However, beware: the one error
     may produce a cascade of additional error messages as its
     consequences are felt through the rest of the file.  (To stop TeX
     when it is producing such an avalanche of error messages, type
     `C-d' (or `C-c C-d', if you are running a shell inside Emacs.))

  3. You can tell TeX to stop this run by typing `x RET' at the `?'
     prompt.

  Please note that if you are running TeX inside Emacs, you need to
switch to the shell buffer and line at which TeX offers the `?' prompt.

  Sometimes TeX will format a file without producing error messages even
though there is a problem.  This usually occurs if a command is not
ended but TeX is able to continue processing anyhow.  For example, if
you fail to end an itemized list with the `@end itemize' command, TeX
will write a DVI file that you can print out.  The only error message
that TeX will give you is the somewhat mysterious comment that

     (@end occurred inside a group at level 1)

However, if you print the DVI file, you will find that the text of the
file that follows the itemized list is entirely indented as if it were
part of the last item in the itemized list.  The error message is the
way TeX says that it expected to find an `@end' command somewhere in
the file; but that it could not determine where it was needed.

  Another source of notoriously hard-to-find errors is a missing `@end
group' command.  If you ever are stumped by incomprehensible errors,
look for a missing `@end group' command first.

  If the Texinfo file lacks header lines, TeX may stop in the beginning
of its run and display output that looks like the following.  The `*'
indicates that TeX is waiting for input.

     This is TeX, Version 2.0 for Berkeley UNIX
     (preloaded format=plain-cm 87.10.25)
     (test.texinfo [1])
     *

In this case, simply type `\end RET' after the asterisk.  Then write
the header lines in the Texinfo file and run the TeX command again.
(Note the use of the backslash, `\'.  TeX uses `\' instead of `@'; and
in this circumstance, you are working directly with TeX, not with
Texinfo.)


File: texinfo.info,  Node: Using texinfo-show-structure,  Next: Using occur,  Prev: Debugging with TeX,  Up: Catching Mistakes

Using `texinfo-show-structure'
==============================

  It is not always easy to keep track of the nodes, chapters, sections,
and subsections of a Texinfo file.  This is especially true if you are
revising or adding to a Texinfo file that someone else has written.

  In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
lists all the lines that begin with the @-commands that specify the
structure: `@chapter', `@section', `@appendix', and so on.  With an
argument (`C-u' as prefix argument, if interactive), the command also
shows the `@node' lines.  The `texinfo-show-structure' command is bound
to `C-c C-s' in Texinfo mode, by default.

  The lines are displayed in a buffer called the `*Occur*' buffer,
indented by hierarchical level.  For example, here is a part of what was
produced by running `texinfo-show-structure' on this manual:

      Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
      unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
      in buffer texinfo.texi.
      ...
      4177:@chapter Nodes
      4198:    @heading Two Paths
      4231:    @section Node and Menu Illustration
      4337:    @section The @code{@@node} Command
      4393:        @subheading Choosing Node and Pointer Names
      4417:        @subsection How to Write an @code{@@node} Line
      4469:        @subsection @code{@@node} Line Tips
      ...

  This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
with the `@section', `@subheading', and `@subsection' commands
respectively.  If you move your cursor into the `*Occur*' window, you
can position the cursor over one of the lines and use the `C-c C-c'
command (`occur-mode-goto-occurrence'), to jump to the corresponding
spot in the Texinfo file.  *Note Using Occur: (emacs)Other Repeating
Search, for more information about `occur-mode-goto-occurrence'.

  The first line in the `*Occur*' window describes the "regular
expression" specified by TEXINFO-HEADING-PATTERN.  This regular
expression is the pattern that `texinfo-show-structure' looks for.
*Note Using Regular Expressions: (emacs)Regexps, for more information.

  When you invoke the `texinfo-show-structure' command, Emacs will
display the structure of the whole buffer.  If you want to see the
structure of just a part of the buffer, of one chapter, for example,
use the `C-x n n' (`narrow-to-region') command to mark the region.
(*Note Narrowing: (emacs)Narrowing.)  This is how the example used
above was generated.  (To see the whole buffer again, use `C-x n w'
(`widen').)

  If you call `texinfo-show-structure' with a prefix argument by typing
`C-u C-c C-s', it will list lines beginning with `@node' as well as the
lines beginning with the @-sign commands for `@chapter', `@section',
and the like.

  You can remind yourself of the structure of a Texinfo file by looking
at the list in the `*Occur*' window; and if you have mis-named a node
or left out a section, you can correct the mistake.


File: texinfo.info,  Node: Using occur,  Next: Running Info-Validate,  Prev: Using texinfo-show-structure,  Up: Catching Mistakes

Using `occur'
=============

  Sometimes the `texinfo-show-structure' command produces too much
information.  Perhaps you want to remind yourself of the overall
structure of a Texinfo file, and are overwhelmed by the detailed list
produced by `texinfo-show-structure'.  In this case, you can use the
`occur' command directly.  To do this, type

     `M-x occur'

and then, when prompted, type a "regexp", a regular expression for the
pattern you want to match.  (*Note Regular Expressions:
(emacs)Regexps.)  The `occur' command works from the current location
of the cursor in the buffer to the end of the buffer.  If you want to
run `occur' on the whole buffer, place the cursor at the beginning of
the buffer.

  For example, to see all the lines that contain the word `@chapter' in
them, just type `@chapter'.  This will produce a list of the chapters.
It will also list all the sentences with `@chapter' in the middle of
the line.

  If you want to see only those lines that start with the word
`@chapter', type `^@chapter' when prompted by `occur'.  If you want to
see all the lines that end with a word or phrase, end the last word
with a `$'; for example, `catching mistakes$'.  This can be helpful
when you want to see all the nodes that are part of the same chapter or
section and therefore have the same `Up' pointer.

  *Note Using Occur: (emacs)Other Repeating Search, for more
information.


File: texinfo.info,  Node: Running Info-Validate,  Prev: Using occur,  Up: Catching Mistakes

Finding Badly Referenced Nodes
==============================

  You can use the `Info-validate' command to check whether any of the
`Next', `Previous', `Up' or other node pointers fail to point to a
node.  This command checks that every node pointer points to an
existing node.  The `Info-validate' command works only on Info files,
not on Texinfo files.

  The `makeinfo' program validates pointers automatically, so you do
not need to use the `Info-validate' command if you are using
`makeinfo'.  You only may need to use `Info-validate' if you are unable
to run `makeinfo' and instead must create an Info file using
`texinfo-format-region' or `texinfo-format-buffer', or if you write an
Info file from scratch.

* Menu:

* Using Info-validate::         How to run `Info-validate'.
* Unsplit::                     How to create an unsplit file.
* Tagifying::                   How to tagify a file.
* Splitting::                   How to split a file manually.


File: texinfo.info,  Node: Using Info-validate,  Next: Unsplit,  Prev: Running Info-Validate,  Up: Running Info-Validate

Running `Info-validate'
-----------------------

  To use `Info-validate', visit the Info file you wish to check and
type:

     M-x Info-validate

(Note that the `Info-validate' command requires an upper case `I'.  You
may also need to create a tag table before running `Info-validate'.
*Note Tagifying::.)

  If your file is valid, you will receive a message that says "File
appears valid".  However, if you have a pointer that does not point to
a node, error messages will be displayed in a buffer called `*problems
in info file*'.

  For example, `Info-validate' was run on a test file that contained
only the first node of this manual.  One of the messages said:

     In node "Overview", invalid Next: Texinfo Mode

This meant that the node called `Overview' had a `Next' pointer that
did not point to anything (which was true in this case, since the test
file had only one node in it).

  Now suppose we add a node named `Texinfo Mode' to our test case but
we do not specify a `Previous' for this node.  Then we will get the
following error message:

     In node "Texinfo Mode", should have Previous: Overview

This is because every `Next' pointer should be matched by a `Previous'
(in the node where the `Next' points) which points back.

  `Info-validate' also checks that all menu entries and cross references
point to actual nodes.

  Note that `Info-validate' requires a tag table and does not work with
files that have been split.  (The `texinfo-format-buffer' command
automatically splits large files.)  In order to use `Info-validate' on
a large file, you must run `texinfo-format-buffer' with an argument so
that it does not split the Info file; and you must create a tag table
for the unsplit file.


File: texinfo.info,  Node: Unsplit,  Next: Tagifying,  Prev: Using Info-validate,  Up: Running Info-Validate

Creating an Unsplit File
------------------------

  You can run `Info-validate' only on a single Info file that has a tag
table.  The command will not work on the indirect subfiles that are
generated when a master file is split.  If you have a large file
(longer than 70,000 bytes or so), you need to run the
`texinfo-format-buffer' or `makeinfo-buffer' command in such a way that
it does not create indirect subfiles.  You will also need to create a
tag table for the Info file.  After you have done this, you can run
`Info-validate' and look for badly referenced nodes.

  The first step is to create an unsplit Info file.  To prevent
`texinfo-format-buffer' from splitting a Texinfo file into smaller Info
files, give a prefix to the `M-x texinfo-format-buffer' command:

     C-u M-x texinfo-format-buffer

or else

     C-u C-c C-e C-b

When you do this, Texinfo will not split the file and will not create a
tag table for it.


File: texinfo.info,  Node: Tagifying,  Next: Splitting,  Prev: Unsplit,  Up: Running Info-Validate

Tagifying a File
----------------

  After creating an unsplit Info file, you must create a tag table for
it.  Visit the Info file you wish to tagify and type:

     M-x Info-tagify

(Note the upper case I in `Info-tagify'.)  This creates an Info file
with a tag table that you can validate.

  The third step is to validate the Info file:

     M-x Info-validate

(Note the upper case I in `Info-validate'.) In brief, the steps are:

     C-u M-x texinfo-format-buffer
     M-x Info-tagify
     M-x Info-validate

  After you have validated the node structure, you can rerun
`texinfo-format-buffer' in the normal way so it will construct a tag
table and split the file automatically, or you can make the tag table
and split the file manually.


File: texinfo.info,  Node: Splitting,  Prev: Tagifying,  Up: Running Info-Validate

Splitting a File Manually
-------------------------

  You should split a large file or else let the `texinfo-format-buffer'
or `makeinfo-buffer' command do it for you automatically.  (Generally
you will let one of the formatting commands do this job for you.  *Note
Create an Info File::.)

  The split-off files are called the indirect subfiles.

  Info files are split to save memory.  With smaller files, Emacs does
not have make such a large buffer to hold the information.

  If an Info file has more than 30 nodes, you should also make a tag
table for it. *Note Using Info-validate::, for information about
creating a tag table.  (Again, tag tables are usually created
automatically by the formatting command; you only need to create a tag
table yourself if you are doing the job manually.  Most likely, you
will do this for a large, unsplit file on which you have run
`Info-validate'.)

  Visit the Info file you wish to tagify and split and type the two
commands:

     M-x Info-tagify
     M-x Info-split

(Note that the `I' in `Info' is upper case.)

  When you use the `Info-split' command, the buffer is modified into a
(small) Info file which lists the indirect subfiles.  This file should
be saved in place of the original visited file.  The indirect subfiles
are written in the same directory the original file is in, with names
generated by appending `-' and a number to the original file name.

  The primary file still functions as an Info file, but it contains just
the tag table and a directory of subfiles.


File: texinfo.info,  Node: Refilling Paragraphs,  Next: Command Syntax,  Prev: Catching Mistakes,  Up: Top

Refilling Paragraphs
********************

  The `@refill' command refills and, optionally, indents the first line
of a paragraph.(1) (*note Refilling Paragraphs-Footnotes::) The
`@refill' command is no longer important, but we describe it here
because you once needed it.  You will see it in many old Texinfo files.

  Without refilling, paragraphs containing long @-constructs may look
bad after formatting because the formatter removes @-commands and
shortens some lines more than others.  In the past, neither the
`texinfo-format-region' command nor the `texinfo-format-buffer' command
refilled paragraphs automatically.  The `@refill' command had to be
written at the end of every paragraph to cause these formatters to fill
them.  (Both TeX and `makeinfo' have always refilled paragraphs
automatically.)  Now, all the Info formatters automatically fill and
indent those paragraphs that need to be filled and indented.

  The `@refill' command causes `texinfo-format-region' and
`texinfo-format-buffer' to refill a paragraph in the Info file *after*
all the other processing has been done.  For this reason, you can not
use `@refill' with a paragraph containing either `@*' or `@w{ ... }'
since the refilling action will override those two commands.

  The `texinfo-format-region' and `texinfo-format-buffer' commands now
automatically append `@refill' to the end of each paragraph that should
be filled.  They do not append `@refill' to the ends of paragraphs that
contain `@*' or `@w{ ...}' and therefore do not refill or indent them.


File: texinfo.info,  Node: Refilling Paragraphs-Footnotes,  Up: Refilling Paragraphs

  (1)  Perhaps the command should have been called the
`@refillandindent' command, but `@refill' is shorter and the name was
chosen before indenting was possible.


File: texinfo.info,  Node: Command Syntax,  Next: Obtaining TeX,  Prev: Refilling Paragraphs,  Up: Top

@-Command Syntax
****************

  The character `@' is used to start special Texinfo commands.  (It has
the same meaning that `\' has in PlainTeX.)  Texinfo has four types of
@-command:

1. Non-alphabetic commands.
     These commands consist of an @ followed by a punctuation mark or
     other character that is not part of the alphabet.  Non-alphabetic
     commands are almost always part of the text within a paragraph,
     and never take any argument.  The two characters (@ and the other
     one) are complete in themselves; none is followed by braces.  The
     non-alphabetic commands are: `@.', `@:', `@*', `@@', `@{', and
     `@}'.

2. Alphabetic commands that do not require arguments.
     These commands start with @ followed by a word followed by left-
     and right-hand braces.  These commands insert special symbols in
     the document; they do not require arguments.  For example,
     `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and
     `@bullet{}' => `*'.

3. Alphabetic commands that require arguments within braces.
     These commands start with @ followed by a letter or a word,
     followed by an argument within braces.  For example, the command
     `@dfn' indicates the introductory or defining use of a term; it is
     used as follows: `In Texinfo, @@-commands are @dfn{mark-up}
     commands.'

4. Alphabetic commands that occupy an entire line.
     These commands occupy an entire line.  The line starts with @,
     followed by the name of the command (a word); for example,
     `@center' or `@cindex'.  If no argument is needed, the word is
     followed by the end of the line.  If there is an argument, it is
     separated from the command name by a space.  Braces are not used.

  Thus, the alphabetic commands fall into classes that have different
argument syntaxes.  You cannot tell to which class a command belongs by
the appearance of its name, but you can tell by the command's meaning:
if the command stands for a glyph, it is in class 2 and does not
require an argument; if it makes sense to use the command together with
other text as part of a paragraph, the command is in class 3 and must
be followed by an argument in braces; otherwise, it is in class 4 and
uses the rest of the line as its argument.

  The purpose of having a different syntax for commands of classes 3 and
4 is to make Texinfo files easier to read, and also to help the GNU
Emacs paragraph and filling commands work properly.  There is only one
exception to this rule: the command `@refill', which is always used at
the end of a paragraph immediately following the final period or other
punctuation character.  `@refill' takes no argument and does *not*
require braces.  `@refill' never confuses the Emacs paragraph commands
because it cannot appear at the beginning of a line.

