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: Tips,  Next: Sample Texinfo Files,  Prev: Command List,  Up: Top

Tips and Hints
**************

  Here are some tips for writing Texinfo documentation:

   * Write in the present tense, not in the past or the future.

   * Write actively!  For example, write "We recommend that ..." rather
     than "It is recommended that ...".

   * Use 70 or 72 as your fill column.  Longer lines are hard to read.

   * Include a copyright notice and copying permissions.

Index, Index, Index!
....................

  Write many index entries, in different ways.  Readers like indices;
they are helpful and convenient.

  Although it is easiest to write index entries as you write the body of
the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.

  Here are more hints we have found valuable:

   * Write each index entry differently, so each entry refers to a
     different place in the document.

   * Write index entries only where a topic is discussed significantly.
     For example, it is not useful to index "debugging information" in
     a chapter on reporting bugs.  Someone who wants to know about
     debugging information will certainly not find it in that chapter.

   * Consistently capitalize the first word of every concept index
     entry, or else consistently use lower case.  Terse entries often
     call for lower case; longer entries for capitalization.  Whichever
     case convention you use, please use one or the other consistently!
     Mixing the two styles looks bad.

   * Always capitalize or use upper case for those words in an index for
     which this is proper, such as names of countries or acronyms.
     Always use the appropriate case for case-sensitive names, such as
     those in C or Lisp.

   * Write the indexing commands that refer to a whole section
     immediately after the section command, and write the indexing
     commands that refer to a paragraph before that paragraph.

     In the example that follows, a blank line comes after the index
     entry for "Leaping":

          @section The Dog and the Fox
          @cindex Jumping, in general
          @cindex Leaping
          
          @cindex Dog, lazy, jumped over
          @cindex Lazy dog jumped over
          @cindex Fox, jumps over dog
          @cindex Quick fox jumps over dog
          The quick brown fox jumps over the lazy dog.

     (Note that the example shows entries for the same concept that are
     written in different ways--`Lazy dog', and `Dog, lazy'--so readers
     can look up the concept in different ways.)

Blank Lines
...........

   * Insert a blank line between a sectioning command and the first
     following sentence or paragraph, or between the indexing commands
     associated with the sectioning command and the first following
     sentence or paragraph, as shown in the tip on indexing.
     Otherwise, a formatter may fold title and paragraph together.

   * Always insert a blank line before an `@table' command and after an
     `@end table' command; but never insert a blank line after an
     `@table' command or before an `@end table' command.

     For example,

          Types of fox:
          
          @table @samp
          @item Quick
          Jump over lazy dogs.
          
          @item Brown
          Also jump over lazy dogs.
          @end table
          @noindent
          On the other hand, ...

     Insert blank lines before and after `@itemize' ... `@end itemize'
     and `@enumerate' ... `@end enumerate' in the same way.

Complete Phrases
................

  Complete phrases are easier to read than ...

   * Write entries in an itemized list as complete sentences; or at
     least, as complete phrases.  Incomplete expressions ... awkward
     ... like this.

   * Write the prefatory sentence or phrase for a multi-item list or
     table as a complete expression.  Do not write "You can set:";
     instead, write "You can set these variables:".  The former
     expression sounds cut off.

Editions, Dates and Versions
............................

  Include edition numbers, version numbers, and dates in the `@copying'
text (for people reading the Texinfo file, and for the legal copyright
in the output files).  Then use `@insertcopying' in the `@titlepage'
section (for people reading the printed output) and the Top node (for
people reading the online output).

  It is easiest to do this using `@set' and `@value'.  *Note `@value'
Example: value Example, and *Note GNU Sample Texts::.

Definition Commands
...................

  Definition commands are `@deffn', `@defun', `@defmac', and the like,
