-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.6 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
Texinfo
*******
- Texinfo is a documentation system that uses a single source file to
+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
* Concept Index:: A menu covering many topics.
- -- The Detailed Node Listing --
+ --- The Detailed Node Listing ---
Overview of Texinfo
Texinfo Copying Conditions
**************************
- The programs currently being distributed that relate to Texinfo
-include portions of GNU Emacs, plus other separate programs (including
+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
Overview of Texinfo
*******************
- "Texinfo"(1) (*note Overview-Footnotes::) is a documentation system
+"Texinfo"(1) (*note Overview-Footnote-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
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.
+file and the printed work. `The XEmacs User's 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
Info files
==========
- An Info file is a Texinfo file formatted so that the Info
-documentation reading program can operate on it. (`makeinfo' and
+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.)
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) (*note Info Files-Footnotes::)
+pointer.(1) (*note Info Files-Footnote-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
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) (*note Printed Books-Footnotes::)
+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) (*note Printed Books-Footnote-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,
@-commands
==========
- In a Texinfo file, the commands that tell TeX how to typeset the
+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'
wide variety of printers.
Depending on what they do or what arguments(1) (*note Formatting
-Commands-Footnotes::) they take, you need to write @-commands on lines
+Commands-Footnote-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
General Syntactic Conventions
=============================
- All printable ASCII characters except `@', `{' and `}' can appear in
-a Texinfo file and stand for themselves. `@' is the escape character
+All printable ASCII 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:
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 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
What a Texinfo File Must Have
=============================
- By convention, the names of Texinfo files end with one of the
+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
Six Parts of a Texinfo File
===========================
- Generally, a Texinfo file contains more than the minimal beginning
-and end--it usually contains six parts:
+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
The "End" contains commands for printing indices and generating
the table of contents, and the `@bye' command on a line of its own.
+\1f
+File: texinfo.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview
+
+A Short Sample Texinfo File
+===========================
+
+Here is a complete but very short Texinfo file, in six 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. (*Note 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 *Note 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)
+ @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.
+
+\1f
+File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview
+
+Acknowledgements
+================
+
+Richard M. Stallman wrote Edition 1.0 of this manual.
+Robert J. Chassell revised and extended it, starting with Edition 1.1.
+Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
+starting with Edition 2.22.
+
+ Our thanks go out to all who helped improve this work, particularly to
+Franc,ois 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.
+
+ Please send suggestions and corrections to:
+
+ Internet address:
+ bug-texinfo@gnu.org
+
+Please include the manual's edition number and update date in your
+messages.
+
+\1f
+File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
+
+Using Texinfo Mode
+******************
+
+You may edit a Texinfo file with any text editor you choose. A Texinfo
+file is no different from any other ASCII file. However, GNU Emacs
+comes with a special mode, called Texinfo mode, that provides Emacs
+commands and tools to help ease your work.
+
+ This chapter describes features of GNU Emacs' Texinfo mode but not any
+features of the Texinfo formatting language. If you are reading this
+manual straight through from the beginning, you may want to skim through
+this chapter briefly and come back to it after reading succeeding
+chapters which describe the Texinfo formatting language in detail.
+
+* Menu:
+
+* Texinfo Mode Overview:: How Texinfo mode can help you.
+* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
+ purpose editing features.
+* Inserting:: How to insert frequently used @-commands.
+* Showing the Structure:: How to show the structure of a file.
+* Updating Nodes and Menus:: How to update or create new nodes and menus.
+* Info Formatting:: How to format for Info.
+* Printing:: How to format and print part or all of a file.
+* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
+
+\1f
+File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode
+
+Texinfo Mode Overview
+=====================
+
+ Texinfo mode provides special features for working with Texinfo files:
+
+ * Insert frequently used @-commands.
+
+ * Automatically create `@node' lines.
+
+ * Show the structure of a Texinfo source file.
+
+ * Automatically create or update the `Next', `Previous', and `Up'
+ pointers of a node.
+
+ * Automatically create or update menus.
+
+ * Automatically create a master menu.
+
+ * Format a part or all of a file for Info.
+
+ * Typeset and print part or all of a file.
+
+ Perhaps the two most helpful features are those for inserting
+frequently used @-commands and for creating node pointers and menus.
+
+\1f
+File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode
+
+The Usual GNU Emacs Editing Commands
+====================================
+
+In most cases, the usual Text mode commands work the same in Texinfo
+mode as they do in Text mode. Texinfo mode adds new editing commands
+and tools to GNU Emacs' general purpose editing features. The major
+difference concerns filling. In Texinfo mode, the paragraph separation
+variable and syntax table are redefined so that Texinfo commands that
+should be on lines of their own are not inadvertently included in
+paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a
+paragraph but not mix an indexing command on a line adjacent to it into
+the paragraph.
+
+ In addition, Texinfo mode sets the `page-delimiter' variable to the
+value of `texinfo-chapter-level-regexp'; by default, this is a regular
+expression matching the commands for chapters and their equivalents,
+such as appendices. With this value for the page delimiter, you can
+jump from chapter title to chapter title with the `C-x ]'
+(`forward-page') and `C-x [' (`backward-page') commands and narrow to a
+chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages:
+(xemacs)Pages, for details about the page commands.)
+
+ You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the three extensions `.texinfo',
+`.texi', or `.tex'. A longer extension is preferred, since it is
+explicit, but a shorter extension may be necessary for operating
+systems that limit the length of file names. GNU Emacs automatically
+enters Texinfo mode when you visit a file with a `.texinfo' or `.texi'
+extension. Also, Emacs switches to Texinfo mode when you visit a file
+that has `-*-texinfo-*-' in its first line. If ever you are in another
+mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
+
+ Like all other Emacs features, you can customize or enhance Texinfo
+mode as you wish. In particular, the keybindings are very easy to
+change. The keybindings described here are the default or standard
+ones.
+
+\1f
+File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode
+
+Inserting Frequently Used Commands
+==================================
+
+Texinfo mode provides commands to insert various frequently used
+@-commands into the buffer. You can use these commands to save
+keystrokes.
+
+ The insert commands are invoked by typing `C-c' twice and then the
+first letter of the @-command:
+
+`C-c C-c c'
+`M-x texinfo-insert-@code'
+ Insert `@code{}' and put the cursor between the braces.
+
+`C-c C-c d'
+`M-x texinfo-insert-@dfn'
+ Insert `@dfn{}' and put the cursor between the braces.
+
+`C-c C-c e'
+`M-x texinfo-insert-@end'
+ Insert `@end' and attempt to insert the correct following word,
+ such as `example' or `table'. (This command does not handle
+ nested lists correctly, but inserts the word appropriate to the
+ immediately preceding list.)
+
+`C-c C-c i'
+`M-x texinfo-insert-@item'
+ Insert `@item' and put the cursor at the beginning of the next
+ line.
+
+`C-c C-c k'
+`M-x texinfo-insert-@kbd'
+ Insert `@kbd{}' and put the cursor between the braces.
+
+`C-c C-c n'
+`M-x texinfo-insert-@node'
+ Insert `@node' and a comment line listing the sequence for the
+ `Next', `Previous', and `Up' nodes. Leave point after the `@node'.
+
+`C-c C-c o'
+`M-x texinfo-insert-@noindent'
+ Insert `@noindent' and put the cursor at the beginning of the next
+ line.
+
+`C-c C-c s'
+`M-x texinfo-insert-@samp'
+ Insert `@samp{}' and put the cursor between the braces.
+
+`C-c C-c t'
+`M-x texinfo-insert-@table'
+ Insert `@table' followed by a <SPC> and leave the cursor after the
+ <SPC>.
+
+`C-c C-c v'
+`M-x texinfo-insert-@var'
+ Insert `@var{}' and put the cursor between the braces.
+
+`C-c C-c x'
+`M-x texinfo-insert-@example'
+ Insert `@example' and put the cursor at the beginning of the next
+ line.
+
+`C-c C-c {'
+`M-x texinfo-insert-braces'
+ Insert `{}' and put the cursor between the braces.
+
+`C-c C-c }'
+`C-c C-c ]'
+`M-x up-list'
+ Move from between a pair of braces forward past the closing brace.
+ Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
+ however, more mnemonic; hence the two keybindings. (Also, you can
+ move out from between braces by typing `C-f'.)
+
+ To put a command such as `@code{...}' around an _existing_ word,
+position the cursor in front of the word and type `C-u 1 C-c C-c c'.
+This makes it easy to edit existing plain text. The value of the
+prefix argument tells Emacs how many words following point to include
+between braces--`1' for one word, `2' for two words, and so on. Use a
+negative argument to enclose the previous word or words. If you do not
+specify a prefix argument, Emacs inserts the @-command string and
+positions the cursor between the braces. This feature works only for
+those @-commands that operate on a word or words within one line, such
+as `@kbd' and `@var'.
+
+ This set of insert commands was created after analyzing the frequency
+with which different @-commands are used in the `GNU Emacs Manual' and
+the `GDB Manual'. If you wish to add your own insert commands, you can
+bind a keyboard macro to a key, use abbreviations, or extend the code
+in `texinfo.el'.
+
+ `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
+that works differently from the other insert commands. It inserts a
+node's section or chapter title in the space for the description in a
+menu entry line. (A menu entry has three parts, the entry name, the
+node name, and the description. Only the node name is required, but a
+description helps explain what the node is about. *Note The Parts of a
+Menu: Menu Parts.)
+
+ To use `texinfo-start-menu-description', position point in a menu
+entry line and type `C-c C-c C-d'. The command looks for and copies
+the title that goes with the node name, and inserts the title as a
+description; it positions point at beginning of the inserted text so you
+can edit it. The function does not insert the title if the menu entry
+line already contains a description.
+
+ This command is only an aid to writing descriptions; it does not do
+the whole job. You must edit the inserted text since a title tends to
+use the same words as a node name but a useful description uses
+different words.
+
+\1f
+File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode
+
+Showing the Section Structure of a File
+=======================================
+
+You can show the section structure of a Texinfo file by using the `C-c
+C-s' command (`texinfo-show-structure'). This command shows the
+section structure of a Texinfo file by listing the lines that begin
+with the @-commands for `@chapter', `@section', and the like. It
+constructs what amounts to a table of contents. These lines are
+displayed in another buffer called the `*Occur*' buffer. In that
+buffer, 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.
+
+`C-c C-s'
+`M-x texinfo-show-structure'
+ Show the `@chapter', `@section', and such lines of a Texinfo file.
+
+`C-c C-c'
+`M-x occur-mode-goto-occurrence'
+ Go to the line in the Texinfo file corresponding to the line under
+ the cursor in the `*Occur*' buffer.
+
+ If you call `texinfo-show-structure' with a prefix argument by typing
+`C-u C-c C-s', it will list not only those lines with the @-commands
+for `@chapter', `@section', and the like, but also the `@node' lines.
+(This is how the `texinfo-show-structure' command worked without an
+argument in the first version of Texinfo. It was changed because
+`@node' lines clutter up the `*Occur*' buffer and are usually not
+needed.) You can use `texinfo-show-structure' with a prefix argument
+to check whether the `Next', `Previous', and `Up' pointers of an
+`@node' line are correct.
+
+ Often, when you are working on a manual, you will be interested only
+in the structure of the current chapter. In this case, you can mark
+off the region of the buffer that you are interested in by using the
+`C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
+will work on only that region. To see the whole buffer again, use
+`C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more
+information about the narrowing commands.)
+
+ In addition to providing the `texinfo-show-structure' command,
+Texinfo mode sets the value of the page delimiter variable to match the
+chapter-level @-commands. This enables you to use the `C-x ]'
+(`forward-page') and `C-x [' (`backward-page') commands to move forward
+and backward by chapter, and to use the `C-x p' (`narrow-to-page')
+command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more
+information about the page commands.
+
+\1f
+File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode
+
+Updating Nodes and Menus
+========================
+
+Texinfo mode provides commands for automatically creating or updating
+menus and node pointers. The commands are called "update" commands
+because their most frequent use is for updating a Texinfo file after
+you have worked on it; but you can use them to insert the `Next',
+`Previous', and `Up' pointers into an `@node' line that has none and to
+create menus in a file that has none.
+
+ If you do not use the updating commands, you need to write menus and
+node pointers by hand, which is a tedious task.
+
+* Menu:
+
+* Updating Commands:: Five major updating commands.
+* Updating Requirements:: How to structure a Texinfo file for
+ using the updating command.
+* Other Updating Commands:: How to indent descriptions, insert
+ missing nodes lines, and update
+ nodes in sequence.
+
+\1f
+File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus
+
+The Updating Commands
+---------------------
+
+ You can use the updating commands
+
+ * to insert or update the `Next', `Previous', and `Up' pointers of a
+ node,
+
+ * to insert or update the menu for a section, and
+
+ * to create a master menu for a Texinfo source file.
+
+ You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo file.
+
+ The updating commands work only with conventional Texinfo files, which
+are structured hierarchically like books. In such files, a structuring
+command line must follow closely after each `@node' line, except for
+the `Top' `@node' line. (A "structuring command line" is a line
+beginning with `@chapter', `@section', or other similar command.)
+
+ You can write the structuring command line on the line that follows
+immediately after an `@node' line or else on the line that follows
+after a single `@comment' line or a single `@ifinfo' line. You cannot
+interpose more than one line between the `@node' line and the
+structuring command line; and you may interpose only an `@comment' line
+or an `@ifinfo' line.
+
+ Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an `@chapter' or equivalent-level command.
+Note that the menu updating commands will not create a main or master
+menu for a Texinfo file that has only `@chapter'-level nodes! The menu
+updating commands only create menus _within_ nodes for lower level
+nodes. To create a menu of chapters, you must provide a `Top' node.
+
+ The menu updating commands remove menu entries that refer to other
+Info files since they do not refer to nodes within the current buffer.
+This is a deficiency. Rather than use menu entries, you can use cross
+references to refer to other Info files. None of the updating commands
+affect cross references.
+
+ Texinfo mode has five updating commands that are used most often: two
+are for updating the node pointers or menu of a single node (or a
+region); two are for updating every node pointer and menu in a file;
+and one, the `texinfo-master-menu' command, is for creating a master
+menu for a complete file, and optionally, for updating every node and
+menu in the whole Texinfo file.
+
+ The `texinfo-master-menu' command is the primary command:
+
+`C-c C-u m'
+`M-x texinfo-master-menu'
+ Create or update a master menu that includes all the other menus
+ (incorporating the descriptions from pre-existing menus, if any).
+
+ With an argument (prefix argument, `C-u,' if interactive), first
+ create or update all the nodes and all the regular menus in the
+ buffer before constructing the master menu. (*Note The Top Node
+ and Master Menu: The Top Node, for more about a master menu.)
+
+ For `texinfo-master-menu' to work, the Texinfo file must have a
+ `Top' node and at least one subsequent node.
+
+ After extensively editing a Texinfo file, you can type the
+ following:
+
+ C-u M-x texinfo-master-menu
+ or
+ C-u C-c C-u m
+
+ This updates all the nodes and menus completely and all at once.
+
+ The other major updating commands do smaller jobs and are designed for
+the person who updates nodes and menus as he or she writes a Texinfo
+file.
+
+ The commands are:
+
+`C-c C-u C-n'
+`M-x texinfo-update-node'
+ Insert the `Next', `Previous', and `Up' pointers for the node that
+ point is within (i.e., for the `@node' line preceding point). If
+ the `@node' line has pre-existing `Next', `Previous', or `Up'
+ pointers in it, the old pointers are removed and new ones inserted.
+ With an argument (prefix argument, `C-u', if interactive), this
+ command updates all `@node' lines in the region (which is the text
+ between point and mark).
+
+`C-c C-u C-m'
+`M-x texinfo-make-menu'
+ Create or update the menu in the node that point is within. With
+ an argument (`C-u' as prefix argument, if interactive), the
+ command makes or updates menus for the nodes which are either
+ within or a part of the region.
+
+ Whenever `texinfo-make-menu' updates an existing menu, the
+ descriptions from that menu are incorporated into the new menu.
+ This is done by copying descriptions from the existing menu to the
+ entries in the new menu that have the same node names. If the
+ node names are different, the descriptions are not copied to the
+ new menu.
+
+`C-c C-u C-e'
+`M-x texinfo-every-node-update'
+ Insert or update the `Next', `Previous', and `Up' pointers for
+ every node in the buffer.
+
+`C-c C-u C-a'
+`M-x texinfo-all-menus-update'
+ Create or update all the menus in the buffer. With an argument
+ (`C-u' as prefix argument, if interactive), first insert or update
+ all the node pointers before working on the menus.
+
+ If a master menu exists, the `texinfo-all-menus-update' command
+ updates it; but the command does not create a new master menu if
+ none already exists. (Use the `texinfo-master-menu' command for
+ that.)
+
+ When working on a document that does not merit a master menu, you
+ can type the following:
+
+ C-u C-c C-u C-a
+ or
+ C-u M-x texinfo-all-menus-update
+
+ This updates all the nodes and menus.
+
+ The `texinfo-column-for-description' variable specifies the column to
+which menu descriptions are indented. By default, the value is 32
+although it is often useful to reduce it to as low as 24. You can set
+the variable with the `M-x edit-options' command (*note Editing
+Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
+command (*note Examining and Setting Variables: (xemacs)Examining.).
+
+ Also, the `texinfo-indent-menu-description' command may be used to
+indent existing menu descriptions to a specified column. Finally, if
+you wish, you can use the `texinfo-insert-node-lines' command to insert
+missing `@node' lines into a file. (*Note Other Updating Commands::,
+for more information.)
+
+\1f
+File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus
+
+Updating Requirements
+---------------------
+
+To use the updating commands, you must organize the Texinfo file
+hierarchically with chapters, sections, subsections, and the like.
+When you construct the hierarchy of the manual, do not `jump down' more
+than one level at a time: you can follow the `Top' node with a chapter,
+but not with a section; you can follow a chapter with a section, but
+not with a subsection. However, you may `jump up' any number of levels
+at one time--for example, from a subsection to a chapter.
+
+ Each `@node' line, with the exception of the line for the `Top' node,
+must be followed by a line with a structuring command such as
+`@chapter', `@section', or `@unnumberedsubsec'.
+
+ Each `@node' line/structuring-command line combination must look
+either like this:
+
+ @node Comments, Minimum, Conventions, Overview
+ @comment node-name, next, previous, up
+ @section Comments
+
+ or like this (without the `@comment' line):
+
+ @node Comments, Minimum, Conventions, Overview
+ @section Comments
+
+In this example, `Comments' is the name of both the node and the
+section. The next node is called `Minimum' and the previous node is
+called `Conventions'. The `Comments' section is within the `Overview'
+node, which is specified by the `Up' pointer. (Instead of an
+`@comment' line, you can write an `@ifinfo' line.)
+
+ If a file has a `Top' node, it must be called `top' or `Top' and be
+the first node in the file.
+
+ The menu updating commands create a menu of sections within a chapter,
+a menu of subsections within a section, and so on. This means that you
+must have a `Top' node if you want a menu of chapters.
+
+ Incidentally, the `makeinfo' command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers. Thus, if you can be sure that your Texinfo file will be
+formatted with `makeinfo', you have no need for the `update node'
+commands. (*Note Creating an Info File: Create an Info File, for more
+information about `makeinfo'.) However, both `makeinfo' and the
+`texinfo-format-...' commands require that you insert menus in the file.
+
+\1f
+File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus
+
+Other Updating Commands
+-----------------------
+
+In addition to the five major updating commands, Texinfo mode possesses
+several less frequently used updating commands:
+
+`M-x texinfo-insert-node-lines'
+ Insert `@node' lines before the `@chapter', `@section', and other
+ sectioning commands wherever they are missing throughout a region
+ in a Texinfo file.
+
+ With an argument (`C-u' as prefix argument, if interactive), the
+ `texinfo-insert-node-lines' command not only inserts `@node' lines
+ but also inserts the chapter or section titles as the names of the
+ corresponding nodes. In addition, it inserts the titles as node
+ names in pre-existing `@node' lines that lack names. Since node
+ names should be more concise than section or chapter titles, you
+ must manually edit node names so inserted.
+
+ For example, the following marks a whole buffer as a region and
+ inserts `@node' lines and titles throughout:
+
+ C-x h C-u M-x texinfo-insert-node-lines
+
+ (Note that this command inserts titles as node names in `@node'
+ lines; the `texinfo-start-menu-description' command (*note
+ Inserting Frequently Used Commands: Inserting.) inserts titles as
+ descriptions in menu entries, a different action. However, in both
+ cases, you need to edit the inserted text.)
+
+`M-x texinfo-multiple-files-update'
+ Update nodes and menus in a document built from several separate
+ files. With `C-u' as a prefix argument, create and insert a
+ master menu in the outer file. With a numeric prefix argument,
+ such as `C-u 2', first update all the menus and all the `Next',
+ `Previous', and `Up' pointers of all the included files before
+ creating and inserting a master menu in the outer file. The
+ `texinfo-multiple-files-update' command is described in the
+ appendix on `@include' files. *Note
+ texinfo-multiple-files-update::.
+
+`M-x texinfo-indent-menu-description'
+ Indent every description in the menu following point to the
+ specified column. You can use this command to give yourself more
+ space for descriptions. With an argument (`C-u' as prefix
+ argument, if interactive), the `texinfo-indent-menu-description'
+ command indents every description in every menu in the region.
+ However, this command does not indent the second and subsequent
+ lines of a multi-line description.
+
+`M-x texinfo-sequential-node-update'
+ Insert the names of the nodes immediately following and preceding
+ the current node as the `Next' or `Previous' pointers regardless
+ of those nodes' hierarchical level. This means that the `Next'
+ node of a subsection may well be the next chapter. Sequentially
+ ordered nodes are useful for novels and other documents that you
+ read through sequentially. (However, in Info, the `g *' command
+ lets you look through the file sequentially, so sequentially
+ ordered nodes are not strictly necessary.) With an argument
+ (prefix argument, if interactive), the
+ `texinfo-sequential-node-update' command sequentially updates all
+ the nodes in the region.
+
+\1f
+File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode
+
+Formatting for Info
+===================
+
+Texinfo mode provides several commands for formatting part or all of a
+Texinfo file for Info. Often, when you are writing a document, you
+want to format only part of a file--that is, a region.
+
+ You can use either the `texinfo-format-region' or the
+`makeinfo-region' command to format a region:
+
+`C-c C-e C-r'
+`M-x texinfo-format-region'
+`C-c C-m C-r'
+`M-x makeinfo-region'
+ Format the current region for Info.
+
+ You can use either the `texinfo-format-buffer' or the
+`makeinfo-buffer' command to format a whole buffer:
+
+`C-c C-e C-b'
+`M-x texinfo-format-buffer'
+`C-c C-m C-b'
+`M-x makeinfo-buffer'
+ Format the current buffer for Info.
+
+ For example, after writing a Texinfo file, you can type the following:
+
+ C-u C-c C-u m
+or
+ C-u M-x texinfo-master-menu
+
+This updates all the nodes and menus. Then type the following to create
+an Info file:
+
+ C-c C-m C-b
+or
+ M-x makeinfo-buffer
+
+ For TeX or the Info formatting commands to work, the file _must_
+include a line that has `@setfilename' in its header.
+
+ *Note Create an Info File::, for details about Info formatting.
+
+\1f
+File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode
+
+Formatting and Printing
+=======================
+
+Typesetting and printing a Texinfo file is a multi-step process in which
+you first create a file for printing (called a DVI file), and then
+print the file. Optionally, you may also create indices. To do this,
+you must run the `texindex' command after first running the `tex'
+typesetting command; and then you must run the `tex' command again. Or
+else run the `texi2dvi' command which automatically creates indices as
+needed (*note Format with texi2dvi::).
+
+ Often, when you are writing a document, you want to typeset and print
+only part of a file to see what it will look like. You can use the
+`texinfo-tex-region' and related commands for this purpose. Use the
+`texinfo-tex-buffer' command to format all of a buffer.
+
+`C-c C-t C-b'
+`M-x texinfo-tex-buffer'
+ Run `texi2dvi' on the buffer. In addition to running TeX on the
+ buffer, this command automatically creates or updates indices as
+ needed.
+
+`C-c C-t C-r'
+`M-x texinfo-tex-region'
+ Run TeX on the region.
+
+`C-c C-t C-i'
+`M-x texinfo-texindex'
+ Run `texindex' to sort the indices of a Texinfo file formatted with
+ `texinfo-tex-region'. The `texinfo-tex-region' command does not
+ run `texindex' automatically; it only runs the `tex' typesetting
+ command. You must run the `texinfo-tex-region' command a second
+ time after sorting the raw index files with the `texindex'
+ command. (Usually, you do not format an index when you format a
+ region, only when you format a buffer. Now that the `texi2dvi'
+ command exists, there is little or no need for this command.)
+
+`C-c C-t C-p'
+`M-x texinfo-tex-print'
+ Print the file (or the part of the file) previously formatted with
+ `texinfo-tex-buffer' or `texinfo-tex-region'.
+
+ For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
+_must_ start with a `\input texinfo' line and must include an
+`@settitle' line. The file must end with `@bye' on a line by itself.
+(When you use `texinfo-tex-region', you must surround the `@settitle'
+line with start-of-header and end-of-header lines.)
+
+ *Note Format/Print Hardcopy::, for a description of the other TeX
+related commands, such as `tex-show-print-queue'.
+
+\1f
+File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode
+
+Texinfo Mode Summary
+====================
+
+In Texinfo mode, each set of commands has default keybindings that
+begin with the same keys. All the commands that are custom-created for
+Texinfo mode begin with `C-c'. The keys are somewhat mnemonic.
+
+Insert Commands
+---------------
+
+The insert commands are invoked by typing `C-c' twice and then the
+first letter of the @-command to be inserted. (It might make more
+sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
+is quick to type.)
+
+ C-c C-c c Insert `@code'.
+ C-c C-c d Insert `@dfn'.
+ C-c C-c e Insert `@end'.
+ C-c C-c i Insert `@item'.
+ C-c C-c n Insert `@node'.
+ C-c C-c s Insert `@samp'.
+ C-c C-c v Insert `@var'.
+ C-c C-c { Insert braces.
+ C-c C-c ]
+ C-c C-c } Move out of enclosing braces.
+
+ C-c C-c C-d Insert a node's section title
+ in the space for the description
+ in a menu entry line.
+
+Show Structure
+--------------
+
+The `texinfo-show-structure' command is often used within a narrowed
+region.
+
+ C-c C-s List all the headings.
+
+The Master Update Command
+-------------------------
+
+The `texinfo-master-menu' command creates a master menu; and can be
+used to update every node and menu in a file as well.
+
+ C-c C-u m
+ M-x texinfo-master-menu
+ Create or update a master menu.
+
+ C-u C-c C-u m With `C-u' as a prefix argument, first
+ create or update all nodes and regular
+ menus, and then create a master menu.
+
+Update Pointers
+---------------
+
+The update pointer commands are invoked by typing `C-c C-u' and then
+either `C-n' for `texinfo-update-node' or `C-e' for
+`texinfo-every-node-update'.
+
+ C-c C-u C-n Update a node.
+ C-c C-u C-e Update every node in the buffer.
+
+Update Menus
+------------
+
+Invoke the update menu commands by typing `C-c C-u' and then either
+`C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
+To update both nodes and menus at the same time, precede `C-c C-u C-a'
+with `C-u'.
+
+ C-c C-u C-m Make or update a menu.
+
+ C-c C-u C-a Make or update all
+ menus in a buffer.
+
+ C-u C-c C-u C-a With `C-u' as a prefix argument,
+ first create or update all nodes and
+ then create or update all menus.
+
+Format for Info
+---------------
+
+The Info formatting commands that are written in Emacs Lisp are invoked
+by typing `C-c C-e' and then either `C-r' for a region or `C-b' for the
+whole buffer.
+
+ The Info formatting commands that are written in C and based on the
+`makeinfo' program are invoked by typing `C-c C-m' and then either
+`C-r' for a region or `C-b' for the whole buffer.
+
+Use the `texinfo-format...' commands:
+
+ C-c C-e C-r Format the region.
+ C-c C-e C-b Format the buffer.
+
+Use `makeinfo':
+
+ C-c C-m C-r Format the region.
+ C-c C-m C-b Format the buffer.
+ C-c C-m C-l Recenter the `makeinfo' output buffer.
+ C-c C-m C-k Kill the `makeinfo' formatting job.
+
+Typeset and Print
+-----------------
+
+The TeX typesetting and printing commands are invoked by typing `C-c
+C-t' and then another control command: `C-r' for `texinfo-tex-region',
+`C-b' for `texinfo-tex-buffer', and so on.
+
+ C-c C-t C-r Run TeX on the region.
+ C-c C-t C-b Run `texi2dvi' on the buffer.
+ C-c C-t C-i Run `texindex'.
+ C-c C-t C-p Print the DVI file.
+ C-c C-t C-q Show the print queue.
+ C-c C-t C-d Delete a job from the print queue.
+ C-c C-t C-k Kill the current TeX formatting job.
+ C-c C-t C-x Quit a currently stopped TeX formatting job.
+ C-c C-t C-l Recenter the output buffer.
+
+Other Updating Commands
+-----------------------
+
+The `other updating commands' do not have standard keybindings because
+they are rarely used.
+
+ M-x texinfo-insert-node-lines
+ Insert missing `@node' lines in region.
+ With `C-u' as a prefix argument,
+ use section titles as node names.
+
+ M-x texinfo-multiple-files-update
+ Update a multi-file document.
+ With `C-u 2' as a prefix argument,
+ create or update all nodes and menus
+ in all included files first.
+
+ M-x texinfo-indent-menu-description
+ Indent descriptions.
+
+ M-x texinfo-sequential-node-update
+ Insert node pointers in strict sequence.
+
+\1f
+File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
+
+Beginning a Texinfo File
+************************
+
+Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name of the file and the title of the
+document.
+
+* Menu:
+
+* Four Parts:: Four parts begin a Texinfo file.
+* Sample Beginning:: Here is a sample beginning for a Texinfo file.
+* Header:: The very beginning of a Texinfo file.
+* Info Summary and Permissions:: Summary and copying permissions for Info.
+* Titlepage & Copyright Page:: Creating the title and copyright pages.
+* The Top Node:: Creating the `Top' node and master menu.
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
+
+\1f
+File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File
+
+Four Parts Begin a File
+=======================
+
+ Generally, the beginning of a Texinfo file has four parts:
+
+ 1. The header, delimited by special comment lines, that includes the
+ commands for naming the Texinfo file and telling TeX what
+ definitions file to use when processing the Texinfo file.
+
+ 2. A short statement of what the file is about, with a copyright
+ notice and copying permissions. This is enclosed in `@ifinfo' and
+ `@end ifinfo' commands so that the formatters place it only in the
+ Info file.
+
+ 3. A title page and copyright page, with a copyright notice and
+ copying permissions. This is enclosed between `@titlepage' and
+ `@end titlepage' commands. The title and copyright page appear
+ only in the printed manual.
+
+ 4. The `Top' node that contains a menu for the whole Info file. The
+ contents of this node appear only in the Info file.
+
+ Also, optionally, you may include the copying conditions for a program
+and a warranty disclaimer. The copying section will be followed by an
+introduction or else by the first chapter of the manual.
+
+ Since the copyright notice and copying permissions for the Texinfo
+document (in contrast to the copying permissions for a program) are in
+parts that appear only in the Info file or only in the printed manual,
+this information must be given twice.
+
+\1f
+File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File
+
+Sample Texinfo File Beginning
+=============================
+
+The following sample shows what is needed.
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename NAME-OF-INFO-FILE
+ @settitle NAME-OF-MANUAL
+ @setchapternewpage odd
+ @c %**end of header
+
+ @ifinfo
+ This file documents ...
+
+ Copyright YEAR COPYRIGHT-OWNER
+
+ Permission is granted to ...
+ @end ifinfo
+
+ @c This title page illustrates only one of the
+ @c two methods of forming a title page.
+
+ @titlepage
+ @title NAME-OF-MANUAL-WHEN-PRINTED
+ @subtitle SUBTITLE-IF-ANY
+ @subtitle SECOND-SUBTITLE
+ @author AUTHOR
+
+ @c The following two commands
+ @c start the copyright page.
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} YEAR COPYRIGHT-OWNER
+
+ Published by ...
+
+ Permission is granted to ...
+ @end titlepage
+
+ @node Top, Overview, , (dir)
+
+ @ifinfo
+ This document describes ...
+
+ This document applies to version ...
+ of the program named ...
+ @end ifinfo
+
+ @menu
+ * Copying:: Your rights and freedoms.
+ * First Chapter:: Getting started ...
+ * Second Chapter:: ...
+ ...
+ ...
+ @end menu
+
+ @node First Chapter, Second Chapter, top, top
+ @comment node-name, next, previous, up
+ @chapter First Chapter
+ @cindex Index entry for First Chapter
+
+\1f
+File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File
+
+The Texinfo File Header
+=======================
+
+Texinfo files start with at least three lines that provide Info and TeX
+with necessary information. These are the `\input texinfo' line, the
+`@settitle' line, and the `@setfilename' line. If you want to run TeX
+on just a part of the Texinfo File, you must write the `@settitle' and
+`@setfilename' lines between start-of-header and end-of-header lines.
+
+ Thus, the beginning of a Texinfo file looks like this:
+
+ \input texinfo @c -*-texinfo-*-
+ @setfilename sample.info
+ @settitle Sample Document
+
+or else like this:
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename sample.info
+ @settitle Sample Document
+ @c %**end of header
+
+* Menu:
+
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: An option to specify paragraph indentation.
+* End of Header:: Formatting a region requires this.
+
+\1f
+File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header
+
+The First Line of a Texinfo File
+--------------------------------
+
+Every Texinfo file that is to be the top-level input to TeX must begin
+with a line that looks like this:
+
+ \input texinfo @c -*-texinfo-*-
+
+This line serves two functions:
+
+ 1. When the file is processed by TeX, the `\input texinfo' command
+ tells TeX to load the macros needed for processing a Texinfo file.
+ These are in a file called `texinfo.tex', which is usually located
+ in the `/usr/lib/tex/macros' directory. TeX uses the backslash,
+ `\', to mark the beginning of a command, just as Texinfo uses `@'.
+ The `texinfo.tex' file causes the switch from `\' to `@'; before
+ the switch occurs, TeX requires `\', which is why it appears at
+ the beginning of the file.
+
+ 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
+ specification tells Emacs to use Texinfo mode.
+
+\1f
+File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header
+
+Start of Header
+---------------
+
+Write a start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with `@setfilename' and `@settitle'
+lines and, optionally, with other command lines, such as `@smallbook'
+or `@footnotestyle'; and then by an end-of-header line (*note End of
+Header::).
+
+ With these lines, you can format part of a Texinfo file for Info or
+typeset part for printing.
+
+ A start-of-header line looks like this:
+
+ @c %**start of header
+
+ The odd string of characters, `%**', is to ensure that no other
+comment is accidentally taken for a start-of-header line.
+
+\1f
+File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header
+
+`@setfilename'
+--------------
+
+In order to serve as the primary input file for either `makeinfo' or
+TeX, a Texinfo file must contain a line that looks like this:
+
+ @setfilename INFO-FILE-NAME
+
+ Write the `@setfilename' command at the beginning of a line and
+follow it on the same line by the Info file name. Do not write anything
+else on the line; anything on the line after the command is considered
+part of the file name, including what would otherwise be a comment.
+
+ The `@setfilename' line specifies the name of the Info file to be
+generated. This name should be different from the name of the Texinfo
+file. There are two conventions for choosing the name: you can either
+remove the `.texi' extension from the input file name, or replace it
+with the `.info' extension.
+
+ Some operating systems cannot handle long file names. You can run
+into a problem even when the file name you specify is itself short
+enough. This occurs because the Info formatters split a long Info file
+into short indirect subfiles, and name them by appending `-1', `-2',
+..., `-10', `-11', and so on, to the original file name. (*Note Tag
+Files and Split Files: Tag and Split Files.) The subfile name
+`texinfo.info-10', for example, is too long for some systems; so the
+Info file name for this document is `texinfo' rather than
+`texinfo.info'.
+
+ The Info formatting commands ignore everything written before the
+`@setfilename' line, which is why the very first line of the file (the
+`\input' line) does not show up in the output.
+
+ The `@setfilename' line produces no output when you typeset a manual
+with TeX, but it nevertheless is essential: it opens the index,
+cross-reference, and other auxiliary files used by Texinfo, and also
+reads `texinfo.cnf' if that file is present on your system (*note
+Preparing to Use TeX: Preparing for TeX.).
+
+\1f
+File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header
+
+`@settitle'
+-----------
+
+In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
+ @settitle TITLE
+
+ Write the `@settitle' command at the beginning of a line and follow
+it on the same line by the title. This tells TeX the title to use in a
+header or footer. Do not write anything else on the line; anything on
+the line after the command is considered part of the title, including a
+comment.
+
+ Conventionally, when TeX formats a Texinfo file for double-sided
+output, the title is printed in the left-hand (even-numbered) page
+headings and the current chapter title is printed in the right-hand
+(odd-numbered) page headings. (TeX learns the title of each chapter
+from each `@chapter' command.) Page footers are not printed.
+
+ Even if you are printing in a single-sided style, TeX looks for an
+`@settitle' command line, in case you include the manual title in the
+heading.
+
+ The `@settitle' command should precede everything that generates
+actual output in TeX.
+
+ Although the title in the `@settitle' command is usually the same as
+the title on the title page, it does not affect the title as it appears
+on the title page. Thus, the two do not need not match exactly; and
+the title in the `@settitle' command can be a shortened or expanded
+version of the title as it appears on the title page. (*Note
+`@titlepage': titlepage.)
+
+ TeX prints page headings only for that text that comes after the
+`@end titlepage' command in the Texinfo file, or that comes after an
+`@headings' command that turns on headings. (*Note The `@headings'
+Command: headings on off, for more information.)
+
+ You may, if you wish, create your own, customized headings and
+footings. *Note Page Headings: Headings, for a detailed discussion of
+this process.
+
+\1f
+File: texinfo.info, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header
+
+`@setchapternewpage'
+--------------------
+
+In a book or a manual, text is usually printed on both sides of the
+paper, chapters start on right-hand pages, and right-hand pages have
+odd numbers. But in short reports, text often is printed only on one
+side of the paper. Also in short reports, chapters sometimes do not
+start on new pages, but are printed on the same page as the end of the
+preceding chapter, after a small amount of vertical whitespace.
+
+ You can use the `@setchapternewpage' command with various arguments
+to specify how TeX should start chapters and whether it should typeset
+pages for printing on one or both sides of the paper (single-sided or
+double-sided printing).
+
+ Write the `@setchapternewpage' command at the beginning of a line
+followed by its argument.
+
+ For example, you would write the following to cause each chapter to
+start on a fresh odd-numbered page:
+
+ @setchapternewpage odd
+
+ You can specify one of three alternatives with the
+`@setchapternewpage' command:
+
+`@setchapternewpage off'
+ Cause TeX to typeset a new chapter on the same page as the last
+ chapter, after skipping some vertical whitespace. Also, cause TeX
+ to format page headers for single-sided printing. (You can
+ override the headers format with the `@headings double' command;
+ see *Note The `@headings' Command: headings on off.)
+
+`@setchapternewpage on'
+ Cause TeX to start new chapters on new pages and to typeset page
+ headers for single-sided printing. This is the form most often
+ used for short reports.
+
+ This alternative is the default.
+
+`@setchapternewpage odd'
+ Cause TeX to start new chapters on new, odd-numbered pages
+ (right-handed pages) and to typeset for double-sided printing.
+ This is the form most often used for books and manuals.
+
+Texinfo does not have an `@setchapternewpage even' command.
+
+(You can countermand or modify an `@setchapternewpage' command with an
+`@headings' command. *Note The `@headings' Command: headings on off.)
+
+ At the beginning of a manual or book, pages are not numbered--for
+example, the title and copyright pages of a book are not numbered. By
+convention, table of contents pages are numbered with roman numerals
+and not in sequence with the rest of the document.
+
+ Since an Info file does not have pages, the `@setchapternewpage'
+command has no effect on it.
+
+ Usually, you do not write an `@setchapternewpage' command for
+single-sided printing, but accept the default which is to typeset for
+single-sided printing and to start new chapters on new pages. Usually,
+you write an `@setchapternewpage odd' command for double-sided printing.
+
+\1f
+File: texinfo.info, Node: paragraphindent, Next: End of Header, Prev: setchapternewpage, Up: Header
+
+Paragraph Indenting
+-------------------
+
+The Info formatting commands may insert spaces at the beginning of the
+first line of each paragraph, thereby indenting that paragraph. You
+can use the `@paragraphindent' command to specify the indentation.
+Write an `@paragraphindent' command at the beginning of a line followed
+by either `asis' or a number. The template is:
+
+ @paragraphindent INDENT
+
+ The Info formatting commands indent according to the value of INDENT:
+
+ * If the value of INDENT is `asis', the Info formatting commands do
+ not change the existing indentation.
+
+ * If the value of INDENT is zero, the Info formatting commands delete
+ existing indentation.
+
+ * If the value of INDENT is greater than zero, the Info formatting
+ commands indent the paragraph by that number of spaces.
+
+ The default value of INDENT is `asis'.
+
+ Write the `@paragraphindent' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you write
+the command between the start-of-header and end-of-header lines, the
+region formatting commands indent paragraphs as specified.)
+
+ A peculiarity of the `texinfo-format-buffer' and
+`texinfo-format-region' commands is that they do not indent (nor fill)
+paragraphs that contain `@w' or `@*' commands. *Note Refilling
+Paragraphs::, for a detailed description of what goes on.
+
+\1f
+File: texinfo.info, Node: End of Header, Prev: paragraphindent, Up: Header
+
+End of Header
+-------------
+
+Follow the header lines with an end-of-header line. An end-of-header
+line looks like this:
+
+ @c %**end of header
+
+ If you include the `@setchapternewpage' command between the
+start-of-header and end-of-header lines, TeX will typeset a region as
+that command specifies. Similarly, if you include an `@smallbook'
+command between the start-of-header and end-of-header lines, TeX will
+typeset a region in the "small" book format.
+
+ The reason for the odd string of characters (`%**') is so that the
+`texinfo-tex-region' command does not accidentally find something that
+it should not when it is looking for the header.
+
+ The start-of-header line and the end-of-header line are Texinfo mode
+variables that you can change.
+
+\1f
+File: texinfo.info, Node: Info Summary and Permissions, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File
+
+Summary and Copying Permissions for Info
+========================================
+
+The title page and the copyright page appear only in the printed copy of
+the manual; therefore, the same information must be inserted in a
+section that appears only in the Info file. This section usually
+contains a brief description of the contents of the Info file, a
+copyright notice, and copying permissions.
+
+ The copyright notice should read:
+
+ Copyright YEAR COPYRIGHT-OWNER
+
+and be put on a line by itself.
+
+ Standard text for the copyright permissions is contained in an
+appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
+Permissions, for the complete text.
+
+ The permissions text appears in an Info file _before_ the first node.
+This mean that a reader does _not_ see this text when reading the file
+using Info, except when using the advanced Info command `g *'.
+
+\1f
+File: texinfo.info, Node: Titlepage & Copyright Page, Next: The Top Node, Prev: Info Summary and Permissions, Up: Beginning a File
+
+The Title and Copyright Pages
+=============================
+
+A manual's name and author are usually printed on a title page.
+Sometimes copyright information is printed on the title page as well;
+more often, copyright information is printed on the back of the title
+page.
+
+ The title and copyright pages appear in the printed manual, but not
+in the Info file. Because of this, it is possible to use several
+slightly obscure TeX typesetting commands that cannot be used in an
+Info file. In addition, this part of the beginning of a Texinfo file
+contains the text of the copying permissions that will appear in the
+printed manual.
+
+ *Note Titlepage Copying Permissions: Titlepage Permissions, for the
+standard text for the copyright permissions.
+
+* Menu:
+
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The `@titlefont', `@center',
+ and `@sp' commands.
+* title subtitle author:: The `@title', `@subtitle',
+ and `@author' commands.
+* Copyright & Permissions:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
+
+\1f
+File: texinfo.info, Node: titlepage, Next: titlefont center sp, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page
+
+`@titlepage'
+------------
+
+Start the material for the title page and following copyright page with
+`@titlepage' on a line by itself and end it with `@end titlepage' on a
+line by itself.
+
+ The `@end titlepage' command starts a new page and turns on page
+numbering. (*Note Page Headings: Headings, for details about how to
+generate page headings.) All the material that you want to appear on
+unnumbered pages should be put between the `@titlepage' and `@end
+titlepage' commands. By using the `@page' command you can force a page
+break within the region delineated by the `@titlepage' and `@end
+titlepage' commands and thereby create more than one unnumbered page.
+This is how the copyright page is produced. (The `@titlepage' command
+might perhaps have been better named the `@titleandadditionalpages'
+command, but that would have been rather long!)
+
+ When you write a manual about a computer program, you should write the
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is
+independent of it, you should also include an edition number(1) (*note
+titlepage-Footnote-1::) for the manual. This helps readers keep track
+of which manual is for which version of the program. (The `Top' node
+should also contain this information; see *Note `@top': makeinfo top.)
+
+ Texinfo provides two main methods for creating a title page. One
+method uses the `@titlefont', `@sp', and `@center' commands to generate
+a title page in which the words on the page are centered.
+
+ The second method uses the `@title', `@subtitle', and `@author'
+commands to create a title page with black rules under the title and
+author lines and the subtitle text set flush to the right hand side of
+the page. With this method, you do not specify any of the actual
+formatting of the title page. You specify the text you want, and
+Texinfo does the formatting. You may use either method.
+
+ For extremely simple applications, Texinfo also provides a command
+`@shorttitlepage' which takes a single argument as the title. The
+argument is typeset on a page by itself and followed by a blank page.
+
+\1f
+File: texinfo.info, Node: titlepage-Footnotes, Up: titlepage
+
+ (1) We have found that it is helpful to refer to versions of manuals
+as `editions' and versions of programs as `versions'; otherwise, we
+find we are liable to confuse each other in conversation by referring
+to both the documentation and the software with the same words.
+
+\1f
+File: texinfo.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page
+
+`@titlefont', `@center', and `@sp'
+----------------------------------
+
+You can use the `@titlefont', `@sp', and `@center' commands to create a
+title page for a printed document. (This is the first of the two
+methods for creating a title page in Texinfo.)
+
+ Use the `@titlefont' command to select a large font suitable for the
+title itself.
+
+ For example:
+
+ @titlefont{Texinfo}
+
+ Use the `@center' command at the beginning of a line to center the
+remaining text on that line. Thus,
+
+ @center @titlefont{Texinfo}
+
+centers the title, which in this example is "Texinfo" printed in the
+title font.
+
+ Use the `@sp' command to insert vertical space. For example:
+
+ @sp 2
+
+This inserts two blank lines on the printed page. (*Note `@sp': sp,
+for more information about the `@sp' command.)
+
+ A template for this method looks like this:
+
+ @titlepage
+ @sp 10
+ @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
+ @sp 2
+ @center SUBTITLE-IF-ANY
+ @sp 2
+ @center AUTHOR
+ ...
+ @end titlepage
+
+ The spacing of the example fits an 8 1/2 by 11 inch manual.
+
+\1f
+File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page
+
+`@title', `@subtitle', and `@author'
+------------------------------------
+
+You can use the `@title', `@subtitle', and `@author' commands to create
+a title page in which the vertical and horizontal spacing is done for
+you automatically. This contrasts with the method described in the
+previous section, in which the `@sp' command is needed to adjust
+vertical spacing.
+
+ Write the `@title', `@subtitle', or `@author' commands at the
+beginning of a line followed by the title, subtitle, or author.
+
+ The `@title' command produces a line in which the title is set flush
+to the left-hand side of the page in a larger than normal font. The
+title is underlined with a black rule.
+
+ The `@subtitle' command sets subtitles in a normal-sized font flush
+to the right-hand side of the page.
+
+ The `@author' command sets the names of the author or authors in a
+middle-sized font flush to the left-hand side of the page on a line
+near the bottom of the title page. The names are underlined with a
+black rule that is thinner than the rule that underlines the title.
+(The black rule only occurs if the `@author' command line is followed
+by an `@page' command line.)
+
+ There are two ways to use the `@author' command: you can write the
+name or names on the remaining part of the line that starts with an
+`@author' command:
+
+ @author by Jane Smith and John Doe
+
+or you can write the names one above each other by using two (or more)
+`@author' commands:
+
+ @author Jane Smith
+ @author John Doe
+
+(Only the bottom name is underlined with a black rule.)
+
+ A template for this method looks like this:
+
+ @titlepage
+ @title NAME-OF-MANUAL-WHEN-PRINTED
+ @subtitle SUBTITLE-IF-ANY
+ @subtitle SECOND-SUBTITLE
+ @author AUTHOR
+ @page
+ ...
+ @end titlepage
+
+Contrast this form with the form of a title page written using the
+`@sp', `@center', and `@titlefont' commands:
+
+ @titlepage
+ @sp 10
+ @center @titlefont{Name of Manual When Printed}
+ @sp 2
+ @center Subtitle, If Any
+ @sp 1
+ @center Second subtitle
+ @sp 2
+ @center Author
+ @page
+ ...
+ @end titlepage
+
+\1f
+File: texinfo.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page
+
+Copyright Page and Permissions
+------------------------------
+
+By international treaty, the copyright notice for a book should be
+either on the title page or on the back of the title page. The
+copyright notice should include the year followed by the name of the
+organization or person who owns the copyright.
+
+ When the copyright notice is on the back of the title page, that page
+is customarily not numbered. Therefore, in Texinfo, the information on
+the copyright page should be within `@titlepage' and `@end titlepage'
+commands.
+
+ Use the `@page' command to cause a page break. To push the copyright
+notice and the other text on the copyright page towards the bottom of
+the page, you can write a somewhat mysterious line after the `@page'
+command that reads like this:
+
+ @vskip 0pt plus 1filll
+
+This is a TeX command that is not supported by the Info formatting
+commands. The `@vskip' command inserts whitespace. The `0pt plus
+1filll' means to put in zero points of mandatory whitespace, and as
+much optional whitespace as needed to push the following text to the
+bottom of the page. Note the use of three `l's in the word `filll';
+this is the correct usage in TeX.
+
+ In a printed manual, the `@copyright{}' command generates a `c'
+inside a circle. (In Info, it generates `(C)'.) The copyright notice
+itself has the following legally defined sequence:
+
+ Copyright (C) YEAR COPYRIGHT-OWNER
+
+ It is customary to put information on how to get a manual after the
+copyright notice, followed by the copying permissions for the manual.
+
+ Note that permissions must be given here as well as in the summary
+segment within `@ifinfo' and `@end ifinfo' that immediately follows the
+header since this text appears only in the printed manual and the
+`ifinfo' text appears only in the Info file.
+
+ *Note Sample Permissions::, for the standard text.
+
+\1f
+File: texinfo.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page
+
+Heading Generation
+------------------
+
+An `@end titlepage' command on a line by itself not only marks the end
+of the title and copyright pages, but also causes TeX to start
+generating page headings and page numbers.
+
+ To repeat what is said elsewhere, Texinfo has two standard page
+heading formats, one for documents which are printed on one side of
+each sheet of paper (single-sided printing), and the other for
+documents which are printed on both sides of each sheet (double-sided
+printing). (*Note `@setchapternewpage': setchapternewpage.) You can
+specify these formats in different ways:
+
+ * The conventional way is to write an `@setchapternewpage' command
+ before the title page commands, and then have the `@end titlepage'
+ command start generating page headings in the manner desired.
+ (*Note `@setchapternewpage': setchapternewpage.)
+
+ * Alternatively, you can use the `@headings' command to prevent page
+ headings from being generated or to start them for either single or
+ double-sided printing. (Write an `@headings' command immediately
+ after the `@end titlepage' command. *Note The `@headings'
+ Command: headings on off, for more information.)
+
+ * Or, you may specify your own page heading and footing format.
+ *Note Page Headings: Headings, for detailed information about page
+ headings and footings.
+
+ Most documents are formatted with the standard single-sided or
+double-sided format, using `@setchapternewpage odd' for double-sided
+printing and no `@setchapternewpage' command for single-sided printing.
+
+\1f
+File: texinfo.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page
+
+The `@headings' Command
+-----------------------
+
+The `@headings' command is rarely used. It specifies what kind of page
+headings and footings to print on each page. Usually, this is
+controlled by the `@setchapternewpage' command. You need the
+`@headings' command only if the `@setchapternewpage' command does not
+do what you want, or if you want to turn off pre-defined page headings
+prior to defining your own. Write an `@headings' command immediately
+after the `@end titlepage' command.
+
+ You can use `@headings' as follows:
+
+`@headings off'
+ Turn off printing of page headings.
+
+`@headings single'
+ Turn on page headings appropriate for single-sided printing.
+
+`@headings double'
+ Turn on page headings appropriate for double-sided printing. The
+ two commands, `@headings on' and `@headings double', are
+ synonymous.
+
+`@headings singleafter'
+`@headings doubleafter'
+ Turn on `single' or `double' headings, respectively, after the
+ current page is output.
+
+`@headings on'
+ Turn on page headings: `single' if `@setchapternewpage on',
+ `double' otherwise.
+
+ For example, suppose you write `@setchapternewpage off' before the
+`@titlepage' command to tell TeX to start a new chapter on the same
+page as the end of the last chapter. This command also causes TeX to
+typeset page headers for single-sided printing. To cause TeX to
+typeset for double sided printing, write `@headings double' after the
+`@end titlepage' command.
+
+ You can stop TeX from generating any page headings at all by writing
+`@headings off' on a line of its own immediately after the line
+containing the `@end titlepage' command, like this:
+
+ @end titlepage
+ @headings off
+
+The `@headings off' command overrides the `@end titlepage' command,
+which would otherwise cause TeX to print page headings.
+
+ You can also specify your own style of page heading and footing.
+*Note Page Headings: Headings, for more information.
+
+\1f
+File: texinfo.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File
+
+The `Top' Node and Master Menu
+==============================
+
+The `Top' node is the node from which you enter an Info file.
+
+ A `Top' node should contain a brief description of the Info file and
+an extensive, master menu for the whole Info file. This helps the
+reader understand what the Info file is about. Also, you should write
+the version number of the program to which the Info file applies; or,
+at least, the edition number.
+
+ The contents of the `Top' node should appear only in the Info file;
+none of it should appear in printed output, so enclose it between
+`@ifinfo' and `@end ifinfo' commands. (TeX does not print either an
+`@node' line or a menu; they appear only in Info; strictly speaking,
+you are not required to enclose these parts between `@ifinfo' and `@end
+ifinfo', but it is simplest to do so. *Note Conditionally Visible
+Text: Conditionals.)
+
+* Menu:
+
+* Title of Top Node:: Sketch what the file is about.
+* Master Menu Parts:: A master menu has three or more parts.
+
+\1f
+File: texinfo.info, Node: Title of Top Node, Next: Master Menu Parts, Prev: The Top Node, Up: The Top Node
+
+`Top' Node Title
+----------------
+
+ Sometimes, you will want to place an `@top' sectioning command line
+containing the title of the document immediately after the `@node Top'
+line (*note The `@top' Sectioning Command: makeinfo top command., for
+more information).
+
+ For example, the beginning of the Top node of this manual contains an
+`@top' sectioning command, a short description, and edition and version
+information. It looks like this:
+
+ ...
+ @end titlepage
+
+ @ifinfo
+ @node Top, Copying, , (dir)
+ @top Texinfo
+
+ Texinfo is a documentation system...
+
+ This is edition...
+ ...
+ @end ifinfo
+
+ @menu
+ * Copying:: Texinfo is freely
+ redistributable.
+ * Overview:: What is Texinfo?
+ ...
+ @end menu
+
+ In a `Top' node, the `Previous', and `Up' nodes usually refer to the
+top level directory of the whole Info system, which is called `(dir)'.
+The `Next' node refers to the first node that follows the main or master
+menu, which is usually the copying permissions, introduction, or first
+chapter.
+
+\1f
+File: texinfo.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node
+
+Parts of a Master Menu
+----------------------
+
+A "master menu" is a detailed main menu listing all the nodes in a file.
+
+ A master menu is enclosed in `@menu' and `@end menu' commands and
+does not appear in the printed document.
+
+ Generally, a master menu is divided into parts.
+
+ * The first part contains the major nodes in the Texinfo file: the
+ nodes for the chapters, chapter-like sections, and the appendices.
+
+ * The second part contains nodes for the indices.
+
+ * The third and subsequent parts contain a listing of the other,
+ lower level nodes, often ordered by chapter. This way, rather
+ than go through an intermediary menu, an inquirer can go directly
+ to a particular node when searching for specific information.
+ These menu items are not required; add them if you think they are a
+ convenience. If you do use them, put `@detailmenu' before the
+ first one, and `@end detailmenu' after the last; otherwise,
+ `makeinfo' will get confused.
+
+ Each section in the menu can be introduced by a descriptive line. So
+long as the line does not begin with an asterisk, it will not be
+treated as a menu entry. (*Note Writing a Menu::, for more
+information.)
+
+ For example, the master menu for this manual looks like the following
+(but has many more entries):
+
+ @menu
+ * Copying:: Texinfo is freely
+ redistributable.
+ * Overview:: What is Texinfo?
+ * Texinfo Mode:: Special features in GNU Emacs.
+ ...
+ ...
+ * Command and Variable Index::
+ An entry for each @-command.
+ * Concept Index:: An entry for each concept.
+
+ @detailmenu
+ --- The Detailed Node Listing ---
+
+ Overview of Texinfo
+
+ * Info Files:: What is an Info file?
+ * Printed Manuals:: Characteristics of
+ a printed manual.
+ ...
+ ...
+
+ Using Texinfo Mode
+
+ * Info on a Region:: Formatting part of a file
+ for Info.
+ ...
+ ...
+ @end detailmenu
+ @end menu
+
+\1f
+File: texinfo.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File
+
+Software Copying Permissions
+============================
+
+If the Texinfo file has a section containing the "General Public
+License" and the distribution information and a warranty disclaimer for
+the software that is documented, this section usually follows the `Top'
+node. The General Public License is very important to Project GNU
+software. It ensures that you and others will continue to have a right
+to use and share the software.
+
+ The copying and distribution information and the disclaimer are
+followed by an introduction or else by the first chapter of the manual.
+
+ Although an introduction is not a required part of a Texinfo file, it
+is very helpful. Ideally, it should state clearly and concisely what
+the file is about and who would be interested in reading it. In
+general, an introduction would follow the licensing and distribution
+information, although sometimes people put it earlier in the document.
+Usually, an introduction is put in an `@unnumbered' section. (*Note
+The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.)
+
+\1f
+File: texinfo.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top
+
+Ending a Texinfo File
+*********************
+
+The end of a Texinfo file should include the commands that create
+indices and generate detailed and summary tables of contents. And it
+must include the `@bye' command that marks the last line processed by
+TeX.
+
+ For example:
+
+ @node Concept Index, , Variables Index, Top
+ @c node-name, next, previous, up
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ @contents
+ @bye
+
+* Menu:
+
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
+
+\1f
+File: texinfo.info, Node: Printing Indices & Menus, Next: Contents, Prev: Ending a File, Up: Ending a File
+
+Index Menus and Printing an Index
+=================================
+
+To print an index means to include it as part of a manual or Info file.
+This does not happen automatically just because you use `@cindex' or
+other index-entry generating commands in the Texinfo file; those just
+cause the raw data for the index to be accumulated. To generate an
+index, you must include the `@printindex' command at the place in the
+document where you want the index to appear. Also, as part of the
+process of creating a printed manual, you must run a program called
+`texindex' (*note Format/Print Hardcopy::) to sort the raw data to
+produce a sorted index file. The sorted index file is what is actually
+used to print the index.
+
+ Texinfo offers six different types of predefined index: the concept
+index, the function index, the variables index, the keystroke index, the
+program index, and the data type index (*note Predefined Indices::).
+Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
+and `tp'. You may merge indices, or put them into separate sections
+(*note Combining Indices::); or you may define your own indices (*note
+Defining New Indices: New Indices.).
+
+ The `@printindex' command takes a two-letter index name, reads the
+corresponding sorted index file and formats it appropriately into an
+index.
+
+ The `@printindex' command does not generate a chapter heading for the
+index. Consequently, you should precede the `@printindex' command with
+a suitable section or chapter command (usually `@unnumbered') to supply
+the chapter heading and put the index into the table of contents.
+Precede the `@unnumbered' command with an `@node' line.
+
+ For example:
+
+ @node Variable Index, Concept Index, Function Index, Top
+ @comment node-name, next, previous, up
+ @unnumbered Variable Index
+
+ @printindex vr
+
+ @node Concept Index, , Variable Index, Top
+ @comment node-name, next, previous, up
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ @summarycontents
+ @contents
+ @bye
+
+(Readers often prefer that the concept index come last in a book, since
+that makes it easiest to find.)
+
+\1f
+File: texinfo.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File
+
+Generating a Table of Contents
+==============================
+
+The `@chapter', `@section', and other structuring commands supply the
+information to make up a table of contents, but they do not cause an
+actual table to appear in the manual. To do this, you must use the
+`@contents' and `@summarycontents' commands:
+
+`@contents'
+ Generate a table of contents in a printed manual, including all
+ chapters, sections, subsections, etc., as well as appendices and
+ unnumbered chapters. (Headings generated by the `@heading' series
+ of commands do not appear in the table of contents.) The
+ `@contents' command should be written on a line by itself.
+
+`@shortcontents'
+`@summarycontents'
+ (`@summarycontents' is a synonym for `@shortcontents'; the two
+ commands are exactly the same.)
+
+ Generate a short or summary table of contents that lists only the
+ chapters (and appendices and unnumbered chapters). Omit sections,
+ subsections and subsubsections. Only a long manual needs a short
+ table of contents in addition to the full table of contents.
+
+ Write the `@shortcontents' command on a line by itself right
+ _before_ the `@contents' command.
+
+ The table of contents commands automatically generate a chapter-like
+heading at the top of the first table of contents page. Write the table
+of contents commands at the very end of a Texinfo file, just before the
+`@bye' command, following any index sections--anything in the Texinfo
+file after the table of contents commands will be omitted from the
+table of contents.
+
+ When you print a manual with a table of contents, the table of
+contents are printed last and numbered with roman numerals. You need
+to place those pages in their proper place, after the title page,
+yourself. (This is the only collating you need to do for a printed
+manual. The table of contents is printed last because it is generated
+after the rest of the manual is typeset.)
+
+ Here is an example of where to write table of contents commands:
+
+ INDICES...
+ @shortcontents
+ @contents
+ @bye
+
+ Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the `@contents' and `@shortcontents'
+commands.
+
+\1f
+File: texinfo.info, Node: File End, Prev: Contents, Up: Ending a File
+
+`@bye' File Ending
+==================
+
+An `@bye' command terminates TeX or Info formatting. None of the
+formatting commands see any of the file following `@bye'. The `@bye'
+command should be on a line by itself.
+
+ If you wish, you may follow the `@bye' line with notes. These notes
+will not be formatted and will not appear in either Info or a printed
+manual; it is as if text after `@bye' were within `@ignore' ... `@end
+ignore'. Also, you may follow the `@bye' line with a local variables
+list. *Note Using Local Variables and the Compile Command:
+Compile-Command, for more information.
+
+\1f
+File: texinfo.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top
+
+Chapter Structuring
+*******************
+
+The "chapter structuring" commands divide a document into a hierarchy of
+chapters, sections, subsections, and subsubsections. These commands
+generate large headings; they also provide information for the table of
+contents of a printed manual (*note Generating a Table of Contents:
+Contents.).
+
+ The chapter structuring commands do not create an Info node structure,
+so normally you should put an `@node' command immediately before each
+chapter structuring command (*note Nodes::). The only time you are
+likely to use the chapter structuring commands without using the node
+structuring commands is if you are writing a document that contains no
+cross references and will never be transformed into Info format.
+
+ It is unlikely that you will ever write a Texinfo file that is
+intended only as an Info file and not as a printable document. If you
+do, you might still use chapter structuring commands to create a
+heading at the top of each node--but you don't need to.
+
+* Menu:
+
+* Tree Structuring:: A manual is like an upside down tree ...
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The `@top' command, part of the `Top' node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
+\1f
+File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Prev: Structuring, Up: Structuring
+
+Tree Structure of Sections
+==========================
+
+A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like. This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
+subsubsections.
+
+ Here is a diagram that shows a Texinfo file with three chapters, each
+of which has two sections.
+
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
+ In a Texinfo file that has this structure, the beginning of Chapter 2
+looks like this:
+
+ @node Chapter 2, Chapter 3, Chapter 1, top
+ @chapter Chapter 2
+
+ The chapter structuring commands are described in the sections that
+follow; the `@node' and `@menu' commands are described in following
+chapters. (*Note Nodes::, and see *Note Menus::.)
+
+\1f
+File: texinfo.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring
+
+Types of Structuring Commands
+=============================
+
+The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
+subsubsections.
+
+ The four groups are the `@chapter' series, the `@unnumbered' series,
+the `@appendix' series, and the `@heading' series.
+
+ Each command produces titles that have a different appearance on the
+printed page or Info file; only some of the commands produce titles
+that are listed in the table of contents of a printed book or manual.
+
+ * The `@chapter' and `@appendix' series of commands produce numbered
+ or lettered entries both in the body of a printed work and in its
+ table of contents.
+
+ * The `@unnumbered' series of commands produce unnumbered entries
+ both in the body of a printed work and in its table of contents.
+ The `@top' command, which has a special use, is a member of this
+ series (*note `@top': makeinfo top.).
+
+ * The `@heading' series of commands produce unnumbered headings that
+ do not appear in a table of contents. The heading commands never
+ start a new page.
+
+ * The `@majorheading' command produces results similar to using the
+ `@chapheading' command but generates a larger vertical whitespace
+ before the heading.
+
+ * When an `@setchapternewpage' command says to do so, the
+ `@chapter', `@unnumbered', and `@appendix' commands start new
+ pages in the printed manual; the `@heading' commands do not.
+
+ Here are the four groups of chapter structuring commands:
+
+
+ No new pages
+ Numbered Unnumbered Lettered and numbered Unnumbered
+ In contents In contents In contents Not in contents
+
+ @top @majorheading
+ @chapter @unnumbered @appendix @chapheading
+ @section @unnumberedsec @appendixsec @heading
+ @subsection @unnumberedsubsec @appendixsubsec @subheading
+ @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
+
+\1f
+File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring
+
+`@top'
+======
+
+The `@top' command is a special sectioning command that you use only
+after an `@node Top' line at the beginning of a Texinfo file. The
+`@top' command tells the `makeinfo' formatter which node is the `Top'
+node. It has the same typesetting effect as `@unnumbered' (*note
+`@unnumbered': (`@appendix')unnumbered & appendix.). For detailed
+information, see *Note The `@top' Command: makeinfo top command.
+
+\1f
+File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring
+
+`@chapter'
+==========
+
+`@chapter' identifies a chapter in the document. Write the command at
+the beginning of a line and follow it on the same line by the title of
+the chapter.
+
+ For example, this chapter in this manual is entitled "Chapter
+Structuring"; the `@chapter' line looks like this:
+
+ @chapter Chapter Structuring
+
+ In TeX, the `@chapter' command creates a chapter in the document,
+specifying the chapter title. The chapter is numbered automatically.
+
+ In Info, the `@chapter' command causes the title to appear on a line
+by itself, with a line of asterisks inserted underneath. Thus, in
+Info, the above example produces the following output:
+
+ Chapter Structuring
+ *******************
+
+ Texinfo also provides a command `@centerchap', which is analogous to
+`@unnumbered', but centers its argument in the printed output. This
+kind of stylistic choice is not usually offered by Texinfo.
+
+\1f
+File: texinfo.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring
+
+`@unnumbered', `@appendix'
+==========================
+
+Use the `@unnumbered' command to create a chapter that appears in a
+printed manual without chapter numbers of any kind. Use the
+`@appendix' command to create an appendix in a printed manual that is
+labelled by letter instead of by number.
+
+ For Info file output, the `@unnumbered' and `@appendix' commands are
+equivalent to `@chapter': the title is printed on a line by itself with
+a line of asterisks underneath. (*Note `@chapter': chapter.)
+
+ To create an appendix or an unnumbered chapter, write an `@appendix'
+or `@unnumbered' command at the beginning of a line and follow it on
+the same line by the title, as you would if you were creating a chapter.
+
+\1f
+File: texinfo.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring
+
+`@majorheading', `@chapheading'
+===============================
+
+The `@majorheading' and `@chapheading' commands put chapter-like
+headings in the body of a document.
+
+ However, neither command causes TeX to produce a numbered heading or
+an entry in the table of contents; and neither command causes TeX to
+start a new page in a printed manual.
+
+ In TeX, an `@majorheading' command generates a larger vertical
+whitespace before the heading than an `@chapheading' command but is
+otherwise the same.
+
+ In Info, the `@majorheading' and `@chapheading' commands are
+equivalent to `@chapter': the title is printed on a line by itself with
+a line of asterisks underneath. (*Note `@chapter': chapter.)
+
+\1f
+File: texinfo.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring
+
+`@section'
+==========
+
+In a printed manual, an `@section' command identifies a numbered
+section within a chapter. The section title appears in the table of
+contents. In Info, an `@section' command provides a title for a
+segment of text, underlined with `='.
+
+ This section is headed with an `@section' command and looks like this
+in the Texinfo file:
+
+ @section @code{@@section}
+
+ To create a section, write the `@section' command at the beginning of
+a line and follow it on the same line by the section title.
+
+ Thus,
+
+ @section This is a section
+
+produces
+
+ This is a section
+ =================
+
+in Info.
+
+\1f
+File: texinfo.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring
+
+`@unnumberedsec', `@appendixsec', `@heading'
+============================================
+
+The `@unnumberedsec', `@appendixsec', and `@heading' commands are,
+respectively, the unnumbered, appendix-like, and heading-like
+equivalents of the `@section' command. (*Note `@section': section.)
+
+`@unnumberedsec'
+ The `@unnumberedsec' command may be used within an unnumbered
+ chapter or within a regular chapter or appendix to provide an
+ unnumbered section.
+
+`@appendixsec'
+`@appendixsection'
+ `@appendixsection' is a longer spelling of the `@appendixsec'
+ command; the two are synonymous.
+
+ Conventionally, the `@appendixsec' or `@appendixsection' command
+ is used only within appendices.
+
+`@heading'
+ You may use the `@heading' command anywhere you wish for a
+ section-style heading that will not appear in the table of
+ contents.
+
+\1f
+File: texinfo.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring
+
+The `@subsection' Command
+=========================
+
+Subsections are to sections as sections are to chapters. (*Note
+`@section': section.) In Info, subsection titles are underlined with
+`-'. For example,
+
+ @subsection This is a subsection
+
+produces
+
+ This is a subsection
+ --------------------
+
+ In a printed manual, subsections are listed in the table of contents
+and are numbered three levels deep.
+
+\1f
+File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring
+
+The `@subsection'-like Commands
+===============================
+
+The `@unnumberedsubsec', `@appendixsubsec', and `@subheading' commands
+are, respectively, the unnumbered, appendix-like, and heading-like
+equivalents of the `@subsection' command. (*Note `@subsection':
+subsection.)
+
+ In Info, the `@subsection'-like commands generate a title underlined
+with hyphens. In a printed manual, an `@subheading' command produces a
+heading like that of a subsection except that it is not numbered and
+does not appear in the table of contents. Similarly, an
+`@unnumberedsubsec' command produces an unnumbered heading like that of
+a subsection and an `@appendixsubsec' command produces a
+subsection-like heading labelled with a letter and numbers; both of
+these commands produce headings that appear in the table of contents.
+
+\1f
+File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring
+
+The `subsub' Commands
+=====================
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:
+
+`@subsubsection'
+ Subsubsections are to subsections as subsections are to sections.
+ (*Note `@subsection': subsection.) In a printed manual,
+ subsubsection titles appear in the table of contents and are
+ numbered four levels deep.
+
+`@unnumberedsubsubsec'
+ Unnumbered subsubsection titles appear in the table of contents of
+ a printed manual, but lack numbers. Otherwise, unnumbered
+ subsubsections are the same as subsubsections. In Info, unnumbered
+ subsubsections look exactly like ordinary subsubsections.
+
+`@appendixsubsubsec'
+ Conventionally, appendix commands are used only for appendices and
+ are lettered and numbered appropriately in a printed manual. They
+ also appear in the table of contents. In Info, appendix
+ subsubsections look exactly like ordinary subsubsections.
+
+`@subsubheading'
+ The `@subsubheading' command may be used anywhere that you need a
+ small heading that will not appear in the table of contents. In
+ Info, subsubheadings look exactly like ordinary subsubsection
+ headings.
+
+ In Info, `subsub' titles are underlined with periods. For example,
+
+ @subsubsection This is a subsubsection
+
+produces
+
+ This is a subsubsection
+ .......................
+
+\1f
+File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring
+
+`@raisesections' and `@lowersections'
+=====================================
+
+The `@raisesections' and `@lowersections' commands raise and lower the
+hierarchical level of chapters, sections, subsections and the like.
+The `@raisesections' command changes sections to chapters, subsections
+to sections, and so on. The `@lowersections' command changes chapters
+to sections, sections to subsections, and so on.
+
+ An `@lowersections' command is useful if you wish to include text
+that is written as an outer or standalone Texinfo file in another
+Texinfo file as an inner, included file. If you write the command at
+the beginning of the file, all your `@chapter' commands are formatted
+as if they were `@section' commands, all your `@section' command are
+formatted as if they were `@subsection' commands, and so on.
+
+ `@raisesections' raises a command one level in the chapter
+structuring hierarchy:
+
+ Change To
+
+ @subsection @section,
+ @section @chapter,
+ @heading @chapheading,
+ etc.
+
+ `@lowersections' lowers a command one level in the chapter
+structuring hierarchy:
+
+ Change To
+
+ @chapter @section,
+ @subsection @subsubsection,
+ @heading @subheading,
+ etc.
+
+ An `@raisesections' or `@lowersections' command changes only those
+structuring commands that follow the command in the Texinfo file.
+Write an `@raisesections' or `@lowersections' command on a line of its
+own.
+
+ An `@lowersections' command cancels an `@raisesections' command, and
+vice versa. Typically, the commands are used like this:
+
+ @lowersections
+ @include somefile.texi
+ @raisesections
+
+ Without the `@raisesections', all the subsequent sections in your
+document will be lowered.
+
+ Repeated use of the commands continue to raise or lower the
+hierarchical level a step at a time.
+
+ An attempt to raise above `chapters' reproduces chapter commands; an
+attempt to lower below `subsubsections' reproduces subsubsection
+commands.
+
+\1f
+File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top
+
+Nodes
+*****
+
+"Nodes" are the primary segments of a Texinfo file. They do not
+themselves impose a hierarchic or any other kind of structure on a file.
+Nodes contain "node pointers" that name other nodes, and can contain
+"menus" which are lists of nodes. In Info, the movement commands can
+carry you to a pointed-to node or to a node listed in a menu. Node
+pointers and menus provide structure for Info files just as chapters,
+sections, subsections, and the like, provide structure for printed
+books.
+
+* Menu:
+
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: How to write a node, in detail.
+* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
+
+\1f
+File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Prev: Nodes, Up: Nodes
+
+Two Paths
+=========
+
+ The node and menu commands and the chapter structuring commands are
+independent of each other:
+
+ * In Info, node and menu commands provide structure. The chapter
+ structuring commands generate headings with different kinds of
+ underlining--asterisks for chapters, hyphens for sections, and so
+ on; they do nothing else.
+
+ * In TeX, the chapter structuring commands generate chapter and
+ section numbers and tables of contents. The node and menu
+ commands provide information for cross references; they do nothing
+ else.
+
+ You can use node pointers and menus to structure an Info file any way
+you want; and you can write a Texinfo file so that its Info output has a
+different structure than its printed output. However, most Texinfo
+files are written such that the structure for the Info output
+corresponds to the structure for the printed output. It is not
+convenient to do otherwise.
+
+ Generally, printed output is structured in a tree-like hierarchy in
+which the chapters are the major limbs from which the sections branch
+out. Similarly, node pointers and menus are organized to create a
+matching structure in the Info output.
+
+\1f
+File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes
+
+Node and Menu Illustration
+==========================
+
+Here is a copy of the diagram shown earlier that illustrates a Texinfo
+file with three chapters, each of which contains two sections.
+
+ Note that the "root" is at the top of the diagram and the "leaves"
+are at the bottom. This is how such a diagram is drawn conventionally;
+it illustrates an upside-down tree. For this reason, the root node is
+called the `Top' node, and `Up' node pointers carry you closer to the
+root.
+
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
+ Write the beginning of the node for Chapter 2 like this:
+
+ @node Chapter 2, Chapter 3, Chapter 1, top
+ @comment node-name, next, previous, up
+
+This `@node' line says that the name of this node is "Chapter 2", the
+name of the `Next' node is "Chapter 3", the name of the `Previous' node
+is "Chapter 1", and the name of the `Up' node is "Top".
+
+ *Please Note:* `Next' refers to the next node at the same
+ hierarchical level in the manual, not necessarily to the next node
+ within the Texinfo file. In the Texinfo file, the subsequent node
+ may be at a lower level--a section-level node may follow a
+ chapter-level node, and a subsection-level node may follow a
+ section-level node. `Next' and `Previous' refer to nodes at the
+ _same_ hierarchical level. (The `Top' node contains the exception
+ to this rule. Since the `Top' node is the only node at that
+ level, `Next' refers to the first following node, which is almost
+ always a chapter or chapter-level node.)
+
+ To go to Sections 2.1 and 2.2 using Info, you need a menu inside
+Chapter 2. (*Note Menus::.) You would write the menu just before the
+beginning of Section 2.1, like this:
+
+ @menu
+ * Sect. 2.1:: Description of this section.
+ * Sect. 2.2::
+ @end menu
+
+ Write the node for Sect. 2.1 like this:
+
+ @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+ @comment node-name, next, previous, up
+
+ In Info format, the `Next' and `Previous' pointers of a node usually
+lead to other nodes at the same level--from chapter to chapter or from
+section to section (sometimes, as shown, the `Previous' pointer points
+up); an `Up' pointer usually leads to a node at the level above (closer
+to the `Top' node); and a `Menu' leads to nodes at a level below (closer
+to `leaves'). (A cross reference can point to a node at any level; see
+*Note Cross References::.)
+
+ Usually, an `@node' command and a chapter structuring command are
+used in sequence, along with indexing commands. (You may follow the
+`@node' line with a comment line that reminds you which pointer is
+which.)
+
+ Here is the beginning of the chapter in this manual called "Ending a
+Texinfo File". This shows an `@node' line followed by a comment line,
+an `@chapter' line, and then by indexing lines.
+
+ @node Ending a File, Structuring, Beginning a File, Top
+ @comment node-name, next, previous, up
+ @chapter Ending a Texinfo File
+ @cindex Ending a Texinfo file
+ @cindex Texinfo file ending
+ @cindex File ending
+
+\1f
+File: texinfo.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes
+
+The `@node' Command
+===================
+
+A "node" is a segment of text that begins at an `@node' command and
+continues until the next `@node' command. The definition of node is
+different from that for chapter or section. A chapter may contain
+sections and a section may contain subsections; but a node cannot
+contain subnodes; the text of a node continues only until the next
+`@node' command in the file. A node usually contains only one chapter
+structuring command, the one that follows the `@node' line. On the
+other hand, in printed output nodes are used only for cross references,
+so a chapter or section may contain any number of nodes. Indeed, a
+chapter usually contains several nodes, one for each section,
+subsection, and subsubsection.
+
+ To create a node, write an `@node' command at the beginning of a
+line, and follow it with four arguments, separated by commas, on the
+rest of the same line. These arguments are the name of the node, and
+the names of the `Next', `Previous', and `Up' pointers, in that order.
+You may insert spaces before each pointer if you wish; the spaces are
+ignored. You must write the name of the node, and the names of the
+`Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
+the formatters fail. (*note info: (info)Top, for more information
+about nodes in Info.)
+
+ Usually, you write one of the chapter-structuring command lines
+immediately after an `@node' line--for example, an `@section' or
+`@subsection' line. (*Note Types of Structuring Commands: Structuring
+Command Types.)
+
+ *Please note:* The GNU Emacs Texinfo mode updating commands work
+ only with Texinfo files in which `@node' lines are followed by
+ chapter structuring lines. *Note Updating Requirements::.
+
+ TeX uses `@node' lines to identify the names to use for cross
+references. For this reason, you must write `@node' lines in a Texinfo
+file that you intend to format for printing, even if you do not intend
+to format it for Info. (Cross references, such as the one at the end
+of this sentence, are made with `@xref' and its related commands; see
+*Note Cross References::.)
+
+* Menu:
+
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an `@node' line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the `@top' command.
+* Top Node Summary:: Write a brief description for readers.
+
+\1f
+File: texinfo.info, Node: Node Names, Next: Writing a Node, Prev: node, Up: node
+
+Choosing Node and Pointer Names
+-------------------------------
+
+ The name of a node identifies the node. The pointers enable you to
+reach other nodes and consist of the names of those nodes.
+
+ Normally, a node's `Up' pointer contains the name of the node whose
+menu mentions that node. The node's `Next' pointer contains the name
+of the node that follows that node in that menu and its `Previous'
+pointer contains the name of the node that precedes it in that menu.
+When a node's `Previous' node is the same as its `Up' node, both node
+pointers name the same node.
+
+ Usually, the first node of a Texinfo file is the `Top' node, and its
+`Up' and `Previous' pointers point to the `dir' file, which contains
+the main menu for all of Info.
+
+ The `Top' node itself contains the main or master menu for the manual.
+Also, it is helpful to include a brief description of the manual in the
+`Top' node. *Note First Node::, for information on how to write the
+first node of a Texinfo file.
+
+\1f
+File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node
+
+How to Write an `@node' Line
+----------------------------
+
+The easiest way to write an `@node' line is to write `@node' at the
+beginning of a line and then the name of the node, like this:
+
+ @node NODE-NAME
+
+ If you are using GNU Emacs, you can use the update node commands
+provided by Texinfo mode to insert the names of the pointers; or you
+can leave the pointers out of the Texinfo file and let `makeinfo'
+insert node pointers into the Info file it creates. (*Note Texinfo
+Mode::, and *Note makeinfo Pointer Creation::.)
+
+ Alternatively, you can insert the `Next', `Previous', and `Up'
+pointers yourself. If you do this, you may find it helpful to use the
+Texinfo mode keyboard command `C-c C-c n'. This command inserts
+`@node' and a comment line listing the names of the pointers in their
+proper order. The comment line helps you keep track of which arguments
+are for which pointers. This comment line is especially useful if you
+are not familiar with Texinfo.
+
+ The template for a node line with `Next', `Previous', and `Up'
+pointers looks like this:
+
+ @node NODE-NAME, NEXT, PREVIOUS, UP
+
+ If you wish, you can ignore `@node' lines altogether in your first
+draft and then use the `texinfo-insert-node-lines' command to create
+`@node' lines for you. However, we do not recommend this practice. It
+is better to name the node itself at the same time that you write a
+segment so you can easily make cross references. A large number of
+cross references are an especially important feature of a good Info
+file.
+
+ After you have inserted an `@node' line, you should immediately write
+an @-command for the chapter or section and insert its name. Next (and
+this is important!), put in several index entries. Usually, you will
+find at least two and often as many as four or five ways of referring
+to the node in the index. Use them all. This will make it much easier
+for people to find the node.
+
+\1f
+File: texinfo.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node
+
+`@node' Line Tips
+-----------------
+
+Here are three suggestions:
+
+ * Try to pick node names that are informative but short.
+
+ In the Info file, the file name, node name, and pointer names are
+ all inserted on one line, which may run into the right edge of the
+ window. (This does not cause a problem with Info, but is ugly.)
+
+ * Try to pick node names that differ from each other near the
+ beginnings of their names. This way, it is easy to use automatic
+ name completion in Info.
+
+ * By convention, node names are capitalized just as they would be for
+ section or chapter titles--initial and significant words are
+ capitalized; others are not.
+
+\1f
+File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node
+
+`@node' Line Requirements
+-------------------------
+
+Here are several requirements for `@node' lines:
+
+ * All the node names for a single Info file must be unique.
+
+ Duplicates confuse the Info movement commands. This means, for
+ example, that if you end every chapter with a summary, you must
+ name each summary node differently. You cannot just call each one
+ "Summary". You may, however, duplicate the titles of chapters,
+ sections, and the like. Thus you can end each chapter in a book
+ with a section called "Summary", so long as the node names for
+ those sections are all different.
+
+ * A pointer name must be the name of a node.
+
+ The node to which a pointer points may come before or after the
+ node containing the pointer.
+
+ * You cannot use any of the Texinfo @-commands in a node name;
+ @-commands confuse Info.
+
+ Thus, the beginning of the section called `@chapter' looks like
+ this:
+
+ @node chapter, unnumbered & appendix, makeinfo top, Structuring
+ @comment node-name, next, previous, up
+ @section @code{@@chapter}
+ @findex chapter
+
+ * You cannot use commas or apostrophes within a node name; these
+ confuse TeX or the Info formatters.
+
+ For example, the following is a section title:
+
+ @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
+
+ The corresponding node name is:
+
+ unnumberedsec appendixsec heading
+
+ * Case is significant.
+
+\1f
+File: texinfo.info, Node: First Node, Next: makeinfo top command, Prev: Node Line Requirements, Up: node
+
+The First Node
+--------------
+
+The first node of a Texinfo file is the "Top" node, except in an
+included file (*note Include Files::). The Top node contains the main
+or master menu for the document, and a short summary of the document
+(*note Top Node Summary::).
+
+ The Top node (which must be named `top' or `Top') should have as its
+`Up' node the name of a node in another file, where there is a menu
+that leads to this file. Specify the file name in parentheses. If the
+file is to be installed directly in the Info directory file, use
+`(dir)' as the parent of the Top node; this is short for `(dir)top',
+and specifies the Top node in the `dir' file, which contains the main
+menu for the Info system as a whole. For example, the `@node Top' line
+of this manual looks like this:
+
+ @node Top, Copying, , (dir)
+
+(You can use the Texinfo updating commands or the `makeinfo' utility to
+insert these pointers automatically.)
+
+ Do not define the `Previous' node of the Top node to be `(dir)', as
+it causes confusing behavior for users: if you are in the Top node and
+hit <DEL> to go backwards, you wind up in the middle of some other
+entry in the `dir' file, which has nothing to do with what you were
+reading.
+
+ *Note Install an Info File::, for more information about installing
+an Info file in the `info' directory.
+
+\1f
+File: texinfo.info, Node: makeinfo top command, Next: Top Node Summary, Prev: First Node, Up: node
+
+The `@top' Sectioning Command
+-----------------------------
+
+A special sectioning command, `@top', has been created for use with the
+`@node Top' line. The `@top' sectioning command tells `makeinfo' that
+it marks the `Top' node in the file. It provides the information that
+`makeinfo' needs to insert node pointers automatically. Write the
+`@top' command at the beginning of the line immediately following the
+`@node Top' line. Write the title on the remaining part of the same
+line as the `@top' command.
+
+ In Info, the `@top' sectioning command causes the title to appear on a
+line by itself, with a line of asterisks inserted underneath.
+
+ In TeX and `texinfo-format-buffer', the `@top' sectioning command is
+merely a synonym for `@unnumbered'. Neither of these formatters
+require an `@top' command, and do nothing special with it. You can use
+`@chapter' or `@unnumbered' after the `@node Top' line when you use
+these formatters. Also, you can use `@chapter' or `@unnumbered' when
+you use the Texinfo updating commands to create or update pointers and
+menus.
+
+\1f
+File: texinfo.info, Node: Top Node Summary, Prev: makeinfo top command, Up: node
+
+The `Top' Node Summary
+----------------------
+
+You can help readers by writing a summary in the `Top' node, after the
+`@top' line, before the main or master menu. The summary should
+briefly describe the document. In Info, this summary will appear just
+before the master menu. In a printed manual, this summary will appear
+on a page of its own.
+
+ If you do not want the summary to appear on a page of its own in a
+printed manual, you can enclose the whole of the `Top' node, including
+the `@node Top' line and the `@top' sectioning command line or other
+sectioning command line between `@ifinfo' and `@end ifinfo'. This
+prevents any of the text from appearing in the printed output. (*note
+Conditionally Visible Text: Conditionals.). You can repeat the brief
+description from the `Top' node within `@iftex' ... `@end iftex' at the
+beginning of the first chapter, for those who read the printed manual.
+This saves paper and may look neater.
+
+ You should write the version number of the program to which the manual
+applies in the summary. This helps the reader keep track of which
+manual is for which version of the program. If the manual changes more
+frequently than the program or is independent of it, you should also
+include an edition number for the manual. (The title page should also
+contain this information: see *Note `@titlepage': titlepage.)
+
+\1f
+File: texinfo.info, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes
+
+Creating Pointers with `makeinfo'
+=================================
+
+The `makeinfo' program has a feature for automatically creating node
+pointers for a hierarchically organized file that lacks them.
+
+ When you take advantage of this feature, you do not need to write the
+`Next', `Previous', and `Up' pointers after the name of a node.
+However, you must write a sectioning command, such as `@chapter' or
+`@section', on the line immediately following each truncated `@node'
+line. You cannot write a comment line after a node line; the section
+line must follow it immediately.
+
+ In addition, you must follow the `Top' `@node' line with a line
+beginning with `@top' to mark the `Top' node in the file. *Note `@top':
+makeinfo top.
+
+ Finally, you must write the name of each node (except for the `Top'
+node) in a menu that is one or more hierarchical levels above the
+node's hierarchical level.
+
+ This node pointer insertion feature in `makeinfo' is an alternative
+to the menu and pointer creation and update commands in Texinfo mode.
+(*Note Updating Nodes and Menus::.) It is especially helpful to people
+who do not use GNU Emacs for writing Texinfo documents.
+
+\1f
+File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top
+
+Menus
+*****
+
+"Menus" contain pointers to subordinate nodes.(1) (*note
+Menus-Footnote-1::) In Info, you use menus to go to such nodes. Menus
+have no effect in printed manuals and do not appear in them.
+
+ By convention, a menu is put at the end of a node since a reader who
+uses the menu may not see text that follows it.
+
+ A node that has a menu should _not_ contain much text. If you have a
+lot of text and a menu, move most of the text into a new subnode--all
+but a few lines.
+
+* Menu:
+
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
+
+\1f
+File: texinfo.info, Node: Menus-Footnotes, Up: Menus
+
+ (1) Menus can carry you to any node, regardless of the hierarchical
+structure; even to nodes in a different Info file. However, the GNU
+Emacs Texinfo mode updating commands work only to create menus of
+subordinate nodes. Conventionally, cross references are used to refer
+to other nodes.
+
+\1f
+File: texinfo.info, Node: Menu Location, Next: Writing a Menu, Prev: Menus, Up: Menus
+
+Menus Need Short Nodes
+======================
+
+ A reader can easily see a menu that is close to the beginning of the
+node. The node should be short. As a practical matter, you should
+locate a menu within 20 lines of the beginning of the node. Otherwise,
+a reader with a terminal that displays only a few lines may miss the
+menu and its associated text.
+
+ The short text before a menu may look awkward in a printed manual. To
+avoid this, you can write a menu near the beginning of its node and
+follow the menu by an `@node' line, and then an `@heading' line located
+within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line,
+and title appear only in the Info file, not the printed document.
+
+ For example, the preceding two paragraphs follow an Info-only menu,
+`@node' line, and heading, and look like this:
+
+ @menu
+ * Menu Location:: Put a menu in a short node.
+ * Writing a Menu:: What is a menu?
+ * Menu Parts:: A menu entry has three parts.
+ * Less Cluttered Menu Entry:: Two part menu entry.
+ * Menu Example:: Two and three part entries.
+ * Other Info Files:: How to refer to a different
+ Info file.
+ @end menu
+
+ @node Menu Location, Writing a Menu, , Menus
+ @ifinfo
+ @heading Menus Need Short Nodes
+ @end ifinfo
+
+ The Texinfo file for this document contains more than a dozen
+examples of this procedure. One is at the beginning of this chapter;
+another is at the beginning of the "Cross References" chapter.
+
+\1f
+File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus
+
+Writing a Menu
+==============
+
+A menu consists of an `@menu' command on a line by itself followed by
+menu entry lines or menu comment lines and then by an `@end menu'
+command on a line by itself.
+
+ A menu looks like this:
+
+ @menu
+ Larger Units of Text
+
+ * Files:: All about handling files.
+ * Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+ @end menu
+
+ In a menu, every line that begins with an `* ' is a "menu entry".
+(Note the space after the asterisk.) A line that does not start with
+an `* ' may also appear in a menu. Such a line is not a menu entry but
+is a menu comment line that appears in the Info file. In the example
+above, the line `Larger Units of Text' is a menu comment line; the two
+lines starting with `* ' are menu entries.
+
+\1f
+File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus
+
+The Parts of a Menu
+===================
+
+A menu entry has three parts, only the second of which is required:
+
+ 1. The menu entry name (optional).
+
+ 2. The name of the node (required).
+
+ 3. A description of the item (optional).
+
+ The template for a menu entry looks like this:
+
+ * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION
+
+ Follow the menu entry name with a single colon and follow the node
+name with tab, comma, period, or newline.
+
+ In Info, a user selects a node with the `m' (`Info-menu') command.
+The menu entry name is what the user types after the `m' command.
+
+ The third part of a menu entry is a descriptive phrase or sentence.
+Menu entry names and node names are often short; the description
+explains to the reader what the node is about. A useful description
+complements the node name rather than repeats it. The description,
+which is optional, can spread over two or more lines; if it does, some
+authors prefer to indent the second line while others prefer to align it
+with the first (and all others). It's up to you.
+
+\1f
+File: texinfo.info, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: Menu Parts, Up: Menus
+
+Less Cluttered Menu Entry
+=========================
+
+When the menu entry name and node name are the same, you can write the
+name immediately after the asterisk and space at the beginning of the
+line and follow the name with two colons.
+
+ For example, write
+
+ * Name:: DESCRIPTION
+
+instead of
+
+ * Name: Name. DESCRIPTION
+
+ You should use the node name for the menu entry name whenever
+possible, since it reduces visual clutter in the menu.
+
+\1f
+File: texinfo.info, Node: Menu Example, Next: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus
+
+A Menu Example
+==============
+
+A menu looks like this in Texinfo:
+
+ @menu
+ * menu entry name: Node name. A short description.
+ * Node name:: This form is preferred.
+ @end menu
+
+This produces:
+
+ * menu:
+
+ * menu entry name: Node name. A short description.
+ * Node name:: This form is preferred.
+
+ Here is an example as you might see it in a Texinfo file:
+
+ @menu
+ Larger Units of Text
+
+ * Files:: All about handling files.
+ * Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+ @end menu
+
+This produces:
+
+ * menu:
+ Larger Units of Text
+
+ * Files:: All about handling files.
+ * Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+
+ In this example, the menu has two entries. `Files' is both a menu
+entry name and the name of the node referred to by that name.
+`Multiples' is the menu entry name; it refers to the node named
+`Buffers'. The line `Larger Units of Text' is a comment; it appears in
+the menu, but is not an entry.
+
+ Since no file name is specified with either `Files' or `Buffers',
+they must be the names of nodes in the same Info file (*note Referring
+to Other Info Files: Other Info Files.).
+
+\1f
+File: texinfo.info, Node: Other Info Files, Prev: Menu Example, Up: Menus
+
+Referring to Other Info Files
+=============================
+
+You can create a menu entry that enables a reader in Info to go to a
+node in another Info file by writing the file name in parentheses just
+before the node name. In this case, you should use the three-part menu
+entry format, which saves the reader from having to type the file name.
+
+ The format looks like this:
+
+ @menu
+ * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION
+ * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION
+ @end menu
+
+ For example, to refer directly to the `Outlining' and `Rebinding'
+nodes in the `XEmacs User's Manual', you would write a menu like this:
+
+ @menu
+ * Outlining: (xemacs)Outline Mode. The major mode for
+ editing outlines.
+ * Rebinding: (xemacs)Rebinding. How to redefine the
+ meaning of a key.
+ @end menu
+
+ If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' node.
+
+ The `dir' file that contains the main menu for Info has menu entries
+that list only file names. These take you directly to the `Top' nodes
+of each Info document. (*Note Install an Info File::.)
+
+ For example:
+
+ * Info: (info). Documentation browsing system.
+ * Emacs: (emacs). The extensible, self-documenting
+ text editor.
+
+(The `dir' top level directory for the Info system is an Info file, not
+a Texinfo file, but a menu entry looks the same in both types of file.)
+
+ Note that the GNU Emacs Texinfo mode menu updating commands only work
+with nodes within the current buffer, so you cannot use them to create
+menus that refer to other files. You must write such menus by hand.
+
+\1f
+File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top
+
+Cross References
+****************
+
+"Cross references" are used to refer the reader to other parts of the
+same or different Texinfo files. In Texinfo, nodes are the places to
+which cross references can refer.
+
+* Menu:
+
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* xref:: Begin a reference with `See' ...
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
+
+\1f
+File: texinfo.info, Node: References, Next: Cross Reference Commands, Prev: Cross References, Up: Cross References
+
+What References Are For
+=======================
+
+ Often, but not always, a printed document should be designed so that
+it can be read sequentially. People tire of flipping back and forth to
+find information that should be presented to them as they need it.
+
+ However, in any document, some information will be too detailed for
+the current context, or incidental to it; use cross references to
+provide access to such information. Also, an on-line help system or a
+reference manual is not like a novel; few read such documents in
+sequence from beginning to end. Instead, people look up what they
+need. For this reason, such creations should contain many cross
+references to help readers find other information that they may not
+have read.
+
+ In a printed manual, a cross reference results in a page reference,
+unless it is to another manual altogether, in which case the cross
+reference names that manual.
+
+ In Info, a cross reference results in an entry that you can follow
+using the Info `f' command. (*note Some advanced Info commands:
+(info)Help-Adv.)
+
+ The various cross reference commands use nodes to define cross
+reference locations. This is evident in Info, in which a cross
+reference takes you to the specified node. TeX also uses nodes to
+define cross reference locations, but the action is less obvious. When
+TeX generates a DVI file, it records nodes' page numbers and uses the
+page numbers in making references. Thus, if you are writing a manual
+that will only be printed, and will not be used on-line, you must
+nonetheless write `@node' lines to name the places to which you make
+cross references.
+
+\1f
+File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References
+
+Different Cross Reference Commands
+==================================
+
+There are four different cross reference commands:
+
+`@xref'
+ Used to start a sentence in the printed manual saying `See ...'
+ or an Info cross-reference saying `*Note NAME: NODE.'.
+
+`@ref'
+ Used within or, more often, at the end of a sentence; same as
+ `@xref' for Info; produces just the reference in the printed
+ manual without a preceding `See'.
+
+`@pxref'
+ Used within parentheses to make a reference that suits both an Info
+ file and a printed book. Starts with a lower case `see' within the
+ printed manual. (`p' is for `parenthesis'.)
+
+`@inforef'
+ Used to make a reference to an Info file for which there is no
+ printed manual.
+
+(The `@cite' command is used to make references to books and manuals
+for which there is no corresponding Info file and, therefore, no node
+to which to point. *Note `@cite': cite.)
+
+\1f
+File: texinfo.info, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References
+
+Parts of a Cross Reference
+==========================
+
+A cross reference command requires only one argument, which is the name
+of the node to which it refers. But a cross reference command may
+contain up to four additional arguments. By using these arguments, you
+can provide a cross reference name for Info, a topic description or
+section title for the printed output, the name of a different Info
+file, and the name of a different printed manual.
+
+ Here is a simple cross reference example:
+
+ @xref{Node name}.
+
+which produces
+
+ *Note Node name::.
+
+and
+
+ See Section NNN [Node name], page PPP.
+
+ Here is an example of a full five-part cross reference:
+
+ @xref{Node name, Cross Reference Name, Particular Topic,
+ info-file-name, A Printed Manual}, for details.
+
+which produces
+
+ *Note Cross Reference Name: (info-file-name)Node name,
+ for details.
+
+in Info and
+
+ See section "Particular Topic" in A Printed Manual, for details.
+
+in a printed book.
+
+ The five possible arguments for a cross reference are:
+
+ 1. The node name (required). This is the node to which the cross
+ reference takes you. In a printed document, the location of the
+ node provides the page reference only for references within the
+ same document.
+
+ 2. The cross reference name for the Info reference, if it is to be
+ different from the node name. If you include this argument, it
+ becomes the first part of the cross reference. It is usually
+ omitted.
+
+ 3. A topic description or section name. Often, this is the title of
+ the section. This is used as the name of the reference in the
+ printed manual. If omitted, the node name is used.
+
+ 4. The name of the Info file in which the reference is located, if it
+ is different from the current file. You need not include any
+ `.info' suffix on the file name, since Info readers try appending
+ it automatically.
+
+ 5. The name of a printed manual from a different Texinfo file.
+
+ The template for a full five argument cross reference looks like this:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
+ INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
+
+ Cross references with one, two, three, four, and five arguments are
+described separately following the description of `@xref'.
+
+ Write a node name in a cross reference in exactly the same way as in
+the `@node' line, including the same capitalization; otherwise, the
+formatters may not find the reference.
+
+ You can write cross reference commands within a paragraph, but note
+how Info and TeX format the output of each of the various commands:
+write `@xref' at the beginning of a sentence; write `@pxref' only
+within parentheses, and so on.
+
+\1f
+File: texinfo.info, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References
+
+`@xref'
+=======
+
+The `@xref' command generates a cross reference for the beginning of a
+sentence. The Info formatting commands convert it into an Info cross
+reference, which the Info `f' command can use to bring you directly to
+another node. The TeX typesetting commands convert it into a page
+reference, or a reference to another book or manual.
+
+* Menu:
+
+* Reference Syntax:: What a reference looks like and requires.
+* One Argument:: `@xref' with one argument.
+* Two Arguments:: `@xref' with two arguments.
+* Three Arguments:: `@xref' with three arguments.
+* Four and Five Arguments:: `@xref' with four and five arguments.
+
+\1f
+File: texinfo.info, Node: Reference Syntax, Next: One Argument, Prev: xref, Up: xref
+
+What a Reference Looks Like and Requires
+----------------------------------------
+
+ Most often, an Info cross reference looks like this:
+
+ *Note NODE-NAME::.
+
+or like this
+
+ *Note CROSS-REFERENCE-NAME: NODE-NAME.
+
+In TeX, a cross reference looks like this:
+
+ See Section SECTION-NUMBER [NODE-NAME], page PAGE.
+
+or like this
+
+ See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE.
+
+ The `@xref' command does not generate a period or comma to end the
+cross reference in either the Info file or the printed output. You
+must write that period or comma yourself; otherwise, Info will not
+recognize the end of the reference. (The `@pxref' command works
+differently. *Note `@pxref': pxref.)
+
+ *Please note:* A period or comma *must* follow the closing brace
+ of an `@xref'. It is required to terminate the cross reference.
+ This period or comma will appear in the output, both in the Info
+ file and in the printed manual.
+
+ `@xref' must refer to an Info node by name. Use `@node' to define
+the node (*note Writing a Node::).
+
+ `@xref' is followed by several arguments inside braces, separated by
+commas. Whitespace before and after these commas is ignored.
+
+ A cross reference requires only the name of a node; but it may contain
+up to four additional arguments. Each of these variations produces a
+cross reference that looks somewhat different.
+
+ *Please note:* Commas separate arguments in a cross reference;
+ avoid including them in the title or other part lest the formatters
+ mistake them for separators.
+
+\1f
+File: texinfo.info, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref
+
+`@xref' with One Argument
+-------------------------
+
+The simplest form of `@xref' takes one argument, the name of another
+node in the same Info file. The Info formatters produce output that
+the Info readers can use to jump to the reference; TeX produces output
+that specifies the page and section number for you.
+
+For example,
+
+ @xref{Tropical Storms}.
+
+produces
+
+ *Note Tropical Storms::.
+
+and
+
+ See Section 3.1 [Tropical Storms], page 24.
+
+(Note that in the preceding example the closing brace is followed by a
+period.)
+
+ You can write a clause after the cross reference, like this:
+
+ @xref{Tropical Storms}, for more info.
+
+which produces
+
+ *Note Tropical Storms::, for more info.
+
+ See Section 3.1 [Tropical Storms], page 24, for more info.
+
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)
+
+\1f
+File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref
+
+`@xref' with Two Arguments
+--------------------------
+
+With two arguments, the second is used as the name of the Info cross
+reference, while the first is still the name of the node to which the
+cross reference points.
+
+The template is like this:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME}.
+
+For example,
+
+ @xref{Electrical Effects, Lightning}.
+
+produces:
+
+ *Note Lightning: Electrical Effects.
+
+and
+
+ See Section 5.2 [Electrical Effects], page 57.
+
+(Note that in the preceding example the closing brace is followed by a
+period; and that the node name is printed, not the cross reference
+name.)
+
+ You can write a clause after the cross reference, like this:
+
+ @xref{Electrical Effects, Lightning}, for more info.
+
+which produces
+ *Note Lightning: Electrical Effects, for more info.
+
+and
+
+ See Section 5.2 [Electrical Effects], page 57, for more info.
+
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)
+
+\1f
+File: texinfo.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref
+
+`@xref' with Three Arguments
+----------------------------
+
+A third argument replaces the node name in the TeX output. The third
+argument should be the name of the section in the printed output, or
+else state the topic discussed by that section. Often, you will want to
+use initial upper case letters so it will be easier to read when the
+reference is printed. Use a third argument when the node name is
+unsuitable because of syntax or meaning.
+
+ Remember to avoid placing a comma within the title or topic section of
+a cross reference, or within any other section. The formatters divide
+cross references into arguments according to the commas; a comma within
+a title or other section will divide it into two arguments. In a
+reference, you need to write a title such as "Clouds, Mist, and Fog"
+without the commas.
+
+ Also, remember to write a comma or period after the closing brace of a
+`@xref' to terminate the cross reference. In the following examples, a
+clause follows a terminating comma.
+
+The template is like this:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.
+
+For example,
+
+ @xref{Electrical Effects, Lightning, Thunder and Lightning},
+ for details.
+
+produces
+
+ *Note Lightning: Electrical Effects, for details.
+
+and
+
+ See Section 5.2 [Thunder and Lightning], page 57, for details.
+
+ If a third argument is given and the second one is empty, then the
+third argument serves both. (Note how two commas, side by side, mark
+the empty second argument.)
+
+ @xref{Electrical Effects, , Thunder and Lightning},
+ for details.
+
+produces
+
+ *Note Thunder and Lightning: Electrical Effects, for details.
+
+and
+
+ See Section 5.2 [Thunder and Lightning], page 57, for details.
+
+ As a practical matter, it is often best to write cross references with
+just the first argument if the node name and the section title are the
+same, and with the first and third arguments if the node name and title
+are different.
+
+ Here are several examples from `The GNU Awk User's Guide':
+
+ @xref{Sample Program}.
+ @xref{Glossary}.
+ @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
+ @xref{Close Output, , Closing Output Files and Pipes},
+ for more information.
+ @xref{Regexp, , Regular Expressions as Patterns}.
+
+\1f
+File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref
+
+`@xref' with Four and Five Arguments
+------------------------------------
+
+In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed manual.
+
+ Remember that a comma or period must follow the closing brace of an
+`@xref' command to terminate the cross reference. In the following
+examples, a clause follows a terminating comma.
+
+The template is:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
+ INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
+
+For example,
+
+ @xref{Electrical Effects, Lightning, Thunder and Lightning,
+ weather, An Introduction to Meteorology}, for details.
+
+produces
+
+ *Note Lightning: (weather)Electrical Effects, for details.
+
+The name of the Info file is enclosed in parentheses and precedes the
+name of the node.
+
+In a printed manual, the reference looks like this:
+
+ See section "Thunder and Lightning" in An Introduction to
+ Meteorology, for details.
+
+The title of the printed manual is typeset in italics; and the
+reference lacks a page number since TeX cannot know to which page a
+reference refers when that reference is to another manual.
+
+ Often, you will leave out the second argument when you use the long
+version of `@xref'. In this case, the third argument, the topic
+description, will be used as the cross reference name in Info.
+
+The template looks like this:
+
+ @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
+ PRINTED-MANUAL-TITLE}, for details.
+
+which produces
+
+ *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
+
+and
+
+ See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
+
+For example,
+
+ @xref{Electrical Effects, , Thunder and Lightning,
+ weather, An Introduction to Meteorology}, for details.
+
+produces
+
+ *Note Thunder and Lightning: (weather)Electrical Effects,
+ for details.
+
+and
+
+ See section "Thunder and Lightning" in An Introduction to
+ Meteorology, for details.
+
+ On rare occasions, you may want to refer to another Info file that is
+within a single printed manual--when multiple Texinfo files are
+incorporated into the same TeX run but make separate Info files. In
+this case, you need to specify only the fourth argument, and not the
+fifth.
+
+\1f
+File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References
+
+Naming a `Top' Node
+===================
+
+In a cross reference, you must always name a node. This means that in
+order to refer to a whole manual, you must identify the `Top' node by
+writing it as the first argument to the `@xref' command. (This is
+different from the way you write a menu entry; see *Note Referring to
+Other Info Files: Other Info Files.) At the same time, to provide a
+meaningful section topic or title in the printed cross reference
+(instead of the word `Top'), you must write an appropriate entry for
+the third argument to the `@xref' command.
+
+Thus, to make a cross reference to `The GNU Make Manual', write:
+
+ @xref{Top, , Overview, make, The GNU Make Manual}.
+
+which produces
+
+ *Note Overview: (make)Top.
+
+and
+
+ See section "Overview" in The GNU Make Manual.
+
+In this example, `Top' is the name of the first node, and `Overview' is
+the name of the first section of the manual.
+
+\1f
+File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References
+
+`@ref'
+======
+
+`@ref' is nearly the same as `@xref' except that it does not generate a
+`See' in the printed output, just the reference itself. This makes it
+useful as the last part of a sentence.
+
+For example,
+
+ For more information, see @ref{Hurricanes}.
+
+produces
+
+ For more information, see *Note Hurricanes::.
+
+and
+
+ For more information, see Section 8.2 [Hurricanes], page 123.
+
+ The `@ref' command sometimes leads writers to express themselves in a
+manner that is suitable for a printed manual but looks awkward in the
+Info format. Bear in mind that your audience will be using both the
+printed and the Info format.
+
+For example,
+
+ Sea surges are described in @ref{Hurricanes}.
+
+produces
+
+ Sea surges are described in Section 6.7 [Hurricanes], page 72.
+
+in a printed document, and the following in Info:
+
+ Sea surges are described in *Note Hurricanes::.
+
+ *Caution:* You _must_ write a period or comma immediately after an
+ `@ref' command with two or more arguments. Otherwise, Info will
+ not find the end of the cross reference entry and its attempt to
+ follow the cross reference will fail. As a general rule, you
+ should write a period or comma after every `@ref' command. This
+ looks best in both the printed and the Info output.
+
+\1f
+File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References
+
+`@pxref'
+========
+
+The parenthetical reference command, `@pxref', is nearly the same as
+`@xref', but you use it _only_ inside parentheses and you do _not_ type
+a comma or period after the command's closing brace. The command
+differs from `@xref' in two ways:
+
+ 1. TeX typesets the reference for the printed manual with a lower case
+ `see' rather than an upper case `See'.
+
+ 2. The Info formatting commands automatically end the reference with a
+ closing colon or period.
+
+ Because one type of formatting automatically inserts closing
+punctuation and the other does not, you should use `@pxref' _only_
+inside parentheses as part of another sentence. Also, you yourself
+should not insert punctuation after the reference, as you do with
+`@xref'.
+
+ `@pxref' is designed so that the output looks right and works right
+between parentheses both in printed output and in an Info file. In a
+printed manual, a closing comma or period should not follow a cross
+reference within parentheses; such punctuation is wrong. But in an
+Info file, suitable closing punctuation must follow the cross reference
+so Info can recognize its end. `@pxref' spares you the need to use
+complicated methods to put a terminator into one form of the output and
+not the other.
+
+With one argument, a parenthetical cross reference looks like this:
+
+ ... storms cause flooding (@pxref{Hurricanes}) ...
+
+which produces
+
+ ... storms cause flooding (*Note Hurricanes::) ...
+
+and
+
+ ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
+ ...
+
+ With two arguments, a parenthetical cross reference has this template:
+
+ ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
+
+which produces
+
+ ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
+
+and
+
+ ... (see Section NNN [NODE-NAME], page PPP) ...
+
+ `@pxref' can be used with up to five arguments just like `@xref'
+(*note `@xref': xref.).
+
+ *Please note:* Use `@pxref' only as a parenthetical reference. Do
+ not try to use `@pxref' as a clause in a sentence. It will look
+ bad in either the Info file, the printed output, or both.
+
+ Also, parenthetical cross references look best at the ends of
+ sentences. Although you may write them in the middle of a
+ sentence, that location breaks up the flow of text.
+
+\1f
+File: texinfo.info, Node: inforef, Next: uref, Prev: pxref, Up: Cross References
+
+`@inforef'
+==========
+
+`@inforef' is used for cross references to Info files for which there
+are no printed manuals. Even in a printed manual, `@inforef' generates
+a reference directing the user to look in an Info file.
+
+ The command takes either two or three arguments, in the following
+order:
+
+ 1. The node name.
+
+ 2. The cross reference name (optional).
+
+ 3. The Info file name.
+
+Separate the arguments with commas, as with `@xref'. Also, you must
+terminate the reference with a comma or period after the `}', as you do
+with `@xref'.
+
+The template is:
+
+ @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
+
+Thus,
+
+ @inforef{Expert, Advanced Info commands, info},
+ for more information.
+
+produces
+
+ *Note Advanced Info commands: (info)Expert,
+ for more information.
+
+and
+
+ See Info file `info', node `Expert', for more information.
+
+Similarly,
+
+ @inforef{Expert, , info}, for more information.
+
+produces
+
+ *Note (info)Expert::, for more information.
+
+and
+
+ See Info file `info', node `Expert', for more information.
+
+ The converse of `@inforef' is `@cite', which is used to refer to
+printed works for which no Info form exists. *Note `@cite': cite.
+
+\1f
+File: texinfo.info, Node: uref, Prev: inforef, Up: Cross References
+
+`@uref{URL[, DISPLAYED-TEXT]}'
+==============================
+
+`@uref' produces a reference to a uniform resource locator (URL). It
+takes one mandatory argument, the URL, and one optional argument, the
+text to display (the default is the URL itself). In HTML output,
+`@uref' produces a link you can follow. For example:
+
+ The official GNU ftp site is
+ @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
+
+produces (in text):
+ The official GNU ftp site is
+ `ftp://ftp.gnu.ai.mit.edu/pub/gnu'
+
+whereas
+ The official
+ @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
+ GNU ftp site} holds programs and texts.
+
+produces (in text):
+ The official GNU ftp site (ftp://ftp.gnu.ai.mit.edu/pub/gnu) holds
+ programs and texts.
+
+and (in HTML):
+ The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
+ site</A> holds programs and texts.
+
+ To merely indicate a URL, use `@url' (*note `@url': url.).
+
+\1f
+File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top
+
+Marking Words and Phrases
+*************************
+
+In Texinfo, you can mark words and phrases in a variety of ways. The
+Texinfo formatters use this information to determine how to highlight
+the text. You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program. Also, you can emphasize text.
+
+* Menu:
+
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
+
+\1f
+File: texinfo.info, Node: Indicating, Next: Emphasis, Prev: Marking Text, Up: Marking Text
+
+Indicating Definitions, Commands, etc.
+======================================
+
+Texinfo has commands for indicating just what kind of object a piece of
+text refers to. For example, metasyntactic variables are marked by
+`@var', and code by `@code'. Since the pieces of text are labelled by
+commands that tell what kind of object they are, it is easy to change
+the way the Texinfo formatters prepare such text. (Texinfo is an
+_intentional_ formatting language rather than a _typesetting_
+formatting language.)
+
+ For example, in a printed manual, code is usually illustrated in a
+typewriter font; `@code' tells TeX to typeset this text in this font.
+But it would be easy to change the way TeX highlights code to use
+another font, and this change would not effect how keystroke examples
+are highlighted. If straight typesetting commands were used in the body
+of the file and you wanted to make a change, you would need to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be changed.
+
+* Menu:
+
+* Useful Highlighting:: Highlighting provides useful information.
+* code:: How to indicate code.
+* kbd:: How to show keyboard input.
+* key:: How to specify keys.
+* samp:: How to show a literal sequence of characters.
+* var:: How to indicate a metasyntactic variable.
+* file:: How to indicate the name of a file.
+* dfn:: How to specify a definition.
+* cite:: How to refer to a book that is not in Info.
+* url:: How to indicate a world wide web reference.
+* email:: How to indicate an electronic mail address.
+
+\1f
+File: texinfo.info, Node: Useful Highlighting, Next: code, Prev: Indicating, Up: Indicating
+
+Highlighting Commands are Useful
+--------------------------------
+
+ The highlighting commands can be used to generate useful information
+from the file, such as lists of functions or file names. It is
+possible, for example, to write a program in Emacs Lisp (or a keyboard
+macro) to insert an index entry after every paragraph that contains
+words or phrases marked by a specified command. You could do this to
+construct an index of functions if you had not already made the entries.
+
+ The commands serve a variety of purposes:
+
+`@code{SAMPLE-CODE}'
+ Indicate text that is a literal example of a piece of a program.
+
+`@kbd{KEYBOARD-CHARACTERS}'
+ Indicate keyboard input.
+
+`@key{KEY-NAME}'
+ Indicate the conventional name for a key on a keyboard.
+
+`@samp{TEXT}'
+ Indicate text that is a literal example of a sequence of
+ characters.
+
+`@var{METASYNTACTIC-VARIABLE}'
+ Indicate a metasyntactic variable.
+
+`@url{UNIFORM-RESOURCE-LOCATOR}'
+ Indicate a uniform resource locator for the World Wide Web.
+
+`@file{FILE-NAME}'
+ Indicate the name of a file.
+
+`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
+ Indicate an electronic mail address.
+
+`@dfn{TERM}'
+ Indicate the introductory or defining use of a term.
+
+`@cite{REFERENCE}'
+ Indicate the name of a book.
+
+
+\1f
+File: texinfo.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating
+
+`@code'{SAMPLE-CODE}
+--------------------
+
+Use the `@code' command to indicate text that is a piece of a program
+and which consists of entire syntactic tokens. Enclose the text in
+braces.
+
+ Thus, you should use `@code' for an expression in a program, for the
+name of a variable or function used in a program, or for a keyword.
+Also, you should use `@code' for the name of a program, such as `diff',
+that is a name used in the machine. (You should write the name of a
+program in the ordinary text font if you regard it as a new English
+word, such as `Emacs' or `Bison'.)
+
+ Use `@code' for environment variables such as `TEXINPUTS', and other
+variables.
+
+ Use `@code' for command names in command languages that resemble
+programming languages, such as Texinfo or the shell. For example,
+`@code' and `@samp' are produced by writing `@code{@@code}' and
+`@code{@@samp}' in the Texinfo source, respectively.
+
+ Note, however, that you should not use `@code' for shell options such
+as `-c' when such options stand alone. (Use `@samp'.) Also, an entire
+shell command often looks better if written using `@samp' rather than
+`@code'. In this case, the rule is to choose the more pleasing format.
+
+ It is incorrect to alter the case of a word inside an `@code' command
+when it appears at the beginning of a sentence. Most computer
+languages are case sensitive. In C, for example, `Printf' is different
+from the identifier `printf', and most likely is a misspelling of it.
+Even in languages which are not case sensitive, it is confusing to a
+human reader to see identifiers spelled in different ways. Pick one
+spelling and always use that. If you do not want to start a sentence
+with a command written all in lower case, you should rearrange the
+sentence.
+
+ Do not use the `@code' command for a string of characters shorter
+than a syntactic token. If you are writing about `TEXINPU', which is
+just a part of the name for the `TEXINPUTS' environment variable, you
+should use `@samp'.
+
+ In particular, you should not use the `@code' command when writing
+about the characters used in a token; do not, for example, use `@code'
+when you are explaining what letters or printable symbols can be used
+in the names of functions. (Use `@samp'.) Also, you should not use
+`@code' to mark text that is considered input to programs unless the
+input is written in a language that is like a programming language.
+For example, you should not use `@code' for the keystroke commands of
+GNU Emacs (use `@kbd' instead) although you may use `@code' for the
+names of the Emacs Lisp functions that the keystroke commands invoke.
+
+ In the printed manual, `@code' causes TeX to typeset the argument in
+a typewriter face. In the Info file, it causes the Info formatting
+commands to use single quotation marks around the text.
+
+ For example,
+
+ Use @code{diff} to compare two files.
+
+produces this in the printed manual:
+
+ Use `diff' to compare two files.
+
+\1f
+File: texinfo.info, Node: kbd, Next: key, Prev: code, Up: Indicating
+
+`@kbd'{KEYBOARD-CHARACTERS}
+---------------------------
+
+Use the `@kbd' command for characters of input to be typed by users.
+For example, to refer to the characters `M-a', write
+
+ @kbd{M-a}
+
+and to refer to the characters `M-x shell', write
+
+ @kbd{M-x shell}
+
+ The `@kbd' command has the same effect as `@code' in Info, but by
+default produces a different font (slanted typewriter instead of normal
+typewriter) in the printed manual, so users can distinguish the
+characters they are supposed to type from those the computer outputs.
+
+ Since the usage of `@kbd' varies from manual to manual, you can
+control the font switching with the `@kbdinputstyle' command. This
+command has no effect on Info output. Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
+`code'
+ Always use the same font for `@kbd' as `@code'.
+
+`example'
+ Use the distinguishing font for `@kbd' only in `@example' and
+ similar environments.
+
+`example'
+ (the default) Always use the distinguishing font for `@kbd'.
+
+ You can embed another @-command inside the braces of an `@kbd'
+command. Here, for example, is the way to describe a command that
+would be described more verbosely as "press an `r' and then press the
+<RET> key":
+
+ @kbd{r @key{RET}}
+
+This produces: `r <RET>'
+
+ You also use the `@kbd' command if you are spelling out the letters
+you type; for example:
+
+ To give the @code{logout} command,
+ type the characters @kbd{l o g o u t @key{RET}}.
+
+This produces:
+
+ To give the `logout' command, type the characters `l o g o u t
+ <RET>'.
+
+ (Also, this example shows that you can add spaces for clarity. If you
+really want to mention a space character as one of the characters of
+input, write `@key{SPC}' for it.)
+
+\1f
+File: texinfo.info, Node: key, Next: samp, Prev: kbd, Up: Indicating
+
+`@key'{KEY-NAME}
+----------------
+
+Use the `@key' command for the conventional name for a key on a
+keyboard, as in:
+
+ @key{RET}
+
+ You can use the `@key' command within the argument of an `@kbd'
+command when the sequence of characters to be typed includes one or
+more keys that are described by name.
+
+ For example, to produce `C-x <ESC>' you would type:
+
+ @kbd{C-x @key{ESC}}
+
+ Here is a list of the recommended names for keys:
+
+ SPC
+ Space
+
+ RET
+ Return
+
+ LFD
+ Linefeed (however, since most keyboards nowadays do not have
+ a Linefeed key, it might be better to call this character
+ `C-j'.
+
+ TAB
+ Tab
+
+ BS
+ Backspace
+
+ ESC
+ Escape
+
+ DEL
+ Delete
+
+ SHIFT
+ Shift
+
+ CTRL
+ Control
+
+ META
+ Meta
+
+ There are subtleties to handling words like `meta' or `ctrl' that are
+names of modifier keys. When mentioning a character in which the
+modifier key is used, such as `Meta-a', use the `@kbd' command alone;
+do not use the `@key' command; but when you are referring to the
+modifier key in isolation, use the `@key' command. For example, write
+`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>.
+
+\1f
+File: texinfo.info, Node: samp, Next: var, Prev: key, Up: Indicating
+
+`@samp'{TEXT}
+-------------
+
+Use the `@samp' command to indicate text that is a literal example or
+`sample' of a sequence of characters in a file, string, pattern, etc.
+Enclose the text in braces. The argument appears within single
+quotation marks in both the Info file and the printed manual; in
+addition, it is printed in a fixed-width font.
+
+ To match @samp{foo} at the end of the line,
+ use the regexp @samp{foo$}.
+
+produces
+
+ To match `foo' at the end of the line, use the regexp `foo$'.
+
+ Any time you are referring to single characters, you should use
+`@samp' unless `@kbd' or `@key' is more appropriate. Use `@samp' for
+the names of command-line options (except in an `@table', where `@code'
+seems to read more easily). Also, you may use `@samp' for entire
+statements in C and for entire shell commands--in this case, `@samp'
+often looks better than `@code'. Basically, `@samp' is a catchall for
+whatever is not covered by `@code', `@kbd', or `@key'.
+
+ Only include punctuation marks within braces if they are part of the
+string you are specifying. Write punctuation marks outside the braces
+if those punctuation marks are part of the English text that surrounds
+the string. In the following sentence, for example, the commas and
+period are outside of the braces:
+
+ In English, the vowels are @samp{a}, @samp{e},
+ @samp{i}, @samp{o}, @samp{u}, and sometimes
+ @samp{y}.
+
+This produces:
+
+ In English, the vowels are `a', `e', `i', `o', `u', and sometimes
+ `y'.
+
+\1f
+File: texinfo.info, Node: var, Next: file, Prev: samp, Up: Indicating
+
+`@var'{METASYNTACTIC-VARIABLE}
+------------------------------
+
+Use the `@var' command to indicate metasyntactic variables. A
+"metasyntactic variable" is something that stands for another piece of
+text. For example, you should use a metasyntactic variable in the
+documentation of a function to describe the arguments that are passed
+to that function.
+
+ Do not use `@var' for the names of particular variables in
+programming languages. These are specific names from a program, so
+`@code' is correct for them. For example, the Emacs Lisp variable
+`texinfo-tex-command' is not a metasyntactic variable; it is properly
+formatted using `@code'.
+
+ The effect of `@var' in the Info file is to change the case of the
+argument to all upper case; in the printed manual, to italicize it.
+
+ For example,
+
+ To delete file @var{filename},
+ type @code{rm @var{filename}}.
+
+produces
+
+ To delete file FILENAME, type `rm FILENAME'.
+
+(Note that `@var' may appear inside `@code', `@samp', `@file', etc.)
+
+ Write a metasyntactic variable all in lower case without spaces, and
+use hyphens to make it more readable. Thus, the Texinfo source for the
+illustration of how to begin a Texinfo manual looks like this:
+
+ \input texinfo
+ @@setfilename @var{info-file-name}
+ @@settitle @var{name-of-manual}
+
+This produces:
+
+ \input texinfo
+ @setfilename INFO-FILE-NAME
+ @settitle NAME-OF-MANUAL
+
+ In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:
+
+ ..., type rm <filename>
+
+However, that is not the style that Texinfo uses. (You can, of course,
+modify the sources to TeX and the Info formatting commands to output
+the `<...>' format if you wish.)
+
+\1f
+File: texinfo.info, Node: file, Next: dfn, Prev: var, Up: Indicating
+
+`@file'{FILE-NAME}
+------------------
+
+Use the `@file' command to indicate text that is the name of a file,
+buffer, or directory, or is the name of a node in Info. You can also
+use the command for file name suffixes. Do not use `@file' for symbols
+in a programming language; use `@code'.
+
+ Currently, `@file' is equivalent to `@samp' in its effects. For
+example,
+
+ The @file{.el} files are in
+ the @file{/usr/local/emacs/lisp} directory.
+
+produces
+
+ The `.el' files are in the `/usr/local/emacs/lisp' directory.
+
+\1f
+File: texinfo.info, Node: dfn, Next: cite, Prev: file, Up: Indicating
+
+`@dfn'{TERM}
+------------
+
+Use the `@dfn' command to identify the introductory or defining use of
+a technical term. Use the command only in passages whose purpose is to
+introduce a term which will be used again or which the reader ought to
+know. Mere passing mention of a term for the first time does not
+deserve `@dfn'. The command generates italics in the printed manual,
+and double quotation marks in the Info file. For example:
+
+ Getting rid of a file is called @dfn{deleting} it.
+
+produces
+
+ Getting rid of a file is called "deleting" it.
+
+ As a general rule, a sentence containing the defining occurrence of a
+term should be a definition of the term. The sentence does not need to
+say explicitly that it is a definition, but it should contain the
+information of a definition--it should make the meaning clear.
+
+\1f
+File: texinfo.info, Node: cite, Next: url, Prev: dfn, Up: Indicating
+
+`@cite'{REFERENCE}
+------------------
+
+Use the `@cite' command for the name of a book that lacks a companion
+Info file. The command produces italics in the printed manual, and
+quotation marks in the Info file.
+
+ (If a book is written in Texinfo, it is better to use a cross
+reference command since a reader can easily follow such a reference in
+Info. *Note `@xref': xref.)
+
+\1f
+File: texinfo.info, Node: url, Next: email, Prev: cite, Up: Indicating
+
+`@url'{UNIFORM-RESOURCE-LOCATOR}
+--------------------------------
+
+Use the `@url' to indicate a uniform resource locator on the World Wide
+Web. This is analogous to `@file', `@var', etc., and is purely for
+markup purposes. It does not produce a link you can follow in HTML
+output (the `@uref' command does, *note `@uref': uref.). It is useful
+for example URL's which do not actually exist. For example:
+
+ For example, the url might be
+ @url{http://host.domain.org/path}.
+
+\1f
+File: texinfo.info, Node: email, Prev: url, Up: Indicating
+
+`@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]}
+-----------------------------------------
+
+Use the `@email' command to indicate an electronic mail address. It
+takes one mandatory argument, the address, and one optional argument,
+the text to display (the default is the address itself).
+
+ In Info and TeX, the address is shown in angle brackets, preceded by
+the text to display if any. In HTML output, `@email' produces a
+`mailto' link that usually brings up a mail composition window. For
+example:
+
+ Send bug reports to @email{bug-texinfo@@gnu.org}.
+ Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
+
+produces
+ Send bug reports to <bug-texinfo@gnu.org>.
+ Send suggestions to the same place <bug-texinfo@gnu.org>.
+
+\1f
+File: texinfo.info, Node: Emphasis, Prev: Indicating, Up: Marking Text
+
+Emphasizing Text
+================
+
+Usually, Texinfo changes the font to mark words in the text according to
+what category the words belong to; an example is the `@code' command.
+Most often, this is the best way to mark words. However, sometimes you
+will want to emphasize text without indicating a category. Texinfo has
+two commands to do this. Also, Texinfo has several commands that
+specify the font in which TeX will typeset text. These commands have
+no affect on Info and only one of them, the `@r' command, has any
+regular use.
+
+* Menu:
+
+* emph & strong:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
+* Customized Highlighting:: How to define highlighting commands.
+
+\1f
+File: texinfo.info, Node: emph & strong, Next: Smallcaps, Prev: Emphasis, Up: Emphasis
+
+`@emph'{TEXT} and `@strong'{TEXT}
+---------------------------------
+
+The `@emph' and `@strong' commands are for emphasis; `@strong' is
+stronger. In printed output, `@emph' produces _italics_ and `@strong'
+produces *bold*.
+
+ For example,
+
+ @quotation
+ @strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
+ files in the directory.
+ @end quotation
+
+produces:
+
+ *Caution*: `rm * .[^.]*' removes *all*
+ files in the directory.
+
+ The `@strong' command is seldom used except to mark what is, in
+effect, a typographical element, such as the word `Caution' in the
+preceding example.
+
+ In the Info file, both `@emph' and `@strong' put asterisks around the
+text.
+
+ *Caution:* Do not use `@emph' or `@strong' with the word `Note';
+ Info will mistake the combination for a cross reference. Use a
+ phrase such as *Please note* or *Caution* instead.
+
+\1f
+File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis
+
+`@sc'{TEXT}: The Small Caps Font
+--------------------------------
+
+Use the `@sc' command to set text in the printed output in a small caps
+font and set text in the Info file in upper case letters.
+
+Write the text between braces in lower case, like this:
+
+ The @sc{acm} and @sc{ieee} are technical societies.
+
+This produces:
+
+ The ACM and IEEE are technical societies.
+
+ TeX typesets the small caps font in a manner that prevents the
+letters from `jumping out at you on the page'. This makes small caps
+text easier to read than text in all upper case. The Info formatting
+commands set all small caps text in upper case.
+
+ If the text between the braces of an `@sc' command is upper case, TeX
+typesets in full-size capitals. Use full-size capitals sparingly.
+
+ You may also use the small caps font for a jargon word such as ATO (a
+NASA word meaning `abort to orbit').
+
+ There are subtleties to using the small caps font with a jargon word
+such as CDR, a word used in Lisp programming. In this case, you should
+use the small caps font when the word refers to the second and
+subsequent elements of a list (the CDR of the list), but you should use
+`@code' when the word refers to the Lisp function of the same spelling.
+
+\1f
+File: texinfo.info, Node: Fonts, Next: Customized Highlighting, Prev: Smallcaps, Up: Emphasis
+
+Fonts for Printing, Not Info
+----------------------------
+
+Texinfo provides four font commands that specify font changes in the
+printed manual but have no effect in the Info file. `@i' requests
+italic font (in some versions of TeX, a slanted font is used), `@b'
+requests bold face, `@t' requests the fixed-width, typewriter-style
+font used by `@code', and `@r' requests a roman font, which is the
+usual font in which text is printed. All four commands apply to an
+argument that follows, surrounded by braces.
+
+ Only the `@r' command has much use: in example programs, you can use
+the `@r' command to convert code comments from the fixed-width font to
+a roman font. This looks better in printed output.
+
+ For example,
+
+ @lisp
+ (+ 2 2) ; @r{Add two plus two.}
+ @end lisp
+
+produces
+
+ (+ 2 2) ; Add two plus two.
+
+ If possible, you should avoid using the other three font commands. If
+you need to use one, it probably indicates a gap in the Texinfo
+language.
+
+\1f
+File: texinfo.info, Node: Customized Highlighting, Prev: Fonts, Up: Emphasis
+
+Customized Highlighting
+-----------------------
+
+You can use regular TeX commands inside of `@iftex' ... `@end iftex'
+to create your own customized highlighting commands for Texinfo. The
+easiest way to do this is to equate your customized commands with
+pre-existing commands, such as those for italics. Such new commands
+work only with TeX.
+
+ You can use the `@definfoenclose' command inside of `@ifinfo' ...
+`@end ifinfo' to define commands for Info with the same names as new
+commands for TeX. `@definfoenclose' creates new commands for Info that
+mark text by enclosing it in strings that precede and follow the text.
+(1) (*note Customized Highlighting-Footnote-1::)
+
+ Here is how to create a new @-command called `@phoo' that causes TeX
+to typeset its argument in italics and causes Info to display the
+argument between `//' and `\\'.
+
+ For TeX, write the following to equate the `@phoo' command with the
+existing `@i' italics command:
+
+ @iftex
+ @global@let@phoo=@i
+ @end iftex
+
+This defines `@phoo' as a command that causes TeX to typeset the
+argument to `@phoo' in italics. `@global@let' tells TeX to equate the
+next argument with the argument that follows the equals sign.
+
+ For Info, write the following to tell the Info formatters to enclose
+the argument between `//' and `\\':
+
+ @ifinfo
+ @definfoenclose phoo, //, \\
+ @end ifinfo
+
+Write the `@definfoenclose' command on a line and follow it with three
+arguments separated by commas (commas are used as separators in an
+`@node' line in the same way).
+
+ * The first argument to `@definfoenclose' is the @-command name
+ *without* the `@';
+
+ * the second argument is the Info start delimiter string; and,
+
+ * the third argument is the Info end delimiter string.
+
+The latter two arguments enclose the highlighted text in the Info file.
+A delimiter string may contain spaces. Neither the start nor end
+delimiter is required. However, if you do not provide a start
+delimiter, you must follow the command name with two commas in a row;
+otherwise, the Info formatting commands will misinterpret the end
+delimiter string as a start delimiter string.
+
+ After you have defined `@phoo' both for TeX and for Info, you can
+then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in
+italics in printed output.
+
+ Note that each definition applies to its own formatter: one for TeX,
+the other for Info.
+
+ Here is another example:
+
+ @ifinfo
+ @definfoenclose headword, , :
+ @end ifinfo
+ @iftex
+ @global@let@headword=@b
+ @end iftex
+
+This defines `@headword' as an Info formatting command that inserts
+nothing before and a colon after the argument and as a TeX formatting
+command to typeset its argument in bold.
+
+\1f
+File: texinfo.info, Node: Customized Highlighting-Footnotes, Up: Customized Highlighting
+
+ (1) Currently, `@definfoenclose' works only with
+`texinfo-format-buffer' and `texinfo-format-region', not with
+`makeinfo'.
+
+\1f
+File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top
+
+Quotations and Examples
+***********************
+
+Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and treated
+differently. They are usually indented.
+
+ In Texinfo, you always begin a quotation or example by writing an
+@-command at the beginning of a line by itself, and end it by writing
+an `@end' command that is also at the beginning of a line by itself.
+For instance, you begin an example by writing `@example' by itself at
+the beginning of a line and end the example by writing `@end example'
+on a line by itself, at the beginning of that line.
+
+* Menu:
+
+* Block Enclosing Commands:: Use different constructs for
+ different purposes.
+* quotation:: How to write a quotation.
+* example:: How to write an example in a fixed-width font.
+* noindent:: How to prevent paragraph indentation.
+* Lisp Example:: How to illustrate Lisp code.
+* smallexample & smalllisp:: Forms for the `@smallbook' option.
+* display:: How to write an example in the current font.
+* format:: How to write an example that does not narrow
+ the margins.
+* exdent:: How to undo the indentation of a line.
+* flushleft & flushright:: How to push text flushleft or flushright.
+* cartouche:: How to draw cartouches around examples.
+
+\1f
+File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Prev: Quotations and Examples, Up: Quotations and Examples
+
+The Block Enclosing Commands
+============================
+
+Here are commands for quotations and examples:
+
+`@quotation'
+ Indicate text that is quoted. The text is filled, indented, and
+ printed in a roman font by default.
+
+`@example'
+ Illustrate code, commands, and the like. The text is printed in a
+ fixed-width font, and indented but not filled.
+
+`@lisp'
+ Illustrate Lisp code. The text is printed in a fixed-width font,
+ and indented but not filled.
+
+`@smallexample'
+ Illustrate code, commands, and the like. Similar to `@example',
+ except that in TeX this command typesets text in a smaller font
+ for the smaller `@smallbook' format than for the 8.5 by 11 inch
+ format.
+
+`@smalllisp'
+ Illustrate Lisp code. Similar to `@lisp', except that in TeX this
+ command typesets text in a smaller font for the smaller
+ `@smallbook' format than for the 8.5 by 11 inch format.
+
+`@display'
+ Display illustrative text. The text is indented but not filled,
+ and no font is specified (so, by default, the font is roman).
+
+`@format'
+ Print illustrative text. The text is not indented and not filled
+ and no font is specified (so, by default, the font is roman).
+
+ The `@exdent' command is used within the above constructs to undo the
+indentation of a line.
+
+ The `@flushleft' and `@flushright' commands are used to line up the
+left or right margins of unfilled text.
+
+ The `@noindent' command may be used after one of the above constructs
+to prevent the following text from being indented as a new paragraph.
+
+ You can use the `@cartouche' command within one of the above
+constructs to highlight the example or quotation by drawing a box with
+rounded corners around it. (The `@cartouche' command affects only the
+printed manual; it has no effect in the Info file; see *Note Drawing
+Cartouches Around Examples: cartouche.)
+
+\1f
+File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples
+
+`@quotation'
+============
+
+The text of a quotation is processed normally except that:
+
+ * the margins are closer to the center of the page, so the whole of
+ the quotation is indented;
+
+ * the first lines of paragraphs are indented no more than other
+ lines;
+
+ * in the printed output, interparagraph spacing is reduced.
+
+ This is an example of text written between an `@quotation' command
+ and an `@end quotation' command. An `@quotation' command is most
+ often used to indicate text that is excerpted from another (real
+ or hypothetical) printed work.
+
+ Write an `@quotation' command as text on a line by itself. This line
+will disappear from the output. Mark the end of the quotation with a
+line beginning with and containing only `@end quotation'. The `@end
+quotation' line will likewise disappear from the output. Thus, the
+following,
+
+ @quotation
+ This is
+ a foo.
+ @end quotation
+
+produces
+
+ This is a foo.
+
+\1f
+File: texinfo.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples
+
+`@example'
+==========
+
+The `@example' command is used to indicate an example that is not part
+of the running text, such as computer input or output.
+
+ This is an example of text written between an
+ `@example' command
+ and an `@end example' command.
+ The text is indented but not filled.
+
+ In the printed manual, the text is typeset in a
+ fixed-width font, and extra spaces and blank lines are
+ significant. In the Info file, an analogous result is
+ obtained by indenting each line with five spaces.
+
+ Write an `@example' command at the beginning of a line by itself.
+This line will disappear from the output. Mark the end of the example
+with an `@end example' command, also written at the beginning of a line
+by itself. The `@end example' will disappear from the output.
+
+ For example,
+
+ @example
+ mv foo bar
+ @end example
+
+produces
+
+ mv foo bar
+
+ Since the lines containing `@example' and `@end example' will
+disappear, you should put a blank line before the `@example' and
+another blank line after the `@end example'. (Remember that blank
+lines between the beginning `@example' and the ending `@end example'
+will appear in the output.)
+
+ *Caution:* Do not use tabs in the lines of an example (or anywhere
+ else in Texinfo, for that matter)! TeX treats tabs as single
+ spaces, and that is not what they look like. This is a problem
+ with TeX. (If necessary, in Emacs, you can use `M-x untabify' to
+ convert tabs in a region to multiple spaces.)
+
+ Examples are often, logically speaking, "in the middle" of a
+paragraph, and the text continues after an example should not be
+indented. The `@noindent' command prevents a piece of text from being
+indented as if it were a new paragraph. (*Note noindent::.)
+
+ (The `@code' command is used for examples of code that are embedded
+within sentences, not set off from preceding and following text. *Note
+`@code': code.)
+
+\1f
+File: texinfo.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples
+
+`@noindent'
+===========
+
+An example or other inclusion can break a paragraph into segments.
+Ordinarily, the formatters indent text that follows an example as a new
+paragraph. However, you can prevent this by writing `@noindent' at the
+beginning of a line by itself preceding the continuation text.
+
+ For example:
+
+ @example
+ This is an example
+ @end example
+
+ @noindent
+ This line is not indented. As you can see, the
+ beginning of the line is fully flush left with the line
+ that follows after it. (This whole example is between
+ @code{@@display} and @code{@@end display}.)
+
+produces
+
+ This is an example
+
+
+ This line is not indented. As you can see, the
+ beginning of the line is fully flush left with the line
+ that follows after it. (This whole example is between
+ `@display' and `@end display'.)
+
+ To adjust the number of blank lines properly in the Info file output,
+remember that the line containing `@noindent' does not generate a blank
+line, and neither does the `@end example' line.
+
+ In the Texinfo source file for this manual, each line that says
+`produces' is preceded by a line containing `@noindent'.
+
+ Do not put braces after an `@noindent' command; they are not
+necessary, since `@noindent' is a command used outside of paragraphs
+(*note Command Syntax::).
+
+\1f
+File: texinfo.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples
+
+`@lisp'
+=======
+
+The `@lisp' command is used for Lisp code. It is synonymous with the
+`@example' command.
+
+ This is an example of text written between an
+ `@lisp' command and an `@end lisp' command.
+
+ Use `@lisp' instead of `@example' to preserve information regarding
+the nature of the example. This is useful, for example, if you write a
+function that evaluates only and all the Lisp code in a Texinfo file.
+Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp
+Example-Footnote-1::)
+
+ Mark the end of `@lisp' with `@end lisp' on a line by itself.
+
+\1f
+File: texinfo.info, Node: Lisp Example-Footnotes, Up: Lisp Example
+
+ (1) It would be straightforward to extend Texinfo to work in a
+similar fashion for C, Fortran, or other languages.
+
+\1f
+File: texinfo.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples
+
+`@smallexample' and `@smalllisp'
+================================
+
+In addition to the regular `@example' and `@lisp' commands, Texinfo has
+two other "example-style" commands. These are the `@smallexample' and
+`@smalllisp' commands. Both these commands are designed for use with
+the `@smallbook' command that causes TeX to produce a printed manual in
+a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format.
+
+ In TeX, the `@smallexample' and `@smalllisp' commands typeset text in
+a smaller font for the smaller `@smallbook' format than for the 8.5 by
+11 inch format. Consequently, many examples containing long lines fit
+in a narrower, `@smallbook' page without needing to be shortened. Both
+commands typeset in the normal font size when you format for the 8.5 by
+11 inch size; indeed, in this situation, the `@smallexample' and
+`@smalllisp' commands are defined to be the `@example' and `@lisp'
+commands.
+
+ In Info, the `@smallexample' and `@smalllisp' commands are equivalent
+to the `@example' and `@lisp' commands, and work exactly the same.
+
+ Mark the end of `@smallexample' or `@smalllisp' with `@end
+smallexample' or `@end smalllisp', respectively.
+
+ This is an example of text written between `@smallexample' and
+ `@end smallexample'. In Info and in an 8.5 by 11 inch manual,
+ this text appears in its normal size; but in a 7 by 9.25 inch manual,
+ this text appears in a smaller font.
+
+ The `@smallexample' and `@smalllisp' commands make it easier to
+prepare smaller format manuals without forcing you to edit examples by
+hand to fit them onto narrower pages.
+
+ As a general rule, a printed document looks better if you write all
+the examples in a chapter consistently in `@example' or in
+`@smallexample'. Only occasionally should you mix the two formats.
+
+ *Note Printing "Small" Books: smallbook, for more information about
+the `@smallbook' command.
+
+\1f
+File: texinfo.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples
+
+`@display'
+==========
+
+The `@display' command begins a kind of example. It is like the
+`@example' command except that, in a printed manual, `@display' does
+not select the fixed-width font. In fact, it does not specify the font
+at all, so that the text appears in the same font it would have
+appeared in without the `@display' command.
+
+ This is an example of text written between an `@display' command
+ and an `@end display' command. The `@display' command
+ indents the text, but does not fill it.
+
+\1f
+File: texinfo.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples
+
+`@format'
+=========
+
+The `@format' command is similar to `@example' except that, in the
+printed manual, `@format' does not select the fixed-width font and does
+not narrow the margins.
+
+This is an example of text written between an `@format' command
+and an `@end format' command. As you can see
+from this example,
+the `@format' command does not fill the text.
+
+\1f
+File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples
+
+`@exdent': Undoing a Line's Indentation
+=======================================
+
+The `@exdent' command removes any indentation a line might have. The
+command is written at the beginning of a line and applies only to the
+text that follows the command that is on the same line. Do not use
+braces around the text. In a printed manual, the text on an `@exdent'
+line is printed in the roman font.
+
+ `@exdent' is usually used within examples. Thus,
+
+ @example
+ This line follows an @@example command.
+ @exdent This line is exdented.
+ This line follows the exdented line.
+ The @@end example comes on the next line.
+ @end group
+
+produces
+
+ This line follows an @example command.
+This line is exdented.
+ This line follows the exdented line.
+ The @end example comes on the next line.
+
+ In practice, the `@exdent' command is rarely used. Usually, you
+un-indent text by ending the example and returning the page to its
+normal width.
+
+\1f
+File: texinfo.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples
+
+`@flushleft' and `@flushright'
+==============================
+
+The `@flushleft' and `@flushright' commands line up the ends of lines
+on the left and right margins of a page, but do not fill the text. The
+commands are written on lines of their own, without braces. The
+`@flushleft' and `@flushright' commands are ended by `@end flushleft'
+and `@end flushright' commands on lines of their own.
+
+ For example,
+
+ @flushleft
+ This text is
+ written flushleft.
+ @end flushleft
+
+produces
+
+ This text is
+ written flushleft.
+
+ `@flushright' produces the type of indentation often used in the
+return address of letters. For example,
+
+ @flushright
+ Here is an example of text written
+ flushright. The @code{@flushright} command
+ right justifies every line but leaves the
+ left end ragged.
+ @end flushright
+
+produces
+
+ Here is an example of text written
+ flushright. The `@flushright' command
+ right justifies every line but leaves the
+ left end ragged.
+
+\1f
+File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples
+
+Drawing Cartouches Around Examples
+==================================
+
+In a printed manual, the `@cartouche' command draws a box with rounded
+corners around its contents. You can use this command to further
+highlight an example or quotation. For instance, you could write a
+manual in which one type of example is surrounded by a cartouche for
+emphasis.
+
+ The `@cartouche' command affects only the printed manual; it has no
+effect in the Info file.
+
+ For example,
+
+ @example
+ @cartouche
+ % pwd
+ /usr/local/share/emacs
+ @end cartouche
+ @end example
+
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+\1f
+File: texinfo.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top
+
+Lists and Tables
+****************
+
+Texinfo has several ways of making lists and tables. Lists can be
+bulleted or numbered; two-column tables can highlight the items in the
+first column; multi-column tables are also supported.
+
+* Menu:
+
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* enumerate:: How to construct a numbered list.
+* Two-column Tables:: How to construct a two-column table.
+* Multi-column Tables:: How to construct generalized tables.
+
+\1f
+File: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, Up: Lists and Tables
+
+Introducing Lists
+=================
+
+ Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list. This last feature is useful if you modify the
+list, since you do not need to renumber it yourself.
+
+ Numbered lists and tables begin with the appropriate @-command at the
+beginning of a line, and end with the corresponding `@end' command on a
+line by itself. The table and itemized-list commands also require that
+you write formatting information on the same line as the beginning
+@-command.
+
+ Begin an enumerated list, for example, with an `@enumerate' command
+and end the list with an `@end enumerate' command. Begin an itemized
+list with an `@itemize' command, followed on the same line by a
+formatting command such as `@bullet', and end the list with an `@end
+itemize' command.
+
+ Precede each element of a list with an `@item' or `@itemx' command.
+
+
+Here is an itemized list of the different kinds of table and lists:
+
+ * Itemized lists with and without bullets.
+
+ * Enumerated lists, using numbers or letters.
+
+ * Two-column tables with highlighting.
+
+
+Here is an enumerated list with the same items:
+
+ 1. Itemized lists with and without bullets.
+
+ 2. Enumerated lists, using numbers or letters.
+
+ 3. Two-column tables with highlighting.
+
+
+And here is a two-column table with the same items and their @-commands:
+
+`@itemize'
+ Itemized lists with and without bullets.
+
+`@enumerate'
+ Enumerated lists, using numbers or letters.
+
+`@table'
+`@ftable'
+`@vtable'
+ Two-column tables with indexing.
+
+\1f
+File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables
+
+Making an Itemized List
+=======================
+
+The `@itemize' command produces sequences of indented paragraphs, with
+a bullet or other mark inside the left margin at the beginning of each
+paragraph for which such a mark is desired.
+
+ Begin an itemized list by writing `@itemize' at the beginning of a
+line. Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark. Usually, you will write
+`@bullet' after `@itemize', but you can use `@minus', or any character
+or any special symbol that results in a single character in the Info
+file. (When you write `@bullet' or `@minus' after an `@itemize'
+command, you may omit the `{}'.)
+
+ Write the text of the indented paragraphs themselves after the
+`@itemize', up to another line that says `@end itemize'.
+
+ Before each paragraph for which a mark in the margin is desired, write
+a line that says just `@item'. Do not write any other text on this
+line.
+
+ Usually, you should put a blank line before an `@item'. This puts a
+blank line in the Info file. (TeX inserts the proper interline
+whitespace in either case.) Except when the entries are very brief,
+these blank lines make the list look better.
+
+ Here is an example of the use of `@itemize', followed by the output
+it produces. Note that `@bullet' produces a `*' in Info and a round
+dot in TeX.
+
+ @itemize @bullet
+ @item
+ Some text for foo.
+
+ @item
+ Some text
+ for bar.
+ @end itemize
+
+This produces:
+
+ * Some text for foo.
+
+ * Some text for bar.
+
+ Itemized lists may be embedded within other itemized lists. Here is a
+list marked with dashes embedded in a list marked with bullets:
+
+ @itemize @bullet
+ @item
+ First item.
+
+ @itemize @minus
+ @item
+ Inner item.
+
+ @item
+ Second inner item.
+ @end itemize
+
+ @item
+ Second outer item.
+ @end itemize
+
+This produces:
+
+ * First item.
+
+ - Inner item.
+
+ - Second inner item.
+
+ * Second outer item.
+
+\1f
+File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables
+
+Making a Numbered or Lettered List
+==================================
+
+`@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
+that the labels on the items are successive integers or letters instead
+of bullets.
+
+ Write the `@enumerate' command at the beginning of a line. The
+command does not require an argument, but accepts either a number or a
+letter as an option. Without an argument, `@enumerate' starts the list
+with the number `1'. With a numeric argument, such as `3', the command
+starts the list with that number. With an upper or lower case letter,
+such as `a' or `A', the command starts the list with that letter.
+
+ Write the text of the enumerated list in the same way you write an
+itemized list: put `@item' on a line of its own before the start of
+each paragraph that you want enumerated. Do not write any other text
+on the line beginning with `@item'.
+
+ You should put a blank line between entries in the list. This
+generally makes it easier to read the Info file.
+
+ Here is an example of `@enumerate' without an argument:
+
+ @enumerate
+ @item
+ Underlying causes.
+
+ @item
+ Proximate causes.
+ @end enumerate
+
+This produces:
+
+ 1. Underlying causes.
+
+ 2. Proximate causes.
+
+
+ Here is an example with an argument of `3':
+
+ @enumerate 3
+ @item
+ Predisposing causes.
+
+ @item
+ Precipitating causes.
+
+ @item
+ Perpetuating causes.
+ @end enumerate
+
+This produces:
+
+ 3. Predisposing causes.
+
+ 4. Precipitating causes.
+
+ 5. Perpetuating causes.
+
+
+ Here is a brief summary of the alternatives. The summary is
+constructed using `@enumerate' with an argument of `a'.
+
+ a. `@enumerate'
+
+ Without an argument, produce a numbered list, starting with the
+ number 1.
+
+ b. `@enumerate POSITIVE-INTEGER'
+
+ With a (positive) numeric argument, start a numbered list with that
+ number. You can use this to continue a list that you interrupted
+ with other text.
+
+ c. `@enumerate UPPER-CASE-LETTER'
+
+ With an upper case letter as argument, start a list in which each
+ item is marked by a letter, beginning with that upper case letter.
+
+ d. `@enumerate LOWER-CASE-LETTER'
+
+ With a lower case letter as argument, start a list in which each
+ item is marked by a letter, beginning with that lower case letter.
+
+ You can also nest enumerated lists, as in an outline.
+
+\1f
+File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables
+
+Making a Two-column Table
+=========================
+
+`@table' is similar to `@itemize' (*note `@itemize': itemize.), but
+allows you to specify a name or heading line for each item. The
+`@table' command is used to produce two-column tables, and is
+especially useful for glossaries, explanatory exhibits, and
+command-line option summaries.
+
+* Menu:
+
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
+
+\1f
+File: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables
+
+Using the `@table' Command
+--------------------------
+
+Use the `@table' command to produce two-column tables.
+
+ Write the `@table' command at the beginning of a line and follow it
+on the same line with an argument that is a Texinfo "indicating"
+command such as `@code', `@samp', `@var', or `@kbd' (*note
+Indicating::). Although these commands are usually followed by
+arguments in braces, in this case you use the command name without an
+argument because `@item' will supply the argument. This command will
+be applied to the text that goes into the first column of each item and
+determines how it will be highlighted. For example, `@code' will cause
+the text in the first column to be highlighted with an `@code' command.
+(We recommend `@code' for `@table''s of command-line options.)
+
+ You may also choose to use the `@asis' command as an argument to
+`@table'. `@asis' is a command that does nothing; if you use this
+command after `@table', TeX and the Info formatting commands output the
+first column entries without added highlighting ("as is").
+
+ (The `@table' command may work with other commands besides those
+listed here. However, you can only use commands that normally take
+arguments in braces.)
+
+ Begin each table entry with an `@item' command at the beginning of a
+line. Write the first column text on the same line as the `@item'
+command. Write the second column text on the line following the
+`@item' line and on subsequent lines. (You do not need to type
+anything for an empty second column entry.) You may write as many
+lines of supporting text as you wish, even several paragraphs. But
+only text on the same line as the `@item' will be placed in the first
+column.
+
+ Normally, you should put a blank line before an `@item' line. This
+puts a blank like in the Info file. Except when the entries are very
+brief, a blank line looks better.
+
+ The following table, for example, highlights the text in the first
+column with an `@samp' command:
+
+ @table @samp
+ @item foo
+ This is the text for
+ @samp{foo}.
+
+ @item bar
+ Text for @samp{bar}.
+ @end table
+
+This produces:
+
+`foo'
+ This is the text for `foo'.
+
+`bar'
+ Text for `bar'.
+
+ If you want to list two or more named items with a single block of
+text, use the `@itemx' command. (*Note `@itemx': itemx.)
+
+\1f
+File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables
+
+`@ftable' and `@vtable'
+-----------------------
+
+The `@ftable' and `@vtable' commands are the same as the `@table'
+command except that `@ftable' automatically enters each of the items in
+the first column of the table into the index of functions and `@vtable'
+automatically enters each of the items in the first column of the table
+into the index of variables. This simplifies the task of creating
+indices. Only the items on the same line as the `@item' commands are
+indexed, and they are indexed in exactly the form that they appear on
+that line. *Note Creating Indices: Indices, for more information about
+indices.
+
+ Begin a two-column table using `@ftable' or `@vtable' by writing the
+@-command at the beginning of a line, followed on the same line by an
+argument that is a Texinfo command such as `@code', exactly as you
+would for an `@table' command; and end the table with an `@end ftable'
+or `@end vtable' command on a line by itself.
+
+ See the example for `@table' in the previous section.
+
+\1f
+File: texinfo.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables
+
+`@itemx'
+--------
+
+Use the `@itemx' command inside a table when you have two or more first
+column entries for the same item, each of which should appear on a line
+of its own. Use `@itemx' for all but the first entry; `@itemx' should
+always follow an `@item' command. The `@itemx' command works exactly
+like `@item' except that it does not generate extra vertical space
+above the first column text.
+
+ For example,
+
+ @table @code
+ @item upcase
+ @itemx downcase
+ These two functions accept a character or a string as
+ argument, and return the corresponding upper case (lower
+ case) character or string.
+ @end table
+
+This produces:
+
+`upcase'
+`downcase'
+ These two functions accept a character or a string as argument,
+ and return the corresponding upper case (lower case) character or
+ string.
+
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)
+
+\1f
+File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables
+
+Multi-column Tables
+===================
+
+`@multitable' allows you to construct tables with any number of
+columns, with each column having any width you like.
+
+ You define the column widths on the `@multitable' line itself, and
+write each row of the actual table following an `@item' command, with
+columns separated by an `@tab' command. Finally, `@end multitable'
+completes the table. Details in the sections below.
+
+* Menu:
+
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
+
+\1f
+File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Prev: Multi-column Tables, Up: Multi-column Tables
+
+Multitable Column Widths
+------------------------
+
+You can define the column widths for a multitable in two ways: as
+fractions of the line length; or with a prototype row. Mixing the two
+methods is not supported. In either case, the widths are defined
+entirely on the same line as the `@multitable' command.
+
+ 1. To specify column widths as fractions of the line length, write
+ `@columnfractions' and the decimal numbers (presumably less than
+ 1) after the `@multitable' command, as in:
+
+ @multitable @columnfractions .33 .33 .33
+
+ The fractions need not add up exactly to 1.0, as these do not.
+ This allows you to produce tables that do not need the full line
+ length.
+
+ 2. To specify a prototype row, write the longest entry for each column
+ enclosed in braces after the `@multitable' command. For example:
+
+ @multitable {some text for column one} {for column two}
+
+ The first column will then have the width of the typeset `some
+ text for column one', and the second column the width of `for
+ column two'.
+
+ The prototype entries need not appear in the table itself.
+
+ Although we used simple text in this example, the prototype
+ entries can contain Texinfo commands; markup commands such as
+ `@code' are particularly likely to be useful.
+
+
+\1f
+File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables
+
+Multitable Rows
+---------------
+
+After the `@multitable' command defining the column widths (see the
+previous section), you begin each row in the body of a multitable with
+`@item', and separate the column entries with `@tab'. Line breaks are
+not special within the table body, and you may break input lines in
+your source file as necessary.
+
+ Here is a complete example of a multi-column table (the text is from
+`The XEmacs Users' Manual', *note Splitting Windows: (xemacs)Split
+Window.):
+
+ @multitable @columnfractions .15 .45 .4
+ @item Key @tab Command @tab Description
+ @item C-x 2
+ @tab @code{split-window-vertically}
+ @tab Split the selected window into two windows,
+ with one above the other.
+ @item C-x 3
+ @tab @code{split-window-horizontally}
+ @tab Split the selected window into two windows
+ positioned side by side.
+ @item C-Mouse-2
+ @tab
+ @tab In the mode line or scroll bar of a window,
+ split that window.
+ @end multitable
+
+produces:
+
+Key Command Description
+C-x 2 `split-window-vertically' Split the selected window
+ into two windows, with one
+ above the other.
+C-x 3 `split-window-horizontally' Split the selected window
+ into two windows positioned
+ side by side.
+C-Mouse-2 In the mode line or scroll
+ bar of a window, split that
+ window.
+
+\1f
+File: texinfo.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top
+
+Creating Indices
+****************
+
+Using Texinfo, you can generate indices without having to sort and
+collate entries manually. In an index, the entries are listed in
+alphabetical order, together with information on how to find the
+discussion of each entry. In a printed manual, this information
+consists of page numbers. In an Info file, this information is a menu
+entry leading to the first node referenced.
+
+ Texinfo provides several predefined kinds of index: an index for
+functions, an index for variables, an index for concepts, and so on.
+You can combine indices or use them for other than their canonical
+purpose. If you wish, you can define your own indices.
+
+* Menu:
+
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
+
+\1f
+File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: Indices, Up: Indices
+
+Making Index Entries
+====================
+
+When you are making index entries, it is good practice to think of the
+different ways people may look for something. Different people _do
+not_ think of the same words when they look something up. A helpful
+index will have items indexed under all the different words that people
+may use. For example, one reader may think it obvious that the
+two-letter names for indices should be listed under "Indices,
+two-letter names", since the word "Index" is the general concept. But
+another reader may remember the specific concept of two-letter names
+and search for the entry listed as "Two letter names for indices". A
+good index will have both entries and will help both readers.
+
+ Like typesetting, the construction of an index is a highly skilled,
+professional art, the subtleties of which are not appreciated until you
+need to do it yourself.
+
+ *Note Printing Indices & Menus::, for information about printing an
+index at the end of a book or creating an index menu in an Info file.
+
+\1f
+File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices
+
+Predefined Indices
+==================
+
+Texinfo provides six predefined indices:
+
+ * A "concept index" listing concepts that are discussed.
+
+ * A "function index" listing functions (such as entry points of
+ libraries).
+
+ * A "variables index" listing variables (such as global variables of
+ libraries).
+
+ * A "keystroke index" listing keyboard commands.
+
+ * A "program index" listing names of programs.
+
+ * A "data type index" listing data types (such as structures defined
+ in header files).
+
+Not every manual needs all of these, and most manuals use two or three
+of them. This manual has two indices: a concept index and an @-command
+index (that is actually the function index but is called a command
+index in the chapter heading). Two or more indices can be combined
+into one using the `@synindex' or `@syncodeindex' commands. *Note
+Combining Indices::.
+
+\1f
+File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices
+
+Defining the Entries of an Index
+================================
+
+The data to make an index come from many individual indexing commands
+scattered throughout the Texinfo source file. Each command says to add
+one entry to a particular index; after formatting, the index will give
+the current page number or node name as the reference.
+
+ An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the entry.
+
+ For example, this section begins with the following five entries for
+the concept index:
+
+ @cindex Defining indexing entries
+ @cindex Index entries
+ @cindex Entries for an index
+ @cindex Specifying index entries
+ @cindex Creating index entries
+
+ Each predefined index has its own indexing command--`@cindex' for the
+concept index, `@findex' for the function index, and so on.
+
+ Concept index entries consist of text. The best way to write an index
+is to choose entries that are terse yet clear. If you can do this, the
+index often looks better if the entries are not capitalized, but
+written just as they would appear in the middle of a sentence.
+(Capitalize proper names and acronyms that always call for upper case
+letters.) This is the case convention we use in most GNU manuals'
+indices.
+
+ If you don't see how to make an entry terse yet clear, make it longer
+and clear--not terse and confusing. If many of the entries are several
+words long, the index may look better if you use a different convention:
+to capitalize the first word of each entry. But do not capitalize a
+case-sensitive name such as a C or Lisp function name or a shell
+command; that would be a spelling error.
+
+ Whichever case convention you use, please use it consistently!
+
+ Entries in indices other than the concept index are symbol names in
+programming languages, or program names; these names are usually
+case-sensitive, so use upper and lower case as required for them.
+
+ By default, entries for a concept index are printed in a small roman
+font and entries for the other indices are printed in a small `@code'
+font. You may change the way part of an entry is printed with the
+usual Texinfo commands, such as `@file' for file names and `@emph' for
+emphasis (*note Marking Text::).
+
+ The six indexing commands for predefined indices are:
+
+`@cindex CONCEPT'
+ Make an entry in the concept index for CONCEPT.
+
+`@findex FUNCTION'
+ Make an entry in the function index for FUNCTION.
+
+`@vindex VARIABLE'
+ Make an entry in the variable index for VARIABLE.
+
+`@kindex KEYSTROKE'
+ Make an entry in the key index for KEYSTROKE.
+
+`@pindex PROGRAM'
+ Make an entry in the program index for PROGRAM.
+
+`@tindex DATA TYPE'
+ Make an entry in the data type index for DATA TYPE.
+
+ *Caution:* Do not use a colon in an index entry. In Info, a colon
+ separates the menu entry name from the node name. An extra colon
+ confuses Info. *Note The Parts of a Menu: Menu Parts, for more
+ information about the structure of a menu entry.
+
+ If you write several identical index entries in different places in a
+Texinfo file, the index in the printed manual will list all the pages to
+which those entries refer. However, the index in the Info file will
+list *only* the node that references the *first* of those index
+entries. Therefore, it is best to write indices in which each entry
+refers to only one place in the Texinfo file. Fortunately, this
+constraint is a feature rather than a loss since it means that the index
+will be easy to use. Otherwise, you could create an index that lists
+several pages for one entry and your reader would not know to which page
+to turn. If you have two identical entries for one topic, change the
+topics slightly, or qualify them to indicate the difference.
+
+ You are not actually required to use the predefined indices for their
+canonical purposes. For example, suppose you wish to index some C
+preprocessor macros. You could put them in the function index along
+with actual functions, just by writing `@findex' commands for them;
+then, when you print the "Function Index" as an unnumbered chapter, you
+could give it the title `Function and Macro Index' and all will be
+consistent for the reader. Or you could put the macros in with the
+data types by writing `@tindex' commands for them, and give that index
+a suitable title so the reader will understand. (*Note Printing
+Indices & Menus::.)
+
+\1f
+File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices
+
+Combining Indices
+=================
+
+Sometimes you will want to combine two disparate indices such as
+functions and concepts, perhaps because you have few enough of one of
+them that a separate index for them would look silly.
+
+ You could put functions into the concept index by writing `@cindex'
+commands for them instead of `@findex' commands, and produce a
+consistent manual by printing the concept index with the title
+`Function and Concept Index' and not printing the `Function Index' at
+all; but this is not a robust procedure. It works only if your
+document is never included as part of another document that is designed
+to have a separate function index; if your document were to be included
+with such a document, the functions from your document and those from
+the other would not end up together. Also, to make your function names
+appear in the right font in the concept index, you would need to
+enclose every one of them between the braces of `@code'.
+
+* Menu:
+
+* syncodeindex:: How to merge two indices, using `@code'
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
+
+\1f
+File: texinfo.info, Node: syncodeindex, Next: synindex, Prev: Combining Indices, Up: Combining Indices
+
+`@syncodeindex'
+---------------
+
+When you want to combine functions and concepts into one index, you
+should index the functions with `@findex' and index the concepts with
+`@cindex', and use the `@syncodeindex' command to redirect the function
+index entries into the concept index.
+
+ The `@syncodeindex' command takes two arguments; they are the name of
+the index to redirect, and the name of the index to redirect it to.
+The template looks like this:
+
+ @syncodeindex FROM TO
+
+ For this purpose, the indices are given two-letter names:
+
+`cp'
+ concept index
+
+`fn'
+ function index
+
+`vr'
+ variable index
+
+`ky'
+ key index
+
+`pg'
+ program index
+
+`tp'
+ data type index
+
+ Write an `@syncodeindex' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. For example, to
+merge a function index with a concept index, write the following:
+
+ @syncodeindex fn cp
+
+This will cause all entries designated for the function index to merge
+in with the concept index instead.
+
+ To merge both a variables index and a function index into a concept
+index, write the following:
+
+ @syncodeindex vr cp
+ @syncodeindex fn cp
+
+ The `@syncodeindex' command puts all the entries from the `from'
+index (the redirected index) into the `@code' font, overriding whatever
+default font is used by the index to which the entries are now
+directed. This way, if you direct function names from a function index
+into a concept index, all the function names are printed in the `@code'
+font as you would expect.
+
+\1f
+File: texinfo.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices
+
+`@synindex'
+-----------
+
+The `@synindex' command is nearly the same as the `@syncodeindex'
+command, except that it does not put the `from' index entries into the
+`@code' font; rather it puts them in the roman font. Thus, you use
+`@synindex' when you merge a concept index into a function index.
+
+ *Note Printing Indices & Menus::, for information about printing an
+index at the end of a book or creating an index menu in an Info file.
+
+\1f
+File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices
+
+Defining New Indices
+====================
+
+In addition to the predefined indices, you may use the `@defindex' and
+`@defcodeindex' commands to define new indices. These commands create
+new indexing @-commands with which you mark index entries. The
+`@defindex 'command is used like this:
+
+ @defindex NAME
+
+ The name of an index should be a two letter word, such as `au'. For
+example:
+
+ @defindex au
+
+ This defines a new index, called the `au' index. At the same time,
+it creates a new indexing command, `@auindex', that you can use to make
+index entries. Use the new indexing command just as you would use a
+predefined indexing command.
+
+ For example, here is a section heading followed by a concept index
+entry and two `au' index entries.
+
+ @section Cognitive Semantics
+ @cindex kinesthetic image schemas
+ @auindex Johnson, Mark
+ @auindex Lakoff, George
+
+(Evidently, `au' serves here as an abbreviation for "author".) Texinfo
+constructs the new indexing command by concatenating the name of the
+index with `index'; thus, defining an `au' index leads to the automatic
+creation of an `@auindex' command.
+
+ Use the `@printindex' command to print the index, as you do with the
+predefined indices. For example:
+
+ @node Author Index, Subject Index, , Top
+ @unnumbered Author Index
+
+ @printindex au
+
+ The `@defcodeindex' is like the `@defindex' command, except that, in
+the printed output, it prints entries in an `@code' font instead of a
+roman font. Thus, it parallels the `@findex' command rather than the
+`@cindex' command.
+
+ You should define new indices within or right after the end-of-header
+line of a Texinfo file, before any `@synindex' or `@syncodeindex'
+commands (*note Header::).
+
+\1f
+File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top
+
+Special Insertions
+******************
+
+Texinfo provides several commands for inserting characters that have
+special meaning in Texinfo, such as braces, and for other graphic
+elements that do not correspond to simple characters you can type.
+
+* Menu:
+
+* Braces Atsigns:: How to insert braces, `@'.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the TeX logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Images:: How to include graphics.
+
+\1f
+File: texinfo.info, Node: Braces Atsigns, Next: Inserting Space, Prev: Insertions, Up: Insertions
+
+Inserting @ and Braces
+======================
+
+`@' and curly braces are special characters in Texinfo. To insert
+these characters so they appear in text, you must put an `@' in front
+of these characters to prevent Texinfo from misinterpreting them.
+
+ Do not put braces after any of these commands; they are not necessary.
+
+* Menu:
+
+* Inserting An Atsign:: How to insert `@'.
+* Inserting Braces:: How to insert `{' and `}'.
+
+\1f
+File: texinfo.info, Node: Inserting An Atsign, Next: Inserting Braces, Prev: Braces Atsigns, Up: Braces Atsigns
+
+Inserting `@' with @@
+---------------------
+
+`@@' stands for a single `@' in either printed or Info output.
+
+ Do not put braces after an `@@' command.
+
+\1f
+File: texinfo.info, Node: Inserting Braces, Prev: Inserting An Atsign, Up: Braces Atsigns
+
+Inserting `{' and `}'with @{ and @}
+-----------------------------------
+
+`@{' stands for a single `{' in either printed or Info output.
+
+ `@}' stands for a single `}' in either printed or Info output.
+
+ Do not put braces after either an `@{' or an `@}' command.
+
+\1f
+File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Braces Atsigns, Up: Insertions
+
+Inserting Space
+===============
+
+The following sections describe commands that control spacing of various
+kinds within and after sentences.
+
+* Menu:
+
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
+
+\1f
+File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Inserting Space, Up: Inserting Space
+
+Not Ending a Sentence
+---------------------
+
+Depending on whether a period or exclamation point or question mark is
+inside or at the end of a sentence, less or more space is inserted after
+a period in a typeset manual. Since it is not always possible for
+Texinfo to determine when a period ends a sentence and when it is used
+in an abbreviation, special commands are needed in some circumstances.
+(Usually, Texinfo can guess how to handle periods, so you do not need to
+use the special commands; you just enter a period as you would if you
+were using a typewriter, which means you put two spaces after the
+period, question mark, or exclamation mark that ends a sentence.)
+
+ Use the `@:' command after a period, question mark, exclamation mark,
+or colon that should not be followed by extra space. For example, use
+`@:' after periods that end abbreviations which are not at the ends of
+sentences.
+
+ For example,
+
+ The s.o.p.@: has three parts ...
+ The s.o.p. has three parts ...
+
+produces
+
+ The s.o.p. has three parts ...
+ The s.o.p. has three parts ...
+
+(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
+Procedure".)
+
+ `@:' has no effect on the Info output. Do not put braces after `@:'.
+
+\1f
+File: texinfo.info, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space
+
+Ending a Sentence
+-----------------
+
+Use `@.' instead of a period, `@!' instead of an exclamation point, and
+`@?' instead of a question mark at the end of a sentence that ends with
+a single capital letter. Otherwise, TeX will think the letter is an
+abbreviation and will not insert the correct end-of-sentence spacing.
+Here is an example:
+
+ Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.
+ Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
+
+produces
+
+ Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
+ Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
+
+ In the Info file output, `@.' is equivalent to a simple `.'; likewise
+for `@!' and `@?'.
+
+ The meanings of `@:' and `@.' in Texinfo are designed to work well
+with the Emacs sentence motion commands (*note Sentences:
+(xemacs)Sentences.). This made it necessary for them to be
+incompatible with some other formatting systems that use @-commands.
+
+ Do not put braces after any of these commands.
+
+\1f
+File: texinfo.info, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space
+
+Multiple Spaces
+---------------
+
+Ordinarily, TeX collapses multiple whitespace characters (space, tab,
+and newline) into a single space. Info output, on the other hand,
+preserves whitespace as you type it, except for changing a newline into
+a space; this is why it is important to put two spaces at the end of
+sentences in Texinfo documents.
+
+ Occasionally, you may want to actually insert several consecutive
+spaces, either for purposes of example (what your program does with
+multiple spaces as input), or merely for purposes of appearance in
+headings or lists. Texinfo supports three commands: `@SPACE', `@TAB',
+and `@NL', all of which insert a single space into the output. (Here,
+`@SPACE' represents an `@' character followed by a space, i.e., `@ ',
+and `TAB' and `NL' represent the tab character and end-of-line, i.e.,
+when `@' is the last character on a line.)
+
+ For example,
+ Spacey@ @ @ @
+ example.
+
+produces
+
+ Spacey example.
+
+ Other possible uses of `@SPACE' have been subsumed by `@multitable'
+(*note Multi-column Tables::).
+
+ Do not follow any of these commands with braces.
+
+\1f
+File: texinfo.info, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space
+
+`@dmn'{DIMENSION}: Format a Dimension
+-------------------------------------
+
+At times, you may want to write `12pt' or `8.5in' with little or no
+space between the number and the abbreviation for the dimension. You
+can use the `@dmn' command to do this. On seeing the command, TeX
+inserts just enough space for proper typesetting; the Info formatting
+commands insert no space at all, since the Info file does not require
+it.
+
+ To use the `@dmn' command, write the number and then follow it
+immediately, with no intervening space, by `@dmn', and then by the
+dimension within braces. For example,
+
+ A4 paper is 8.27@dmn{in} wide.
+
+produces
+
+ A4 paper is 8.27in wide.
+
+ Not everyone uses this style. Some people prefer `8.27 in.@:' or
+`8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases,
+however, the formatters may insert a line break between the number and
+the dimension, so use `@w' (*note w::). Also, if you write a period
+after an abbreviation within a sentence, you should write `@:' after
+the period to prevent TeX from inserting extra whitespace, as shown
+here. *Note Inserting Space::.
+
+\1f
+File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions
+
+Inserting Accents
+=================
+
+Here is a table with the commands Texinfo provides for inserting
+floating accents. The commands with non-alphabetic names do not take
+braces around their argument (which is taken to be the next character).
+(Exception: `@,' _does_ take braces around its argument.) This is so
+as to make the source as convenient to type and read as possible, since
+accented characters are very common in some languages.
+
+Command Output What
+@"o o" umlaut accent
+@'o o' acute accent
+@,{c} c, cedilla accent
+@=o o= macron/overbar accent
+@^o o^ circumflex accent
+@`o o` grave accent
+@~o o~ tilde accent
+@dotaccent{o} o. overdot accent
+@H{o} o'' long Hungarian umlaut
+@ringaccent{o} o* ring accent
+@tieaccent{oo} oo[ tie-after accent
+@u{o} o( breve accent
+@ubaraccent{o} o_ underbar accent
+@udotaccent{o} .o underdot accent
+@v{o} o< hacek or check accent
+
+ This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
+@exclamdown{} ! upside-down !
+@questiondown{} ? upside-down ?
+@aa{},@AA{} aa,AA A,a with circle
+@ae{},@AE{} ae,AE ae,AE ligatures
+@dotless{i} i dotless i
+@dotless{j} j dotless j
+@l{},@L{} /l,/L suppressed-L,l
+@o{},@O{} /o,/O O,o with slash
+@oe{},@OE{} oe,OE OE,oe ligatures
+@ss{} ss es-zet or sharp S
+
+\1f
+File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions
+
+Inserting Ellipsis, Dots, and Bullets
+=====================================
+
+An "ellipsis" (a line of dots) is not typeset as a string of periods,
+so a special command is used for ellipsis in Texinfo. The `@bullet'
+command is special, too. Each of these commands is followed by a pair
+of braces, `{}', without any whitespace between the name of the command
+and the braces. (You need to use braces with these commands because
+you can use them next to other text; without the braces, the formatters
+would be confused. *Note @-Command Syntax: Command Syntax, for further
+information.)
+
+* Menu:
+
+* dots:: How to insert dots ...
+* bullet:: How to insert a bullet.
+
+\1f
+File: texinfo.info, Node: dots, Next: bullet, Prev: Dots Bullets, Up: Dots Bullets
+
+`@dots'{} (...)
+---------------
+
+Use the `@dots{}' command to generate an ellipsis, which is three dots
+in a row, appropriately spaced, like this: `...'. Do not simply write
+three periods in the input file; that would work for the Info file
+output, but would produce the wrong amount of space between the periods
+in the printed manual.
+
+ Similarly, the `@enddots{}' command generates an end-of-sentence
+ellipsis (four dots) ....
+
+\1f
+File: texinfo.info, Node: bullet, Prev: dots, Up: Dots Bullets
+
+`@bullet'{} (*)
+---------------
+
+Use the `@bullet{}' command to generate a large round dot, or the
+closest possible thing to one. In Info, an asterisk is used.
+
+ Here is a bullet: *
+
+ When you use `@bullet' in `@itemize', you do not need to type the
+braces, because `@itemize' supplies them. (*Note `@itemize': itemize.)
+
+\1f
+File: texinfo.info, Node: TeX and copyright, Next: pounds, Prev: Dots Bullets, Up: Insertions
+
+Inserting TeX and the Copyright Symbol
+======================================
+
+The logo `TeX' is typeset in a special fashion and it needs an
+@-command. The copyright symbol, `(C)', is also special. Each of
+these commands is followed by a pair of braces, `{}', without any
+whitespace between the name of the command and the braces.
+
+* Menu:
+
+* tex:: How to insert the TeX logo.
+* copyright symbol:: How to use `@copyright'{}.
+
+\1f
+File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright
+
+`@TeX'{} (TeX)
+--------------
+
+Use the `@TeX{}' command to generate `TeX'. In a printed manual, this
+is a special logo that is different from three ordinary letters. In
+Info, it just looks like `TeX'. The `@TeX{}' command is unique among
+Texinfo commands in that the `T' and the `X' are in upper case.
+
+\1f
+File: texinfo.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright
+
+`@copyright'{} ((C))
+--------------------
+
+Use the `@copyright{}' command to generate `(C)'. In a printed manual,
+this is a `c' inside a circle, and in Info, this is `(C)'.
+
+\1f
+File: texinfo.info, Node: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions
+
+`@pounds{}' (#): Pounds Sterling
+================================
+
+Use the `@pounds{}' command to generate `#'. In a printed manual, this
+is the symbol for the currency pounds sterling. In Info, it is a `#'.
+Other currency symbols are unfortunately not available.
+
+\1f
+File: texinfo.info, Node: minus, Next: math, Prev: pounds, Up: Insertions
+
+`@minus'{} (-): Inserting a Minus Sign
+======================================
+
+Use the `@minus{}' command to generate a minus sign. In a fixed-width
+font, this is a single hyphen, but in a proportional font, the symbol
+is the customary length for a minus sign--a little longer than a
+hyphen, shorter than an em-dash:
+
+ `-' is a minus sign generated with `@minus{}',
+
+ `-' is a hyphen generated with the character `-',
+
+ `---' is an em-dash for text.
+
+In the fixed-width font used by Info, `@minus{}' is the same as a
+hyphen.
+
+ You should not use `@minus{}' inside `@code' or `@example' because
+the width distinction is not made in the fixed-width font they use.
+
+ When you use `@minus' to specify the mark beginning each entry in an
+itemized list, you do not need to type the braces (*note `@itemize':
+itemize..)
+
+\1f
+File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions
+
+`@math' - Inserting Mathematical Expressions
+============================================
+
+You can write a short mathematical expression with the `@math' command.
+Write the mathematical expression between braces, like this:
+
+ @math{(a + b)(a + b) = a^2 + 2ab + b^2}
+
+This produces the following in Info:
+
+ (a + b)(a + b) = a^2 + 2ab + b^2
+
+ Thus, the `@math' command has no effect on the Info output.
+
+ For complex mathematical expressions, you can also use TeX directly
+(*note Raw Formatter Commands::). When you use TeX directly, remember
+to write the mathematical expression between one or two `$'
+(dollar-signs) as appropriate.
+
+\1f
+File: texinfo.info, Node: Glyphs, Next: Images, Prev: math, Up: Insertions
+
+Glyphs for Examples
+===================
+
+In Texinfo, code is often illustrated in examples that are delimited by
+`@example' and `@end example', or by `@lisp' and `@end lisp'. In such
+examples, you can indicate the results of evaluation or an expansion
+using `=>' or `==>'. Likewise, there are commands to insert glyphs to
+indicate printed output, error messages, equivalence of expressions,
+and the location of point.
+
+ The glyph-insertion commands do not need to be used within an
+example, but most often they are. Every glyph-insertion command is
+followed by a pair of left- and right-hand braces.
+
+* Menu:
+
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
+
+\1f
+File: texinfo.info, Node: Glyphs Summary, Next: result, Prev: Glyphs, Up: Glyphs
+
+Glyphs Summary
+--------------
+
+Here are the different glyph commands:
+
+=>
+ `@result{}' points to the result of an expression.
+
+==>
+ `@expansion{}' shows the results of a macro expansion.
+
+-|
+ `@print{}' indicates printed output.
+
+error-->
+ `@error{}' indicates that the following text is an error message.
+
+==
+ `@equiv{}' indicates the exact equivalence of two forms.
+
+-!-
+ `@point{}' shows the location of point.
+
+* Menu:
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+\1f
+File: texinfo.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs
+
+`@result{}' (=>): Indicating Evaluation
+---------------------------------------
+
+Use the `@result{}' command to indicate the result of evaluating an
+expression.
+
+ The `@result{}' command is displayed as `=>' in Info and as a double
+stemmed arrow in the printed output.
+
+ Thus, the following,
+
+ (cdr '(1 2 3))
+ => (2 3)
+
+may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
+
+\1f
+File: texinfo.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs
+
+`@expansion{}' (==>): Indicating an Expansion
+---------------------------------------------
+
+When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the `@expansion{}'
+command.
+
+ The `@expansion{}' command is displayed as `==>' in Info and as a
+long arrow with a flat base in the printed output.
+
+ For example, the following
+
+ @lisp
+ (third '(a b c))
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
+ @end lisp
+
+produces
+
+ (third '(a b c))
+ ==> (car (cdr (cdr '(a b c))))
+ => c
+
+which may be read as:
+
+ `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
+ result of evaluating the expression is `c'.
+
+Often, as in this case, an example looks better if the `@expansion{}'
+and `@result{}' commands are indented five spaces.
+
+\1f
+File: texinfo.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs
+
+`@print{}' (-|): Indicating Printed Output
+------------------------------------------
+
+Sometimes an expression will print output during its execution. You
+can indicate the printed output with the `@print{}' command.
+
+ The `@print{}' command is displayed as `-|' in Info and similarly, as
+a horizontal dash butting against a vertical bar, in the printed output.
+
+ In the following example, the printed text is indicated with `-|',
+and the value of the expression follows on the last line.
+
+ (progn (print 'foo) (print 'bar))
+ -| foo
+ -| bar
+ => bar
+
+In a Texinfo source file, this example is written as follows:
+
+ @lisp
+ (progn (print 'foo) (print 'bar))
+ @print{} foo
+ @print{} bar
+ @result{} bar
+ @end lisp
+
+\1f
+File: texinfo.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs
+
+`@error{}' (error-->): Indicating an Error Message
+--------------------------------------------------
+
+A piece of code may cause an error when you evaluate it. You can
+designate the error message with the `@error{}' command.
+
+ The `@error{}' command is displayed as `error-->' in Info and as the
+word `error' in a box in the printed output.
+
+ Thus,
+
+ @lisp
+ (+ 23 'x)
+ @error{} Wrong type argument: integer-or-marker-p, x
+ @end lisp
+
+produces
+
+ (+ 23 'x)
+ error--> Wrong type argument: integer-or-marker-p, x
+
+This indicates that the following error message is printed when you
+evaluate the expression:
+
+ Wrong type argument: integer-or-marker-p, x
+
+ `error-->' itself is not part of the error message.
+
+\1f
+File: texinfo.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs
+
+`@equiv{}' (==): Indicating Equivalence
+---------------------------------------
+
+Sometimes two expressions produce identical results. You can indicate
+the exact equivalence of two forms with the `@equiv{}' command.
+
+ The `@equiv{}' command is displayed as `==' in Info and as a three
+parallel horizontal lines in the printed output.
+
+ Thus,
+
+ @lisp
+ (make-sparse-keymap) @equiv{} (list 'keymap)
+ @end lisp
+
+produces
+
+ (make-sparse-keymap) == (list 'keymap)
+
+This indicates that evaluating `(make-sparse-keymap)' produces
+identical results to evaluating `(list 'keymap)'.
+
+\1f
+File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs
+
+`@point{}' (-!-): Indicating Point in a Buffer
+----------------------------------------------
+
+Sometimes you need to show an example of text in an Emacs buffer. In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
+name.
+
+ You can use the `@point{}' command to show the location of point in
+the text in the buffer. (The symbol for point, of course, is not part
+of the text in the buffer; it indicates the place _between_ two
+characters where point is located.)
+
+ The `@point{}' command is displayed as `-!-' in Info and as a small
+five pointed star in the printed output.
+
+ The following example shows the contents of buffer `foo' before and
+after evaluating a Lisp command to insert the word `changed'.
+
+ ---------- Buffer: foo ----------
+ This is the -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+ (insert "changed ")
+ => nil
+ ---------- Buffer: foo ----------
+ This is the changed -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+ In a Texinfo source file, the example is written like this:
+
+ @example
+ ---------- Buffer: foo ----------
+ This is the @point{}contents of foo.
+ ---------- Buffer: foo ----------
+
+ (insert "changed ")
+ @result{} nil
+ ---------- Buffer: foo ----------
+ This is the changed @point{}contents of foo.
+ ---------- Buffer: foo ----------
+ @end example
+
+\1f
+File: texinfo.info, Node: Images, Prev: Glyphs, Up: Insertions
+
+Inserting Images
+================
+
+You can insert an image in an external file with the `@image' command:
+
+ @image{FILENAME, [WIDTH], [HEIGHT]}
+
+ The FILENAME argument is mandatory, and must not have an extension,
+because the different processors support different formats: TeX reads
+the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo'
+uses `FILENAME.txt' verbatim for Info output (more or less as if it was
+an `@example'). HTML output requires `FILENAME.jpg'.
+
+ The optional WIDTH and HEIGHT arguments specify the size to scale the
+image to (they are ignored for Info output). If they are both
+specified, the image is presented in its natural size (given in the
+file); if only one is specified, the other is scaled proportionately;
+and if both are specified, both are respected, thus possibly distorting
+the original image by changing its aspect ratio.
+
+ The WIDTH and HEIGHT may be specified using any valid TeX dimension,
+namely:
+
+pt
+ point (72.27pt = 1in)
+
+pc
+ pica (1pc = 12pt)
+
+bp
+ big point (72bp = 1in)
+
+in
+ inch
+
+cm
+ centimeter (2.54cm = 1in)
+
+mm
+ millimeter (10mm = 1cm)
+
+dd
+ dido^t point (1157dd = 1238pt)
+
+cc
+ cicero (1cc = 12dd)
+
+sp
+ scaled point (65536sp = 1pt)
+
+ For example, the following will scale a file `ridt.eps' to one inch
+vertically, with the width scaled proportionately:
+
+ @image{ridt,,1in}
+
+ For `@image' to work with TeX, the file `epsf.tex' must be installed
+somewhere that TeX can find it. This file is included in the Texinfo
+distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'.
+
+\1f
+File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
+
+Making and Preventing Breaks
+****************************
+
+Usually, a Texinfo file is processed both by TeX and by one of the Info
+formatting commands. Line, paragraph, or page breaks sometimes occur
+in the `wrong' place in one or other form of output. You must ensure
+that text looks right both in the printed manual and in the Info file.
+
+ For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages. Conversely, you may want to force a page break where none
+would occur normally. Fortunately, problems like these do not often
+arise. When they do, use the break, break prevention, or pagination
+commands.
+
+* Menu:
+
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell TeX about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+
+\1f
+File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks
+
+The Break Commands
+==================
+
+ The break commands create or allow line and paragraph breaks:
+
+`@*'
+ Force a line break.
+
+`@sp N'
+ Skip N blank lines.
+
+`@-'
+ Insert a discretionary hyphen.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Define hyphen points in HY-PHEN-A-TED WORDS.
+
+ The line-break-prevention command holds text together all on one line:
+
+`@w{TEXT}'
+ Prevent TEXT from being split and hyphenated across two lines.
+
+ The pagination commands apply only to printed output, since Info
+files do not have pages.
+
+`@page'
+ Start a new page in the printed manual.
+
+`@group'
+ Hold text together that must appear on one printed page.
+
+`@need MILS'
+ Start a new printed page if not enough space on this one.
+
+\1f
+File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
+
+`@*': Generate Line Breaks
+==========================
+
+The `@*' command forces a line break in both the printed manual and in
+Info.
+
+ For example,
+
+ This line @* is broken @*in two places.
+
+produces
+
+ This line
+ is broken
+ in two places.
+
+(Note that the space after the first `@*' command is faithfully carried
+down to the next line.)
+
+ The `@*' command is often used in a file's copyright page:
+
+ This is edition 2.0 of the Texinfo documentation,@*
+ and is for ...
+
+In this case, the `@*' command keeps TeX from stretching the line
+across the whole page in an ugly manner.
+
+ *Please note:* Do not write braces after an `@*' command; they are
+ not needed.
+
+ Do not write an `@refill' command at the end of a paragraph
+ containing an `@*' command; it will cause the paragraph to be
+ refilled after the line break occurs, negating the effect of the
+ line break.
+
+\1f
+File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
+
+`@-' and `@hyphenation': Helping TeX hyphenate
+==============================================
+
+Although TeX's hyphenation algorithm is generally pretty good, it does
+miss useful hyphenation points from time to time. (Or, far more
+rarely, insert an incorrect hyphenation.) So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help TeX out. Texinfo supports two commands for this:
+
+`@-'
+ Insert a discretionary hyphen, i.e., a place where TeX can (but
+ does not have to) hyphenate. This is especially useful when you
+ notice an overfull hbox is due to TeX missing a hyphenation (*note
+ Overfull hboxes::). TeX will not insert any hyphenation points in
+ a word containing `@-'.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
+ a `-' at each hyphenation point. For example:
+ @hyphenation{man-u-script man-u-scripts}
+
+ TeX only uses the specified hyphenation points when the words
+ match exactly, so give all necessary variants.
+
+ Info output is not hyphenated, so these commands have no effect there.
+
+\1f
+File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks
+
+`@w'{TEXT}: Prevent Line Breaks
+===============================
+
+`@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
+
+ You can use the `@w' command to prevent TeX from automatically
+hyphenating a long name or phrase that happens to fall near the end of a
+line.
+
+ You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
+
+produces
+
+ You can copy GNU software from `ftp.gnu.ai.mit.edu'.
+
+ *Caution:* Do not write an `@refill' command at the end of a
+ paragraph containing an `@w' command; it will cause the paragraph
+ to be refilled and may thereby negate the effect of the `@w'
+ command.
+
+\1f
+File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks
+
+`@sp' N: Insert Blank Lines
+===========================
+
+A line beginning with and containing only `@sp N' generates N blank
+lines of space in both the printed manual and the Info file. `@sp'
+also forces a paragraph break. For example,
+
+ @sp 2
+
+generates two blank lines.
+
+ The `@sp' command is most often used in the title page.
+
+\1f
+File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks
+
+`@page': Start a New Page
+=========================
+
+A line containing only `@page' starts a new page in a printed manual.
+The command has no effect on Info files since they are not paginated.
+An `@page' command is often used in the `@titlepage' section of a
+Texinfo file to start the copyright page.
+
+\1f
+File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks
+
+`@group': Prevent Page Breaks
+=============================
+
+The `@group' command (on a line by itself) is used inside an `@example'
+or similar construct to begin an unsplittable vertical group, which
+will appear entirely on one page in the printed output. The group is
+terminated by a line containing only `@end group'. These two lines
+produce no output of their own, and in the Info file output they have
+no effect at all.
+
+ Although `@group' would make sense conceptually in a wide variety of
+contexts, its current implementation works reliably only within
+`@example' and variants, and within `@display', `@format', `@flushleft'
+and `@flushright'. *Note Quotations and Examples::. (What all these
+commands have in common is that each line of input produces a line of
+output.) In other contexts, `@group' can cause anomalous vertical
+spacing.
+
+ This formatting requirement means that you should write:
+
+ @example
+ @group
+ ...
+ @end group
+ @end example
+
+with the `@group' and `@end group' commands inside the `@example' and
+`@end example' commands.
+
+ The `@group' command is most often used to hold an example together
+on one page. In this Texinfo manual, more than 100 examples contain
+text that is enclosed between `@group' and `@end group'.
+
+ If you forget to end a group, you may get strange and unfathomable
+error messages when you run TeX. This is because TeX keeps trying to
+put the rest of the Texinfo file onto the one page and does not start
+to generate error messages until it has processed considerable text.
+It is a good rule of thumb to look for a missing `@end group' if you
+get incomprehensible error messages in TeX.
+
+\1f
+File: texinfo.info, Node: need, Prev: group, Up: Breaks
+
+`@need MILS': Prevent Page Breaks
+=================================
+
+A line containing only `@need N' starts a new page in a printed manual
+if fewer than N mils (thousandths of an inch) remain on the current
+page. Do not use braces around the argument N. The `@need' command
+has no effect on Info files since they are not paginated.
+
+ This paragraph is preceded by an `@need' command that tells TeX to
+start a new page if fewer than 800 mils (eight-tenths inch) remain on
+the page. It looks like this:
+
+ @need 800
+ This paragraph is preceded by ...
+
+ The `@need' command is useful for preventing orphans (single lines at
+the bottoms of printed pages).
+
+\1f
+File: texinfo.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top
+
+Definition Commands
+*******************
+
+The `@deffn' command and the other "definition commands" enable you to
+describe functions, variables, macros, commands, user options, special
+forms and other such artifacts in a uniform format.
+
+ In the Info file, a definition causes the entity
+category--`Function', `Variable', or whatever--to appear at the
+beginning of the first line of the definition, followed by the entity's
+name and arguments. In the printed manual, the command causes TeX to
+print the entity's name and its arguments on the left margin and print
+the category next to the right margin. In both output formats, the
+body of the definition is indented. Also, the name of the entity is
+entered into the appropriate index: `@deffn' enters the name into the
+index of functions, `@defvr' enters it into the index of variables, and
+so on.
+
+ A manual need not and should not contain more than one definition for
+a given name. An appendix containing a summary should use `@table'
+rather than the definition commands.
+
+* Menu:
+
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
+
+\1f
+File: texinfo.info, Node: Def Cmd Template, Next: Optional Arguments, Prev: Definition Commands, Up: Definition Commands
+
+The Template for a Definition
+=============================
+
+The `@deffn' command is used for definitions of entities that resemble
+functions. To write a definition using the `@deffn' command, write the
+`@deffn' command at the beginning of a line and follow it on the same
+line by the category of the entity, the name of the entity itself, and
+its arguments (if any). Then write the body of the definition on
+succeeding lines. (You may embed examples in the body.) Finally, end
+the definition with an `@end deffn' command written on a line of its
+own. (The other definition commands follow the same format.)
+
+ The template for a definition looks like this:
+
+ @deffn CATEGORY NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end deffn
+
+For example,
+
+ @deffn Command forward-word count
+ This command moves point forward @var{count} words
+ (or backward if @var{count} is negative). ...
+ @end deffn
+
+produces
+
+ - Command: forward-word count
+ This function moves point forward COUNT words (or backward if
+ COUNT is negative). ...
+
+ Capitalize the category name like a title. If the name of the
+category contains spaces, as in the phrase `Interactive Command', write
+braces around it. For example:
+
+ @deffn {Interactive Command} isearch-forward
+ ...
+ @end deffn
+
+Otherwise, the second word will be mistaken for the name of the entity.
+
+ Some of the definition commands are more general than others. The
+`@deffn' command, for example, is the general definition command for
+functions and the like--for entities that may take arguments. When you
+use this command, you specify the category to which the entity belongs.
+The `@deffn' command possesses three predefined, specialized
+variations, `@defun', `@defmac', and `@defspec', that specify the
+category for you: "Function", "Macro", and "Special Form" respectively.
+(In Lisp, a special form is an entity much like a function.) The
+`@defvr' command also is accompanied by several predefined, specialized
+variations for describing particular kinds of variables.
+
+ The template for a specialized definition, such as `@defun', is
+similar to the template for a generalized definition, except that you
+do not need to specify the category:
+
+ @defun NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end defun
+
+Thus,
+
+ @defun buffer-end flag
+ This function returns @code{(point-min)} if @var{flag}
+ is less than 1, @code{(point-max)} otherwise.
+ ...
+ @end defun
+
+produces
+
+ - Function: buffer-end flag
+ This function returns `(point-min)' if FLAG is less than 1,
+ `(point-max)' otherwise. ...
+
+*Note Sample Function Definition: Sample Function Definition, for a
+more detailed example of a function definition, including the use of
+`@example' inside the definition.
+
+ The other specialized commands work like `@defun'.
+
projects / chise / xemacs-chise.git- / blobdiff