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

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

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

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Texinfo
*******

   Texinfo is a documentation system that uses a single source file to
produce both on-line information and printed output.

   The first part of this master menu lists the major nodes in this Info
document, including the @-command and concept indices.  The rest of the
menu lists all the lower level nodes in the document.

   This is Edition 2.18 of the Texinfo documentation, 26 March 1993,
for Texinfo Version 2.

Texinfo Copying Conditions
**************************

   The programs currently being distributed that relate to Texinfo
include portions of GNU Emacs, plus other separate programs (including
`makeinfo', `info', `texindex', and `texinfo.tex').  These programs are
"free"; this means that everyone is free to use them and free to
redistribute them on a free basis.  The Texinfo-related programs are
not in the public domain; they are copyrighted and there are
restrictions on their distribution, but these restrictions are designed
to permit everything that a good cooperating citizen would want to do.
What is not allowed is to try to prevent others from further sharing
any version of these programs that they might get from you.

   Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to Texinfo, that you receive
source code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

   To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of the Texinfo related programs, you must give the recipients all
the rights that you have.  You must make sure that they, too, receive or
can get the source code.  And you must tell them their rights.

   Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for the programs that relate to
Texinfo.  If these programs are modified by someone else and passed on,
we want their recipients to know that what they have is not what we
distributed, so that any problems introduced by others will not reflect
on our reputation.

   The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General Public
Licenses that accompany them.

Overview of Texinfo
*******************

   "Texinfo"(1) is a documentation system that uses a single source
file to produce both on-line information and printed output.  This
means that instead of writing two different documents, one for the
on-line help or other on-line information and the other for a typeset
manual or other printed work, you need write only one document.  When
the work is revised, you need revise only one document.  (You can read
the on-line information, known as an "Info file", with an Info
documentation-reading program.)

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

   (1)  Note that the first syllable of "Texinfo" is pronounced like
"speck", not "hex".  This odd pronunciation is derived from, but is not
the same as, the pronunciation of TeX.  In the word TeX, the `X' is
actually the Greek letter "chi" rather than the English letter "ex".
Pronounce TeX as if the `X' were the last sound in the name `Bach'; but
pronounce Texinfo as if the `x' were a `k'.  Spell "Texinfo" with a
capital "T" and write the other letters in lower case.

Using Texinfo
=============

   Using Texinfo, you can create a printed document with the normal
features of a book, including chapters, sections, cross references, and
indices.  From the same Texinfo source file, you can create a
menu-driven, on-line Info file with nodes, menus, cross references, and
indices.  You can, if you wish, make the chapters and sections of the
printed document correspond to the nodes of the on-line information;
and you use the same cross references and indices for both the Info
file and the printed work.  `The GNU Emacs Manual' is a good example of
a Texinfo file, as is this manual.

   To make a printed document, you process a Texinfo source file with
the TeX typesetting program.  This creates a DVI file that you can
typeset and print as a book or report.  (Note that the Texinfo language
is completely different from TeX's usual language, PlainTeX, which
Texinfo replaces.)  If you do not have TeX, but do have `troff' or
`nroff', you can use the `texi2roff' program instead.

   To make an Info file, you process a Texinfo source file with the
`makeinfo' utility or Emacs's `texinfo-format-buffer' command; this
creates an Info file that you can install on-line.

   TeX and `texi2roff' work with many types of printer; similarly, Info
works with almost every type of computer terminal.  This power makes
Texinfo a general purpose system, but brings with it a constraint,
which is that a Texinfo file may contain only the customary
"typewriter" characters (letters, numbers, spaces, and punctuation
marks) but no special graphics.

   A Texinfo file is a plain ASCII file containing text and
"@-commands" (words preceded by an `@') that tell the typesetting and
formatting programs what to do.  You may edit a Texinfo file with any
text editor; but it is especially convenient to use GNU Emacs since
that editor has a special mode, called Texinfo mode, that provides
various Texinfo-related features.  (see Texinfo Mode.)

   Before writing a Texinfo source file, you should become familiar with
the Info documentation reading program and learn about nodes, menus,
cross references, and the rest.  (see info, for more
information.)

   You can use Texinfo to create both on-line help and printed manuals;
moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
is the format in which documentation for GNU utilities and libraries is
written.

Info files
==========

   An Info file is a Texinfo file formatted so that the Info
documentation reading program can operate on it.  (`makeinfo' and
`texinfo-format-buffer' are two commands that convert a Texinfo file
into an Info file.)

   Info files are divided into pieces called "nodes", each of which
contains the discussion of one topic.  Each node has a name, and
contains both text for the user to read and pointers to other nodes,
which are identified by their names.  The Info program displays one node
at a time, and provides commands with which the user can move to other
related nodes.

   See info, for more information about using Info.

   Each node of an Info file may have any number of child nodes that
describe subtopics of the node's topic.  The names of child nodes are
listed in a "menu" within the parent node; this allows you to use
certain Info commands to move to one of the child nodes.  Generally, an
Info file is organized like a book.  If a node is at the logical level
of a chapter, its child nodes are at the level of sections; likewise,
the child nodes of sections are at the level of subsections.

   All the children of any one parent are linked together in a
bidirectional chain of `Next' and `Previous' pointers.  The `Next'
pointer provides a link to the next section, and the `Previous' pointer
provides a link to the previous section.  This means that all the nodes
that are at the level of sections within a chapter are linked together.
Normally the order in this chain is the same as the order of the
children in the parent's menu.  Each child node records the parent node
name as its `Up' pointer.  The last child has no `Next' pointer, and the
first child has the parent both as its `Previous' and as its `Up'
pointer.(1)

   The book-like structuring of an Info file into nodes that correspond
to chapters, sections, and the like is a matter of convention, not a
requirement.  The `Up', `Previous', and `Next' pointers of a node can
point to any other nodes, and a menu can contain any other nodes.
Thus, the node structure can be any directed graph.  But it is usually
more comprehensible to follow a structure that corresponds to the
structure of chapters and sections in a printed book or report.

   In addition to menus and to `Next', `Previous', and `Up' pointers,
Info provides pointers of another kind, called references, that can be
sprinkled throughout the text.  This is usually the best way to
represent links that do not fit a hierarchical structure.

   Usually, you will design a document so that its nodes match the
structure of chapters and sections in the printed output.  But there
are times when this is not right for the material being discussed.
Therefore, Texinfo uses separate commands to specify the node structure
for the Info file and the section structure for the printed output.

   Generally, you enter an Info file through a node that by convention
is called `Top'.  This node normally contains just a brief summary of
the file's purpose, and a large menu through which the rest of the file
is reached.  From this node, you can either traverse the file
systematically by going from node to node, or you can go to a specific
node listed in the main menu, or you can search the index menus and
then go directly to the node that has the information you want.

   If you want to read through an Info file in sequence, as if it were a
printed manual, you can get the whole file with the advanced Info
command `g* RET'.  (see Advanced Info commands (info))

   The `dir' file in the `info' directory serves as the departure point
for the whole Info system.  From it, you can reach the `Top' nodes of
each of the documents in a complete Info system.

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

   (1)  In some documents, the first child has no `Previous' pointer.
Occasionally, the last child has the node name of the next following
higher level node as its `Next' pointer.

Printed Books
=============

   A Texinfo file can be formatted and typeset as a printed book or
manual.  To do this, you need TeX, a powerful, sophisticated typesetting
program written by Donald Knuth.(1)

   A Texinfo-based book is similar to any other typeset, printed work:
it can have a title page, copyright page, table of contents, and
preface, as well as chapters, numbered or unnumbered sections and
subsections, page headers, cross references, footnotes, and indices.

   You can use Texinfo to write a book without ever having the intention
of converting it into on-line information.  You can use Texinfo for
writing a printed novel, and even to write a printed memo, although
this latter application is not recommended since electronic mail is so
much easier.

   TeX is a general purpose typesetting program.  Texinfo provides a
file called `texinfo.tex' that contains information (definitions or
"macros") that TeX uses when it typesets a Texinfo file.
(`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX
commands, which TeX can then process to create the typeset document.)
`texinfo.tex' contains the specifications for printing a document.

   Most often, documents are printed on 8.5 inch by 11 inch pages
(216mm by 280mm; this is the default size), but you can also print for
7 inch by 9.25 inch pages (178mm by 235mm; the `@smallbook' size) or on
European A4 size paper (`@afourpaper').  (see Printing "Small" Books.
Also, see Printing on A4 Paper.)

   By changing the parameters in `texinfo.tex', you can change the size
of the printed document.  In addition, you can change the style in
which the printed document is formatted; for example, you can change the
sizes and fonts used, the amount of indentation for each paragraph, the
degree to which words are hyphenated, and the like.  By changing the
specifications, you can make a book look dignified, old and serious, or
light-hearted, young and cheery.

   TeX is freely distributable.  It is written in a dialect of Pascal
called WEB and can be compiled either in Pascal or (by using a
conversion program that comes with the TeX distribution) in C.  (see
TeX Mode (emacs), for information about TeX.)

   TeX is very powerful and has a great many features.  Because a
Texinfo file must be able to present information both on a
character-only terminal in Info form and in a typeset book, the
formatting commands that Texinfo supports are necessarily limited.

   See How to Obtain TeX.

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

   (1)  You can also use the `texi2roff' program if you do not have
TeX; since Texinfo is designed for use with TeX, `texi2roff' is not
described here.  `texi2roff' is part of the standard GNU distribution.

@-commands
==========

   In a Texinfo file, the commands that tell TeX how to typeset the
printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
create an Info file are preceded by `@'; they are called "@-commands".
For example, `@node' is the command to indicate a node and `@chapter'
is the command to indicate the start of a chapter.

     *Please note:* All the @-commands, with the exception of the
     `@TeX{}' command, must be written entirely in lower case.

   The Texinfo @-commands are a strictly limited set of constructs.  The
strict limits make it possible for Texinfo files to be understood both
by TeX and by the code that converts them into Info files.  You can
display Info files on any terminal that displays alphabetic and numeric
characters.  Similarly, you can print the output generated by TeX on a
wide variety of printers.

   Depending on what they do or what arguments(1) they take, you need
to write @-commands on lines of their own or as part of sentences:

   * Write a command such as `@noindent' at the beginning of a line as
     the only text on the line.  (`@noindent' prevents the beginning of
     the next line from being indented as the beginning of a paragraph.)

   * Write a command such as `@chapter' at the beginning of a line
     followed by the command's arguments, in this case the chapter
     title, on the rest of the line.  (`@chapter' creates chapter
     titles.)

   * Write a command such as `@dots{}' wherever you wish but usually
     within a sentence. (`@dots{}' creates dots ...)

   * Write a command such as `@code{SAMPLE-CODE}' wherever you wish
     (but usually within a sentence) with its argument, SAMPLE-CODE in
     this example, between the braces.  (`@code' marks text as being
     code.)

   * Write a command such as `@example' at the beginning of a line of
     its own; write the body-text on following lines; and write the
     matching `@end' command, `@end example' in this case, at the
     beginning of a line of its own after the body-text. (`@example'
     ... `@end example' indents and typesets body-text as an example.)

As a general rule, a command requires braces if it mingles among other
text; but it does not need braces if it starts a line of its own.  The
non-alphabetic commands, such as `@:', are exceptions to the rule; they
do not need braces.

   As you gain experience with Texinfo, you will rapidly learn how to
write the different commands: the different ways to write commands make
it easier to write and read Texinfo files than if all commands followed
exactly the same syntax.  (For details about @-command syntax, see
@-Command Syntax.)

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

   (1)  The word "argument" comes from the way it is used in
mathematics and does not refer to a disputation between two people; it
refers to the information presented to the command.  According to the
`Oxford English Dictionary', the word derives from the Latin for "to
make clear, prove"; thus it came to mean `the evidence offered as
proof', which is to say, `the information offered', which led to its
mathematical meaning.  In its other thread of derivation, the word came
to mean `to assert in a manner against which others may make counter
assertions', which led to the meaning of `argument' as a disputation.

General Syntactic Conventions
=============================

   All ASCII printing characters except `@', `{' and `}' can appear in
a Texinfo file and stand for themselves.  `@' is the escape character
which introduces commands.  `{' and `}' should be used only to surround
arguments to certain commands.  To put one of these special characters
into the document, put an `@' character in front of it, like this:
`@@', `@{', and `@}'.

   It is customary in TeX to use doubled single-quote characters to
begin and end quotations: ` ` and ' ' (but without a space between the
two single-quote characters).  This convention should be followed in
Texinfo files.  TeX converts doubled single-quote characters to left-
and right-hand doubled quotation marks and Info converts doubled
single-quote characters to ASCII double-quotes: ` ` and ' ' to " .

   Use three hyphens in a row, `---', for a dash--like this.  In TeX, a
single or even a double hyphen produces a printed dash that is shorter
than the usual typeset dash. Info reduces three hyphens to two for
display on the screen.

   To prevent a paragraph from being indented in the printed manual, put
the command `@noindent' on a line by itself before the paragraph.

   If you mark off a region of the Texinfo file with the `@iftex' and
`@end iftex' commands, that region will appear only in the printed
copy; in that region, you can use certain commands borrowed from
PlainTeX that you cannot use in Info.  Likewise, if you mark off a
region with the `@ifinfo' and `@end ifinfo' commands, that region will
appear only in the Info file; in that region, you can use Info commands
that you cannot use in TeX.  (see Conditionals.)

     *Caution:* Do not use tabs in a Texinfo file!  TeX uses
     variable-width fonts, which means that it cannot predefine a tab
     to work in all circumstances.  Consequently, TeX treats tabs like
     single spaces, and that is not what they look like.

     To avoid this problem, Texinfo mode causes GNU Emacs to insert
     multiple spaces when you press the TAB key.

     Also, you can run `untabify' in Emacs to convert tabs in a region
     to multiple spaces.

Comments
========

   You can write comments in a Texinfo file that will not appear in
either the Info file or the printed manual by using the `@comment'
command (which may be abbreviated to `@c').  Such comments are for the
person who reads the Texinfo file.  All the text on a line that follows
either `@comment' or `@c' is a comment; the rest of the line does not
appear in either the Info file or the printed manual. (Often, you can
write the `@comment' or `@c' in the middle of a line, and only the text
that follows after the `@comment' or `@c' command does not appear; but
some commands, such as `@settitle' and `@setfilename', work on a whole
line.  You cannot use `@comment' or `@c' in a line beginning with such
a command.)

   You can write long stretches of text that will not appear in either
the Info file or the printed manual by using the `@ignore' and `@end
ignore' commands.  Write each of these commands on a line of its own,
starting each command at the beginning of the line.  Text between these
two commands does not appear in the processed output.  You can use
`@ignore' and `@end ignore' for writing comments.  Often, `@ignore' and
`@end ignore' is used to enclose a part of the copying permissions that
applies to the Texinfo source file of a document, but not to the Info
or printed version of the document.

What a Texinfo File Must Have
=============================

   By convention, the names of Texinfo files end with one of the
extensions `.texinfo', `.texi', or `.tex'.  The longer extension is
preferred since it describes more clearly to a human reader the nature
of the file.  The shorter extensions are for operating systems that
cannot handle long file names.

   In order to be made into a printed manual and an Info file, a
Texinfo file *must* begin with lines like this:

     \input texinfo
     @setfilename INFO-FILE-NAME
     @settitle NAME-OF-MANUAL

The contents of the file follow this beginning, and then you *must* end
a Texinfo file with a line like this:

     @bye

The `\input texinfo' line tells TeX to use the `texinfo.tex' file,
which tells TeX how to translate the Texinfo @-commands into TeX
typesetting commands.  (Note the use of the backslash, `\'; this is
correct for TeX.)  The `@setfilename' line provides a name for the Info
file and the `@settitle' line specifies a title for the page headers (or
footers) of the printed manual.

   The `@bye' line at the end of the file on a line of its own tells
the formatters that the file is ended and to stop formatting.

   Usually, you will not use quite such a spare format, but will include
mode setting and start-of-header and end-of-header lines at the
beginning of a Texinfo file, like this:

     \input texinfo   @c -*-texinfo-*-
     @c %**start of header
     @setfilename INFO-FILE-NAME
     @settitle NAME-OF-MANUAL
     @c %**end of header

In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo
mode when you edit the file.

   The `@c' lines which surround the `@setfilename' and `@settitle'
lines are optional, but you need them in order to run TeX or Info on
just part of the file.  (see Start of Header, for more information.)

   Furthermore, you will usually provide a Texinfo file with a title
page, indices, and the like.  But the minimum, which can be useful for
short documents, is just the three lines at the beginning and the one
line at the end.

Six Parts of a Texinfo File
===========================

   Generally, a Texinfo file contains more than the minimal beginning
and end--it usually contains six parts:

1. Header
     The "Header" names the file, tells TeX which definitions' file to
     use, and performs other "housekeeping" tasks.

2. Summary Description and Copyright
     The "Summary Description and Copyright" segment describes the
     document and contains the copyright notice and copying permissions
     for the Info file.  The segment must be enclosed between `@ifinfo'
     and `@end ifinfo' commands so that the formatters place it only in
     the Info file.

3. Title and Copyright
     The "Title and Copyright" segment contains the title and copyright
     pages and copying permissions for the printed manual.  The segment
     must be enclosed between `@titlepage' and `@end titlepage'
     commands.  The title and copyright page appear only in the printed
     manual.

4. `Top' Node and Master Menu
     The "Master Menu" contains a complete menu of all the nodes in the
     whole Info file.  It appears only in the Info file, in the `Top'
     node.

5. Body
     The "Body" of the document may be structured like a traditional
     book or encyclopedia or it may be free form.

6. End
     The "End" contains commands for printing indices and generating
     the table of contents, and the `@bye' command on a line of its own.

A Short Sample Texinfo File
===========================

   Here is a complete but very short Texinfo file, in 6 parts.  The
first three parts of the file, from `\input texinfo' through to `@end
titlepage', look more intimidating than they are.  Most of the material
is standard boilerplate; when you write a manual, simply insert the
names for your own manual in this segment. (see Beginning a File.)

In the following, the sample text is *indented*; comments on it are
not.  The complete file, without any comments, is shown in Sample Texinfo File.

Part 1: Header
--------------

The header does not appear in either the Info file or the
printed output.  It sets various parameters, including the
name of the Info file and the title used in the header.

     \input texinfo   @c -*-texinfo-*-
     @c %**start of header
     @setfilename sample.info
     @settitle Sample Document
     @c %**end of header

     @setchapternewpage odd

Part 2: Summary Description and Copyright
-----------------------------------------

The summary description and copyright segment does not
appear in the printed document.

     @ifinfo
     This is a short example of a complete Texinfo file.

     Copyright @copyright{} 1990 Free Software Foundation, Inc.
     @end ifinfo

Part 3: Titlepage and Copyright
-------------------------------

The titlepage segment does not appear in the Info file.

     @titlepage
     @sp 10
     @comment The title is printed in a large font.
     @center @titlefont{Sample Title}

     @c The following two commands start the copyright page.
     @page
     @vskip 0pt plus 1filll
     Copyright @copyright{} 1990 Free Software Foundation, Inc.
     @end titlepage

Part 4: `Top' Node and Master Menu
----------------------------------

The `Top' node contains the master menu for the Info file.
Since a printed manual uses a table of contents rather than
a menu, the master menu appears only in the Info file.

     @node    Top,       First Chapter, (dir),    (dir)
     @comment node-name, next,          previous, up

     @menu
     * First Chapter::    The first chapter is the
                          only chapter in this sample.
     * Concept Index::    This index has two entries.
     @end menu

Part 5:  The Body of the Document
---------------------------------

The body segment contains all the text of the document, but not the
indices or table of contents.  This example illustrates a node and a
chapter containing an enumerated list.

     @node    First Chapter, Concept Index, Top,      Top
     @comment node-name,     next,          previous, up
     @chapter First Chapter
     @cindex Sample index entry

     This is the contents of the first chapter.
     @cindex Another sample index entry

     Here is a numbered list.

     @enumerate
     @item
     This is the first item.

     @item
     This is the second item.
     @end enumerate

     The @code{makeinfo} and @code{texinfo-format-buffer}
     commands transform a Texinfo file such as this into
     an Info file; and @TeX{} typesets it for a printed
     manual.

Part 6: The End of the Document
-------------------------------

The end segment contains commands both for generating an index in a node
and unnumbered chapter of its own and for generating the table of
contents; and it contains the `@bye' command that marks the end of the
document.

     @node    Concept Index,    ,  First Chapter, Top
     @comment node-name,    next,  previous,      up
     @unnumbered Concept Index

     @printindex cp

     @contents
     @bye

The Results
-----------

   Here is what the contents of the first chapter of the sample look
like:

     This is the contents of the first chapter.

     Here is a numbered list.

       1. This is the first item.

       2. This is the second item.

     The `makeinfo' and `texinfo-format-buffer' commands transform a
     Texinfo file such as this into an Info file; and TeX typesets it
     for a printed manual.

Acknowledgements
================

   Richard M. Stallman wrote Edition 1.0 of this manual.
Robert J. Chassell revised and extended it, starting with Edition 1.1.

   Our thanks go out to all who helped improve this work, particularly
to Francois Pinard and David D. Zuhn, who tirelessly recorded and
reported mistakes and obscurities; our special thanks go to
Melissa Weisshaus for her frequent and often tedious reviews of nearly
similar editions.  Our mistakes are our own.