and enable you to write descriptions in a uniform format.

   * Write just one definition command for each entity you define with a
     definition command.  The automatic indexing feature creates an
     index entry that leads the reader to the definition.

   * Use `@table' ... `@end table' in an appendix that contains a
     summary of functions, not `@deffn' or other definition commands.

Capitalization
..............

   * Capitalize "Texinfo"; it is a name.  Do not write the `x' or `i'
     in upper case.

   * Capitalize "Info"; it is a name.

   * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
     `X'.  This command causes the formatters to typeset the name
     according to the wishes of Donald Knuth, who wrote TeX.

Spaces
......

  Do not use spaces to format a Texinfo file, except inside of
`@example' ... `@end example' and similar commands.

  For example, TeX fills the following:

         @kbd{C-x v}
         @kbd{M-x vc-next-action}
            Perform the next logical operation
            on the version-controlled file
            corresponding to the current buffer.

so it looks like this:

     `C-x v' `M-x vc-next-action' Perform the next logical operation on
     the version-controlled file corresponding to the current buffer.

In this case, the text should be formatted with `@table', `@item', and
`@itemx', to create a table.

@code, @samp, @var, and `---'
.............................

   * Use `@code' around Lisp symbols, including command names.  For
     example,

          The main function is @code{vc-next-action}, ...

   * Avoid putting letters such as `s' immediately after an `@code'.
     Such letters look bad.

   * Use `@var' around meta-variables.  Do not write angle brackets
     around them.

   * Use three hyphens in a row, `---', to indicate a long dash.  TeX
     typesets these as a long dash and the Info formatters reduce three
     hyphens to two.

Periods Outside of Quotes
.........................

  Place periods and other punctuation marks _outside_ of quotations,
unless the punctuation is part of the quotation.  This practice goes
against publishing conventions in the United States, but enables the
reader to distinguish between the contents of the quotation and the
whole passage.

  For example, you should write the following sentence with the period
outside the end quotation marks:

     Evidently, `au' is an abbreviation for ``author''.

since `au' does _not_ serve as an  abbreviation for `author.' (with a
period following the word).

Introducing New Terms
.....................

   * Introduce new terms so that a reader who does not know them can
     understand them from context; or write a definition for the term.

     For example, in the following, the terms "check in", "register" and
     "delta" are all appearing for the first time; the example sentence
     should be rewritten so they are understandable.

          The major function assists you in checking in a file to your
          version control system and registering successive sets of
          changes to it as deltas.

   * Use the `@dfn' command around a word being introduced, to indicate
     that the reader should not expect to know the meaning already, and
     should expect to learn the meaning from this passage.

@pxref
......

  Absolutely never use `@pxref' except in the special context for which
it is designed: inside parentheses, with the closing parenthesis
following immediately after the closing brace.  One formatter
automatically inserts closing punctuation and the other does not.  This
means that the output looks right both in printed output and in an Info
file, but only when the command is used inside parentheses.

Invoking from a Shell
.....................

  You can invoke programs such as Emacs, GCC, and `gawk' from a shell.
The documentation for each program should contain a section that
describes this.  Unfortunately, if the node names and titles for these
sections are all different, they are difficult for users to find.

  So, there is a convention to name such sections with a phrase
beginning with the word `Invoking', as in `Invoking Emacs'; this way,
users can find the section easily.

ANSI C Syntax
.............

  When you use `@example' to describe a C function's calling
conventions, use the ANSI C syntax, like this:

     void dld_init (char *@var{path});

And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with `@var'.

  Avoid the obsolete style that looks like this:

     #include <dld.h>
     
     dld_init (path)
     char *path;

  Also, it is best to avoid writing `#include' above the declaration
just to indicate that the function is declared in a header file.  The
practice may give the misimpression that the `#include' belongs near
the declaration of the function.  Either state explicitly which header
file holds the declaration or, better yet, name the header file used
for a group of functions at the beginning of the section that describes
the functions.

Bad Examples
............

  Here are several examples of bad writing to avoid:

  In this example, say, " ... you must `@dfn'{check in} the new
version."  That flows better.

     When you are done editing the file, you must perform a
     `@dfn'{check in}.

  In the following example, say, "... makes a unified interface such as
VC mode possible."

     SCCS, RCS and other version-control systems all perform similar
     functions in broadly similar ways (it is this resemblance which
     makes a unified control mode like this possible).

  And in this example, you should specify what `it' refers to:

     If you are working with other people, it assists in coordinating
     everyone's changes so they do not step on each other.

And Finally ...
...............

   * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
     in the name `Bach'.  But pronounce Texinfo as in `speck':
     "teckinfo".

   * Write notes for yourself at the very end of a Texinfo file after
     the `@bye'.  None of the formatters process text after the `@bye';
     it is as if the text were within `@ignore' ...  `@end ignore'.


File: texinfo,  Node: Sample Texinfo Files,  Next: Include Files,  Prev: Tips,  Up: Top

Sample Texinfo Files
********************

  The first example is from the first chapter (*note Short Sample::),
given here in its entirety, without commentary.  The second sample
includes the full texts to be used in GNU manuals.

* Menu:

* Short Sample Texinfo File::
* GNU Sample Texts::


File: texinfo,  Node: Short Sample Texinfo File,  Next: GNU Sample Texts,  Up: Sample Texinfo Files

Short Sample
============

  Here is a complete, short sample Texinfo file, without any commentary.
You can see this file, with comments, in the first chapter.  *Note
Short Sample::.

  In a nutshell: The `makeinfo' program transforms a Texinfo source
file such as this into an Info file or HTML; and TeX typesets it for a
printed manual.


     \input texinfo   @c -*-texinfo-*-
     @c %**start of header
     @setfilename sample.info
     @settitle Sample Manual 1.0
     @c %**end of header
     
     @copying
     This is a short example of a complete Texinfo file.
     
     Copyright (C) 2002 Free Software Foundation, Inc.
     @end copying
     
     @titlepage
     @title Sample Title
     @page
     @vskip 0pt plus 1filll
     @insertcopying
     @end titlepage
     
     @c Output the table of the contents at the beginning.
     @contents
     
     @ifnottex
     @node Top
     
     @insertcopying
     @end ifnottex
     
     @menu
     * First Chapter::    The first chapter is the
                            only chapter in this sample.
     * Index::            Complete index.
     @end menu
     
     
     @node First Chapter
     @chapter First Chapter
     
     @cindex chapter, first
     
     This is the first chapter.
     @cindex index entry, another
     
     Here is a numbered list.
     
     @enumerate
     @item
     This is the first item.
     
     @item
     This is the second item.
     @end enumerate
     
     
     @node Index
     @unnumbered Index
     
     @printindex cp
     
     @bye


File: texinfo,  Node: GNU Sample Texts,  Prev: Short Sample Texinfo File,  Up: Sample Texinfo Files

GNU Sample Texts
================

  Here is a sample Texinfo document with the full texts that should be
used in GNU manuals.

  As well as the legal texts, it also serves as a practical example of
how many elements in a GNU system can affect the manual.  If you're not
familiar with all these different elements, don't worry.  They're not
required and a perfectly good manual can be written without them.
They're included here nonetheless because many manuals do (or could)
benefit from them.

  *Note Short Sample::, for a minimal example of a Texinfo file.  *Note
Beginning a File::, for a full explanation of that minimal example.

  Here are some notes on the example:

   * The `$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $'
     comment is for CVS (*note Overview: (cvs)Top.) or RCS (see
     rcsintro(1)) version control systems, which expand it into a
     string such as:
          $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
     (This is useful in all sources that use version control, not just
     manuals.)

   * The `version.texi' in the `@include' command is maintained
     automatically by Automake (*note Introduction: (automake)Top.).
     It sets the `VERSION' and `UPDATED' values used elsewhere.  If
     your distribution doesn't use Automake, you can mimic these or
     equivalent settings.

   * The `@syncodeindex' command reflects the recommendation to use only
     one index if at all possible, to make it easier for readers.

   * The `@dircategory' is for constructing the Info directory.  *Note
     Installing Dir Entries::, which includes a variety of recommended
     category names.

   * The `Invoking' node is a GNU standard to help users find the basic
     information about command-line usage of a given program.  *Note
     Manual Structure Details: (standards)Manual Structure Details.

   * It is best to include the entire GNU Free Documentation License in
     a GNU manual, unless the manual is only a few pages long.  Of
     course this sample is even shorter than that, but it includes the
     FDL anyway in order to show one conventional way of doing so.  The
     `fdl.texi' file is available on the GNU machines (and in the
     Texinfo and other GNU distributions).

     The FDL provides for omitting itself under certain conditions, but
     in that case the sample texts given here have to be modified.
     *Note GNU Free Documentation License::.

   * If your manual has invariant sections (again, see the license
     itself for details), then don't forget to include them.

  Here is the sample document:

     \input texinfo    @c -*-texinfo-*-
     @comment $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
     @comment %**start of header
     @setfilename sample.info
     @include version.texi
     @settitle GNU Sample @value{VERSION}
     @syncodeindex pg cp
     @comment %**end of header
     @copying
     This manual is for GNU Sample
     (version @value{VERSION}, @value{UPDATED}),
     which is an example in the Texinfo documentation.
     
     Copyright @copyright{} 2002 Free Software Foundation, Inc.
     
     @quotation
     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.''
     @end quotation
     @end copying
     
     @dircategory Texinfo documentation system
     @direntry
     * sample: (sample)Invoking sample.
     @end direntry
     
     @titlepage
     @title GNU Sample
     @subtitle for version @value{VERSION}, @value{UPDATED}
     @author A.U. Thor (@email{bug-texinfo@@gnu.org})
     @page
     @vskip 0pt plus 1filll
     @insertcopying
     @end titlepage
     
     @contents
     
     @ifnottex
     @node Top
     @top GNU Sample
     
     @insertcopying
     @end ifnottex
     
     @menu
     * Invoking sample::
     * Copying This Manual::
     * Index::
     @end menu
     
     
     @node Invoking sample
     @chapter Invoking sample
     
     @pindex sample
     @cindex invoking @command{sample}
     
     This is a sample manual.  There is no sample program to
     invoke, but if there was, you could see its basic usage
     and command line options here.
     
     
     @node Copying This Manual
     @appendix Copying This Manual
     
     @menu
     * GNU Free Documentation License::  License for copying this manual.
     @end menu
     
     @include fdl.texi
     
     
     @node Index
     @unnumbered Index
     
     @printindex cp
     
     @bye


File: texinfo,  Node: Include Files,  Next: Headings,  Prev: Sample Texinfo Files,  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,  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,  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,  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,  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{} 2002 Free Software Foundation, Inc.
     @end titlepage
     
     @ifinfo
     @node Top, First, , (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
     @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,  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,  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,  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.  Typically, you will use 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,  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,  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,  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.  By default, Texinfo has no footers, so if you specify them,
the available page size for the main text will be slightly reduced.

  Texinfo provides six commands for specifying headings and footings:
   * `@everyheading' `@everyfooting' generate page headers and footers
     that are the same for both even- and odd-numbered pages.

   * `@evenheading' and `@evenfooting' command generate headers and
     footers for even-numbered (left-hand) pages.

   * `@oddheading' and `@oddfooting' generate headers and footers for
     odd-numbered (right-hand) pages.

  Write custom heading specifications in the Texinfo file immediately
after the `@end titlepage' command.  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:

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

You need to divide the left part from the central part and the central
part from the right 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:

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

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


File: texinfo,  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,  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,  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,  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-c' (or `C-c C-c', if you are running a shell inside Emacs).

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

  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 3.14159 (Web2c 7.0)
     (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.)

