--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/texinfo/texinfo.texi	Fri Feb 19 22:39:19 2010 -0600
@@ -0,0 +1,21238 @@
+\input texinfo.tex    @c -*-texinfo-*-
+@c $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
+@c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
+@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
+
+@c Everything between the start/end of header lines will be passed by
+@c XEmacs's {texinfo,makeinfo}-format region commands.  See the `start of
+@c header' node for more info.
+@c %**start of header
+@c Synced up with: Texinfo 4.13 of Sep 18, 2008.
+@c Synced by: Ben Wing, 2-17-10.
+
+@c makeinfo and texinfo.tex ignore all text before @setfilename.
+@c
+@c Ordinarily, the setfilename argument ends with .info.  But
+@c texinfo.info-13 is too long for 14-character filesystems.
+@setfilename ../../info/texinfo.info
+
+@c Automake automatically updates version.texi to @set VERSION and
+@c @set UPDATED to appropriate values.
+@include version.texi
+@c XEmacs: @settitle Texinfo @value{edition}
+@settitle GNU Texinfo @value{VERSION}
+
+@c Define a new index for options.
+@defcodeindex op
+@c Put everything except function (command, in this case) names in one
+@c index (arbitrarily chosen to be the concept index).
+@syncodeindex op cp
+@syncodeindex vr cp
+@syncodeindex pg cp
+
+@paragraphindent 2
+@c finalout
+
+@comment %**end of header
+
+@copying
+This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
+a documentation system that can produce both online information and a
+printed manual from a single source.
+
+Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
+Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
+this GNU Manual.  Buying copies from GNU Press supports the FSF in
+developing GNU and promoting software freedom.''
+@end quotation
+@end copying
+
+@dircategory Texinfo documentation system
+@direntry
+* Texinfo: (texinfo).           The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
+* texi2pdf: (texinfo)PDF Output.                PDF output for Texinfo.
+* pdftexi2dvi: (texinfo)PDF Output.             PDF output for Texinfo.
+* texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
+* makeinfo: (texinfo)Invoking makeinfo.         Translate Texinfo source.
+@end direntry
+
+@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
+@c prefix arg).  This updates the node pointers, which texinfmt.el needs.
+
+@c Set smallbook if printing in smallbook format so the example of the
+@c smallbook font is actually written using smallbook; in bigbook, a kludge
+@c is used for TeX output.  Do this through the -t option to texi2dvi,
+@c so this same source can be used for other paper sizes as well.
+@c smallbook
+@c set smallbook
+@c @@clear smallbook
+
+@c If you like blank pages, add through texi2dvi -t.
+@c setchapternewpage odd
+
+@c Currently undocumented command, 5 December 1993:
+@c nwnode          (Same as node, but no warnings; for `makeinfo'.)
+
+
+@shorttitlepage GNU Texinfo
+
+@titlepage
+@title Texinfo
+@subtitle The GNU Documentation Format
+@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
+
+@author Robert J. Chassell
+@author Richard M. Stallman
+
+@c Include the Distribution inside the titlepage so
+@c that headings are turned off.
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+@sp 1
+Published by the Free Software Foundation @*
+51 Franklin St, Fifth Floor @*
+Boston, MA 02110-1301 @*
+USA @*
+ISBN 1-882114-67-1 @c for version 4.0, September 1999.
+@c ISBN 1-882114-65-5 is for version 3.12, March 1998.
+@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
+@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
+
+@sp 1
+Cover art by Etienne Suvasa.
+@end titlepage
+
+
+@summarycontents
+@contents
+
+
+@ifnottex
+@node Top
+@top Texinfo
+
+This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
+a documentation system that can produce both online information and a
+printed manual from a single source.
+
+The first part of this master menu lists the major nodes in this Info
+document, including the @@-command and concept indices.  The rest of
+the menu lists all the lower level nodes in the document.
+
+@end ifnottex
+
+@menu
+* Copying Conditions::            Your rights.
+* Overview::                      Texinfo in brief.
+* Texinfo Mode::                  Using the XEmacs Texinfo mode.
+* Beginning a File::              What is at the beginning of a Texinfo file?
+* Ending a File::                 What is at the end of a Texinfo file?
+* Structuring::                   Creating chapters, sections, appendices, etc.
+* Nodes::                         Writing nodes, the basic unit of Texinfo.
+* Menus::                         Writing menus.
+* Cross References::              Writing cross references.
+* Marking Text::                  Marking words and phrases as code,
+                                    keyboard input, meta-syntactic
+                                    variables, and the like.
+* Quotations and Examples::       Block quotations, examples, etc.
+* Lists and Tables::              Itemized or numbered lists, and tables.
+* Special Displays::              Floating figures and footnotes.
+* Indices::                       Creating indices.
+* Insertions::                    Inserting @@-signs, braces, etc.
+* Breaks::                        Forcing or preventing line and page breaks.
+* Definition Commands::           Describing functions and the like uniformly.
+* Conditionals::                  Specifying text for only some output cases.
+* Internationalization::          Supporting languages other than English.
+* Defining New Texinfo Commands:: User-defined macros and aliases.
+* Hardcopy::                            Output for paper, with @TeX{}.
+* Creating and Installing Info Files::  Details on Info output.
+* Generating HTML::               Details on HTML output.
+
+* Command List::                  All the Texinfo @@-commands.
+* Tips::                          Hints on how to write a Texinfo document.
+* Sample Texinfo Files::          Complete examples, including full texts.
+* Include Files::                 How to incorporate other Texinfo files.
+* Headings::                      How to write page headings and footings.
+* Catching Mistakes::             How to find formatting mistakes.
+* GNU Free Documentation License::Copying this manual.
+* Command and Variable Index::    A menu containing commands and variables.
+* General Index::                 A menu covering many topics.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs::              Submitting effective bug reports.
+* Using Texinfo::               Create printed or online output.
+* Output Formats::              Overview of the supported output formats.
+* Info Files::                  What is an Info file?
+* Printed Books::               Characteristics of a printed book or manual.
+* Formatting Commands::         @@-commands are used for formatting.
+* Conventions::                 General rules for writing a Texinfo file.
+* Comments::                    Writing comments and ignored text in general.
+* Minimum::                     What a Texinfo file must have.
+* Six Parts::                   Usually, a Texinfo file has six parts.
+* Short Sample::                A short sample Texinfo file.
+* History::                     Acknowledgements, contributors and genesis.
+
+Using Texinfo Mode
+
+* Texinfo Mode Overview::       How Texinfo mode can help you.
+* XEmacs Editing::               Texinfo mode adds to XEmacs' 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.
+
+Updating Nodes and Menus
+
+* 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.
+
+Beginning a Texinfo File
+
+* Sample Beginning::            A sample beginning for a Texinfo file.
+* Texinfo File Header::         The first lines.
+* Document Permissions::        Ensuring your manual is free.
+* Titlepage & Copyright Page::  Creating the title and copyright pages.
+* Contents::                    How to create a table of contents.
+* The Top Node::                Creating the `Top' node and master menu.
+* Global Document Commands::    Affecting formatting throughout.
+* Software Copying Permissions::  Ensure that you and others continue to
+                                   have the right to use and share software.
+
+Texinfo File Header
+
+* 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.
+* End of Header::               Formatting a region requires this.
+
+Document Permissions
+
+* copying::                     Declare the document's copying permissions.
+* insertcopying::               Where to insert the permissions.
+
+Title and Copyright Pages
+
+* titlepage::                   Create a title for the printed document.
+* titlefont center sp::         The @code{@@titlefont}, @code{@@center},
+                                 and @code{@@sp} commands.
+* title subtitle author::       The @code{@@title}, @code{@@subtitle},
+                                 and @code{@@author} commands.
+* Copyright::                   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.
+
+The `Top' Node and Master Menu
+
+* Top Node Example::
+* Master Menu Parts::
+
+Global Document Commands
+
+* documentdescription::         Document summary for the HTML output.
+* setchapternewpage::           Start chapters on right-hand pages.
+* paragraphindent::             Specify paragraph indentation.
+* firstparagraphindent::        Suppress indentation of the first paragraph.
+* exampleindent::               Specify environment indentation.
+
+Ending a Texinfo File
+
+* Printing Indices & Menus::    How to print an index in hardcopy and
+                                 generate index menus in Info.
+* File End::                    How to mark the end of a file.
+
+Chapter Structuring
+
+* Tree Structuring::            A manual is like an upside down tree @dots{}
+* Structuring Command Types::   How to divide a manual into parts.
+* makeinfo top::                The @code{@@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.
+
+Nodes
+
+* Two Paths::                   Different commands to structure
+                                 Info output and printed output.
+* Node Menu Illustration::      A diagram, and sample nodes and menus.
+* node::                        Creating nodes, in detail.
+* makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
+* anchor::                      Defining arbitrary cross-reference targets.
+
+The @code{@@node} Command
+
+* Node Names::                  How to choose node and pointer names.
+* Writing a Node::              How to write an @code{@@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 @code{@@top} command.
+
+Menus
+
+* Menu Location::               Menus go at the ends of short nodes.
+* 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.
+
+Cross References
+
+* 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' @dots{}
+* 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.
+* cite::                        How to refer to books not in the Info system.
+
+@code{@@xref}
+
+* Reference Syntax::            What a reference looks like and requires.
+* One Argument::                @code{@@xref} with one argument.
+* Two Arguments::               @code{@@xref} with two arguments.
+* Three Arguments::             @code{@@xref} with three arguments.
+* Four and Five Arguments::     @code{@@xref} with four and five arguments.
+
+Marking Words and Phrases
+
+* Indicating::                  How to indicate definitions, files, etc.
+* Emphasis::                    How to emphasize text.
+
+Indicating Definitions, Commands, etc.
+
+* Useful Highlighting::         Highlighting provides useful information.
+* code::                        Indicating program code.
+* kbd::                         Showing keyboard input.
+* key::                         Specifying keys.
+* samp::                        A literal sequence of characters.
+* verb::                        A verbatim sequence of characters.
+* var::                         Indicating metasyntactic variables.
+* env::                         Indicating environment variables.
+* file::                        Indicating file names.
+* command::                     Indicating command names.
+* option::                      Indicating option names.
+* dfn::                         Specifying definitions.
+* abbr::                        Indicating abbreviations.
+* acronym::                     Indicating acronyms.
+* indicateurl::                 Indicating a World Wide Web reference.
+* email::                       Indicating an electronic mail address.
+
+Emphasizing Text
+
+* emph & strong::               How to emphasize text in Texinfo.
+* Smallcaps::                   How to use the small caps font.
+* Fonts::                       Various font commands for printed output.
+
+Quotations and Examples
+
+* Block Enclosing Commands::    Different constructs for different purposes.
+* quotation::                   Writing a quotation.
+* example::                     Writing an example in a fixed-width font.
+* verbatim::                    Writing a verbatim example.
+* verbatiminclude::             Including a file verbatim.
+* lisp::                        Illustrating Lisp code.
+* small::                       Examples in a smaller font.
+* display::                     Writing an example in the current font.
+* format::                      Writing an example without narrowed margins.
+* exdent::                      Undo indentation on a line.
+* flushleft & flushright::      Pushing text flush left or flush right.
+* noindent::                    Preventing paragraph indentation.
+* indent::                      Forcing paragraph indentation.
+* cartouche::                   Drawing rounded rectangles around examples.
+
+Lists and Tables
+
+* 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.
+
+Making a Two-column Table
+
+* 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.
+
+@code{@@multitable}: Multi-column Tables
+
+* Multitable Column Widths::    Defining multitable column widths.
+* Multitable Rows::             Defining multitable rows, with examples.
+
+Special Displays
+
+* Floats::                      Figures, tables, and the like.
+* Images::                      Including graphics and images.
+* Footnotes::                   Writing footnotes.
+
+Floats
+
+* float::                       Producing floating material.
+* caption shortcaption::        Specifying descriptions for floats.
+* listoffloats::                A table of contents for floats.
+
+Inserting Images
+
+* Image Syntax::
+* Image Scaling::
+
+Footnotes
+
+* Footnote Commands::           How to write a footnote in Texinfo.
+* Footnote Styles::             Controlling how footnotes appear in Info.
+
+Indices
+
+* Index Entries::               Choose different words for index entries.
+* Predefined Indices::          Use different indices for different kinds
+                                 of entries.
+* Indexing Commands::           How to make an index entry.
+* Combining Indices::           How to combine indices.
+* New Indices::                 How to define your own indices.
+
+Combining Indices
+
+* syncodeindex::                How to merge two indices, using @code{@@code}
+                                 font for the merged-from index.
+* synindex::                    How to merge two indices, using the
+                                 default font of the merged-to index.
+
+Special Insertions
+
+* Atsign Braces Comma::         Inserting @@ and @{@} and ,.
+* Inserting Quote Characters::  Inserting left and right quotes, in code.
+* Inserting Space::             How to insert the right amount of space
+                                 within a sentence.
+* Inserting Accents::           How to insert accents and special characters.
+* Inserting Quotation Marks::   How to insert quotation marks.
+* Dots Bullets::                How to insert dots and bullets.
+* TeX and copyright::           How to insert the @TeX{} logo
+                                 and the copyright symbol.
+* euro::                        How to insert the Euro currency symbol.
+* pounds::                      How to insert the pounds currency symbol.
+* textdegree::                  How to insert the degrees symbol.
+* minus::                       How to insert a minus sign.
+* geq leq::                     How to insert greater/less-than-or-equal signs.
+* math::                        How to format a mathematical expression.
+* Click Sequences::             Inserting GUI usage sequences.
+* Glyphs::                      How to indicate results of evaluation,
+                                 expansion of macros, errors, etc.
+
+Inserting @@ and @{@} and @comma{}
+
+* Inserting an Atsign::
+* Inserting Braces::
+* Inserting a Comma::
+
+Inserting Space
+
+* Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
+* Ending a Sentence::           Sometimes it does.
+* Multiple Spaces::             Inserting multiple spaces.
+* frenchspacing::               Specifying end-of-sentence spacing.
+* dmn::                         How to format a dimension.
+
+Inserting Ellipsis and Bullets
+
+* dots::                        How to insert dots @dots{}
+* bullet::                      How to insert a bullet.
+
+Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{}
+
+* tex::                         The @TeX{} logos.
+* copyright symbol::            The copyright symbol (c in a circle).
+* registered symbol::           The registered symbol (R in a circle).
+
+Glyphs for Examples
+
+* 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.
+
+Glyphs Summary
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+Forcing and Preventing Breaks
+
+* Break Commands::              Summary of break-related commands.
+* Line Breaks::                 Forcing line breaks.
+* - and hyphenation::           Helping @TeX{} with hyphenation points.
+* allowcodebreaks::             Controlling line breaks within @@code text.
+* w::                           Preventing unwanted line breaks in text.
+* tie::                         Inserting an unbreakable but varying space.
+* sp::                          Inserting blank lines.
+* page::                        Forcing the start of a new page.
+* group::                       Preventing unwanted page breaks.
+* need::                        Another way to prevent unwanted page breaks.
+
+Definition Commands
+
+* Def Cmd Template::            Writing descriptions using definition commands.
+* Def Cmd Continuation Lines::  Continuing the heading over source lines.
+* Optional Arguments::          Handling optional and repeated arguments.
+* deffnx::                      Group two or more `first' lines.
+* Def Cmds in Detail::          Reference for all the definition commands.
+* Def Cmd Conventions::         Conventions for writing definitions.
+* Sample Function Definition::  An example.
+
+The Definition Commands
+
+* Functions Commands::          Commands for functions and similar entities.
+* Variables Commands::          Commands for variables and similar entities.
+* Typed Functions::             Commands for functions in typed languages.
+* Typed Variables::             Commands for variables in typed languages.
+* Data Types::                  The definition command for data types.
+* Abstract Objects::            Commands for object-oriented programming.
+
+Object-Oriented Programming
+
+* Variables: Object-Oriented Variables.
+* Methods: Object-Oriented Methods.
+
+Conditionally Visible Text
+
+* Conditional Commands::        Text for a given format.
+* Conditional Not Commands::    Text for any format other than a given one.
+* Raw Formatter Commands::      Using raw formatter commands.
+* set clear value::             Variable tests and substitutions.
+* Conditional Nesting::         Using conditionals inside conditionals.
+
+@code{@@set}, @code{@@clear}, and @code{@@value}
+
+* set value::                   Expand a flag variable to a string.
+* ifset ifclear::               Format a region if a flag is set.
+* value Example::               An easy way to update edition information.
+
+Internationalization
+
+* documentlanguage::            Declaring the current language.
+* documentencoding::            Declaring the input encoding.
+
+Defining New Texinfo Commands
+
+* Defining Macros::             Defining and undefining new commands.
+* Invoking Macros::             Using a macro, once you've defined it.
+* Macro Details::               Limitations of Texinfo macros.
+* alias::                       Command aliases.
+* definfoenclose::              Customized highlighting.
+
+Formatting and Printing Hardcopy
+
+* Use TeX::                     Use @TeX{} to format for hardcopy.
+* Format with tex/texindex::    How to format with explicit shell commands.
+* Format with texi2dvi::        A simpler way to format.
+* Print with lpr::              How to print.
+* Within XEmacs::                How to format and print from an XEmacs shell.
+* Texinfo Mode Printing::       How to format and print in Texinfo mode.
+* Compile-Command::             How to print using XEmacs's compile command.
+* Requirements Summary::        @TeX{} formatting requirements summary.
+* Preparing for TeX::           What to do before you use @TeX{}.
+* Overfull hboxes::             What are and what to do with overfull hboxes.
+* smallbook::                   How to print small format books and manuals.
+* A4 Paper::                    How to print on A4 or A5 paper.
+* pagesizes::                   How to print with customized page sizes.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+                                 of pages and how to print scaled up output.
+* PDF Output::                  Portable Document Format output.
+* Obtaining TeX::               How to Obtain @TeX{}.
+
+Creating and Installing Info Files
+
+* Creating an Info File::
+* Installing an Info File::
+
+Creating an Info File
+
+* makeinfo advantages::         @code{makeinfo} provides better error checking.
+* Invoking makeinfo::           How to run @code{makeinfo} from a shell.
+* makeinfo options::            Specify fill-column and other options.
+* Pointer Validation::          How to check that pointers point somewhere.
+* makeinfo in XEmacs::           How to run @code{makeinfo} from XEmacs.
+* texinfo-format commands::     Two Info formatting commands written
+                                 in XEmacs Lisp are an alternative
+                                 to @code{makeinfo}.
+* Batch Formatting::            How to format for Info in XEmacs Batch mode.
+* Tag and Split Files::         How tagged and split files help Info
+                                 to run better.
+
+Installing an Info File
+
+* Directory File::              The top level menu for all Info files.
+* New Info File::               Listing a new Info file.
+* Other Info Directories::      How to specify Info files that are
+                                 located in other directories.
+* Installing Dir Entries::      How to specify what menu entry to add
+                                 to the Info directory.
+* Invoking install-info::       @code{install-info} options.
+
+Generating HTML
+
+* HTML Translation::       Details of the HTML output.
+* HTML Splitting::         How HTML output is split.
+* HTML CSS::               Influencing HTML output with Cascading Style Sheets.
+* HTML Xref::              Cross-references in HTML output.
+
+HTML Cross-references
+
+* Link Basics:       HTML Xref Link Basics.
+* Node Expansion:    HTML Xref Node Name Expansion.
+* Command Expansion: HTML Xref Command Expansion.
+* 8-bit Expansion:   HTML Xref 8-bit Character Expansion.
+* Mismatch:          HTML Xref Mismatch.
+
+@@-Command List
+
+* Command Syntax::    General syntax for varieties of @@-commands.
+
+Sample Texinfo Files
+
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+* Verbatim Copying License::
+* All-permissive Copying License::
+
+GNU Free Documentation License
+
+Include Files
+
+* Using Include Files::         How to use the @code{@@include} command.
+* texinfo-multiple-files-update::  How to create and update nodes and
+                                     menus when using included files.
+* Include Files Requirements::  @code{texinfo-multiple-files-update} needs.
+* Sample Include File::         A sample outer file with included files
+                                     within it; and a sample included file.
+* Include Files Evolution::     How use of the @code{@@include} command
+                                     has changed over time.
+
+Page Headings
+
+* Headings Introduced::         Conventions for using page headings.
+* Heading Format::              Standard page heading formats.
+* Heading Choice::              How to specify the type of page heading.
+* Custom Headings::             How to create your own headings and footings.
+
+Formatting Mistakes
+
+* makeinfo Preferred::          @code{makeinfo} finds errors.
+* Debugging with Info::         How to catch errors with Info formatting.
+* Debugging with TeX::          How to catch errors with @TeX{} formatting.
+* Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
+* Using occur::                 How to list all lines containing a pattern.
+* Running Info-Validate::       How to find badly referenced nodes.
+
+Finding Badly Referenced Nodes
+
+* Using Info-validate::         How to run @code{Info-validate}.
+* Unsplit::                     How to create an unsplit file.
+* Tagifying::                   How to tagify a file.
+* Splitting::                   How to split a file manually.
+
+@end detailmenu
+@end menu
+
+@c Reward readers for getting to the end of the menu :).
+@c Contributed by Arnold Robbins.
+@quotation
+Documentation is like sex: when it is good, it is very, very good; and
+when it is bad, it is better than nothing.
+---Dick Brandon
+@end quotation
+
+
+@node Copying Conditions
+@unnumbered Texinfo Copying Conditions
+@cindex Copying conditions
+@cindex Conditions for copying Texinfo
+
+The programs currently being distributed that relate to Texinfo include
+@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
+These programs are @dfn{free}; this means that everyone is free to use
+them and free to redistribute them on a free basis.  The Texinfo-related
+programs are not in the public domain; they are copyrighted and there
+are restrictions on their distribution, but these restrictions are
+designed to permit everything that a good cooperating citizen would want
+to do.  What is not allowed is to try to prevent others from further
+sharing any version of these programs that they might get from you.
+
+Specifically, we want to make sure that you have the right to give away
+copies of the programs that relate to Texinfo, that you receive source
+code or else can get it if you want it, that you can change these
+programs or use pieces of them in new free programs, and that you know
+you can do these things.
+
+To make sure that everyone has such rights, we have to forbid you to
+deprive anyone else of these rights.  For example, if you distribute
+copies of the Texinfo related programs, you must give the recipients all
+the rights that you have.  You must make sure that they, too, receive or
+can get the source code.  And you must tell them their rights.
+
+Also, for our own protection, we must make certain that everyone finds
+out that there is no warranty for the programs that relate to Texinfo.
+If these programs are modified by someone else and passed on, we want
+their recipients to know that what they have is not what we distributed,
+so that any problems introduced by others will not reflect on our
+reputation.
+
+The precise conditions of the licenses for the programs currently being
+distributed that relate to Texinfo are found in the General Public
+Licenses that accompany them.  This manual specifically is covered by
+the GNU Free Documentation License (@pxref{GNU Free Documentation
+License}).
+
+
+@node Overview
+@chapter Overview of Texinfo
+@cindex Overview of Texinfo
+@cindex Texinfo overview
+
+@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
+like ``speck'', not ``hex''.  This odd pronunciation is derived from,
+but is not the same as, the pronunciation of @TeX{}.  In the word
+@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
+the English letter ``ex''.  Pronounce @TeX{} as if the @samp{X} were the
+last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
+were a `k'.  Spell ``Texinfo'' with a capital ``T'' and the other
+letters in lower case.}  is a documentation system that uses a single
+source file to produce both online information and printed output.  This
+means that instead of writing two different documents, one for the
+online information and the other for a printed work, you need write only
+one document.  Therefore, when the work is revised, you need revise only
+that one document.
+
+Manuals for most GNU packages are written in Texinfo, and available
+online at @url{http://www.gnu.org/doc}.
+
+@menu
+* Reporting Bugs::              Submitting effective bug reports.
+* Using Texinfo::               Create printed or online output.
+* Output Formats::              Overview of the supported output formats.
+* Info Files::                  What is an Info file?
+* Printed Books::               Characteristics of a printed book or manual.
+* Formatting Commands::         @@-commands are used for formatting.
+* Conventions::                 General rules for writing a Texinfo file.
+* Comments::                    Writing comments and ignored text in general.
+* Minimum::                     What a Texinfo file must have.
+* Six Parts::                   Usually, a Texinfo file has six parts.
+* Short Sample::                A short sample Texinfo file.
+* History::                     Acknowledgements, contributors and genesis.
+@end menu
+
+
+@node Reporting Bugs
+@section Reporting Bugs
+
+@cindex Bugs, reporting
+@cindex Suggestions for Texinfo, making
+@cindex Reporting bugs
+We welcome bug reports and suggestions for any aspect of the Texinfo system,
+programs, documentation, installation, anything.  Please email them to
+@email{bug-texinfo@@gnu.org}.  You can get the latest version of Texinfo
+from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
+
+@cindex Checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem.  Generally speaking, that means:
+
+@itemize @bullet
+@item the version number of Texinfo and the program(s) or manual(s) involved.
+@item hardware and operating system names and versions.
+@item the contents of any input files necessary to reproduce the bug.
+@item a description of the problem and samples of any erroneous output.
+@item any unusual options you gave to @command{configure}.
+@item anything else that you think would be helpful.
+@end itemize
+
+When in doubt whether something is needed or not, include it.  It's
+better to include too much than to leave out something important.
+
+@cindex Patches, contributing
+Patches are most welcome; if possible, please make them with
+@samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging
+Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,,
+xemacs, XEmacs User's Manual}), and follow the existing coding style.
+
+
+@node Using Texinfo
+@section Using Texinfo
+
+@cindex Using Texinfo in general
+@cindex Texinfo, introduction to
+@cindex Introduction to Texinfo
+
+Using Texinfo, you can create a printed document (via the @TeX{}
+typesetting system) the normal features of a book, including chapters,
+sections, cross references, and indices.  From the same Texinfo source
+file, you can create an Info file with special features to make
+documentation browsing easy.  You can also create from that same
+source file an HTML output file suitable for use with a web browser,
+or an XML file.  See the next section (@pxref{Output Formats}) for
+details and the exact commands to generate output from the source.
+
+@TeX{} works with virtually all printers; Info works with virtually all
+computer terminals; the HTML output works with virtually all web
+browsers.  Thus Texinfo can be used by almost any computer user.
+
+@cindex Source file format
+A Texinfo source file is a plain ASCII file containing text
+interspersed with @dfn{@@-commands} (words preceded by an @samp{@@})
+that tell the typesetting and formatting programs what to do.  You can
+edit a Texinfo file with any text editor, but it is especially
+convenient to use XEmacs since that editor has a special mode,
+called Texinfo mode, that provides various Texinfo-related features.
+(@xref{Texinfo Mode}.)
+
+You can use Texinfo to create both online help and printed manuals;
+moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
+is the official documentation format of the GNU project.  More
+information is available at the @uref{http://www.gnu.org/doc/, GNU
+documentation web page}.
+
+
+@node Output Formats
+@section Output Formats
+@cindex Output formats
+@cindex Back-end output formats
+
+Here is a brief overview of the output formats currently supported by
+Texinfo.
+
+@table @asis
+@item Info
+@cindex Info output
+(Generated via @command{makeinfo}.)  This format is essentially a
+plain text transliteration of the Texinfo source.  It adds a few
+control characters to separate nodes and provide navigational
+information for menus, cross-references, indices, and so on.  See the
+next section (@pxref{Info Files}) for more details on this format.
+The XEmacs Info subsystem (@pxref{Top,,Getting Started,info, Info}),
+and the standalone @command{info} program (@pxref{Top
+,, Info Standalone, info-stnd, GNU Info}), among others, can read these
+files.  @xref{Creating and Installing Info Files}.
+
+@item Plain text
+@cindex Plain text output
+(Generated via @command{makeinfo --no-headers}.)  This is almost the
+same as Info output, except the navigational control characters are
+omitted.  Also, standard output is used by default.
+
+@item HTML
+@cindex HTML output
+@cindex W3 consortium
+@cindex Mozilla
+@cindex Lynx
+@cindex Emacs-W3
+(Generated via @command{makeinfo --html}.)  This is the Hyper Text
+Markup Language that has become the most commonly used language for
+writing documents on the World Wide Web.  Web browsers, such as
+Mozilla, Lynx, and Emacs-W3, can render this language online.  There
+are many versions of HTML; @command{makeinfo} tries to use a subset
+of the language that can be interpreted by any common browser.  For
+details of the HTML language and much related information, see
+@uref{http://www.w3.org/MarkUp/}.  @xref{Generating HTML}.
+
+@item DVI
+@cindex DVI output
+@pindex dvips
+@pindex xdvi
+(Generated via @command{texi2dvi}.)  This DeVice Independent binary
+format is output by the @TeX{} typesetting program
+(@uref{http://tug.org}).  This is then read by a DVI `driver', which
+writes the actual device-specific commands that can be viewed or
+printed, notably Dvips for translation to PostScript (@pxref{Invoking
+Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display
+(@uref{http://sourceforge.net/projects/xdvi/}).  @xref{Hardcopy}.
+
+Be aware that the Texinfo language is very different from and much
+stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}.
+For more information on @TeX{} in general, please see the book
+@cite{@TeX{} for the Impatient}, available from
+@uref{http://savannah.gnu.org/projects/teximpatient}.
+
+@item PDF
+@cindex PDF output
+@cindex Beebe, Nelson
+@pindex pdftex
+(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.)  This
+format was developed by Adobe Systems for portable document
+interchange, based on their previous PostScript language.  It can
+represent the exact appearance of a document, including fonts and
+graphics, and supporting arbitrary scaling.  It is intended to be
+platform-independent and easily viewable, among other design goals;
+@uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has
+some background.  Texinfo uses the @command{pdftex} program, a variant
+of @TeX{}, to output PDF; see
+@uref{http://tug.org/applications/pdftex}.  @xref{PDF Output}.
+
+@item XML
+@cindex XML output
+@cindex DTD, for Texinfo XML
+@pindex texinfo.dtd
+(Generated via @command{makeinfo --xml}.)  XML is a generic syntax
+specification usable for any sort of content (see, for example,
+@uref{http://www.w3.org/XML/}).  The @command{makeinfo} XML output,
+unlike all the formats above, interprets very little of the Texinfo
+source.  Rather, it merely translates the Texinfo markup commands into
+XML syntax, for processing by further XML tools.  The particular
+syntax output is defined in the file @file{texinfo.dtd} included in
+the Texinfo source distribution.
+
+@item Docbook
+@cindex Docbook output
+(Generated via @command{makeinfo --docbook}.)  This is an XML-based
+format developed some years ago, primarily for technical
+documentation.  It therefore bears some resemblance, in broad
+outlines, to Texinfo.  See @uref{http://www.docbook.org}.  If you want
+to convert from Docbook @emph{to} Texinfo, please see
+@uref{http://docbook2X.sourceforge.net}.
+
+@end table
+
+@cindex Man page output, not supported
+From time to time, proposals are made to generate traditional Unix man
+pages from Texinfo source.  However, because man pages have a very
+strict conventional format, generating a good man page requires a
+completely different source than the typical Texinfo applications of
+writing a good user tutorial and/or a good reference manual.  This
+makes generating man pages incompatible with the Texinfo design goal
+of not having to document the same information in different ways for
+different output formats.  You might as well just write the man page
+directly.
+
+@pindex help2man
+@cindex O'Dea, Brendan
+Man pages still have their place, and if you wish to support them, you
+may find the program @command{help2man} to be useful; it generates a
+traditional man page from the @samp{--help} output of a program.  In
+fact, this is currently used to generate man pages for the programs in
+the Texinfo distribution.  It is GNU software written by Brendan
+O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}.
+
+@cindex Output formats, supporting more
+@cindex SGML-tools output format
+If you are a programmer and would like to contribute to the GNU project
+by implementing additional output formats for Texinfo, that would be
+excellent.  But please do not write a separate translator texi2foo for
+your favorite format foo!  That is the hard way to do the job, and makes
+extra work in subsequent maintenance, since the Texinfo language is
+continually being enhanced and updated.  Instead, the best approach is
+modify @code{makeinfo} to generate the new format.
+
+
+@node Info Files
+@section Info Files
+@cindex Info files
+
+An Info file is a Texinfo file formatted so that the Info documentation
+reading program can operate on it.  (@code{makeinfo}
+and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
+into an Info file.)
+
+Info files are divided into pieces called @dfn{nodes}, each of which
+contains the discussion of one topic.  Each node has a name, and
+contains both text for the user to read and pointers to other nodes,
+which are identified by their names.  The Info program displays one node
+at a time, and provides commands with which the user can move to other
+related nodes.
+
+@xref{Top,,, info, GNU Info}, for more information about using Info.
+
+Each node of an Info file may have any number of child nodes that
+describe subtopics of the node's topic.  The names of child
+nodes are listed in a @dfn{menu} within the parent node; this
+allows you to use certain Info commands to move to one of the child
+nodes.  Generally, an Info file is organized like a book.  If a node
+is at the logical level of a chapter, its child nodes are at the level
+of sections; likewise, the child nodes of sections are at the level
+of subsections.
+
+All the children of any one parent are linked together in a
+bidirectional chain of `Next' and `Previous' pointers.  The `Next'
+pointer provides a link to the next section, and the `Previous' pointer
+provides a link to the previous section.  This means that all the nodes
+that are at the level of sections within a chapter are linked together.
+Normally the order in this chain is the same as the order of the
+children in the parent's menu.  Each child node records the parent node
+name as its `Up' pointer.  The last child has no `Next' pointer, and the
+first child has the parent both as its `Previous' and as its `Up'
+pointer.@footnote{In some documents, the first child has no `Previous'
+pointer.  Occasionally, the last child has the node name of the next
+following higher level node as its `Next' pointer.}
+
+The book-like structuring of an Info file into nodes that correspond
+to chapters, sections, and the like is a matter of convention, not a
+requirement.  The `Up', `Previous', and `Next' pointers of a node can
+point to any other nodes, and a menu can contain any other nodes.
+Thus, the node structure can be any directed graph.  But it is usually
+more comprehensible to follow a structure that corresponds to the
+structure of chapters and sections in a printed book or report.@refill
+
+In addition to menus and to `Next', `Previous', and `Up' pointers, Info
+provides pointers of another kind, called references, that can be
+sprinkled throughout the text.  This is usually the best way to
+represent links that do not fit a hierarchical structure.@refill
+
+Usually, you will design a document so that its nodes match the
+structure of chapters and sections in the printed output.  But
+occasionally there are times when this is not right for the material
+being discussed.  Therefore, Texinfo uses separate commands to specify
+the node structure for the Info file and the section structure for the
+printed output.@refill
+
+Generally, you enter an Info file through a node that by convention is
+named `Top'.  This node normally contains just a brief summary of the
+file's purpose, and a large menu through which the rest of the file is
+reached.  From this node, you can either traverse the file
+systematically by going from node to node, or you can go to a specific
+node listed in the main menu, or you can search the index menus and then
+go directly to the node that has the information you want.  Alternatively,
+with the standalone Info program, you can specify specific menu items on
+the command line (@pxref{Top,,, info, Info}).
+
+If you want to read through an Info file in sequence, as if it were a
+printed manual, you can hit @key{SPC} repeatedly, or you get the whole
+file with the advanced Info command @kbd{g *}.  (@inforef{Advanced,
+Advanced Info commands, info}.)@refill
+
+@c !!! dir file may be located in one of many places:
+@c     /usr/local/xemacs/info            mentioned in info.c DEFAULT_INFOPATH
+@c     /usr/local/lib/xemacs/info        mentioned in info.c DEFAULT_INFOPATH
+@c     /usr/gnu/info                    mentioned in info.c DEFAULT_INFOPATH
+@c     /usr/local/info
+@c     /usr/local/lib/info
+The @file{dir} file in the @file{info} directory serves as the
+departure point for the whole Info system.  From it, you can reach the
+`Top' nodes of each of the documents in a complete Info system.@refill
+
+@cindex URI syntax for Info
+If you wish to refer to an Info file in a URI, you can use the
+(unofficial) syntax exemplified in the following.  This works with
+Emacs/W3, for example:
+@example
+info:///usr/info/xemacs#Dissociated%20Press
+info:xemacs#Dissociated%20Press
+info://localhost/usr/info/xemacs#Dissociated%20Press
+@end example
+
+The @command{info} program itself does not follow URIs of any kind.
+
+
+@node Printed Books
+@section Printed Books
+@cindex Printed book and manual characteristics
+@cindex Manual characteristics, printed
+@cindex Book characteristics, printed
+@cindex Texinfo printed book characteristics
+@cindex Characteristics, printed books or manuals
+
+@cindex Knuth, Donald
+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.@footnote{You can also use the
+@pindex texi2roff@r{, unsupported software}
+@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
+do not have @TeX{}; since Texinfo is designed for use with @TeX{},
+@code{texi2roff} is not described here.  @code{texi2roff} is not part of
+the standard GNU distribution and is not maintained or up-to-date with
+all the Texinfo features described in this manual.}
+
+A Texinfo-based book is similar to any other typeset, printed work: it
+can have a title page, copyright page, table of contents, and preface,
+as well as chapters, numbered or unnumbered sections and subsections,
+page headers, cross references, footnotes, and indices.@refill
+
+You can use Texinfo to write a book without ever having the intention
+of converting it into online information.  You can use Texinfo for
+writing a printed novel, and even to write a printed memo, although
+this latter application is not recommended since electronic mail is so
+much easier.@refill
+
+@TeX{} is a general purpose typesetting program.  Texinfo provides a
+file @file{texinfo.tex} that contains information (definitions or
+@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
+(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
+to @TeX{} commands, which @TeX{} can then process to create the typeset
+document.)  @file{texinfo.tex} contains the specifications for printing
+a document.  You can get the latest version of @file{texinfo.tex} from
+the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
+
+In the United States, documents are most often printed on 8.5 inch by 11
+inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size.  But
+you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
+235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
+(@code{@@afourpaper}, @code{@@afivepaper}).  (@xref{smallbook, ,
+Printing ``Small'' Books}.  Also, see @ref{A4 Paper, ,Printing on A4
+Paper}.)
+
+By changing the parameters in @file{texinfo.tex}, you can change the
+size of the printed document.  In addition, you can change the style in
+which the printed document is formatted; for example, you can change the
+sizes and fonts used, the amount of indentation for each paragraph, the
+degree to which words are hyphenated, and the like.  By changing the
+specifications, you can make a book look dignified, old and serious, or
+light-hearted, young and cheery.
+
+@TeX{} is freely distributable.  It is written in a superset of Pascal
+called WEB and can be compiled either in Pascal or (by using a
+conversion program that comes with the @TeX{} distribution) in C.
+(@xref{TeX Mode, ,@TeX{} Mode, xemacs, XEmacs User's Manual}, for information
+about @TeX{}.)@refill
+
+@TeX{} is very powerful and has a great many features.  Because a
+Texinfo file must be able to present information both on a
+character-only terminal in Info form and in a typeset book, the
+formatting commands that Texinfo supports are necessarily limited.
+
+To get a copy of @TeX{}, see
+@ref{Obtaining TeX, , How to Obtain @TeX{}}.
+
+
+@node Formatting Commands
+@section @@-commands
+@cindex @@-commands
+@cindex Formatting commands
+
+In a Texinfo file, the commands that tell @TeX{} how to typeset the
+printed manual and tell @code{makeinfo} and
+@code{texinfo-format-buffer} how to create an Info file are preceded
+by @samp{@@}; they are called @dfn{@@-commands}.  For example,
+@code{@@node} is the command to indicate a node and @code{@@chapter}
+is the command to indicate the start of a chapter.@refill
+
+@quotation Note
+Almost all @@ command names are entirely lower case.
+@end quotation
+
+The Texinfo @@-commands are a strictly limited set of constructs.  The
+strict limits make it possible for Texinfo files to be understood both
+by @TeX{} and by the code that converts them into Info files.  You can
+display Info files on any terminal that displays alphabetic and
+numeric characters.  Similarly, you can print the output generated by
+@TeX{} on a wide variety of printers.@refill
+
+Depending on what they do or what arguments@footnote{The word
+@dfn{argument} comes from the way it is used in mathematics and does not
+refer to a dispute between two people; it refers to the information
+presented to the command.  According to the @cite{Oxford English
+Dictionary}, the word derives from the Latin for @dfn{to make clear,
+prove}; thus it came to mean `the evidence offered as proof', which is
+to say, `the information offered', which led to its mathematical
+meaning.  In its other thread of derivation, the word came to mean `to
+assert in a manner against which others may make counter assertions',
+which led to the meaning of `argument' as a dispute.} they take, you
+need to write @@-commands on lines of their own or as part of
+sentences:
+
+@itemize @bullet
+@item
+Write a command such as @code{@@quotation} at the beginning of a line as
+the only text on the line.  (@code{@@quotation} begins an indented
+environment.)
+
+@item
+Write a command such as @code{@@chapter} at the beginning of a line
+followed by the command's arguments, in this case the chapter title, on
+the rest of the line.  (@code{@@chapter} creates chapter titles.)@refill
+
+@item
+Write a command such as @code{@@dots@{@}} wherever you wish but usually
+within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill
+
+@item
+Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
+wish (but usually within a sentence) with its argument,
+@var{sample-code} in this example, between the braces.  (@code{@@code}
+marks text as being code.)@refill
+
+@item
+Write a command such as @code{@@example} on a line of its own; write the
+body-text on following lines; and write the matching @code{@@end}
+command, @code{@@end example} in this case, on a line of its own
+after the body-text. (@code{@@example} @dots{} @code{@@end example}
+indents and typesets body-text as an example.)  It's usually ok to
+indent environment commands like this, but in complicated and
+hard-to-define circumstances the extra spaces cause extra space to
+appear in the output, so beware.
+@end itemize
+
+@noindent
+@cindex Braces, when to use
+As a general rule, a command requires braces if it mingles among other
+text; but it does not need braces if it starts a line of its own.  The
+non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
+they do not need braces.@refill
+
+As you gain experience with Texinfo, you will rapidly learn how to
+write the different commands: the different ways to write commands
+actually make it easier to write and read Texinfo files than if all
+commands followed exactly the same syntax.  @xref{Command Syntax, ,
+@@-Command Syntax}, for all the details.
+
+
+@node Conventions
+@section General Syntactic Conventions
+@cindex General syntactic conventions
+@cindex Syntactic conventions
+@cindex Conventions, syntactic
+@cindex Characters, basic input
+
+This section describes the general conventions used in all Texinfo documents.
+
+@itemize @bullet
+@item
+@cindex Source files, characters used
+All printable ASCII characters except @samp{@@}, @samp{@{} and
+@samp{@}} can appear in a Texinfo file and stand for themselves.
+@samp{@@} is the escape character which introduces commands, while
+@samp{@{} and @samp{@}} are used to surround arguments to certain
+commands.  To put one of these special characters into the document, put
+an @samp{@@} character in front of it, like this: @samp{@@@@},
+@samp{@@@{}, and @samp{@@@}}.
+
+@item
+@cindex Paragraph separator
+@cindex Blank lines, as paragraph separator
+@cindex Newlines, as blank lines
+Separate paragraphs with one or more blank lines.  Currently Texinfo
+only recognizes newline characters as end of line, not the CRLF
+sequence used on some systems; so a @dfn{blank line} means exactly two
+consecutive newlines.  Sometimes blank lines are useful or convenient
+in other cases as well; you can use the @code{@@noindent} to inhibit
+paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}).
+
+@item
+Texinfo supports the usual quotation marks used in English, and
+quotation marks used in other languages, please see @ref{Inserting
+Quotation Marks}.
+
+@item
+@cindex Multiple dashes in source
+@cindex Dashes in source
+@cindex Hyphens in source, two or three in a row
+@cindex Em dash, producing
+@cindex En dash, producing
+Use three hyphens in a row, @samp{---}, to produce a long dash---like
+this (called an @dfn{em dash}), used for punctuation in sentences.
+Use two hyphens, @samp{--}, to produce a medium dash (called an
+@dfn{en dash}), used primarily for numeric ranges, as in ``June
+25--26''.  Use a single hyphen, @samp{-}, to produce a standard hyphen
+used in compound words.  For display on the screen, Info reduces three
+hyphens to two and two hyphens to one (not transitively!).  Of course,
+any number of hyphens in the source remain as they are in literal
+contexts, such as @code{@@code} and @code{@@example}.
+
+@item
+@cindex Tabs; don't use!
+@strong{Caution:} Last, do not use tab characters in a Texinfo file
+(except in verbatim modes)!  @TeX{} uses variable-width fonts, which
+means that it is impractical at best to define a tab to work in all
+circumstances.  Consequently, @TeX{} treats tabs like single spaces,
+and that is not what they look like in the source.  Furthermore,
+@code{makeinfo} does nothing special with tabs, and thus a tab
+character in your input file will usually appear differently in the
+output.
+
+@noindent
+To avoid this problem, Texinfo mode in XEmacs inserts
+multiple spaces when you press the @key{TAB} key.  Also, you can run
+@code{untabify} in XEmacs to convert tabs in a region to multiple
+spaces, or use the @code{unexpand} command from the shell.
+
+@end itemize
+
+
+@node Comments
+@section Comments
+
+@cindex Comments
+@findex comment
+@findex c @r{(comment)}
+
+You can write comments in a Texinfo file that will not appear in
+either the Info file or the printed manual by using the
+@code{@@comment} command (which may be abbreviated to @code{@@c}).
+Such comments are for the person who revises the Texinfo file.  All the
+text on a line that follows either @code{@@comment} or @code{@@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 @code{@@comment} or @code{@@c} in the middle of
+a line, and only the text that follows after the @code{@@comment} or
+@code{@@c} command does not appear; but some commands, such as
+@code{@@settitle} and @code{@@setfilename}, work on a whole line.  You
+cannot use @code{@@comment} or @code{@@c} in a line beginning with such
+a command.
+
+@cindex Ignored text
+@cindex Unprocessed text
+@findex ignore
+You can write long stretches of text that will not appear in either
+the Info file or the printed manual by using the @code{@@ignore} and
+@code{@@end ignore} commands.  Write each of these commands on a line
+of its own, starting each command at the beginning of the line.  Text
+between these two commands does not appear in the processed output.
+You can use @code{@@ignore} and @code{@@end ignore} for writing
+comments.
+
+Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
+@code{@@ifclear} conditions is ignored in the sense that it will not
+contribute to the formatted output.  However, @TeX{} and makeinfo must
+still parse the ignored text, in order to understand when to @emph{stop}
+ignoring text from the source file; that means that you may still get
+error messages if you have invalid Texinfo commands within ignored text.
+
+
+@node Minimum
+@section What a Texinfo File Must Have
+@cindex Minimal Texinfo file (requirements)
+@cindex Must have in Texinfo file
+@cindex Required in Texinfo file
+@cindex Texinfo file minimum
+
+By convention, the name of a Texinfo file ends with (in order of
+preference) one of the extensions @file{.texinfo}, @file{.texi},
+@file{.txi}, or @file{.tex}.  The longer extensions are preferred since
+they describe more clearly to a human reader the nature of the file.
+The shorter extensions are for operating systems that cannot handle long
+file names.
+
+In order to be made into a printed manual and an Info file, a Texinfo
+file @strong{must} begin with lines like this:
+
+@example
+@group
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
+@end group
+@end example
+
+@noindent
+The contents of the file follow this beginning, and then you
+@strong{must} end a Texinfo file with a line like this:
+
+@example
+@@bye
+@end example
+
+@findex \input @r{(raw @TeX{} startup)}
+@noindent
+Here's an explanation:
+
+@itemize @bullet
+@item
+The @samp{\input texinfo} line tells @TeX{} to use the
+@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
+@@-commands into @TeX{} typesetting commands.  (Note the use of the
+backslash, @samp{\}; this is correct for @TeX{}.)
+
+@item
+The @code{@@setfilename} line provides a name for the Info file and
+tells @TeX{} to open auxiliary files.  @strong{All text before
+@code{@@setfilename} is ignored!}
+
+@item
+The @code{@@settitle} line specifies a title for the page headers (or
+footers) of the printed manual, and the default document description for
+the @samp{<head>} in HTML format.  Strictly speaking, @code{@@settitle}
+is optional---if you don't mind your document being titled `Untitled'.
+
+@item
+The @code{@@bye} line at the end of the file on a line of its own tells
+the formatters that the file is ended and to stop formatting.
+
+@end itemize
+
+Typically, you will not use quite such a spare format, but will include
+mode setting and start-of-header and end-of-header lines at the
+beginning of a Texinfo file, like this:
+
+@example
+@group
+\input texinfo   @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
+@@c %**end of header
+@end group
+@end example
+
+@noindent
+In the first line, @samp{-*-texinfo-*-} causes XEmacs to switch into
+Texinfo mode when you edit the file.
+
+The @code{@@c} lines which surround the @code{@@setfilename} and
+@code{@@settitle} lines are optional, but you need them in order to
+run @TeX{} or Info on just part of the file.  (@xref{Start of Header}.)
+
+Furthermore, you will usually provide a Texinfo file with a title page,
+indices, and the like, all of which are explained in this manual.  But
+the minimum, which can be useful for short documents, is just the three
+lines at the beginning and the one line at the end.
+
+
+@node Six Parts
+@section Six Parts of a Texinfo File
+
+Generally, a Texinfo file contains more than the minimal beginning and
+end described in the previous section---it usually contains the six
+parts listed below.  These are described fully in the following sections.
+
+@table @r
+@item 1. Header
+The @dfn{Header} names the file, tells @TeX{} which definitions file to
+use, and other such housekeeping tasks.
+
+@item 2. Summary and Copyright
+The @dfn{Summary and Copyright} segment describes the document and
+contains the copyright notice and copying permissions.  This is done
+with the @code{@@copying} command.
+
+@item 3. Title and Copyright
+The @dfn{Title and Copyright} segment contains the title and copyright
+pages for the printed manual.  The segment must be enclosed between
+@code{@@titlepage} and @code{@@end titlepage} commands.  The title and
+copyright page appear only in the printed manual.
+
+@item 4. `Top' Node and Master Menu
+The `Top' node starts off the online output; it does not appear in the
+printed manual.  We recommend including the copying permissions here as
+well as the segments above.  And it contains at least a top-level menu
+listing the chapters, and possibly a @dfn{Master Menu} listing all the
+nodes in the entire document.
+
+@item 5. Body
+The @dfn{Body} of the document is typically structured like a
+traditional book or encyclopedia, but it may be free form.
+
+@item 6. End
+The @dfn{End} segment may contain commands for printing indices, and
+closes with the @code{@@bye} command on a line of its own.
+@end table
+
+
+@node Short Sample
+@section A Short Sample Texinfo File
+@cindex Sample Texinfo file, with comments
+
+Here is a very short but complete Texinfo file, in the six conventional
+parts enumerated in the previous section, so you can see how Texinfo
+source appears in practice.  The first three parts of the file, from
+@samp{\input texinfo} through to @samp{@@end titlepage}, look more
+intimidating than they are: most of the material is standard
+boilerplate; when writing a manual, you simply change the names as
+appropriate.
+
+@xref{Beginning a File}, for full documentation on the commands listed
+here.  @xref{GNU Sample Texts}, for the full texts to be used in GNU
+manuals.
+
+In the following, the sample text is @emph{indented}; comments on it are
+not.  The complete file, without interspersed comments, is shown in
+@ref{Short Sample Texinfo File}.
+
+@subheading Part 1: Header
+
+@noindent
+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.
+
+@example
+@group
+\input texinfo   @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+@end group
+@end example
+
+@subheading Part 2: Summary Description and Copyright
+
+@noindent
+A real manual includes more text here, according to the license under
+which it is distributed.  @xref{GNU Sample Texts}.
+
+@example
+@group
+@@copying
+This is a short example of a complete Texinfo file, version 1.0.
+
+Copyright @@copyright@{@} 2005 Free Software Foundation, Inc.
+@@end copying
+@end group
+@end example
+
+@subheading Part 3: Titlepage, Contents, Copyright
+
+@noindent
+The titlepage segment does not appear in the online output, only in the
+printed manual.  We use the @code{@@insertcopying} command to
+include the permission text from the previous section, instead of
+writing it out again; it is output on the back of the title page.  The
+@code{@@contents} command generates a table of contents.
+
+@example
+@group
+@@titlepage
+@@title Sample Title
+@end group
+
+@group
+@@c The following two commands start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+@end group
+
+@@c Output the table of contents at the beginning.
+@@contents
+@end example
+
+@subheading Part 4: `Top' Node and Master Menu
+
+@noindent
+The `Top' node contains the master menu for the Info file.  Since the
+printed manual uses a table of contents rather than a menu, it
+excludes the `Top' node.  We repeat the short description from the
+beginning of the @samp{@@copying} text, but there's no need to repeat
+the copyright information, so we don't use @samp{@@insertcopying} here.
+The @samp{@@top} command itself helps @command{makeinfo} determine the
+relationships between nodes.
+
+@example
+@@ifnottex
+@@node Top
+@@top Short Sample
+
+This is a short sample Texinfo file.
+@@end ifnottex
+
+@group
+@@menu
+* First Chapter::    The first chapter is the
+                       only chapter in this sample.
+* Index::            Complete index.
+@@end menu
+@end group
+@end example
+
+
+@subheading Part 5: The Body of the Document
+
+@noindent
+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.
+
+@example
+@group
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
+@end group
+
+@group
+This is the first chapter.
+@@cindex index entry, another
+@end group
+
+@group
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
+@end group
+@end example
+
+
+@subheading Part 6: The End of the Document
+
+@noindent
+The end segment contains commands for generating an index in a node and
+unnumbered chapter of its own, and the @code{@@bye} command that marks
+the end of the document.
+
+@example
+@group
+@@node Index
+@@unnumbered Index
+@end group
+
+@group
+@@printindex cp
+
+@@bye
+@end group
+@end example
+
+
+@subheading Some Results
+
+Here is what the contents of the first chapter of the sample look like:
+
+@sp 1
+@need 700
+@quotation
+This is the first chapter.
+
+Here is a numbered list.
+
+@enumerate
+@item
+This is the first item.
+
+@item
+This is the second item.
+@end enumerate
+@end quotation
+
+
+@node History
+@section History
+
+@cindex Stallman, Richard M.
+@cindex Chassell, Robert J.
+@cindex Fox, Brian
+@cindex Berry, Karl
+Richard M. Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual.  Robert@tie{}J.
+Chassell greatly revised and extended the manual, starting with
+Edition 1.1.  Brian Fox was responsible for the standalone Texinfo
+distribution until version 3.8, and wrote the standalone
+@command{makeinfo} and @command{info} programs.  Karl Berry has
+continued maintenance since Texinfo 3.8 (manual edition 2.22).
+
+@cindex Pinard, Fran@,{c}ois
+@cindex Zuhn, David D.
+@cindex Weisshaus, Melissa
+@cindex Zaretskii, Eli
+@cindex Schwab, Andreas
+@cindex Weinberg, Zack
+Our thanks go out to all who helped improve this work, particularly the
+indefatigable Eli Zaretskii and Andreas Schwab, who have provided
+patches beyond counting.  Fran@,{c}ois Pinard and David@tie{}D. Zuhn,
+tirelessly recorded and reported mistakes and obscurities.  Zack
+Weinberg did the impossible by implementing the macro syntax in
+@file{texinfo.tex}.  Special thanks go to Melissa Weisshaus for her
+frequent reviews of nearly similar editions.  Dozens of others have
+contributed patches and suggestions, they are gratefully acknowledged in
+the @file{ChangeLog} file.  Our mistakes are our own.
+
+@cindex Scribe
+@cindex Reid, Brian
+@cindex History of Texinfo
+@cindex Texinfo history
+A bit of history: in the 1970's at CMU, Brian Reid developed a program
+and format named Scribe to mark up documents for printing.  It used the
+@code{@@} character to introduce commands, as Texinfo does.  Much more
+consequentially, it strove to describe document contents rather than
+formatting, an idea wholeheartedly adopted by Texinfo.
+
+@cindex Bolio
+@cindex Bo@TeX{}
+Meanwhile, people at MIT developed another, not too dissimilar format
+called Bolio.  This then was converted to using @TeX{} as its typesetting
+language: Bo@TeX{}.  The earliest Bo@TeX{} version seems to have been
+0.02 on October 31, 1984.
+
+Bo@TeX{} could only be used as a markup language for documents to be
+printed, not for online documents.  Richard Stallman (RMS) worked on
+both Bolio and Bo@TeX{}.  He also developed a nifty on-line help format
+called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
+mark up language for text that is intended to be read both online and
+as printed hard copy.
+
+
+@node Texinfo Mode
+@chapter Using Texinfo Mode
+@cindex Texinfo mode
+@cindex Mode, using Texinfo
+@cindex XEmacs
+
+You may edit a Texinfo file with any text editor you choose.  A Texinfo
+file is no different from any other ASCII file.  However, XEmacs
+comes with a special mode, called Texinfo mode, that provides XEmacs
+commands and tools to help ease your work.
+
+This chapter describes features of XEmacs' Texinfo mode but not any
+features of the Texinfo formatting language.  So 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.
+* XEmacs Editing::               Texinfo mode adds to XEmacs' 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.
+@end menu
+
+@node Texinfo Mode Overview
+@section Texinfo Mode Overview
+
+Texinfo mode provides special features for working with Texinfo files.
+You can:
+
+@itemize @bullet
+@item
+Insert frequently used @@-commands. @refill
+
+@item
+Automatically create @code{@@node} lines.
+
+@item
+Show the structure of a Texinfo source file.@refill
+
+@item
+Automatically create or update the `Next',
+`Previous', and `Up' pointers of a node.
+
+@item
+Automatically create or update menus.@refill
+
+@item
+Automatically create a master menu.@refill
+
+@item
+Format a part or all of a file for Info.@refill
+
+@item
+Typeset and print part or all of a file.@refill
+@end itemize
+
+Perhaps the two most helpful features are those for inserting frequently
+used @@-commands and for creating node pointers and menus.@refill
+
+@node XEmacs Editing
+@section The Usual XEmacs 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 XEmacs' 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 @kbd{M-q} (@code{fill-paragraph})
+command will refill a paragraph but not mix an indexing command on a
+line adjacent to it into the paragraph.@refill
+
+In addition, Texinfo mode sets the @code{page-delimiter} variable to
+the value of @code{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
+@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
+(@code{backward-page}) commands and narrow to a chapter with the
+@kbd{C-x n p} (@code{narrow-to-page}) command.  (@xref{Pages, , ,xemacs,
+XEmacs User's Manual}, for details about the page commands.)@refill
+
+You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the extensions
+@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.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.  XEmacs automatically enters Texinfo mode when you visit a
+file with a @file{.texinfo}, @file{.texi} or @file{.txi}
+extension.  Also, XEmacs switches to Texinfo mode
+when you visit a
+file that has @samp{-*-texinfo-*-} in its first line.  If ever you are
+in another mode and wish to switch to Texinfo mode, type @code{M-x
+texinfo-mode}.@refill
+
+Like all other XEmacs 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.@refill
+
+@node Inserting
+@comment  node-name,  next,  previous,  up
+@section Inserting Frequently Used Commands
+@cindex Inserting frequently used commands
+@cindex Frequently used commands, inserting
+@cindex Commands, inserting them
+
+Texinfo mode provides commands to insert various frequently used
+@@-commands into the buffer.  You can use these commands to save
+keystrokes.@refill
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command:@refill
+
+@table @kbd
+@item  C-c C-c c
+@itemx M-x texinfo-insert-@@code
+@findex texinfo-insert-@@code
+Insert @code{@@code@{@}} and put the
+cursor between the braces.@refill
+
+@item  C-c C-c d
+@itemx M-x texinfo-insert-@@dfn
+@findex texinfo-insert-@@dfn
+Insert @code{@@dfn@{@}} and put the
+cursor between the braces.@refill
+
+@item  C-c C-c e
+@itemx M-x texinfo-insert-@@end
+@findex texinfo-insert-@@end
+Insert @code{@@end} and attempt to insert the correct following word,
+such as @samp{example} or @samp{table}.  (This command does not handle
+nested lists correctly, but inserts the word appropriate to the
+immediately preceding list.)@refill
+
+@item  C-c C-c i
+@itemx M-x texinfo-insert-@@item
+@findex texinfo-insert-@@item
+Insert @code{@@item} and put the
+cursor at the beginning of the next line.@refill
+
+@item  C-c C-c k
+@itemx M-x texinfo-insert-@@kbd
+@findex texinfo-insert-@@kbd
+Insert @code{@@kbd@{@}} and put the
+cursor between the braces.@refill
+
+@item  C-c C-c n
+@itemx M-x texinfo-insert-@@node
+@findex texinfo-insert-@@node
+Insert @code{@@node} and a comment line
+listing the sequence for the `Next',
+`Previous', and `Up' nodes.
+Leave point after the @code{@@node}.@refill
+
+@item  C-c C-c o
+@itemx M-x texinfo-insert-@@noindent
+@findex texinfo-insert-@@noindent
+Insert @code{@@noindent} and put the
+cursor at the beginning of the next line.@refill
+
+@item  C-c C-c s
+@itemx M-x texinfo-insert-@@samp
+@findex texinfo-insert-@@samp
+Insert @code{@@samp@{@}} and put the
+cursor between the braces.@refill
+
+@item  C-c C-c t
+@itemx M-x texinfo-insert-@@table
+@findex texinfo-insert-@@table
+Insert @code{@@table} followed by a @key{SPC}
+and leave the cursor after the @key{SPC}.@refill
+
+@item  C-c C-c v
+@itemx M-x texinfo-insert-@@var
+@findex texinfo-insert-@@var
+Insert @code{@@var@{@}} and put the
+cursor between the braces.@refill
+
+@item  C-c C-c x
+@itemx M-x texinfo-insert-@@example
+@findex texinfo-insert-@@example
+Insert @code{@@example} and put the
+cursor at the beginning of the next line.@refill
+
+@c M-@{  was the binding for texinfo-insert-braces;
+@c in Emacs 19, backward-paragraph will take this binding.
+@item C-c C-c @{
+@itemx M-x texinfo-insert-braces
+@findex texinfo-insert-braces
+Insert @code{@{@}} and put the cursor between the braces.@refill
+
+@item C-c @}
+@itemx C-c  ]
+@itemx M-x up-list
+@findex up-list
+Move from between a pair of braces forward past the closing brace.
+Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which
+is, however, more mnemonic; hence the two keybindings.  (Also, you can
+move out from between braces by typing @kbd{C-f}.)@refill
+@end table
+
+To put a command such as @w{@code{@@code@{@dots{}@}}} around an
+@emph{existing} word, position the cursor in front of the word and type
+@kbd{C-u 1 C-c C-c c}.  This makes it easy to edit existing plain text.
+The value of the prefix argument tells XEmacs how many words following
+point to include between braces---@samp{1} for one word, @samp{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, XEmacs 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 @code{@@kbd} and @code{@@var}.@refill
+
+This set of insert commands was created after analyzing the frequency
+with which different @@-commands are used in the @cite{XEmacs
+Manual} and the @cite{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 @file{texinfo.el}.@refill
+
+@findex texinfo-start-menu-description
+@cindex Menu description, start
+@cindex Description for menu, start
+@kbd{C-c C-c C-d} (@code{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.
+@xref{Menu Parts, , The Parts of a Menu}.)@refill
+
+To use @code{texinfo-start-menu-description}, position point in a menu
+entry line and type @kbd{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.@refill
+
+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.@refill
+
+@node Showing the Structure
+@comment  node-name,  next,  previous,  up
+@section Showing the Section Structure of a File
+@cindex Showing the section structure of a file
+@cindex Section structure of a file, showing it
+@cindex Structure of a file, showing it
+@cindex Outline of file structure, showing it
+@cindex Contents-like outline of file structure
+@cindex File section structure, showing it
+@cindex Texinfo file section structure, showing it
+
+You can show the section structure of a Texinfo file by using the
+@kbd{C-c C-s} command (@code{texinfo-show-structure}).  This command
+shows the section structure of a Texinfo file by listing the lines
+that begin with the @@-commands for @code{@@chapter},
+@code{@@section}, and the like.  It constructs what amounts
+to a table of contents.  These lines are displayed in another buffer
+called the @samp{*Occur*} buffer.  In that buffer, you can position
+the cursor over one of the lines and use the @kbd{C-c C-c} command
+(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
+in the Texinfo file.@refill
+
+@table @kbd
+@item  C-c C-s
+@itemx M-x texinfo-show-structure
+@findex texinfo-show-structure
+Show the @code{@@chapter}, @code{@@section}, and such lines of a
+Texinfo file.@refill
+
+@item  C-c C-c
+@itemx M-x occur-mode-goto-occurrence
+@findex occur-mode-goto-occurrence
+Go to the line in the Texinfo file corresponding to the line under the
+cursor in the @file{*Occur*} buffer.@refill
+@end table
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
+@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
+also the @code{@@node} lines.  You can use @code{texinfo-show-structure}
+with a prefix argument to check whether the `Next', `Previous', and `Up'
+pointers of an @code{@@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
+@kbd{C-x n n} (@code{narrow-to-region}) command and
+@code{texinfo-show-structure} will work on only that region.  To see
+the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
+(@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more
+information about the narrowing commands.)@refill
+
+@vindex page-delimiter
+@cindex Page delimiter in Texinfo mode
+In addition to providing the @code{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 @kbd{C-x
+]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
+commands to move forward and backward by chapter, and to use the
+@kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter.
+@xref{Pages, , , xemacs, XEmacs User's Manual}, for more information
+about the page commands.@refill
+
+@node Updating Nodes and Menus
+@comment  node-name,  next,  previous,  up
+@section Updating Nodes and Menus
+@cindex Updating nodes and menus
+@cindex Create nodes, menus automatically
+@cindex Insert nodes, menus automatically
+@cindex Automatically insert nodes, 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 @code{@@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.@refill
+
+@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.
+@end menu
+
+@node Updating Commands
+@subsection The Updating Commands
+
+You can use the updating commands to:@refill
+
+@itemize @bullet
+@item
+insert or update the `Next', `Previous', and `Up' pointers of a
+node,@refill
+
+@item
+insert or update the menu for a section, and@refill
+
+@item
+create a master menu for a Texinfo source file.@refill
+@end itemize
+
+You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo file.@refill
+
+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 @code{@@node} line, except
+for the `Top' @code{@@node} line.  (A @dfn{structuring command line} is
+a line beginning with @code{@@chapter}, @code{@@section}, or other
+similar command.)
+
+You can write the structuring command line on the line that follows
+immediately after an @code{@@node} line or else on the line that
+follows after a single @code{@@comment} line or a single
+@code{@@ifinfo} line.  You cannot interpose more than one line between
+the @code{@@node} line and the structuring command line; and you may
+interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
+
+Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an @code{@@chapter} or equivalent-level command.
+The menu updating commands will not create a main or master menu for a
+Texinfo file that has only @code{@@chapter}-level nodes!  The menu
+updating commands only create menus @emph{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.@refill
+
+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 @code{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.@refill
+
+The @code{texinfo-master-menu} command is the primary command:@refill
+
+@table @kbd
+@item C-c C-u m
+@itemx M-x texinfo-master-menu
+@findex texinfo-master-menu
+Create or update a master menu that includes all the other menus
+(incorporating the descriptions from pre-existing menus, if
+any).@refill
+
+With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
+update all the nodes and all the regular menus in the buffer before
+constructing the master menu.  (@xref{The Top Node, , The Top Node and
+Master Menu}, for more about a master menu.)@refill
+
+For @code{texinfo-master-menu} to work, the Texinfo file must have a
+`Top' node and at least one subsequent node.@refill
+
+After extensively editing a Texinfo file, you can type the following:
+
+@example
+C-u M-x texinfo-master-menu
+@exdent or
+C-u C-c C-u m
+@end example
+
+@noindent
+This updates all the nodes and menus completely and all at once.@refill
+@end table
+
+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.@refill
+
+@need 1000
+The commands are:@refill
+
+@table @kbd
+@item C-c C-u C-n
+@itemx M-x texinfo-update-node
+@findex texinfo-update-node
+Insert the `Next', `Previous', and `Up' pointers for the node that point is
+within (i.e., for the @code{@@node} line preceding point).  If the
+@code{@@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, @kbd{C-u}, if interactive), this command
+updates all @code{@@node} lines in the region (which is the text
+between point and mark).@refill
+
+@item C-c C-u C-m
+@itemx M-x texinfo-make-menu
+@findex texinfo-make-menu
+Create or update the menu in the node that point is within.
+With an argument (@kbd{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.@refill
+
+Whenever @code{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.@refill
+
+@item C-c C-u C-e
+@itemx M-x texinfo-every-node-update
+@findex texinfo-every-node-update
+Insert or update the `Next', `Previous', and `Up' pointers for every
+node in the buffer.@refill
+
+@item C-c C-u C-a
+@itemx M-x texinfo-all-menus-update
+@findex texinfo-all-menus-update
+Create or update all the menus in the buffer.  With an argument
+(@kbd{C-u} as prefix argument, if interactive), first insert
+or update all the node
+pointers before working on the menus.@refill
+
+If a master menu exists, the @code{texinfo-all-menus-update} command
+updates it; but the command does not create a new master menu if none
+already exists.  (Use the @code{texinfo-master-menu} command for
+that.)@refill
+
+When working on a document that does not merit a master menu, you can
+type the following:
+
+@example
+C-u C-c C-u C-a
+@exdent or
+C-u M-x texinfo-all-menus-update
+@end example
+
+@noindent
+This updates all the nodes and menus.@refill
+@end table
+
+The @code{texinfo-column-for-description} variable specifies the
+column to which menu descriptions are indented.  By default, the value
+is 32 although it can be useful to reduce it to as low as 24.  You
+can set the variable via customization (@pxref{Changing an Option,,,
+xemacs, XEmacs User's Manual}) or with the @kbd{M-x set-variable}
+command (@pxref{Examining, , Examining and Setting Variables, xemacs,
+XEmacs User's Manual}).
+
+Also, the @code{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 @code{texinfo-insert-node-lines} command to
+insert missing @code{@@node} lines into a file.  (@xref{Other Updating
+Commands}, for more information.)@refill
+
+@node Updating Requirements
+@subsection Updating Requirements
+@cindex Updating requirements
+@cindex Requirements for updating commands
+
+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.@refill
+
+Each @code{@@node} line, with the exception of the line for the `Top'
+node, must be followed by a line with a structuring command such as
+@code{@@chapter}, @code{@@section}, or
+@code{@@unnumberedsubsec}.@refill
+
+Each @code{@@node} line/structuring-command line combination
+must look either like this:
+
+@example
+@group
+@@node     Comments,  Minimum, Conventions, Overview
+@@comment  node-name, next,    previous,    up
+@@section Comments
+@end group
+@end example
+
+or like this (without the @code{@@comment} line):
+
+@example
+@group
+@@node Comments, Minimum, Conventions, Overview
+@@section Comments
+@end group
+@end example
+
+or like this (without the explicit node pointers):
+
+@example
+@group
+@@node Comments
+@@section Comments
+@end group
+@end example
+
+@noindent
+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
+@code{@@comment} line, you may also write an @code{@@ifinfo} line.)
+
+If a file has a `Top' node, it must be called @samp{top} or @samp{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.@refill
+
+Incidentally, the @code{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 @code{makeinfo}, you have no need for the update node
+commands.  (@xref{Creating an Info File}, for more information about
+@code{makeinfo}.)  However, both @code{makeinfo} and the
+@code{texinfo-format-@dots{}} commands require that you insert menus in
+the file.
+
+
+@node Other Updating Commands
+@subsection Other Updating Commands
+
+In addition to the five major updating commands, Texinfo mode
+possesses several less frequently used updating commands:@refill
+
+@table @kbd
+@item M-x texinfo-insert-node-lines
+@findex texinfo-insert-node-lines
+Insert @code{@@node} lines before the @code{@@chapter},
+@code{@@section}, and other sectioning commands wherever they are
+missing throughout a region in a Texinfo file.@refill
+
+With an argument (@kbd{C-u} as prefix argument, if interactive), the
+@code{texinfo-insert-node-lines} command not only inserts
+@code{@@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 @code{@@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.@refill
+
+For example, the following marks a whole buffer as a region and inserts
+@code{@@node} lines and titles throughout:@refill
+
+@example
+C-x h C-u M-x texinfo-insert-node-lines
+@end example
+
+This command inserts titles as node names in @code{@@node} lines; the
+@code{texinfo-start-menu-description} command (@pxref{Inserting,
+Inserting Frequently Used Commands}) inserts titles as descriptions in
+menu entries, a different action.  However, in both cases, you need to
+edit the inserted text.
+
+@item M-x texinfo-multiple-files-update
+@findex texinfo-multiple-files-update @r{(in brief)}
+Update nodes and menus in a document built from several separate files.
+With @kbd{C-u} as a prefix argument, create and insert a master menu in
+the outer file.  With a numeric prefix argument, such as @kbd{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 @code{texinfo-multiple-files-update} command is
+described in the appendix on @code{@@include} files.
+@xref{texinfo-multiple-files-update}.
+
+@item M-x texinfo-indent-menu-description
+@findex 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 (@kbd{C-u} as prefix argument, if
+interactive), the @code{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.@refill
+
+@item M-x texinfo-sequential-node-update
+@findex 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 @kbd{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 @code{texinfo-sequential-node-update} command
+sequentially updates all the nodes in the region.@refill
+@end table
+
+@node Info Formatting
+@comment  node-name,  next,  previous,  up
+@section Formatting for Info
+@cindex Formatting for Info
+@cindex Running an Info formatter
+@cindex Info formatting
+
+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.@refill
+
+You can use either the @code{texinfo-format-region} or the
+@code{makeinfo-region} command to format a region:@refill
+
+@table @kbd
+@findex texinfo-format-region
+@item  C-c C-e C-r
+@itemx M-x texinfo-format-region
+@itemx C-c C-m C-r
+@itemx M-x makeinfo-region
+Format the current region for Info.@refill
+@end table
+
+You can use either the @code{texinfo-format-buffer} or the
+@code{makeinfo-buffer} command to format a whole buffer:@refill
+
+@table @kbd
+@findex texinfo-format-buffer
+@item  C-c C-e C-b
+@itemx M-x texinfo-format-buffer
+@itemx C-c C-m C-b
+@itemx M-x makeinfo-buffer
+Format the current buffer for Info.@refill
+@end table
+
+@need 1000
+For example, after writing a Texinfo file, you can type the following:
+
+@example
+C-u C-c C-u m
+@exdent or
+C-u M-x texinfo-master-menu
+@end example
+
+@noindent
+This updates all the nodes and menus.  Then type the following to create
+an Info file:
+
+@example
+C-c C-m C-b
+@exdent or
+M-x makeinfo-buffer
+@end example
+
+For @TeX{} or the Info formatting commands to work, the file @emph{must}
+include a line that has @code{@@setfilename} in its header.
+
+@xref{Creating an Info File}, for details about Info formatting.@refill
+
+@node Printing
+@comment node-name,  next,  previous,  up
+@section Printing
+@cindex Formatting for printing
+@cindex Printing a region or buffer
+@cindex Region formatting and printing
+@cindex Buffer formatting and printing
+@cindex Part of file 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 @code{texindex} command after first running the
+@code{tex} typesetting command; and then you must run the @code{tex}
+command again.  Or else run the @code{texi2dvi} command which
+automatically creates indices as needed (@pxref{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
+@code{texinfo-tex-region} and related commands for this purpose.  Use
+the @code{texinfo-tex-buffer} command to format all of a
+buffer.@refill
+
+@table @kbd
+@item  C-c C-t C-b
+@itemx M-x texinfo-tex-buffer
+@findex texinfo-tex-buffer
+Run @code{texi2dvi} on the buffer.  In addition to running @TeX{} on the
+buffer, this command automatically creates or updates indices as
+needed.@refill
+
+@item  C-c C-t C-r
+@itemx M-x texinfo-tex-region
+@findex texinfo-tex-region
+Run @TeX{} on the region.@refill
+
+@item C-c C-t C-i
+@itemx M-x texinfo-texindex
+Run @code{texindex} to sort the indices of a Texinfo file formatted with
+@code{texinfo-tex-region}.  The @code{texinfo-tex-region} command does
+not run @code{texindex} automatically; it only runs the @code{tex}
+typesetting command.  You must run the @code{texinfo-tex-region} command
+a second time after sorting the raw index files with the @code{texindex}
+command.  (Usually, you do not format an index when you format a region,
+only when you format a buffer.  Now that the @code{texi2dvi} command
+exists, there is little or no need for this command.)@refill
+
+@item C-c C-t C-p
+@itemx M-x texinfo-tex-print
+@findex texinfo-tex-print
+Print the file (or the part of the file) previously formatted with
+@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
+@end table
+
+For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
+file @emph{must} start with a @samp{\input texinfo} line and must
+include an @code{@@settitle} line.  The file must end with @code{@@bye}
+on a line by itself.  (When you use @code{texinfo-tex-region}, you must
+surround the @code{@@settitle} line with start-of-header and
+end-of-header lines.)@refill
+
+@xref{Hardcopy}, for a description of the other @TeX{} related
+commands, such as @code{tex-show-print-queue}.@refill
+
+@node Texinfo Mode Summary
+@comment  node-name,  next,  previous,  up
+@section 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 @kbd{C-c}.  The keys are somewhat
+mnemonic.@refill
+
+@subheading Insert Commands
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command to be inserted.  (It might make more
+sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
+@kbd{C-c C-c} is quick to type.)@refill
+
+@example
+C-c C-c c       @r{Insert} @samp{@@code}.
+C-c C-c d       @r{Insert} @samp{@@dfn}.
+C-c C-c e       @r{Insert} @samp{@@end}.
+C-c C-c i       @r{Insert} @samp{@@item}.
+C-c C-c n       @r{Insert} @samp{@@node}.
+C-c C-c s       @r{Insert} @samp{@@samp}.
+C-c C-c v       @r{Insert} @samp{@@var}.
+C-c @{       @r{Insert braces.}
+C-c ]
+C-c @}       @r{Move out of enclosing braces.}
+
+@group
+C-c C-c C-d     @r{Insert a node's section title}
+               @r{in the space for the description}
+               @r{in a menu entry line.}
+@end group
+@end example
+
+@subheading Show Structure
+
+The @code{texinfo-show-structure} command is often used within a
+narrowed region.@refill
+
+@example
+C-c C-s         @r{List all the headings.}
+@end example
+
+@subheading The Master Update Command
+
+The @code{texinfo-master-menu} command creates a master menu; and can
+be used to update every node and menu in a file as well.@refill
+
+@c Probably should use @tables in this section.
+@example
+@group
+C-c C-u m
+M-x texinfo-master-menu
+               @r{Create or update a master menu.}
+@end group
+
+@group
+C-u C-c C-u m   @r{With @kbd{C-u} as a prefix argument, first}
+               @r{create or update all nodes and regular}
+               @r{menus, and then create a master menu.}
+@end group
+@end example
+
+@subheading Update Pointers
+
+The update pointer commands are invoked by typing @kbd{C-c C-u} and
+then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
+@code{texinfo-every-node-update}.@refill
+
+@example
+C-c C-u C-n     @r{Update a node.}
+C-c C-u C-e     @r{Update every node in the buffer.}
+@end example
+
+@subheading Update Menus
+
+Invoke the  update menu commands by typing @kbd{C-c C-u}
+and then either @kbd{C-m} for @code{texinfo-make-menu} or
+@kbd{C-a} for @code{texinfo-all-menus-update}.  To update
+both nodes and menus at the same time, precede @kbd{C-c C-u
+C-a} with @kbd{C-u}.@refill
+
+@example
+C-c C-u C-m     @r{Make or update a menu.}
+
+@group
+C-c C-u C-a     @r{Make or update all}
+               @r{menus in a buffer.}
+@end group
+
+@group
+C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
+               @r{first create or update all nodes and}
+               @r{then create or update all menus.}
+@end group
+@end example
+
+@subheading Format for Info
+
+The Info formatting commands that are written in XEmacs Lisp are
+invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
+or @kbd{C-b} for the whole buffer.@refill
+
+The Info formatting commands that are written in C and based on the
+@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
+either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
+
+@need 800
+@noindent
+Use the @code{texinfo-format@dots{}} commands:
+
+@example
+@group
+C-c C-e C-r     @r{Format the region.}
+C-c C-e C-b     @r{Format the buffer.}
+@end group
+@end example
+
+@need 750
+@noindent
+Use @code{makeinfo}:
+
+@example
+C-c C-m C-r     @r{Format the region.}
+C-c C-m C-b     @r{Format the buffer.}
+C-c C-m C-l     @r{Recenter the @code{makeinfo} output buffer.}
+C-c C-m C-k     @r{Kill the @code{makeinfo} formatting job.}
+@end example
+
+@subheading Typeset and Print
+
+The @TeX{} typesetting and printing commands are invoked by typing
+@kbd{C-c C-t} and then another control command: @kbd{C-r} for
+@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
+and so on.@refill
+
+@example
+C-c C-t C-r     @r{Run @TeX{} on the region.}
+C-c C-t C-b     @r{Run} @code{texi2dvi} @r{on the buffer.}
+C-c C-t C-i     @r{Run} @code{texindex}.
+C-c C-t C-p     @r{Print the DVI file.}
+C-c C-t C-q     @r{Show the print queue.}
+C-c C-t C-d     @r{Delete a job from the print queue.}
+C-c C-t C-k     @r{Kill the current @TeX{} formatting job.}
+C-c C-t C-x     @r{Quit a currently stopped @TeX{} formatting job.}
+C-c C-t C-l     @r{Recenter the output buffer.}
+@end example
+
+@subheading Other Updating Commands
+
+The remaining updating commands do not have standard keybindings because
+they are rarely used.
+
+@example
+@group
+M-x texinfo-insert-node-lines
+               @r{Insert missing @code{@@node} lines in region.}
+               @r{With @kbd{C-u} as a prefix argument,}
+               @r{use section titles as node names.}
+@end group
+
+@group
+M-x texinfo-multiple-files-update
+               @r{Update a multi-file document.}
+               @r{With @kbd{C-u 2} as a prefix argument,}
+               @r{create or update all nodes and menus}
+               @r{in all included files first.}
+@end group
+
+@group
+M-x texinfo-indent-menu-description
+               @r{Indent descriptions.}
+@end group
+
+@group
+M-x texinfo-sequential-node-update
+               @r{Insert node pointers in strict sequence.}
+@end group
+@end example
+
+
+@node Beginning a File
+@chapter Beginning a Texinfo File
+@cindex Beginning a Texinfo file
+@cindex Texinfo file beginning
+@cindex File beginning
+
+Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name for the output file(s), the title of the
+document, and the Top node.  A table of contents is also generally
+produced here.
+
+This chapter expands on the minimal complete Texinfo source file
+previously given (@pxref{Six Parts}).  It describes the numerous
+commands for handling the traditional frontmatter items in Texinfo.
+
+@cindex Frontmatter, text in
+Straight text outside of any command before the Top node should be
+avoided.  Such text is treated differently in the different output
+formats: visible in @TeX{} and HTML, by default not shown in Info
+readers, and so on.
+
+@menu
+* Sample Beginning::            A sample beginning for a Texinfo file.
+* Texinfo File Header::         The first lines.
+* Document Permissions::        Ensuring your manual is free.
+* Titlepage & Copyright Page::  Creating the title and copyright pages.
+* Contents::                    How to create a table of contents.
+* The Top Node::                Creating the `Top' node and master menu.
+* Global Document Commands::    Affecting formatting throughout.
+* Software Copying Permissions::  Ensure that you and others continue to
+                                   have the right to use and share software.
+@end menu
+
+
+@node Sample Beginning
+@section Sample Texinfo File Beginning
+
+@cindex Example beginning of Texinfo file
+
+The following sample shows what is needed.  The elements given here are
+explained in more detail in the following sections.  Other commands are
+often included at the beginning of Texinfo files, but the ones here are
+the most critical.
+
+@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
+
+@example
+\input texinfo   @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{infoname}.info
+@@settitle @var{name-of-manual} @var{version}
+@@c %**end of header
+
+@@copying
+This manual is for @var{program}, version @var{version}.
+
+Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
+
+@group
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
+@end group
+
+@group
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
+@end group
+
+@group
+@@c  The following two commands
+@@c  start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@end group
+
+Published by @dots{}
+@@end titlepage
+
+@@c So the toc is printed at the start.
+@@contents
+
+@@ifnottex
+@@node Top
+@@top @var{title}
+
+This manual is for @var{program}, version @var{version}.
+@@end ifnottex
+
+@group
+@@menu
+* First Chapter::    Getting started @dots{}
+* Second Chapter::          @dots{}
+ @dots{}
+* Copying::          Your rights and freedoms.
+@@end menu
+@end group
+
+@group
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex first chapter
+@@cindex chapter, first
+@dots{}
+@end group
+@end example
+
+
+@node Texinfo File Header
+@section Texinfo File Header
+@cindex Header for Texinfo files
+@cindex Texinfo file header
+
+Texinfo files start with at least three lines that provide Info and
+@TeX{} with necessary information.  These are the @code{\input texinfo}
+line, the @code{@@settitle} line, and the @code{@@setfilename} line.
+
+Also, if you want to format just part of the Texinfo file, you must
+write the @code{@@settitle} and @code{@@setfilename} lines between
+start-of-header and end-of-header lines.  The start- and end-of-header
+lines are optional, but they do no harm, so you might as well always
+include them.
+
+Any command that affects document formatting as a whole makes sense to
+include in the header.  @code{@@synindex} (@pxref{synindex}), for
+instance, is another command often included in the header.  @xref{GNU
+Sample Texts}, for complete sample texts.
+
+Thus, the beginning of a Texinfo file generally looks like this:
+
+@example
+@group
+\input texinfo   @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+@end group
+@end example
+
+@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.
+* End of Header::               Formatting a region requires this.
+@end menu
+
+
+@node First Line
+@subsection The First Line of a Texinfo File
+@cindex First line of a Texinfo file
+@cindex Beginning line of a Texinfo file
+@cindex Header 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:
+
+@example
+\input texinfo   @@c -*-texinfo-*-
+@end example
+
+@noindent
+This line serves two functions:
+
+@enumerate
+@item
+When the file is processed by @TeX{}, the @samp{\input texinfo} command
+tells @TeX{} to load the macros needed for processing a Texinfo file.
+These are in a file called @file{texinfo.tex}, which should have been
+installed on your system along with either the @TeX{} or Texinfo
+software.  @TeX{} uses the backslash, @samp{\}, to mark the beginning of
+a command, exactly as Texinfo uses @samp{@@}.  The @file{texinfo.tex}
+file causes the switch from @samp{\} to @samp{@@}; before the switch
+occurs, @TeX{} requires @samp{\}, which is why it appears at the
+beginning of the file.
+
+@item
+When the file is edited in XEmacs, the @samp{-*-texinfo-*-} mode
+specification tells XEmacs to use Texinfo mode.
+@end enumerate
+
+
+@node Start of Header
+@subsection Start of Header
+@cindex Start of header line
+
+A start-of-header line is a Texinfo comment that looks like this:
+
+@example
+@@c %**start of header
+@end example
+
+Write the start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with @code{@@setfilename} and
+@code{@@settitle} lines and, optionally, with other commands that
+globally affect the document formatting, such as @code{@@synindex} or
+@code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
+Header}).
+
+The start- and end-of-header lines allow you to format only part of a
+Texinfo file for Info or printing.  @xref{texinfo-format commands}.
+
+The odd string of characters, @samp{%**}, is to ensure that no other
+comment is accidentally taken for a start-of-header line.  You can
+change it if you wish by setting the @code{tex-start-of-header} and/or
+@code{tex-end-of-header} XEmacs variables.  @xref{Texinfo Mode Printing}.
+
+
+@node setfilename
+@subsection @code{@@setfilename}: Set the output file name
+@findex setfilename
+@cindex Texinfo requires @code{@@setfilename}
+
+In order to serve as the primary input file for either @code{makeinfo}
+or @TeX{}, a Texinfo file must contain a line that looks like this:
+
+@example
+@@setfilename @var{info-file-name}
+@end example
+
+Write the @code{@@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.
+
+@cindex Ignored before @code{@@setfilename}
+@cindex @samp{\input} source line ignored
+The Info formatting commands ignore everything written before the
+@code{@@setfilename} line, which is why the very first line of
+the file (the @code{\input} line) does not show up in the output.
+
+The @code{@@setfilename} line specifies the name of the output file to
+be generated.  This name must be different from the name of the Texinfo
+file.  There are two conventions for choosing the name: you can either
+remove the extension (such as @samp{.texi}) entirely from the input file
+name, or, preferably, replace it with the @samp{.info} extension.
+
+@cindex Length of file names
+@cindex File name collision
+@cindex Info file name, choosing
+Although an explicit @samp{.info} extension is preferable, 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 @samp{-1},
+@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
+file name.  (@xref{Tag and Split Files}.)  The subfile name
+@file{texinfo.info-10}, for example, is too long for old systems with a
+14-character limit on filenames; so the Info file name for this document
+is @file{texinfo} rather than @file{texinfo.info}.  When @code{makeinfo}
+is running on operating systems such as MS-DOS which impose severe
+limits on file names, it may remove some characters from the original
+file name to leave enough space for the subfile suffix, thus producing
+files named @file{texin-10}, @file{gcc.i12}, etc.
+
+When producing HTML output, @code{makeinfo} will replace any extension
+with @samp{html}, or add @samp{.html} if the given name has no
+extension.
+
+@pindex texinfo.cnf
+The @code{@@setfilename} line produces no output when you typeset a
+manual with @TeX{}, but it is nevertheless essential: it opens the
+index, cross-reference, and other auxiliary files used by Texinfo, and
+also reads @file{texinfo.cnf} if that file is present on your system
+(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
+
+
+@node settitle
+@subsection @code{@@settitle}: Set the document title
+@findex settitle
+
+In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
+@example
+@@settitle @var{title}
+@end example
+
+Write the @code{@@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 what would otherwise be a comment.
+
+The @code{@@settitle} command should precede everything that generates
+actual output.  The best place for it is right after the
+@code{@@setfilename} command (see the previous section).
+
+@cindex <title> HTML tag
+In the HTML file produced by @command{makeinfo}, @var{title} serves as
+the document @samp{<title>}.  It also becomes the default document
+description in the @samp{<head>} part (@pxref{documentdescription}).
+
+The title in the @code{@@settitle} command does not affect the title as
+it appears on the title page.  Thus, the two do not need not match
+exactly.  A practice we recommend is to include the version or edition
+number of the manual in the @code{@@settitle} title; on the title page,
+the version number generally appears as a @code{@@subtitle} so it would
+be omitted from the @code{@@title}.  @xref{titlepage}.
+
+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 @code{@@chapter} command.)  By default, no page footer is
+printed.
+
+Even if you are printing in a single-sided style, @TeX{} looks for an
+@code{@@settitle} command line, in case you include the manual title
+in the heading.
+
+@TeX{} prints page headings only for that text that comes after the
+@code{@@end titlepage} command in the Texinfo file, or that comes
+after an @code{@@headings} command that turns on headings.
+(@xref{headings on off, , The @code{@@headings} Command}, for more
+information.)
+
+You may, if you wish, create your own, customized headings and footings.
+@xref{Headings}, for a detailed discussion of this.
+
+
+@node End of Header
+@subsection End of Header
+@cindex End of header line
+
+Follow the header lines with an @w{end-of-header} line, which is a
+Texinfo comment that looks like this:
+
+@example
+@@c %**end of header
+@end example
+
+@xref{Start of Header}.
+
+
+@node Document Permissions
+@section Document Permissions
+@cindex Document Permissions
+@cindex Copying Permissions
+
+The copyright notice and copying permissions for a document need to
+appear in several places in the various Texinfo output formats.
+Therefore, Texinfo provides a command (@code{@@copying}) to declare
+this text once, and another command (@code{@@insertcopying}) to
+insert the text at appropriate points.
+
+@menu
+* copying::                     Declare the document's copying permissions.
+* insertcopying::               Where to insert the permissions.
+@end menu
+
+
+@node copying
+@subsection @code{@@copying}: Declare Copying Permissions
+@findex copying
+
+The @code{@@copying} command should be given very early in the document;
+the recommended location is right after the header material
+(@pxref{Texinfo File Header}).  It conventionally consists of a sentence
+or two about what the program is, identification of the documentation
+itself, the legal copyright line, and the copying permissions.  Here is
+a skeletal example:
+
+@example
+@@copying
+This manual is for @var{program} (version @var{version}, updated
+@var{date}), which @dots{}
+
+Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
+
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
+@end example
+
+The @code{@@quotation} has no legal significance; it's there to improve
+readability in some contexts.
+
+@xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
+@xref{GNU Free Documentation License}, for the license itself under
+which GNU and other free manuals are distributed.  You need to include
+the license as an appendix to your document.
+
+The text of @code{@@copying} is output as a comment at the beginning of
+Info, HTML, and XML output files.  It is @emph{not} output implicitly in
+plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
+emit the copying information.  See the next section for details.
+
+@findex copyright
+The @code{@@copyright@{@}} command generates a @samp{c} inside a circle
+in output formats that support this (print and HTML).  In the other
+formats (Info and plain text), it generates @samp{(C)}.  The copyright
+notice itself has the following legally defined sequence:
+
+@example
+Copyright @copyright{} @var{years} @var{copyright-owner}.
+@end example
+
+@cindex Copyright word, always in English
+The word `Copyright' must always be written in English, even if the
+document is otherwise written in another language.  This is due to
+international law.
+
+@cindex Years, in copyright line
+The list of years should include all years in which a version was
+completed (even if it was released in a subsequent year).  Ranges are
+not allowed; each year must be written out individually and in full,
+separated by commas.
+
+@cindex Copyright holder for FSF works
+@cindex Holder of copyright for FSF works
+@cindex Owner of copyright for FSF works
+The copyright owner (or owners) is whoever holds legal copyright on the
+work.  In the case of works assigned to the FSF, the owner is `Free
+Software Foundation, Inc.'.
+
+The copyright `line' may actually be split across multiple lines, both
+in the source document and in the output.  This often happens for
+documents with a long history, having many different years of
+publication.  If you do use several lines, do not indent any of them
+(or anything else in the @code{@@copying} block) in the source file.
+
+@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
+additional information.
+
+
+@node insertcopying
+@subsection @code{@@insertcopying}: Include Permissions Text
+@findex insertcopying
+@cindex Copying text, including
+@cindex Permissions text, including
+@cindex Including permissions text
+
+The @code{@@insertcopying} command is simply written on a line by
+itself, like this:
+
+@example
+@@insertcopying
+@end example
+
+This inserts the text previously defined by @code{@@copying}.  To meet
+legal requirements, it must be used on the copyright page in the printed
+manual (@pxref{Copyright}).
+
+The @code{@@copying} command itself causes the permissions text to
+appear in an Info file @emph{before} the first node.  The text is also
+copied into the beginning of each split Info output file, as is legally
+necessary.  This location implies a human reading the manual using Info
+does @emph{not} see this text (except when using the advanced Info
+command @kbd{g *}), but this does not matter for legal purposes,
+because the text is present.
+
+Similarly, the @code{@@copying} text is automatically included at the
+beginning of each HTML output file, as an HTML comment.  Again, this
+text is not visible (unless the reader views the HTML source).
+
+The permissions text defined by @code{@@copying} also appears
+automatically at the beginning of the XML output file.
+
+
+@node Titlepage & Copyright Page
+@section Title and Copyright Pages
+
+In hard copy output, the manual's name and author are usually printed on
+a title page.  Copyright information is usually 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 appears in the printed manual.
+
+@cindex Title page, for plain text
+@cindex Copyright page, for plain text
+You may wish to include titlepage-like information for plain text
+output.  Simply place any such leading material between
+@code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
+includes this when writing plain text (@samp{--no-headers}), along with
+an @code{@@insertcopying}.
+
+@menu
+* titlepage::                   Create a title for the printed document.
+* titlefont center sp::         The @code{@@titlefont}, @code{@@center},
+                                 and @code{@@sp} commands.
+* title subtitle author::       The @code{@@title}, @code{@@subtitle},
+                                 and @code{@@author} commands.
+* Copyright::                   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.
+@end menu
+
+
+@node titlepage
+@subsection @code{@@titlepage}
+@cindex Title page
+@findex titlepage
+
+Start the material for the title page and following copyright page
+with @code{@@titlepage} on a line by itself and end it with
+@code{@@end titlepage} on a line by itself.
+
+The @code{@@end titlepage} command starts a new page and turns on page
+numbering.  (@xref{Headings, , Page 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 @code{@@titlepage} and
+@code{@@end titlepage} commands.  You can force the table of contents to
+appear there with the @code{@@setcontentsaftertitlepage} command
+(@pxref{Contents}).
+
+@findex page@r{, within @code{@@titlepage}}
+By using the @code{@@page} command you can force a page break within the
+region delineated by the @code{@@titlepage} and @code{@@end titlepage}
+commands and thereby create more than one unnumbered page.  This is how
+the copyright page is produced.  (The @code{@@titlepage} command might
+perhaps have been better named the @code{@@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@footnote{We have found
+that it is helpful to refer to versions of independent 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.} 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
+@ref{The Top Node}.)
+
+Texinfo provides two main methods for creating a title page.  One method
+uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
+to generate a title page in which the words on the page are
+centered.
+
+The second method uses the @code{@@title}, @code{@@subtitle}, and
+@code{@@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, or you may combine them; see the examples in
+the sections below.
+
+@findex shorttitlepage
+@cindex Bastard title page
+@cindex Title page, bastard
+For extremely simple documents, and for the bastard title page in
+traditional book frontmatter, Texinfo also provides a command
+@code{@@shorttitlepage} which takes the rest of the line as the title.
+The argument is typeset on a page by itself and followed by a blank
+page.
+
+
+@node titlefont center sp
+@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
+@findex titlefont
+@findex center
+@findex sp @r{(titlepage line spacing)}
+
+You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@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 @code{@@titlefont} command to select a large font suitable for
+the title itself.  You can use @code{@@titlefont} more than once if you
+have an especially long title.
+
+For HTML output, each @code{@@titlefont} command produces an
+@code{<h1>} heading, but the HTML document @code{<title>} is not
+affected.  For that, you must put an @code{@@settitle} command before
+the @code{@@titlefont} command (@pxref{settitle}).
+
+@need 700
+For example:
+
+@example
+@@titlefont@{Texinfo@}
+@end example
+
+Use the @code{@@center} command at the beginning of a line to center
+the remaining text on that line.  Thus,
+
+@example
+@@center @@titlefont@{Texinfo@}
+@end example
+
+@noindent
+centers the title, which in this example is ``Texinfo'' printed
+in the title font.
+
+Use the @code{@@sp} command to insert vertical space.  For example:
+
+@example
+@@sp 2
+@end example
+
+@noindent
+This inserts two blank lines on the printed page.  (@xref{sp, ,
+@code{@@sp}}, for more information about the @code{@@sp}
+command.)
+
+A template for this method looks like this:
+
+@example
+@group
+@@titlepage
+@@sp 10
+@@center @@titlefont@{@var{name-of-manual-when-printed}@}
+@@sp 2
+@@center @var{subtitle-if-any}
+@@sp 2
+@@center @var{author}
+@dots{}
+@@end titlepage
+@end group
+@end example
+
+The spacing of the example fits an 8.5 by 11 inch manual.
+
+You can in fact use these commands anywhere, not just on a title page,
+but since they are not logical markup commands, we don't recommend
+them.
+
+@node title subtitle author
+@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
+@findex title
+@findex subtitle
+@findex author
+
+You can use the @code{@@title}, @code{@@subtitle}, and @code{@@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 @code{@@sp} command is
+needed to adjust vertical spacing.
+
+Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
+commands at the beginning of a line followed by the title, subtitle,
+or author.  These commands are only effective in @TeX{} output; it's
+an error to use them anywhere except within @code{@@titlepage}.
+
+The @code{@@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.  Only a single line is
+allowed; the @code{@@*} command may not be used to break the title into
+two lines.  To handle very long titles, you may find it profitable to
+use both @code{@@title} and @code{@@titlefont}; see the final example in
+this section.
+
+The @code{@@subtitle} command sets subtitles in a normal-sized font
+flush to the right-hand side of the page.
+
+The @code{@@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 @code{@@author} command line is
+followed by an @code{@@page} command line.)
+
+There are two ways to use the @code{@@author} command: you can write
+the name or names on the remaining part of the line that starts with
+an @code{@@author} command:
+
+@example
+@@author by Jane Smith and John Doe
+@end example
+
+@noindent
+or you can write the names one above each other by using two (or more)
+@code{@@author} commands:
+
+@example
+@group
+@@author Jane Smith
+@@author John Doe
+@end group
+@end example
+
+@noindent
+(Only the bottom name is underlined with a black rule.)
+
+@need 950
+A template for this method looks like this:
+
+@example
+@group
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
+@@page
+@dots{}
+@@end titlepage
+@end group
+@end example
+
+You may also combine the @code{@@titlefont} method described in the
+previous section and @code{@@title} method described in this one.  This
+may be useful if you have a very long title.  Here is a real-life example:
+
+@example
+@group
+@@titlepage
+@@titlefont@{GNU Software@}
+@@sp 1
+@@title for MS-Windows and MS-DOS
+@@subtitle Edition @@value@{e@} for Release @@value@{cde@}
+@@author by Daniel Hagerty, Melissa Weisshaus
+@@author and Eli Zaretskii
+@end group
+@end example
+
+@noindent
+(The use of @code{@@value} here is explained in @ref{value Example}.
+
+
+@node Copyright
+@subsection Copyright Page
+@cindex Copyright page
+@cindex Printed permissions
+@cindex Permissions, printed
+
+By international treaty, the copyright notice for a book must be either
+on the title page or on the back of the title page.  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 @code{@@titlepage} and @code{@@end titlepage}
+commands.
+
+@findex vskip @r{@TeX{} vertical skip}
+@findex filll @r{@TeX{} dimension}
+Use the @code{@@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, use the following incantation after @code{@@page}:
+
+@example
+@@vskip 0pt plus 1filll
+@end example
+
+@noindent
+This is a @TeX{} command that is not supported by the Info formatting
+commands.  The @code{@@vskip} command inserts whitespace.  The @samp{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 @samp{l}s in the word
+@samp{filll}; this is correct.
+
+To insert the copyright text itself, write @code{@@insertcopying}
+next (@pxref{Document Permissions}):
+
+@example
+@@insertcopying
+@end example
+
+Follow the copying text by the publisher, ISBN numbers, cover art
+credits, and other such information.
+
+Here is an example putting all this together:
+
+@example
+@@titlepage
+@dots{}
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+
+Published by @dots{}
+
+Cover art by @dots{}
+@@end titlepage
+@end example
+
+
+@node end titlepage
+@subsection Heading Generation
+@findex end titlepage
+@cindex Headings, page, begin to appear
+@cindex Titlepage end starts headings
+@cindex End titlepage starts headings
+
+Like all @code{@@end} commands (@pxref{Quotations and Examples}), the @code{@@end titlepage} command
+must be written at the beginning of a line by itself, with only one
+space between the @code{@@end} and the @code{titlepage}.  It 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).
+You can specify these formats in different ways:
+
+@itemize @bullet
+@item
+The conventional way is to write an @code{@@setchapternewpage} command
+before the title page commands, and then have the @code{@@end
+titlepage} command start generating page headings in the manner desired.
+(@xref{setchapternewpage}.)
+
+@item
+Alternatively, you can use the @code{@@headings} command to prevent page
+headings from being generated or to start them for either single or
+double-sided printing.  (Write an @code{@@headings} command immediately
+after the @code{@@end titlepage} command.  @xref{headings on off, , The
+@code{@@headings} Command}, for more information.)@refill
+
+@item
+Or, you may specify your own page heading and footing format.
+@xref{Headings, , Page Headings}, for detailed
+information about page headings and footings.
+@end itemize
+
+Most documents are formatted with the standard single-sided or
+double-sided format, using @code{@@setchapternewpage odd} for
+double-sided printing and no @code{@@setchapternewpage} command for
+single-sided printing.
+
+
+@node headings on off
+@subsection The @code{@@headings} Command
+@findex headings
+
+The @code{@@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 @code{@@setchapternewpage} command.  You need the
+@code{@@headings} command only if the @code{@@setchapternewpage} command
+does not do what you want, or if you want to turn off predefined page
+headings prior to defining your own.  Write an @code{@@headings} command
+immediately after the @code{@@end titlepage} command.
+
+You can use @code{@@headings} as follows:
+
+@table @code
+@item @@headings off
+Turn off printing of page headings.
+
+@item @@headings single
+Turn on page headings appropriate for single-sided printing.
+
+@item @@headings double
+Turn on page headings appropriate for double-sided printing.  
+
+@item @@headings singleafter
+@itemx @@headings doubleafter
+Turn on @code{single} or @code{double} headings, respectively, after the
+current page is output.
+
+@item @@headings on
+Turn on page headings: @code{single} if @samp{@@setchapternewpage
+on}, @code{double} otherwise.
+@end table
+
+For example, suppose you write @code{@@setchapternewpage off} before the
+@code{@@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 @code{@@headings
+double} after the @code{@@end titlepage} command.
+
+You can stop @TeX{} from generating any page headings at all by
+writing @code{@@headings off} on a line of its own immediately after the
+line containing the @code{@@end titlepage} command, like this:
+
+@example
+@@end titlepage
+@@headings off
+@end example
+
+@noindent
+The @code{@@headings off} command overrides the @code{@@end titlepage}
+command, which would otherwise cause @TeX{} to print page headings.
+
+You can also specify your own style of page heading and footing.
+@xref{Headings, , Page Headings}, for more information.
+
+
+@node Contents
+@section Generating a Table of Contents
+@cindex Table of contents
+@cindex Contents, Table of
+@cindex Short table of contents
+@findex contents
+@findex summarycontents
+@findex shortcontents
+
+The @code{@@chapter}, @code{@@section}, and other structuring commands
+(@pxref{Structuring}) 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 @code{@@contents} and/or
+@code{@@summarycontents} command(s).
+
+@table @code
+@item @@contents
+Generates a table of contents in a printed manual, including all
+chapters, sections, subsections, etc., as well as appendices and
+unnumbered chapters.  Headings generated by @code{@@majorheading},
+@code{@@chapheading}, and the other @code{@@@dots{}heading} commands
+do not appear in the table of contents (@pxref{Structuring Command
+Types}).
+
+@item @@shortcontents
+@itemx @@summarycontents
+(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
+
+Generates a short or summary table of contents that lists only the
+chapters, appendices, and unnumbered chapters.  Sections, subsections
+and subsubsections are omitted.  Only a long manual needs a short
+table of contents in addition to the full table of contents.
+
+@end table
+
+Both contents commands should be written on a line by themselves, and
+are best placed near the beginning of the file, after the @code{@@end
+titlepage} (@pxref{titlepage}).  The contents commands automatically
+generate a chapter-like heading at the top of the first table of
+contents page, so don't include any sectioning command such as
+@code{@@unnumbered} before them.
+
+Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the contents commands.  But the contents are
+included in plain text output (generated by @code{makeinfo
+--no-headers}), unless @code{makeinfo} is writing its output to standard
+output.
+
+When @code{makeinfo} writes a short table of contents while producing
+HTML output, the links in the short table of contents point to
+corresponding entries in the full table of contents rather than the text
+of the document. The links in the full table of contents point to the
+main text of the document.
+
+In the past, the contents commands were sometimes placed at the end of
+the file, after any indices and just before the @code{@@bye}, but we
+no longer recommend this.
+
+@findex setcontentsaftertitlepage
+@findex setshortcontentsaftertitlepage
+@cindex Contents, after title page
+@cindex Table of contents, after title page
+However, since many existing Texinfo documents still do have the
+@code{@@contents} at the end of the manual, if you are a user printing
+a manual, you may wish to force the contents to be printed after the
+title page.  You can do this by specifying
+@code{@@setcontentsaftertitlepage} and/or
+@code{@@setshortcontentsaftertitlepage}.  The first prints only the
+main contents after the @code{@@end titlepage}; the second prints both
+the short contents and the main contents.  In either case, any
+subsequent @code{@@contents} or @code{@@shortcontents} is ignored
+(unless, erroneously, no @code{@@end titlepage} is ever encountered).
+
+You need to include the @code{@@set@dots{}contentsaftertitlepage}
+commands early in the document (just after @code{@@setfilename}, for
+example).  We recommend using @command{texi2dvi} (@pxref{Format with
+texi2dvi}) to specify this without altering the source file at all.  For
+example:
+@example
+texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
+@end example
+
+
+@node The Top Node
+@section The `Top' Node and Master Menu
+@cindex Top node
+@cindex Node, `Top'
+
+The `Top' node is the node in which a reader enters an Info manual.
+As such, it should begin with a brief description of the manual
+(including the version number), and end with a master menu for the
+whole manual.  Of course you should include any other general
+information you feel a reader would find helpful.
+
+@findex top
+It is conventional and desirable to write an @code{@@top} sectioning
+command line containing the title of the document immediately after
+the @code{@@node Top} line (@pxref{makeinfo top command, , The
+@code{@@top} Sectioning Command}).
+
+The contents of the `Top' node should appear only in the online output;
+none of it should appear in printed output, so enclose it between
+@code{@@ifnottex} and @code{@@end ifnottex} commands.  (@TeX{} does not
+print either an @code{@@node} line or a menu; they appear only in Info;
+strictly speaking, you are not required to enclose these parts between
+@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
+so.  @xref{Conditionals, , Conditionally Visible Text}.)
+
+@menu
+* Top Node Example::
+* Master Menu Parts::
+@end menu
+
+
+@node Top Node Example
+@subsection Top Node Example
+
+@cindex Top node example
+
+Here is an example of a Top node.
+
+@example
+@group
+@@ifnottex
+@@node Top
+@@top Sample Title
+
+@@insertcopying
+@@end ifnottex
+@end group
+
+Additional general information.
+
+@group
+@@menu
+* First Chapter::
+* Second Chapter::
+@dots{}
+* Index::
+@end group
+@@end menu
+@end example
+
+
+@node Master Menu Parts
+@subsection Parts of a Master Menu
+@cindex Master menu
+@cindex Menu, master
+@cindex Parts of a master menu
+
+A @dfn{master menu} is a detailed main menu listing all the nodes in a
+file.
+
+A master menu is enclosed in @code{@@menu} and @code{@@end menu}
+commands and does not appear in the printed document.
+
+Generally, a master menu is divided into parts.
+
+@itemize @bullet
+@item
+The first part contains the major nodes in the Texinfo file: the nodes
+for the chapters, chapter-like sections, and the appendices.
+
+@item
+The second part contains nodes for the indices.
+
+@item
+@findex detailmenu
+@cindex Detailed menu
+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 @code{@@detailmenu} before the
+first one, and @code{@@end detailmenu} after the last; otherwise,
+@code{makeinfo} will get confused.
+@end itemize
+
+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.  (@xref{Writing a Menu}, for more
+information.)
+
+For example, the master menu for this manual looks like the following
+(but has many more entries):
+
+@example
+@group
+@@menu
+* Copying Conditions::  Your rights.
+* Overview::            Texinfo in brief.
+@dots{}
+@end group
+@group
+* Command and Variable Index::
+* General Index::
+@end group
+
+@group
+@@detailmenu
+--- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: @dots{}
+@dots{}
+@end group
+
+@group
+Beginning a Texinfo File
+
+* Sample Beginning:: @dots{}
+@dots{}
+@@end detailmenu
+@@end menu
+@end group
+@end example
+
+
+@node Global Document Commands
+@section Global Document Commands
+@cindex Global Document Commands
+
+Besides the basic commands mentioned in the previous sections, here are
+additional commands which affect the document as a whole.  They are
+generally all given before the Top node, if they are given at all.
+
+@menu
+* documentdescription::         Document summary for the HTML output.
+* setchapternewpage::           Start chapters on right-hand pages.
+* paragraphindent::             Specify paragraph indentation.
+* firstparagraphindent::        Suppress indentation of the first paragraph.
+* exampleindent::               Specify environment indentation.
+@end menu
+
+
+@node documentdescription
+@subsection @code{@@documentdescription}: Summary Text
+@cindex Document description
+@cindex Description of document
+@cindex Summary of document
+@cindex Abstract of document
+@cindex <meta> HTML tag, and document description
+@findex documentdescription
+
+When producing HTML output for a document, @command{makeinfo} writes a
+@samp{<meta>} element in the @samp{<head>} to give some idea of the
+content of the document.  By default, this @dfn{description} is the title
+of the document, taken from the @code{@@settitle} command
+(@pxref{settitle}).  To change this, use the @code{@@documentdescription}
+environment, as in:
+
+@example
+@@documentdescription
+descriptive text.
+@@end documentdescription
+@end example
+
+@noindent
+This will produce the following output in the @samp{<head>} of the HTML:
+
+@example
+<meta name=description content="descriptive text.">
+@end example
+
+@code{@@documentdescription} must be specified before the first node of
+the document.
+
+
+@node setchapternewpage
+@subsection @code{@@setchapternewpage}:
+@cindex Starting chapters
+@cindex Pages, starting odd
+@findex setchapternewpage
+
+In an officially bound book, 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 @code{@@setchapternewpage} command with various
+arguments to specify how @TeX{} should start chapters and whether it
+should format headers for printing on one or both sides of the paper
+(single-sided or double-sided printing).
+
+Write the @code{@@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:
+
+@example
+@@setchapternewpage odd
+@end example
+
+You can specify one of three alternatives with the
+@code{@@setchapternewpage} command:
+
+@table @asis
+
+@item @code{@@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.
+
+@item @code{@@setchapternewpage on}
+Cause @TeX{} to start new chapters on new pages and to format page
+headers for single-sided printing.  This is the form most often used for
+short reports or personal printing. This is the default.
+
+@item @code{@@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.
+@end table
+
+Texinfo does not have an @code{@@setchapternewpage even} command,
+because there is no printing tradition of starting chapters or books on
+an even-numbered page.
+
+If you don't like the default headers that @code{@@setchapternewpage}
+sets, you can explicit control them with the @code{@@headings} command.
+@xref{headings on off, , The @code{@@headings} Command}.
+
+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 and frontmatter 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 @code{@@setchapternewpage}
+command has no effect on it.
+
+We recommend not including any @code{@@setchapternewpage} command in
+your manual sources at all, since the desired output is not intrinsic to
+the document.  For a particular hard copy run, if you don't want the
+default option (no blank pages, same headers on all pages) use the
+@option{--texinfo} option to @command{texi2dvi} to specify the output
+you want.
+
+
+@node paragraphindent
+@subsection @code{@@paragraphindent}: Paragraph Indenting
+@cindex Indenting paragraphs, control of
+@cindex Paragraph indentation control
+@findex paragraphindent
+
+The Texinfo processors may insert whitespace at the beginning of the
+first line of each paragraph, thereby indenting that paragraph.  You can
+use the @code{@@paragraphindent} command to specify this indentation.
+Write an @code{@@paragraphindent} command at the beginning of a line
+followed by either @samp{asis} or a number:
+
+@example
+@@paragraphindent @var{indent}
+@end example
+
+The indentation is according to the value of @var{indent}:
+
+@table @asis
+@item @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
+@item @code{none}
+@itemx 0
+Omit all indentation.
+
+@item @var{n}
+Indent by @var{n} space characters in Info output, by @var{n} ems in
+@TeX{}.
+
+@end table
+
+The default value of @var{indent} is 3.  @code{@@paragraphindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@paragraphindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified.  @xref{Start of
+Header}.
+
+A peculiarity of the @code{texinfo-format-buffer} and
+@code{texinfo-format-region} commands is that they do not indent (nor
+fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
+
+
+@node firstparagraphindent
+@subsection @code{@@firstparagraphindent}: Indenting After Headings
+@cindex First paragraph, suppressing indentation of
+@cindex Suppressing first paragraph indentation
+@cindex Preventing first paragraph indentation
+@cindex Indenting, suppressing of first paragraph
+@cindex Headings, indentation after
+@findex firstparagraphindent
+
+As you can see in the present manual, the first paragraph in any
+section is not indented by default.  Typographically, indentation is a
+paragraph separator, which means that it is unnecessary when a new
+section begins.  This indentation is controlled with the
+@code{@@firstparagraphindent} command:
+
+@example
+@@firstparagraphindent @var{word}
+@end example
+
+The first paragraph after a heading is indented according to the value
+of @var{word}:
+
+@table @asis
+@item @code{none}
+Prevents the first paragraph from being indented (default).
+This option is ignored by @command{makeinfo} if
+@code{@@paragraphindent asis} is in effect.
+
+@item @code{insert}
+Include normal paragraph indentation.  This respects the paragraph
+indentation set by a @code{@@paragraphindent} command
+(@pxref{paragraphindent}).
+@end table
+
+For HTML and XML output, the @code{@@firstparagraphindent} setting is
+ignored.
+
+It is best to write the @code{@@paragraphindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified.  @xref{Start of
+Header}.
+
+
+@node exampleindent
+@subsection @code{@@exampleindent}: Environment Indenting
+@cindex Indenting environments
+@cindex Environment indentation
+@cindex Example indentation
+@findex exampleindent
+
+The Texinfo processors indent each line of @code{@@example} and similar
+environments.  You can use the @code{@@exampleindent} command to specify
+this indentation.  Write an @code{@@exampleindent} command at the
+beginning of a line followed by either @samp{asis} or a number:
+
+@example
+@@exampleindent @var{indent}
+@end example
+
+@code{@@exampleindent} is ignored for HTML output.  Otherwise, the
+indentation is according to the value of @var{indent}:
+
+@table @asis
+@item @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
+@item 0
+Omit all indentation.
+
+@item @var{n}
+Indent environments by @var{n} space characters in Info output, by
+@var{n} ems in @TeX{}.
+
+@end table
+
+The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in}
+in @TeX{}, which is somewhat less.  (The reduction is to help @TeX{}
+fit more characters onto physical lines.)
+
+It is best to write the @code{@@exampleindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified.  @xref{Start of
+Header}.
+
+
+@node Software Copying Permissions
+@section Software Copying Permissions
+@cindex Software copying permissions
+@cindex Copying software
+@cindex Distribution
+@cindex License agreement
+
+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, we recommend placing this right after
+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.
+
+@cindex Introduction, as part of file
+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.
+
+
+@node Ending a File
+@chapter Ending a Texinfo File
+@cindex Ending a Texinfo file
+@cindex Texinfo file ending
+@cindex File ending
+@findex bye
+
+The end of a Texinfo file should include commands to create indices,
+and the @code{@@bye} command to mark the last line to be processed.
+
+For example:
+
+@example
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@bye
+@end example
+
+@menu
+* Printing Indices & Menus::    How to print an index in hardcopy and
+                                 generate index menus in Info.
+* File End::                    How to mark the end of a file.
+@end menu
+
+
+@node Printing Indices & Menus
+@section Printing Indices and Menus
+@cindex Printing an index
+@cindex Indices, printing and menus
+@cindex Generating menus with indices
+@cindex Menus generated with indices
+
+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 @code{@@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 @code{@@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
+@code{texindex} (@pxref{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 separate types of predefined index, which suffice
+in most cases.  @xref{Indices}, for information on this, as well
+defining your own new indices, combining indices, and, most
+importantly advice on writing the actual index entries.  This section
+focuses on printing indices, which is done with the
+@code{@@printindex} command.
+
+@findex printindex
+@code{@@printindex} takes one argument, a two-letter index
+abbreviation.  It reads the corresponding sorted index file (for
+printed output), and formats it appropriately into an index.
+
+The @code{@@printindex} command does not generate a chapter heading
+for the index, since different manuals have different needs.
+Consequently, you should precede the @code{@@printindex} command with
+a suitable section or chapter command (usually @code{@@appendix} or
+@code{@@unnumbered}) to supply the chapter heading and put the index
+into the table of contents.  Precede the chapter heading with an
+@code{@@node} line as usual.
+
+For example:
+
+@smallexample
+@group
+@@node Variable Index
+@@unnumbered Variable Index
+
+@@printindex vr
+@end group
+
+@group
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
+@end group
+@end smallexample
+
+If you have more than one index, we recommend placing the concept index last.
+
+@itemize
+@item
+In printed output, @code{@@printindex} produces a traditional
+two-column index, with dot leaders between the index terms and page
+numbers.
+
+@item
+In Info output, @code{@@printindex} produces a special menu containing
+the line number of the entry, relative to the start of the node.  Info
+readers can use this to go to the exact line of an entry, not just the
+containing node.  (Older Info readers will just go to the node.)
+Here's an example:
+
+@smallexample
+* First index entry:   Top.   (line  7)
+@end smallexample
+
+@noindent The actual number of spaces is variable, to right-justify
+the line number; it's been reduced here to make the line fit in the
+printed manual.
+
+@item
+In plain text output, @code{@@printindex} produces the same menu, but
+the line numbers are relative to the start of the file, since that's
+more convenient for that format.
+
+@item
+In HTML and Docbook output, @code{@@printindex} produces links
+to the index entries.
+
+@item
+In XML output, it simply records the index to be printed.
+@end itemize
+
+It's not possible to generate an index when writing to standard
+output; @command{makeinfo} generates a warning in this case.
+
+
+@node File End
+@section @code{@@bye} File Ending
+@findex bye
+
+An @code{@@bye} command terminates Texinfo processing.  None of the
+formatters read anything following @code{@@bye}.  The @code{@@bye}
+command should be on a line by itself.
+
+If you wish, you may follow the @code{@@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 @code{@@bye} were within
+@code{@@ignore} @dots{} @code{@@end ignore}.  Also, you may follow the
+@code{@@bye} line with a local variables list for XEmacs.
+@xref{Compile-Command, , Using Local Variables and the Compile Command},
+for more information.
+
+
+@node Structuring
+@chapter Chapter Structuring
+@cindex Chapter structuring
+@cindex Structuring of chapters
+
+The @dfn{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 (@pxref{Contents, , Generating a Table
+of Contents}).@refill
+
+The chapter structuring commands do not create an Info node structure,
+so normally you should put an @code{@@node} command immediately before
+each chapter structuring command (@pxref{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.@refill
+
+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.@refill
+
+@menu
+* Tree Structuring::            A manual is like an upside down tree @dots{}
+* Structuring Command Types::   How to divide a manual into parts.
+* makeinfo top::                The @code{@@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.
+@end menu
+
+
+@node Tree Structuring
+@section Tree Structure of Sections
+@cindex Tree structuring
+
+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.@refill
+
+Here is a diagram that shows a Texinfo file with three chapters,
+each of which has two sections.@refill
+
+@example
+@group
+                         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
+
+@end group
+@end example
+
+In a Texinfo file that has this structure, the beginning of Chapter 2
+looks like this:@refill
+
+@example
+@group
+@@node    Chapter 2,  Chapter 3, Chapter 1, top
+@@chapter Chapter 2
+@end group
+@end example
+
+The chapter structuring commands are described in the sections that
+follow; the @code{@@node} and @code{@@menu} commands are described in
+following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
+
+
+@node Structuring Command Types
+@section Structuring Command Types
+
+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.@refill
+
+The four groups are the @code{@@chapter} series, the
+@code{@@unnumbered} series, the @code{@@appendix} series, and the
+@code{@@heading} series.@refill
+
+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.@refill
+
+@itemize @bullet
+@item
+The @code{@@chapter} and @code{@@appendix} series of commands produce
+numbered or lettered entries both in the body of a printed work and in
+its table of contents.@refill
+
+@item
+The @code{@@unnumbered} series of commands produce unnumbered entries
+both in the body of a printed work and in its table of contents.  The
+@code{@@top} command, which has a special use, is a member of this
+series (@pxref{makeinfo top, , @code{@@top}}).  An @code{@@unnumbered}
+section should be associated with a node and be a normal part of the
+document structure.
+
+@item
+The @code{@@heading} series of commands produce simple unnumbered
+headings that do not appear in a table of contents, are not associated
+with nodes, and cannot be cross-referenced.  The heading commands
+never start a new page.
+
+@item
+The @code{@@majorheading} command is similar to @code{@@chapheading},
+except that it generates a larger vertical whitespace before the
+heading.
+
+@item
+When an @code{@@setchapternewpage} command says to do so, the
+@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
+start new pages in the printed manual; the @code{@@heading} commands
+do not.@refill
+@end itemize
+
+Here are the four groups of chapter structuring commands:
+
+@tex
+{\globaldefs = 1 \smallfonts}
+@end tex
+
+@multitable @columnfractions .19 .30 .29 .22
+@item                        @tab                              @tab                       @tab No new page
+@item @i{Numbered}           @tab @i{Unnumbered}               @tab @i{Lettered/numbered} @tab @i{Unnumbered}
+@item In contents            @tab In contents                  @tab In contents           @tab Not in contents
+@item                        @tab @code{@@top}                 @tab                       @tab @code{@@majorheading}
+@item @code{@@chapter}       @tab @code{@@unnumbered}          @tab @code{@@appendix} @tab @code{@@chapheading}
+@item @code{@@section}       @tab @code{@@unnumberedsec}       @tab @code{@@appendixsec} @tab @code{@@heading}
+@item @code{@@subsection}    @tab @code{@@unnumberedsubsec}    @tab @code{@@appendixsubsec} @tab @code{@@subheading}
+@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
+@end multitable
+@tex
+{\globaldefs = 1 \textfonts}
+@end tex
+
+
+@node makeinfo top
+@section @code{@@top}
+
+The @code{@@top} command is a special sectioning command that you use
+only after an @samp{@@node Top} line at the beginning of a Texinfo file.
+The @code{@@top} command tells the @code{makeinfo} formatter which node
+is the `Top' node, so it can use it as the root of the node tree if your
+manual uses implicit node pointers.  It has the same typesetting effect as
+@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
+and @code{@@appendix}}).  For detailed information, see @ref{makeinfo
+top command, , The @code{@@top} Command}.
+
+The @code{@@top} node and its menu (if any) is conventionally wrapped in
+an @code{@@ifnottex} conditional so that it will appear only in Info and
+HTML output, not @TeX{}.
+
+
+@node chapter
+@comment  node-name,  next,  previous,  up
+@section @code{@@chapter}
+@findex chapter
+
+@code{@@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.@refill
+
+For example, this chapter in this manual is entitled ``Chapter
+Structuring''; the @code{@@chapter} line looks like this:@refill
+
+@example
+@@chapter Chapter Structuring
+@end example
+
+In @TeX{}, the @code{@@chapter} command creates a chapter in the
+document, specifying the chapter title.  The chapter is numbered
+automatically.@refill
+
+In Info, the @code{@@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:@refill
+
+@example
+Chapter Structuring
+*******************
+@end example
+
+@findex centerchap
+Texinfo also provides a command @code{@@centerchap}, which is analogous
+to @code{@@unnumbered}, but centers its argument in the printed output.
+This kind of stylistic choice is not usually offered by Texinfo.
+@c but the Hacker's Dictionary wanted it ...
+
+
+@node unnumbered & appendix
+@section @code{@@unnumbered} and @code{@@appendix}
+@findex unnumbered
+@findex appendix
+
+Use the @code{@@unnumbered} command to create a chapter that appears
+in a printed manual without chapter numbers of any kind.  Use the
+@code{@@appendix} command to create an appendix in a printed manual
+that is labelled by letter (`A', `B', @dots{}) instead of by number.
+
+Write an @code{@@appendix} or @code{@@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.
+
+
+@node majorheading & chapheading
+@section @code{@@majorheading}, @code{@@chapheading}
+@findex majorheading
+@findex chapheading
+
+The @code{@@majorheading} and @code{@@chapheading} commands put
+chapter-like headings in the body of a document.@refill
+
+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.@refill
+
+In @TeX{}, an @code{@@majorheading} command generates a larger vertical
+whitespace before the heading than an @code{@@chapheading} command but
+is otherwise the same.
+
+In Info,
+the @code{@@majorheading} and
+@code{@@chapheading} commands are equivalent to
+@code{@@chapter}: the title is printed on a line by itself with a line
+of asterisks underneath.  (@xref{chapter, , @code{@@chapter}}.)@refill
+
+
+@node section
+@section @code{@@section}
+@findex section
+
+A @code{@@section} command identifies a section within a chapter unit,
+whether created with @code{@@chapter}, @code{@@unnumbered}, or
+@code{@@appendix}, following the numbering scheme of the chapter-level
+command.  Thus, within a @code{@@chapter} chapter numbered `1', the
+section is numbered like `1.2'; within an @code{@@appendix}
+``chapter'' labeled `A', the section is numbered like `A.2'; within an
+@code{@@unnumbered} chapter, the section gets no number.
+
+For example, this section is headed with an @code{@@section} command
+and looks like this in the Texinfo file:
+
+@example
+@@section @@code@{@@@@section@}
+@end example
+
+To create a section, write the @code{@@section} command at the
+beginning of a line and follow it on the same line by the section
+title.  The output is underlined with @samp{=} in Info.
+
+Thus,
+
+@example
+@@section This is a section
+@end example
+
+@noindent
+might produce the following in Info:
+
+@example
+@group
+5.7 This is a section
+=====================
+@end group
+@end example
+
+
+@node unnumberedsec appendixsec heading
+@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
+@findex unnumberedsec
+@findex appendixsec
+@findex heading
+
+The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the @code{@@section} command, as described
+in the previous section.
+
+@table @code
+@item @@unnumberedsec
+The @code{@@unnumberedsec} command may be used within an
+unnumbered chapter or within a regular chapter or appendix to
+provide an unnumbered section.@refill
+
+@item @@appendixsec
+@itemx @@appendixsection
+@code{@@appendixsection} is a longer spelling of the
+@code{@@appendixsec} command; the two are synonymous.@refill
+@findex appendixsection
+
+Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
+command is used only within appendices.@refill
+
+@item @@heading
+You may use the @code{@@heading} command anywhere you wish for a
+section-style heading that will not appear in the table of contents.@refill
+@end table
+
+@code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used
+in ordinary circumstances, because @code{@@section} may also be used
+within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
+the previous section.
+
+
+@node subsection
+@section The @code{@@subsection} Command
+@findex subsection
+
+Subsections are to sections as sections are to chapters.
+(@xref{section, , @code{@@section}}.)  In Info, subsection titles are
+underlined with @samp{-}.  For example,
+
+@example
+@@subsection This is a subsection
+@end example
+
+@noindent
+produces
+
+@example
+@group
+1.2.3 This is a subsection
+--------------------------
+@end group
+@end example
+
+In a printed manual, subsections are listed in the table of contents
+and are numbered three levels deep.@refill
+
+
+@node unnumberedsubsec appendixsubsec subheading
+@section The @code{@@subsection}-like Commands
+@cindex Subsection-like commands
+@findex unnumberedsubsec
+@findex appendixsubsec
+@findex subheading
+
+The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
+@code{@@subheading} commands are, respectively, the unnumbered,
+appendix-like, and heading-like equivalents of the @code{@@subsection}
+command.  (@xref{subsection, , @code{@@subsection}}.)
+
+In Info, the @code{@@subsection}-like commands generate a title
+underlined with hyphens.  In a printed manual, an @code{@@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 @code{@@unnumberedsubsec} command produces an unnumbered heading like
+that of a subsection and an @code{@@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.
+
+@code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
+be used in ordinary circumstances, because @code{@@subsection} may
+also be used within sections of @code{@@unnumbered} and
+@code{@@appendix} chapters (@pxref{section,,@code{section}}).
+
+
+@node subsubsection
+@section The `subsub' Commands
+@cindex Subsub commands
+@findex subsubsection
+@findex unnumberedsubsubsec
+@findex appendixsubsubsec
+@findex subsubheading
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands.  They are:@refill
+
+@table @code
+@item @@subsubsection
+Subsubsections are to subsections as subsections are to sections.
+(@xref{subsection, , @code{@@subsection}}.)  In a printed manual,
+subsubsection titles appear in the table of contents and are numbered
+four levels deep.@refill
+
+@item @@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.@refill
+
+@item @@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.@refill
+
+@item @@subsubheading
+The @code{@@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.@refill
+@end table
+
+@code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec} do not
+need to be used in ordinary circumstances, because
+@code{@@subsubsection} may also be used within subsections of
+@code{@@unnumbered} and @code{@@appendix} chapters
+(@pxref{section,,@code{section}}).
+
+
+In Info,  `subsub' titles are underlined with periods.
+For example,@refill
+
+@example
+@@subsubsection This is a subsubsection
+@end example
+
+@noindent
+produces
+
+@example
+@group
+1.2.3.4 This is a subsubsection
+...............................
+@end group
+@end example
+
+
+@node Raise/lower sections
+@section @code{@@raisesections} and @code{@@lowersections}
+@findex raisesections
+@findex lowersections
+@cindex Raising and lowering sections
+@cindex Lowering and raising sections
+@cindex Sections, raising and lowering
+
+The @code{@@raisesections} and @code{@@lowersections} commands
+implicitly raise and lower the hierarchical level of following
+chapters, sections and the other sectioning commands.
+
+That is, the @code{@@raisesections} command changes sections to
+chapters, subsections to sections, and so on.  Conversely, the
+@code{@@lowersections} command changes chapters to sections, sections
+to subsections, and so on.  Thus, an @code{@@lowersections} command
+cancels an @code{@@raisesections} command, and vice versa.
+
+@cindex Include files, and section levels
+You can use @code{@@lowersections} to include text written as an outer
+or standalone Texinfo file in another Texinfo file as an inner,
+included file.  Typical usage looks like this:
+
+@example
+@@lowersections
+@@include somefile.texi
+@@raisesections
+@end example
+
+@noindent (Without the @code{@@raisesections}, all the subsequent
+sections in the document would be lowered.)
+
+If the included file being lowered has a @code{@@top} node, you'll
+need to conditionalize its inclusion with a flag (@pxref{set value}).
+
+Another difficulty can arise with documents that use the (recommended)
+feature of @command{makeinfo} for implicitly determining node
+pointers.  Since @command{makeinfo} must assume a hierarchically
+organized document to determine the pointers, you cannot just
+arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections}
+commands in the document.  The final result has to have menus that
+take the raising and lowering into account.  Therefore, as a practical
+matter, you generally only want to raise or lower large chunks,
+usually in external files as shown above.
+
+Repeated use of the commands continue to raise or lower the
+hierarchical level a step at a time.  An attempt to raise above
+`chapter' reproduces chapter commands; an attempt to lower below
+`subsubsection' reproduces subsubsection commands.  Also, lowered
+subsubsections and raised chapters will not work with
+@command{makeinfo}'s feature of implicitly determining node pointers,
+since the menu structure won't be correct.
+
+Write each @code{@@raisesections} and @code{@@lowersections} command
+on a line of its own.
+
+
+@node Nodes
+@chapter Nodes
+
+@dfn{Nodes} are the primary segments of a Texinfo file.  They do not
+in and of themselves impose a hierarchical or any other kind of
+structure on a file.  Nodes contain @dfn{node pointers} that name
+other nodes, and can contain @dfn{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.
+
+Because node names are used in cross-references, it is not desirable
+to casually change them.  Such name changes invalidate references from
+other manuals, from mail archives, and so on.
+
+@menu
+* Two Paths::                   Different commands to structure
+                                 Info output and printed output.
+* Node Menu Illustration::      A diagram, and sample nodes and menus.
+* node::                        Creating nodes, in detail.
+* makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
+* anchor::                      Defining arbitrary cross-reference targets.
+@end menu
+
+
+@node Two Paths
+@section Two Paths
+
+The node and menu commands and the chapter structuring commands are
+technically independent of each other:
+
+@itemize @bullet
+@item
+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.@refill
+
+@item
+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.@refill
+@end itemize
+
+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, virtually all
+Texinfo files are written such that the structure for the Info output
+corresponds to the structure for the printed output.  It is neither
+convenient nor understandable to the reader to do otherwise.@refill
+
+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.@refill
+
+
+@node Node Menu Illustration
+@section 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.@refill
+
+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.@refill
+
+@example
+@group
+                         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
+@end group
+@end example
+
+The fully-written command to start Chapter 2 would be this:
+
+@example
+@group
+@@node     Chapter 2,  Chapter 3, Chapter 1, Top
+@@comment  node-name,  next,      previous,  up
+@end group
+@end example
+
+@noindent
+This @code{@@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''.  You can omit writing out these node names if your document is
+hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
+pointer relationships still obtain.
+
+@quotation Note
+@strong{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 most often follows a
+chapter-level node, for example.  `Next' and `Previous' refer to nodes
+at the @emph{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.)@refill
+@end quotation
+
+To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
+2.  (@xref{Menus}.)  You would write the menu just
+before the beginning of Section 2.1, like this:@refill
+
+@example
+@group
+   @@menu
+   * Sect. 2.1::    Description of this section.
+   * Sect. 2.2::
+   @@end menu
+@end group
+@end example
+
+Write the node for Sect. 2.1 like this:@refill
+
+@example
+@group
+   @@node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+   @@comment  node-name, next,      previous,  up
+@end group
+@end example
+
+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 @ref{Cross References}.)@refill
+
+Usually, an @code{@@node} command and a chapter structuring command are
+used in sequence, along with indexing commands.  (You may follow the
+@code{@@node} line with a comment line that reminds you which pointer is
+which.)@refill
+
+Here is the beginning of the chapter in this manual called ``Ending a
+Texinfo File''.  This shows an @code{@@node} line followed by a comment
+line, an @code{@@chapter} line, and then by indexing lines.@refill
+
+@example
+@group
+@@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
+@end group
+@end example
+
+
+@node node
+@section The @code{@@node} Command
+
+@cindex Node, defined
+@findex node
+
+A @dfn{node} is a segment of text that begins at an @code{@@node}
+command and continues until the next @code{@@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 @code{@@node} command in the file.  A node usually
+contains only one chapter structuring command, the one that follows
+the @code{@@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 specify a node, write an @code{@@node} command at the beginning of
+a line, and follow it with up to four arguments, separated by commas,
+on the rest of the same line.  The first argument is required; it is
+the name of this node (for details of node names, @pxref{Node Line
+Requirements}).  The subsequent arguments are the names of the `Next',
+`Previous', and `Up' pointers, in that order, and may be omitted if
+your Texinfo document is hierarchically organized (@pxref{makeinfo
+Pointer Creation}).
+
+@opindex accesskey@r{, in HTML output}
+Whether the node pointers are specified implicitly or explicitly, the
+HTML output from @command{makeinfo} for each node includes links to
+the `Next', `Previous', and `Up' nodes.  The HTML also uses the
+@code{accesskey} attribute with the values @samp{n}, @samp{p}, and
+@samp{u} respectively.  This allows people using web browsers to
+follow the nagivation using (typically) @kbd{M-@var{letter}}, e.g.,
+@kbd{M-n} for the `Next' node, from anywhere within the node.
+
+You may insert spaces before each name on the @code{@@node} line if
+you wish; the spaces are ignored.  You must write the name of the node
+and (if present) the names of the `Next', `Previous', and `Up'
+pointers all on the same line.  Otherwise, the formatters fail.
+(@inforef{Top, info, info}, for more information about nodes in Info.)
+
+Usually, you write one of the chapter-structuring command lines
+immediately after an @code{@@node} line---for example, an
+@code{@@section} or @code{@@subsection} line.  (@xref{Structuring
+Command Types}.)
+
+@TeX{} uses @code{@@node} lines to identify the names to use for cross
+references.  For this reason, you must write @code{@@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 @code{@@xref} and related commands;
+see @ref{Cross References}.)
+
+@menu
+* Node Names::                  How to choose node and pointer names.
+* Writing a Node::              How to write an @code{@@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 @code{@@top} command.
+@end menu
+
+
+@node Node Names
+@subsection Choosing Node and Pointer Names
+
+@cindex Node names, choosing
+The name of a node identifies the node (for details of node names,
+@pxref{Node Line Requirements}).  The pointers enable you to reach
+other nodes and consist simply 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 the present 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 @file{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.  @xref{First Node}, for information on how to write the
+first node of a Texinfo file.
+
+Even when you explicitly specify all pointers, that does not mean you
+can write the nodes in the Texinfo source file in an arbitrary order!
+Because @TeX{} processes the file sequentially, irrespective of node
+pointers, you must write the nodes in the order you wish them to appear
+in the output.
+
+
+@node Writing a Node
+@subsection How to Write an @code{@@node} Line
+@cindex Writing an @code{@@node} line
+@cindex @code{@@node} line writing
+@cindex Node line writing
+
+The easiest way to write an @code{@@node} line is to write @code{@@node}
+at the beginning of a line and then the name of the node, like
+this:
+
+@example
+@@node @var{node-name}
+@end example
+
+If you are using XEmacs, 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 @code{makeinfo}
+insert node pointers into the Info file it creates.  (@xref{Texinfo
+Mode}, and @ref{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 @kbd{C-c C-c n}.  This command inserts
+@samp{@@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 fully-written-out node line with `Next', `Previous',
+and `Up' pointers looks like this:
+
+@example
+@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
+@end example
+
+The @var{node-name} argument must be present, but the others are
+optional.  If you wish to specify some but not others, just insert
+commas as needed, as in: @samp{@@node mynode,,,uppernode}.  However,
+we recommend leaving off all the pointers and letting @code{makeinfo}
+determine them, as described above.
+
+If you wish, you can ignore @code{@@node} lines altogether in your first
+draft and then use the @code{texinfo-insert-node-lines} command to
+create @code{@@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 @code{@@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.
+
+
+@node Node Line Tips
+@subsection @code{@@node} Line Tips
+
+Here are three suggestions:
+
+@itemize @bullet
+@item
+Try to pick node names that are informative but short.@refill
+
+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.)@refill
+
+@item
+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.@refill
+
+@item
+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.@refill
+@end itemize
+
+
+@node Node Line Requirements
+@subsection @code{@@node} Line Requirements
+
+@cindex Node line requirements
+@cindex Restrictions on node names
+Here are several requirements for @code{@@node} lines:
+
+@itemize @bullet
+@cindex Unique nodename requirement
+@cindex Node name must be unique
+@item
+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.
+
+@item
+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.
+
+@cindex @@-commands in nodename
+@cindex Node name, should not contain @@-commands
+@item
+@@-commands in node names are not allowed.  This includes punctuation
+characters that are escaped with a @samp{@@}, such as @code{@@} and
+@code{@{}, and accent commands such as @samp{@@'}.  (For a few cases
+when this is useful, Texinfo has limited support for using
+@w{@@-commands} in node names; see @ref{Pointer Validation}.)  Perhaps
+this limitation will be removed some day.
+
+@item
+@cindex Colon in nodename
+@cindex Comma in nodename
+@cindex Parentheses in nodename
+@cindex Period in nodename
+@cindex Characters, invalid in node name
+@cindex Invalid characters in node names
+@cindex Node names, invalid characters in
+Unfortunately, you cannot use periods, commas, colons or parentheses
+within a node name; these confuse the Texinfo processors.  Perhaps
+this limitation will be removed some day, too.
+
+@need 700
+For example, the following is a section title in this manual:
+
+@smallexample
+@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
+@end smallexample
+
+@noindent
+But the corresponding node name lacks the commas and the @@'s:
+
+@smallexample
+unnumberedsec appendixsec heading
+@end smallexample
+
+@cindex Case in node name
+@item
+Case is significant in node names.
+
+@cindex White space in node name
+@cindex Spaces in node name
+Spaces before and after names on the @samp{@@node} line are ignored,
+but spaces ``inside'' a name are significant.  For example:
+
+@example
+@@node  foo bar,
+@@node foo bar ,
+@@node  foo bar ,
+@end example
+
+@noindent all define the same node, @samp{foo bar}.  References to the
+node should all use that name, without the leading or trailing spaces,
+but with the internal spaces.
+@end itemize
+
+
+@node First Node
+@subsection The First Node
+@cindex Top node is first
+@cindex First node
+
+The first node of a Texinfo file is the @dfn{Top} node, except in an
+included file (@pxref{Include Files}).  The Top node should contain a
+short summary, copying permissions, and a master menu.  @xref{The Top
+Node}, for more information on the Top node contents and examples.
+
+Here is a description of the node pointers to be used in the Top node:
+
+@itemize @bullet
+
+@item
+@cindex Up node of Top node
+@cindex (dir) as Up node of Top node
+The Top node (which must be named @samp{top} or @samp{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.
+
+Usually, all Info files are installed in the same Info directory tree;
+in this case, use @samp{(dir)} as the parent of the Top node; this is
+short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
+file, which contains the main menu for the Info system as a whole.
+
+@item
+@cindex Prev node of Top node
+The `Prev' node of the Top node should also be your @samp{(dir)} file.
+
+@item
+@cindex Next node of Top node
+The `Next' node of the Top node should be the first chapter in your
+document.
+
+@end itemize
+
+@xref{Installing an Info File}, for more information about installing
+an Info file in the @file{info} directory.
+
+It is usually best to leave the pointers off entirely and let the
+tools implicitly define them, with this simple result:
+
+@example
+@@node Top
+@end example
+
+
+@node makeinfo top command
+@subsection The @code{@@top} Sectioning Command
+@findex top @r{(@@-command)}
+
+A special sectioning command, @code{@@top} should be used with the
+@code{@@node Top} line.  The @code{@@top} sectioning command tells
+@code{makeinfo} that it marks the `Top' node in the file.  It provides
+the information that @code{makeinfo} needs to insert node pointers
+automatically.  Write the @code{@@top} command at the beginning of the
+line immediately following the @code{@@node Top} line.  Write the title
+on the remaining part of the same line as the @code{@@top} command.
+
+In Info, the @code{@@top} sectioning command causes the title to appear
+on a line by itself, with a line of asterisks inserted underneath, as
+other sectioning commands do.
+
+In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+sectioning command is merely a synonym for @code{@@unnumbered}.
+Neither of these formatters require an @code{@@top} command, and do
+nothing special with it.  You can use @code{@@chapter} or
+@code{@@unnumbered} after the @code{@@node Top} line when you use
+these formatters.  Also, you can use @code{@@chapter} or
+@code{@@unnumbered} when you use the Texinfo updating commands to
+create or update pointers and menus.
+
+Thus, in practice, a Top node starts like this:
+
+@example
+@@node Top
+@@top Your Manual Title
+@end example
+
+
+@node makeinfo Pointer Creation
+@section Creating Pointers with @code{makeinfo}
+@cindex Creating pointers with @code{makeinfo}
+@cindex Pointer creation with @code{makeinfo}
+@cindex Automatic pointer creation with @code{makeinfo}
+
+The @code{makeinfo} program has a feature for automatically
+determining node pointers for a hierarchically organized document.  We
+highly recommend using it.
+
+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 @code{@@chapter}
+or @code{@@section}, on the line immediately following each truncated
+@code{@@node} line (except that comment lines may intervene).
+
+In addition, you must follow the `Top' @code{@@node} line with a line
+beginning with @code{@@top} to mark the `Top' node in the
+file.  @xref{makeinfo top, , @code{@@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.
+
+@cindex Detail menu
+@findex detailmenu
+If you use a detailed menu in your master menu (@pxref{Master Menu
+Parts}), mark it with the @code{@@detailmenu @@dots@{@} @@end
+detailmenu} environment, or @command{makeinfo} will get confused,
+typically about the last and/or first node in the document.
+
+This implicit node pointer creation feature in @code{makeinfo}
+relieves you from the need to update menus and pointers manually or
+with Texinfo mode commands.  (@xref{Updating Nodes and Menus}.)
+
+In most cases, you will want to take advantage of this feature and not
+redundantly specify node pointers.  However, Texinfo documents are not
+required to be organized hierarchically or in fact to contain
+sectioning commands at all (for example, if you never intend the
+document to be printed).  The special procedure for handling the short
+text before a menu (@pxref{Menus}) also disables this
+feature, for that group of nodes.  In those cases, you will need to
+explicitly specify all pointers.
+
+@node anchor
+@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
+
+@findex anchor
+@cindex Anchors
+@cindex Cross-reference targets, arbitrary
+@cindex Targets for cross-references, arbitrary
+
+An @dfn{anchor} is a position in your document, labeled so that
+cross-references can refer to it, just as they can to nodes.  You create
+an anchor with the @code{@@anchor} command, and give the label as a
+normal brace-delimited argument.  For example:
+
+@example
+This marks the @@anchor@{x-spot@}spot.
+@dots{}
+@@xref@{x-spot,,the spot@}.
+@end example
+
+@noindent produces:
+
+@example
+This marks the spot.
+@dots{}
+See [the spot], page 1.
+@end example
+
+As you can see, the @code{@@anchor} command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an @code{@@xref} or other cross-reference
+command, as shown.  @xref{Cross References}, for details on the
+cross-reference commands.
+
+It is best to put @code{@@anchor} commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor.  You can put the @code{@@anchor}
+command on a line by itself if that helps readability of the source.
+Whitespace (including newlines) is ignored after @code{@@anchor}.
+
+Anchor names and node names may not conflict.  Anchors and nodes are
+given similar treatment in some ways; for example, the @code{goto-node}
+command in standalone Info takes either an anchor name or a node name as
+an argument.  (@xref{goto-node,,,info-stnd,GNU Info}.)
+
+Also like node names, anchor names cannot include some characters
+(@pxref{Node Line Requirements}).
+
+
+@node Menus
+@chapter Menus
+@cindex Menus
+@findex menu
+
+@dfn{Menus} contain pointers to subordinate nodes.  In online output,
+you use menus to go to such nodes.  Menus have no effect in printed
+manuals and do not appear in them.
+
+A node with a menu should not contain much text.  If you find yourself
+writing a lot of text before a menu, we generally recommend moving
+most of the text into a new subnode---all but a paragraph or two.
+Otherwise, a reader with a terminal that displays only a few lines may
+miss the menu and its associated text.  As a practical matter, it is
+best to locate a menu within 20 or so lines of the beginning of the
+node.
+
+@menu
+* Menu Location::               Menus go at the ends of short nodes.
+* 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.
+@end menu
+
+
+@node Menu Location
+@section Menu Location
+@cindex Menu location
+@cindex Location of menus
+
+A menu must be located at the end of a node, without any regular text
+or additional commands between the @code{@@end menu} and the beginning
+of the next node.  (As a consequence, there may be at most one menu in
+a node.)
+
+@cindex Info format, and menus
+This is actually a useful restriction, since a reader who uses the
+menu could easily miss any such text.  Technically, it is necessary
+because in Info format, there is no marker for the end of a menu, so
+Info-reading programs would have no way to know when the menu ends and
+normal text resumes.
+
+@cindex Hierarchical documents, and menus
+Technically, menus can carry you to any node, regardless of the
+structure of the document; even to nodes in a different Info file.
+However, we do not recommend ever making use of this, because the
+@command{makeinfo} implicit pointer creation feature (@pxref{makeinfo
+Pointer Creation}) and XEmacs Texinfo mode updating commands work
+only to create menus of subordinate nodes in a hierarchically
+structured document.  Instead, use cross references to refer to
+arbitrary nodes.
+
+In the past, we recommended using a @samp{@@heading} command within an
+@code{@@ifinfo} conditional instead of the normal sectioning commands
+after a very short node with a menu.  This had the advantage of making
+the printed output look better, because there was no very short text
+between two headings on the page.  But this also does not work with
+@command{makeinfo}'s implicit pointer creation, and it also makes the
+XML output incorrect, since it does not reflect the true document
+structure.  So, regrettably, we can no longer recommend this.
+
+
+@node Writing a Menu
+@section Writing a Menu
+@cindex Writing a menu
+@cindex Menu writing
+
+A menu consists of an @code{@@menu} command on a line by itself
+followed by menu entry lines or menu comment lines and then by an
+@code{@@end menu} command on a line by itself.
+
+A menu looks like this:
+
+@example
+@group
+@@menu
+Larger Units of Text
+
+* Files::                       All about handling files.
+* Multiples: Buffers.           Multiple buffers; editing
+                                 several files at once.
+@@end menu
+@end group
+@end example
+
+In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
+entry}.  (Note the space after the asterisk.)  A line that does not
+start with an @w{@samp{* }} 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 @samp{Larger Units of Text} is a
+menu comment line; the two lines starting with @w{@samp{* }} are menu
+@cindex Spaces, in menus
+entries.  Space characters in a menu are preserved as-is; this allows
+you to format the menu as you wish.
+
+@opindex accesskey@r{, in HTML output}
+In the HTML output from @command{makeinfo}, the @code{accesskey}
+attribute is used with the values @samp{1}@dots{}@samp{9} for the
+first nine entries.  This allows people using web browsers to follow
+the first menu entries using (typically) @kbd{M-@var{digit}}, e.g.,
+@kbd{M-1} for the first entry.
+
+
+@node Menu Parts
+@section The Parts of a Menu
+@cindex Parts of a menu
+@cindex Menu parts
+@cindex @code{@@menu} parts
+
+A menu entry has three parts, only the second of which is required:
+
+@enumerate
+@item
+The menu entry name (optional).
+
+@item
+The name of the node (required).
+
+@item
+A description of the item (optional).
+@end enumerate
+
+The template for a generic menu entry looks like this (but see the
+next section for one more possibility):
+
+@example
+* @var{menu-entry-name}: @var{node-name}.   @var{description}
+@end example
+
+Follow the menu entry name with a single colon and follow the node name
+with tab, comma, newline, or the two characters period and space
+(@samp{. }).
+
+In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
+command.  The menu entry name is what the user types after the @kbd{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.
+
+
+@node Less Cluttered Menu Entry
+@section Less Cluttered Menu Entry
+@cindex Two part menu entry
+@cindex Double-colon menu entries
+@cindex Menu entries with two colons
+@cindex Less cluttered menu entry
+@cindex Uncluttered 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.
+
+@need 800
+For example, write
+
+@example
+* Name::                        @var{description}
+@end example
+
+@need 800
+@noindent
+instead of
+
+@example
+* Name: Name.                   @var{description}
+@end example
+
+You should indeed use the node name for the menu entry name whenever
+possible, since it reduces visual clutter in the menu.
+
+
+@node Menu Example
+@section A Menu Example
+@cindex Menu example
+@cindex Example menu
+
+A menu looks like this in Texinfo:@refill
+
+@example
+@group
+@@menu
+* menu entry name: Node name.   A short description.
+* Node name::                   This form is preferred.
+@@end menu
+@end group
+@end example
+
+@need 800
+@noindent
+This produces:
+
+@example
+@group
+* menu:
+
+* menu entry name: Node name.   A short description.
+* Node name::                   This form is preferred.
+@end group
+@end example
+
+@need 700
+Here is an example as you might see it in a Texinfo file:@refill
+
+@example
+@group
+@@menu
+Larger Units of Text
+
+* Files::                       All about handling files.
+* Multiples: Buffers.           Multiple buffers; editing
+                                 several files at once.
+@@end menu
+@end group
+@end example
+
+@need 800
+@noindent
+This produces:
+
+@example
+@group
+* menu:
+Larger Units of Text
+
+* Files::                       All about handling files.
+* Multiples: Buffers.           Multiple buffers; editing
+                                 several files at once.
+@end group
+@end example
+
+In this example, the menu has two entries.  @samp{Files} is both a menu
+entry name and the name of the node referred to by that name.
+@samp{Multiples} is the menu entry name; it refers to the node named
+@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
+appears in the menu, but is not an entry.@refill
+
+Since no file name is specified with either @samp{Files} or
+@samp{Buffers}, they must be the names of nodes in the same Info file
+(@pxref{Other Info Files, , Referring to Other Info Files}).@refill
+
+@node Other Info Files
+@comment  node-name,  next,  previous,  up
+@section Referring to Other Info Files
+@cindex Referring to other Info files
+@cindex Nodes in other Info files
+@cindex Other Info files' nodes
+@cindex Going to other Info files' nodes
+@cindex Info; other files' nodes
+
+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.@refill
+
+@need 800
+The format looks like this:@refill
+
+@example
+@group
+@@menu
+* @var{first-entry-name}:(@var{filename})@var{nodename}.     @var{description}
+* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
+@@end menu
+@end group
+@end example
+
+For example, to refer directly to the @samp{Outlining} and
+@samp{Rebinding} nodes in the @cite{XEmacs User's Manual}, you would
+write a menu like this:@refill
+
+@example
+@group
+@@menu
+* Outlining: (xemacs)Outline Mode. The major mode for
+                                 editing outlines.
+* Rebinding: (xemacs)Rebinding.    How to redefine the
+                                 meaning of a key.
+@@end menu
+@end group
+@end example
+
+If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' node.@refill
+
+The @file{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.  (@xref{Installing an Info File}.)
+
+@need 700
+For example:
+
+@example
+@group
+* Info: (info).         Documentation browsing system.
+* XEmacs: (xemacs).     The extensible, self-documenting
+                        text editor.
+@end group
+@end example
+
+@noindent
+(The @file{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.)@refill
+
+The XEmacs 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.
+
+
+@node Cross References
+@chapter Cross References
+@cindex Making cross references
+@cindex Cross references
+@cindex References
+
+@dfn{Cross references} are used to refer the reader to other parts of the
+same or different Texinfo files.  In Texinfo, nodes and anchors 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' @dots{}
+* 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.
+* cite::                        How to refer to books not in the Info system.
+@end menu
+
+@node References
+@section 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.@refill
+
+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 online 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.@refill
+
+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.@refill
+
+In Info, a cross reference results in an entry that you can follow
+using the Info @samp{f} command.  (@inforef{Help-Xref, Following
+cross-references, info}.)
+
+The various cross reference commands use nodes (or anchors,
+@pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
+This is evident in Info, in which a cross reference takes you to the
+specified location.  @TeX{} also uses nodes to define cross reference
+locations, but the action is less obvious.  When @TeX{} generates a DVI
+file, it records each node's page number 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 online, you must nonetheless write
+@code{@@node} lines to name the places to which you make cross
+references.@refill
+
+@need 800
+@node Cross Reference Commands
+@comment  node-name,  next,  previous,  up
+@section Different Cross Reference Commands
+@cindex Different cross reference commands
+
+There are four different cross reference commands:@refill
+
+@table @code
+@item @@xref
+Used to start a sentence in the printed manual saying @w{`See @dots{}'}
+or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
+
+@item @@ref
+Used within or, more often, at the end of a sentence; same as
+@code{@@xref} for Info; produces just the reference in the printed
+manual without a preceding `See'.@refill
+
+@item @@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. (@samp{p} is for `parenthesis'.)@refill
+
+@item @@inforef
+Used to make a reference to an Info file for which there is no printed
+manual.@refill
+@end table
+
+@noindent
+(The @code{@@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.   @xref{cite, , @code{@@cite}}.)@refill
+
+@node Cross Reference Parts
+@comment  node-name,  next,  previous,  up
+@section Parts of a Cross Reference
+@cindex Cross reference parts
+@cindex 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.@refill
+
+Here is a simple cross reference example:@refill
+
+@example
+@@xref@{Node name@}.
+@end example
+
+@noindent
+which produces
+
+@example
+*Note Node name::.
+@end example
+
+@noindent
+and
+
+@quotation
+See Section @var{nnn} [Node name], page @var{ppp}.
+@end quotation
+
+@need 700
+Here is an example of a full five-part cross reference:@refill
+
+@example
+@group
+@@xref@{Node name, Cross Reference Name, Particular Topic,
+info-file-name, A Printed Manual@}, for details.
+@end group
+@end example
+
+@noindent
+which produces
+
+@example
+*Note Cross Reference Name: (info-file-name)Node name,
+for details.
+@end example
+
+@noindent
+in Info and
+
+@quotation
+See section ``Particular Topic'' in @i{A Printed Manual}, for details.
+@end quotation
+
+@noindent
+in a printed book.
+
+The five possible arguments for a cross reference are:@refill
+
+@enumerate
+@item
+The node or anchor name (required).  This is the location 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.@refill
+
+@item
+The cross reference name for the Info reference, if it is to be
+different from the node name or the topic description.  If you
+include this argument, it becomes the first part of the cross reference.
+It is usually omitted; then the topic description (third argument) is
+used if it was specified; if that was omitted as well, the node name
+is used.
+
+@item
+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.@refill
+
+@item
+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 @samp{.info}
+suffix on the file name, since Info readers try appending it
+automatically.
+
+@item
+The name of a printed manual from a different Texinfo file.@refill
+@end enumerate
+
+The template for a full five argument cross reference looks like
+this:@refill
+
+@example
+@group
+@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
+@var{info-file-name}, @var{printed-manual-title}@}.
+@end group
+@end example
+
+Cross references with one, two, three, four, and five arguments are
+described separately following the description of @code{@@xref}.@refill
+
+Write a node name in a cross reference in exactly the same way as in
+the @code{@@node} line, including the same capitalization; otherwise, the
+formatters may not find the reference.@refill
+
+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 @code{@@xref} at the beginning of a sentence; write
+@code{@@pxref} only within parentheses, and so on.@refill
+
+@node xref
+@comment  node-name,  next,  previous,  up
+@section @code{@@xref}
+@findex xref
+@cindex Cross references using @code{@@xref}
+@cindex References using @code{@@xref}
+
+The @code{@@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 @samp{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.@refill
+
+@menu
+* Reference Syntax::            What a reference looks like and requires.
+* One Argument::                @code{@@xref} with one argument.
+* Two Arguments::               @code{@@xref} with two arguments.
+* Three Arguments::             @code{@@xref} with three arguments.
+* Four and Five Arguments::     @code{@@xref} with four and five arguments.
+@end menu
+
+@node Reference Syntax
+@subsection What a Reference Looks Like and Requires
+
+Most often, an Info cross reference looks like this:@refill
+
+@example
+*Note @var{node-name}::.
+@end example
+
+@noindent
+or like this
+
+@example
+*Note @var{cross-reference-name}: @var{node-name}.
+@end example
+
+@noindent
+In @TeX{}, a cross reference looks like this:
+
+@quotation
+See Section @var{section-number} [@var{node-name}], page @var{page}.
+@end quotation
+
+@noindent
+or like this
+
+@quotation
+See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
+@end quotation
+
+The @code{@@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 @code{@@pxref} command works
+differently.  @xref{pxref, , @code{@@pxref}}.)@refill
+
+@quotation Caution
+A period or comma @strong{must} follow the closing
+brace of an @code{@@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.@refill
+@end quotation
+
+@code{@@xref} must refer to an Info node by name.  Use @code{@@node}
+to define the node (@pxref{Writing a Node}).@refill
+
+@code{@@xref} is followed by several arguments inside braces, separated by
+commas.  Whitespace before and after these commas is ignored.@refill
+
+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.@refill
+
+@quotation Note
+Commas separate arguments in a cross reference;
+avoid including them in the title or other part lest the formatters
+mistake them for separators.@refill
+@end quotation
+
+@node One Argument
+@subsection @code{@@xref} with One Argument
+
+The simplest form of @code{@@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.@refill
+
+@need 700
+@noindent
+For example,
+
+@example
+@@xref@{Tropical Storms@}.
+@end example
+
+@noindent
+produces
+
+@example
+*Note Tropical Storms::.
+@end example
+
+@noindent
+and
+
+@quotation
+See Section 3.1 [Tropical Storms], page 24.
+@end quotation
+
+@noindent
+(Note that in the preceding example the closing brace is followed by a
+period.)@refill
+
+You can write a clause after the cross reference, like this:@refill
+
+@example
+@@xref@{Tropical Storms@}, for more info.
+@end example
+
+@noindent
+which produces
+
+@example
+*Note Tropical Storms::, for more info.
+@end example
+
+@noindent
+and
+
+@quotation
+See Section 3.1 [Tropical Storms], page 24, for more info.
+@end quotation
+
+@noindent
+(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.)@refill
+
+@node Two Arguments
+@subsection @code{@@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.@refill
+
+@need 750
+@noindent
+The template is like this:
+
+@example
+@@xref@{@var{node-name}, @var{cross-reference-name}@}.
+@end example
+
+@need 700
+@noindent
+For example,
+
+@example
+@@xref@{Electrical Effects, Lightning@}.
+@end example
+
+@noindent
+produces:
+
+@example
+*Note Lightning: Electrical Effects.
+@end example
+
+@noindent
+and
+
+@quotation
+See Section 5.2 [Electrical Effects], page 57.
+@end quotation
+
+@noindent
+(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:@refill
+
+@example
+@@xref@{Electrical Effects, Lightning@}, for more info.
+@end example
+
+@noindent
+which produces
+@example
+*Note Lightning: Electrical Effects, for more info.
+@end example
+
+@noindent
+and
+
+@quotation
+See Section 5.2 [Electrical Effects], page 57, for more info.
+@end quotation
+
+@noindent
+(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.)@refill
+
+@node Three Arguments
+@subsection @code{@@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.@refill
+
+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.@refill
+
+Also, remember to write a comma or period after the closing brace of an
+@code{@@xref} to terminate the cross reference.  In the following
+examples, a clause follows a terminating comma.@refill
+
+
+@need 750
+@noindent
+The template is like this:
+
+@example
+@group
+@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
+@end group
+@end example
+
+@need 700
+@noindent
+For example,
+
+@example
+@group
+@@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
+for details.
+@end group
+@end example
+
+@noindent
+produces
+
+@example
+*Note Lightning: Electrical Effects, for details.
+@end example
+
+@noindent
+and
+
+@quotation
+See Section 5.2 [Thunder and Lightning], page 57, for details.
+@end quotation
+
+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.)@refill
+
+@example
+@group
+@@xref@{Electrical Effects, , Thunder and Lightning@},
+for details.
+@end group
+@end example
+
+@noindent
+produces
+
+@example
+*Note Thunder and Lightning: Electrical Effects, for details.
+@end example
+
+@noindent
+and
+
+@quotation
+See Section 5.2 [Thunder and Lightning], page 57, for details.
+@end quotation
+
+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.@refill
+
+Here are several examples from @cite{The GNU Awk User's Guide}:@refill
+
+@smallexample
+@@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@}.
+@end smallexample
+
+@node Four and Five Arguments
+@subsection @code{@@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.@refill
+
+Remember that a comma or period must follow the closing brace of an
+@code{@@xref} command to terminate the cross reference.  In the
+following examples, a clause follows a terminating comma.@refill
+
+@need 800
+@noindent
+The template is:
+
+@example
+@group
+@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
+@var{info-file-name}, @var{printed-manual-title}@}.
+@end group
+@end example
+
+@need 700
+@noindent
+For example,
+
+@example
+@@xref@{Electrical Effects, Lightning, Thunder and Lightning,
+weather, An Introduction to Meteorology@}, for details.
+@end example
+
+@noindent
+produces
+
+@example
+*Note Lightning: (weather)Electrical Effects, for details.
+@end example
+
+@noindent
+The name of the Info file is enclosed in parentheses and precedes
+the name of the node.
+
+@noindent
+In a printed manual, the reference looks like this:@refill
+
+@quotation
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
+@end quotation
+
+@noindent
+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.@refill
+
+Often, you will leave out the second argument when you use the long
+version of @code{@@xref}.  In this case, the third argument, the topic
+description, will be used as the cross reference name in Info.@refill
+
+@noindent
+The template looks like this:
+
+@example
+@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
+@var{printed-manual-title}@}, for details.
+@end example
+
+@noindent
+which produces
+
+@example
+*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
+@end example
+
+@noindent
+and
+
+@quotation
+See section @var{title-or-topic} in @var{printed-manual-title}, for details.
+@end quotation
+
+@need 700
+@noindent
+For example,
+
+@example
+@@xref@{Electrical Effects, , Thunder and Lightning,
+weather, An Introduction to Meteorology@}, for details.
+@end example
+
+@noindent
+produces
+
+@example
+@group
+*Note Thunder and Lightning: (weather)Electrical Effects,
+for details.
+@end group
+@end example
+
+@noindent
+and
+
+@quotation
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
+@end quotation
+
+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.@refill
+
+@node Top Node Naming
+@section Naming a `Top' Node
+@cindex Naming a `Top' Node in references
+@cindex @samp{@r{Top}} node naming for references
+
+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 @code{@@xref} command.  (This
+is different from the way you write a menu entry; see @ref{Other Info
+Files, , Referring to 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 @code{@@xref} command.
+@refill
+
+@noindent
+Thus, to make a cross reference to @cite{The GNU Make Manual},
+write:@refill
+
+@example
+@@xref@{Top, , Overview, make, The GNU Make Manual@}.
+@end example
+
+@noindent
+which produces
+
+@example
+*Note Overview: (make)Top.
+@end example
+
+@noindent
+and
+
+@quotation
+See section ``Overview'' in @i{The GNU Make Manual}.
+@end quotation
+
+@noindent
+In this example, @samp{Top} is the name of the first node, and
+@samp{Overview} is the name of the first section of the manual.
+
+
+@node ref
+@section @code{@@ref}
+@cindex Cross references using @code{@@ref}
+@cindex References using @code{@@ref}
+@findex ref
+
+@code{@@ref} is nearly the same as @code{@@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.
+
+@noindent For example,
+
+@cindex Hurricanes
+@example
+For more information, @@pxref@{This@}, and @@ref@{That@}.
+@end example
+
+@noindent produces in Info:
+
+@example
+For more information, *note This::, and *note That::.
+@end example
+
+@noindent and in printed output:
+
+@quotation
+For more information, see Section 1.1 [This], page 1,
+and Section 1.2 [That], page 2.
+@end quotation
+
+The @code{@@ref} command sometimes tempts 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:
+
+@cindex Sea surges
+@example
+Sea surges are described in @@ref@{Hurricanes@}.
+@end example
+
+@noindent looks ok in the printed output:
+
+@quotation
+Sea surges are described in Section 6.7 [Hurricanes], page 72.
+@end quotation
+
+@noindent but is awkward to read in Info, ``note'' being a verb:
+
+@example
+Sea surges are described in *note Hurricanes::.
+@end example
+
+You should write a period or comma immediately after an @code{@@ref}
+command with two or more arguments.  If there is no such following
+punctuation, @command{makeinfo} will generate a (grammatically
+incorrect) period in the Info output; otherwise, the cross-reference
+would fail completely, due to the current syntax of Info format.
+
+In general, it is best to use @code{@@ref} only when you need some
+word other than ``see'' to precede the reference.  When ``see'' (or
+``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.
+
+
+@node pxref
+@section @code{@@pxref}
+@cindex Cross references using @code{@@pxref}
+@cindex References using @code{@@pxref}
+@findex pxref
+
+The parenthetical reference command, @code{@@pxref}, is nearly the
+same as @code{@@xref}, but it is best used at the end of a sentence or
+before a closing parenthesis.  The command differs from @code{@@xref}
+in two ways:
+
+@enumerate
+@item
+@TeX{} typesets the reference for the printed manual with a lower case
+`see' rather than an upper case `See'.
+
+@item
+The Info formatting commands automatically end the reference with a
+closing colon or period, if necessary.
+@end enumerate
+
+@code{@@pxref} is designed so that the output looks right and works
+right at the end of a sentence or parenthetical phrase, 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.  @code{@@pxref} spares you the need to use
+complicated methods to put a terminator into one form of the output
+and not the other.
+
+@noindent
+With one argument, a parenthetical cross reference looks like this:
+
+@cindex Flooding
+@example
+@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
+@end example
+
+@need 800
+@noindent
+which produces
+
+@example
+@group
+@dots{} storms cause flooding (*note Hurricanes::) @dots{}
+@end group
+@end example
+
+@noindent
+and
+
+@quotation
+@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
+@end quotation
+
+With two arguments, a parenthetical cross reference has this template:
+
+@example
+@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
+@end example
+
+@noindent
+which produces
+
+@example
+@dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{}
+@end example
+
+@noindent
+and
+
+@quotation
+@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
+@end quotation
+
+@code{@@pxref} can be used with up to five arguments, just like
+@code{@@xref} (@pxref{xref, , @code{@@xref}}).
+
+In past versions of Texinfo, it was not allowed to write punctuation
+after a @code{@@pxref}, so it could be used @emph{only} before a right
+parenthesis.  This is no longer the case, so now it can be used (for
+example) at the end of a sentence, where a lowercase ``see'' works
+best.  For instance:
+
+@example
+@dots{} For more information, @@pxref@{More@}.
+@end example
+
+@noindent
+which outputs (in Info):
+
+@example
+@dots{} For more information, *note More::.
+@end example
+
+@noindent
+This works fine.  @code{@@pxref} should only be followed by a comma,
+period, or right parenthesis; in other cases, @command{makeinfo} has
+to insert a period to make the cross-reference work correctly in Info,
+and that period looks wrong.
+
+As a matter of general style, @code{@@pxref} is best used at the ends
+of sentences.  Although it technically works in the middle of a
+sentence, that location breaks up the flow of reading.
+
+
+@node inforef
+@section @code{@@inforef}
+@cindex Cross references using @code{@@inforef}
+@cindex References using @code{@@inforef}
+@findex inforef
+
+@code{@@inforef} is used for making cross references to Info
+documents---even from a printed manual.  This might be because you
+want to refer to conditional @code{@@ifinfo} text
+(@pxref{Conditionals}), or because printed output is not available
+(perhaps because there is no Texinfo source), among other
+possibilities.
+
+The command takes either two or three arguments, in the following
+order:@refill
+
+@enumerate
+@item
+The node name.
+
+@item
+The cross reference name (optional).
+
+@item
+The Info file name.
+@end enumerate
+
+@noindent
+Separate the arguments with commas, as with @code{@@xref}.  Also, you
+must terminate the reference with a comma or period after the
+@samp{@}}, as you do with @code{@@xref}.@refill
+
+@noindent
+The template is:
+
+@example
+@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
+@end example
+
+@need 800
+@noindent
+For example,
+
+@example
+@group
+@@inforef@{Advanced, Advanced Info commands, info@},
+for more information.
+@end group
+@end example
+
+@need 800
+@noindent
+produces (in Info):
+
+@example
+@group
+*Note Advanced Info commands: (info)Advanced,
+for more information.
+@end group
+@end example
+
+@need 800
+@noindent
+and (in the printed output):
+
+@quotation
+See Info file @file{info}, node @samp{Advanced}, for more information.
+@end quotation
+
+(This particular example is not realistic, since the Info manual is
+written in Texinfo, so all formats are available.)
+
+The converse of @code{@@inforef} is @code{@@cite}, which is used to
+refer to printed works for which no Info form exists.  @xref{cite, ,
+@code{@@cite}}.
+
+
+@node uref
+@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
+@findex uref
+@cindex Uniform resource locator, referring to
+@cindex URL, referring to
+
+@cindex @code{href}, producing HTML
+@code{@@uref} produces a reference to a uniform resource locator (url).
+It takes one mandatory argument, the url, and two optional arguments
+which control the text that is displayed.  In HTML output, @code{@@uref}
+produces a link you can follow.
+
+@code{@@url} is a synonym for @code{@@uref}.  Originally, @code{@@url}
+had the meaning of @code{@@indicateurl}
+(@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it
+was misused the vast majority of the time.  So we've changed the
+meaning.
+
+The second argument, if specified, is the text to display (the default
+is the url itself); in Info and DVI output, but not in HTML output, the
+url is also output.
+
+@cindex Man page, reference to
+The third argument, if specified, is the text to display, but in this
+case the url is @emph{not} output in any format.  This is useful when
+the text is already sufficiently referential, as in a man page.  If
+the third argument is given, the second argument is ignored.
+
+If the url is long enough to cause problems with line breaking, you
+may find it useful to insert @code{@@/} at places where a line break
+would be acceptable (after @samp{/} characters, for instance).  This
+tells @TeX{} to allow (but not force) a line break at those places.
+@xref{Line Breaks}.
+
+Here is an example of the simple one argument form, where the url is
+both the target and the text of the link:
+
+@example
+The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
+@end example
+
+@noindent produces:
+@display
+The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
+@end display
+
+
+An example of the two-argument form:
+@example
+The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
+holds programs and texts.
+@end example
+
+@noindent produces:
+@display
+The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
+holds programs and texts.
+@end display
+
+@noindent that is, the Info output is this:
+@example
+The official GNU ftp site (ftp://ftp.gnu.org/gnu)
+holds programs and texts.
+@end example
+
+@noindent and the HTML output is this:
+@example
+The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
+holds programs and texts.
+@end example
+
+
+An example of the three-argument form:
+@example
+The @@uref@{/man.cgi/1/ls,,ls@} program @dots{}
+@end example
+
+@noindent produces:
+@display
+The @uref{/man.cgi/1/ls,,ls} program @dots{}
+@end display
+
+@noindent but with HTML:
+@example
+The <a href="/man.cgi/1/ls">ls</a> program @dots{}
+@end example
+
+To merely indicate a url without creating a link people can follow, use
+@code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}).
+
+Some people prefer to display url's in the unambiguous format:
+
+@display
+<URL:http://@var{host}/@var{path}>
+@end display
+
+@noindent
+@cindex <URL: convention, not used
+You can use this form in the input file if you wish.  We feel it's not
+necessary to include the @samp{<URL:} and @samp{>} in the output,
+since any software that tries to detect url's in text already has to
+detect them without the @samp{<URL:} to be useful.
+
+
+@node cite
+@section @code{@@cite}@{@var{reference}@}
+@findex cite
+
+Use the @code{@@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.
+@xref{xref, , @code{@@xref}}.
+
+
+@node Marking Text
+@chapter Marking Words and Phrases
+@cindex Paragraph, marking text within
+@cindex Marking words and phrases
+@cindex Words and phrases, marking them
+@cindex Marking text within a paragraph
+@cindex Text, marking up
+
+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, in several different ways.
+
+@menu
+* Indicating::                  How to indicate definitions, files, etc.
+* Emphasis::                    How to emphasize text.
+@end menu
+
+
+@node Indicating
+@section Indicating Definitions, Commands, etc.
+@cindex Highlighting text
+@cindex Indicating commands, definitions, etc.
+
+Texinfo has commands for indicating just what kind of object a piece of
+text refers to.  For example, metasyntactic variables are marked by
+@code{@@var}, and code by @code{@@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 @emph{intentional} formatting language rather than a @emph{typesetting}
+formatting language.)@refill
+
+For example, in a printed manual,
+code is usually illustrated in a typewriter font;
+@code{@@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 affect 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.@refill
+
+@menu
+* Useful Highlighting::         Highlighting provides useful information.
+* code::                        Indicating program code.
+* kbd::                         Showing keyboard input.
+* key::                         Specifying keys.
+* samp::                        Indicating a literal sequence of characters.
+* verb::                        Indicating a verbatim sequence of characters.
+* var::                         Indicating metasyntactic variables.
+* env::                         Indicating environment variables.
+* file::                        Indicating file names.
+* command::                     Indicating command names.
+* option::                      Indicating option names.
+* dfn::                         Specifying definitions.
+* abbr::                        Indicating abbreviations.
+* acronym::                     Indicating acronyms.
+* indicateurl::                 Indicating an example URL.
+* email::                       Indicating an electronic mail address.
+@end menu
+
+
+@node Useful Highlighting
+@subsection Highlighting Commands are Useful
+
+The highlighting commands can be used to extract useful information
+from the file, such as lists of functions or file names.  It is
+possible, for example, to write a program in XEmacs 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.@refill
+
+The commands serve a variety of purposes:@refill
+
+@table @code
+@item @@code@{@var{sample-code}@}
+Indicate text that is a literal example of a piece of a program.
+@xref{code,,@code{@@code}}.
+
+@item @@kbd@{@var{keyboard-characters}@}
+Indicate keyboard input.
+@xref{kbd,,@code{@@kbd}}.
+
+@item @@key@{@var{key-name}@}
+Indicate the conventional name for a key on a keyboard.
+@xref{key,,@code{@@key}}.
+
+@item @@samp@{@var{text}@}
+Indicate text that is a literal example of a sequence of characters.
+@xref{samp,,@code{@@samp}}.
+
+@item @@verb@{@var{text}@}
+Write a verbatim sequence of characters.
+@xref{verb,,@code{@@verb}}.
+
+@item @@var@{@var{metasyntactic-variable}@}
+Indicate a metasyntactic variable.
+@xref{var,,@code{@@var}}.
+
+@item @@env@{@var{environment-variable}@}
+Indicate an environment variable.
+@xref{env,,@code{@@env}}.
+
+@item @@file@{@var{file-name}@}
+Indicate the name of a file.
+@xref{file,,@code{@@file}}.
+
+@item @@command@{@var{command-name}@}
+Indicate the name of a command.
+@xref{command,,@code{@@command}}.
+
+@item @@option@{@var{option}@}
+Indicate a command-line option.
+@xref{option,,@code{@@option}}.
+
+@item @@dfn@{@var{term}@}
+Indicate the introductory or defining use of a term.
+@xref{dfn,,@code{@@dfn}}.
+
+@item @@cite@{@var{reference}@}
+Indicate the name of a book.
+@xref{cite,,@code{@@cite}}.
+
+@item @@abbr@{@var{abbreviation}@}
+Indicate an abbreviation, such as `Comput.'.
+
+@item @@acronym@{@var{acronym}@}
+Indicate an acronym.
+@xref{acronym,,@code{@@acronym}}.
+
+@item @@indicateurl@{@var{uniform-resource-locator}@}
+Indicate an example (that is, nonfunctional) uniform resource locator.
+@xref{indicateurl,,@code{@@indicateurl}}.  (Use @code{@@url}
+(@pxref{uref,,@code{@@url}}) for live url's.)
+
+@item @@email@{@var{email-address}[, @var{displayed-text}]@}
+Indicate an electronic mail address.
+@xref{email,,@code{@@email}}.
+
+@ignore
+@item @@ctrl@{@var{ctrl-char}@}
+Use for an ASCII control character.
+@end ignore
+@end table
+
+
+@node code
+@subsection @code{@@code}@{@var{sample-code}@}
+@findex code
+
+@cindex Syntactic tokens, indicating
+Use the @code{@@code} command to indicate text that is a piece of a
+program and which consists of entire syntactic tokens.  Enclose the
+text in braces.
+
+@cindex Expressions in a program, indicating
+@cindex Keywords, indicating
+@cindex Reserved words, indicating
+Thus, you should use @code{@@code} for an expression in a program, for
+the name of a variable or function used in a program, or for a
+keyword in a programming language.
+
+Use @code{@@code} for command names in languages that resemble
+programming languages, such as Texinfo.  For example, @code{@@code} and
+@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
+@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
+
+@cindex Case, not altering in @code{@@code}
+It is incorrect to alter the case of a word inside an @code{@@code}
+command when it appears at the beginning of a sentence.  Most computer
+languages are case sensitive.  In C, for example, @code{Printf} is
+different from the identifier @code{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 name written all in lower case, you
+should rearrange the sentence.
+
+In the printed manual, @code{@@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,
+
+@example
+The function returns @@code@{nil@}.
+@end example
+
+@noindent
+produces this:
+
+@quotation
+The function returns @code{nil}.
+@end quotation
+
+@iftex
+@noindent
+and this in the Info file:
+@example
+The function returns `nil'.
+@end example
+@end iftex
+
+Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
+
+@itemize @bullet
+@item
+For shell command names such as @command{ls} (use @code{@@command}).
+
+@item
+For shell options such as @samp{-c} when such options stand alone (use
+@code{@@option}).
+
+@item
+Also, an entire shell command often looks better if written using
+@code{@@samp} rather than @code{@@code}.  In this case, the rule is to
+choose the more pleasing format.
+
+@item
+For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
+
+@item
+For a string of characters shorter than a syntactic token.  For example,
+if you are writing about @samp{goto-ch}, which is just a part of the
+name for the @code{goto-char} XEmacs Lisp function, you should use
+@code{@@samp}.
+
+@item
+In general, when writing about the characters used in a token; for
+example, do not use @code{@@code} when you are explaining what letters
+or printable symbols can be used in the names of functions.  (Use
+@code{@@samp}.)  Also, you should not use @code{@@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{@@code} for the keystroke commands of XEmacs (use
+@code{@@kbd} instead) although you may use @code{@@code} for the names
+of the XEmacs Lisp functions that the keystroke commands invoke.
+
+@end itemize
+
+Since @code{@@command}, @code{@@option}, and @code{@@env} were
+introduced relatively recently, it is acceptable to use @code{@@code} or
+@code{@@samp} for command names, options, and environment variables.
+The new commands allow you to express the markup more precisely, but
+there is no real harm in using the older commands, and of course the
+long-standing manuals do so.
+
+Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
+@samp{_} characters within @code{@@code} and related commands.  This
+can be controlled with @code{@@allowcodebreaks}
+(@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}).
+
+
+@node kbd
+@subsection @code{@@kbd}@{@var{keyboard-characters}@}
+@findex kbd
+@cindex Keyboard input
+
+Use the @code{@@kbd} command for characters of input to be typed by
+users.  For example, to refer to the characters @kbd{M-a}, write:
+
+@example
+@@kbd@{M-a@}
+@end example
+
+@noindent
+and to refer to the characters @kbd{M-x shell}, write:
+
+@example
+@@kbd@{M-x shell@}
+@end example
+
+@cindex User input
+@cindex Slanted typewriter font, for @code{@@kbd}
+By default, the @code{@@kbd} command produces a different font
+(slanted typewriter instead of normal typewriter) in the printed
+manual, so users can distinguish the characters that they are supposed
+to type from those that the computer outputs.
+
+In Info output, @code{@@kbd} is usually the same as @code{@@code},
+producing `quotes' around its argument.  However, in typewriter-like
+contexts such as the @code{@@example} environment (@pxref{example})
+and @code{@@code} command itself, the quotes are omitted, since Info
+format cannot use distinguishing fonts.
+
+@findex kbdinputstyle
+Since the usage of @code{@@kbd} varies from manual to manual, you can
+control the font switching with the @code{@@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:
+
+@vindex distinct@r{, value for @code{@@kbdinputstyle}}
+@vindex example@r{, value for @code{@@kbdinputstyle}}
+@vindex code@r{, value for @code{@@kbdinputstyle}}
+@table @samp
+@item code
+Always use the same font for @code{@@kbd} as @code{@@code}.
+@item example
+Use the distinguishing font for @code{@@kbd} only in @code{@@example}
+and similar environments.
+@item distinct
+(the default) Always use the distinguishing font for @code{@@kbd}.
+@end table
+
+You can embed another @@-command inside the braces of an @code{@@kbd}
+command.  Here, for example, is the way to describe a command that
+would be described more verbosely as ``press the @samp{r} key and then
+press the @key{RETURN} key'':
+
+@example
+@@kbd@{r @@key@{RET@}@}
+@end example
+
+@noindent
+This produces: @kbd{r @key{RET}}.  (The present manual uses the
+default for @code{@@kbdinputstyle}.)
+
+You also use the @code{@@kbd} command if you are spelling out the letters
+you type; for example:
+
+@example
+To give the @@code@{logout@} command,
+type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
+@end example
+
+@noindent
+This produces:
+
+@quotation
+To give the @code{logout} command,
+type the characters @kbd{l o g o u t @key{RET}}.
+@end quotation
+
+(Also, this example shows that you can add spaces for clarity.  If you
+explicitly want to mention a space character as one of the characters of
+input, write @kbd{@@key@{SPC@}} for it.)@refill
+
+
+@node key
+@subsection @code{@@key}@{@var{key-name}@}
+@findex key
+
+Use the @code{@@key} command for the conventional name for a key on a
+keyboard, as in:@refill
+
+@example
+@@key@{RET@}
+@end example
+
+You can use the @code{@@key} command within the argument of an
+@code{@@kbd} command when the sequence of characters to be typed
+includes one or more keys that are described by name.@refill
+
+For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you
+would type:
+
+@example
+@@kbd@{C-x @@key@{ESC@}@}
+@@kbd@{M-@@key@{TAB@}@}
+@end example
+
+Here is a list of the recommended names for keys:
+@cindex Recommended names for keys
+@cindex Keys, recommended names
+@cindex Names recommended for keys
+@cindex Abbreviations for keys
+
+@quotation
+@table @t
+@item SPC
+Space
+@item RET
+Return
+@item LFD
+Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
+it might be better to call this character @kbd{C-j})
+@item TAB
+Tab
+@item BS
+Backspace
+@item ESC
+Escape
+@item DELETE
+Delete
+@item SHIFT
+Shift
+@item CTRL
+Control
+@item META
+Meta
+@end table
+@end quotation
+
+@cindex META key
+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 @kbd{Meta-a}, use the @code{@@kbd} command
+alone; do not use the @code{@@key} command; but when you are referring
+to the modifier key in isolation, use the @code{@@key} command.  For
+example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
+@samp{@@key@{META@}} to produce @key{META}.
+
+As a convention in GNU manuals, @code{@@key} should not be used in
+index entries.
+
+
+@node samp
+@subsection @code{@@samp}@{@var{text}@}
+@findex samp
+
+Use the @code{@@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.@refill
+
+@example
+To match @@samp@{foo@} at the end of the line,
+use the regexp @@samp@{foo$@}.
+@end example
+
+@noindent
+produces
+
+@quotation
+To match @samp{foo} at the end of the line, use the regexp
+@samp{foo$}.@refill
+@end quotation
+
+Any time you are referring to single characters, you should use
+@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
+Also, you may use @code{@@samp} for entire statements in C and for entire
+shell commands---in this case, @code{@@samp} often looks better than
+@code{@@code}.  Basically, @code{@@samp} is a catchall for whatever is
+not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
+
+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:@refill
+
+@example
+@group
+In English, the vowels are @@samp@{a@}, @@samp@{e@},
+@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
+@@samp@{y@}.
+@end group
+@end example
+
+@noindent
+This produces:
+
+@quotation
+In English, the vowels are @samp{a}, @samp{e},
+@samp{i}, @samp{o}, @samp{u},  and sometimes
+@samp{y}.
+@end quotation
+
+
+@node verb
+@subsection @code{@@verb}@{<char>@var{text}<char>@}
+@findex verb
+@cindex Verbatim in-line text
+
+@cindex Delimiter character, for verbatim
+Use the @code{@@verb} command to print a verbatim sequence of
+characters.
+
+Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using
+any unique delimiter character.  Enclose the verbatim text, including the
+delimiters, in braces.  Text is printed in a fixed-width font:
+
+@example
+How many @@verb@{|@@|@}-escapes does one need to print this
+@@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
+@end example
+
+@noindent
+produces
+
+@example
+How many @verb{|@|}-escapes does one need to print this
+@verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
+@end example
+
+This is in contrast to @code{@@samp} (see the previous section),
+@code{@@code}, and similar commands; in those cases, the argument is
+normal Texinfo text, where the three characters @code{@@@{@}} are
+special.  With @code{@@verb}, nothing is special except the delimiter
+character you choose.
+
+It is not reliable to use @code{@@verb} inside other Texinfo
+constructs.  In particular, it does not work to use @code{@@verb} in
+anything related to cross-referencing, such as section titles or
+figure captions.
+
+
+@node var
+@subsection @code{@@var}@{@var{metasyntactic-variable}@}
+@findex var
+
+Use the @code{@@var} command to indicate metasyntactic variables.  A
+@dfn{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.@refill
+
+Do not use @code{@@var} for the names of particular variables in
+programming languages.  These are specific names from a program, so
+@code{@@code} is correct for them (@pxref{code}).  For example, the
+XEmacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
+variable; it is properly formatted using @code{@@code}.
+
+Do not use @code{@@var} for environment variables either; @code{@@env}
+is correct for them (see the next section).
+
+The effect of @code{@@var} in the Info file is to change the case of the
+argument to all upper case.  In the printed manual and HTML output, the
+argument is printed in slanted type.
+
+@need 700
+For example,
+
+@example
+To delete file @@var@{filename@},
+type @@samp@{rm @@var@{filename@}@}.
+@end example
+
+@noindent
+produces
+
+@quotation
+To delete file @var{filename}, type @samp{rm @var{filename}}.
+@end quotation
+
+@noindent
+(Note that @code{@@var} may appear inside @code{@@code},
+@code{@@samp}, @code{@@file}, etc.)@refill
+
+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:@refill
+
+@example
+@group
+\input texinfo
+@@@@setfilename @@var@{info-file-name@}
+@@@@settitle @@var@{name-of-manual@}
+@end group
+@end example
+
+@noindent
+This produces:
+
+@example
+@group
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
+@end group
+@end example
+
+In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:@refill
+
+@example
+@dots{}, type rm <filename>
+@end example
+
+@noindent
+However, that is not the style that Texinfo uses.  (You can, of
+course, modify the sources to @file{texinfo.tex} and the Info formatting commands
+to output the @code{<@dots{}>} format if you wish.)@refill
+
+
+@node env
+@subsection @code{@@env}@{@var{environment-variable}@}
+@findex env
+
+Use the @code{@@env} command to indicate environment variables, as used
+by many operating systems, including GNU.  Do not use it for
+metasyntactic variables; use @code{@@var} instead (see the previous
+section).
+
+@code{@@env} is equivalent to @code{@@code} in its effects.
+For example:
+
+@example
+The @@env@{PATH@} environment variable @dots{}
+@end example
+@noindent produces
+@quotation
+The @env{PATH} environment variable @dots{}
+@end quotation
+
+
+@node file
+@subsection @code{@@file}@{@var{file-name}@}
+@findex file
+
+Use the @code{@@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 @code{@@file}
+for symbols in a programming language; use @code{@@code}.
+
+Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
+For example,@refill
+
+@example
+The @@file@{.el@} files are in
+the @@file@{/usr/local/xemacs/lisp@} directory.
+@end example
+
+@noindent
+produces
+
+@quotation
+The @file{.el} files are in
+the @file{/usr/local/xemacs/lisp} directory.
+@end quotation
+
+
+@node command
+@subsection @code{@@command}@{@var{command-name}@}
+@findex command
+@cindex Command names, indicating
+@cindex Program names, indicating
+
+Use the @code{@@commannd} command to indicate command names, such as
+@command{ls} or @command{cc}.
+
+@code{@@command} is equivalent to @code{@@code} in its effects.
+For example:
+
+@example
+The command @@command@{ls@} lists directory contents.
+@end example
+@noindent produces
+@quotation
+The command @command{ls} lists directory contents.
+@end quotation
+
+You should write the name of a program in the ordinary text font, rather
+than using @code{@@command}, if you regard it as a new English word,
+such as `XEmacs' or `Bison'.
+
+When writing an entire shell command invocation, as in @samp{ls -l},
+you should use either @code{@@samp} or @code{@@code} at your discretion.
+
+
+@node option
+@subsection @code{@@option}@{@var{option-name}@}
+@findex option
+
+Use the @code{@@option} command to indicate a command-line option; for
+example, @option{-l} or @option{--version} or
+@option{--output=@var{filename}}.
+
+@code{@@option} is equivalent to @code{@@samp} in its effects.
+For example:
+
+@example
+The option @@option@{-l@} produces a long listing.
+@end example
+@noindent produces
+@quotation
+The option @option{-l} produces a long listing.
+@end quotation
+
+In tables, putting options inside @code{@@code} produces a
+more pleasing effect.
+
+@node dfn
+@comment  node-name,  next,  previous,  up
+@subsection @code{@@dfn}@{@var{term}@}
+@findex dfn
+
+Use the @code{@@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 @code{@@dfn}.  The command generates italics in
+the printed manual, and double quotation marks in the Info file.  For
+example:@refill
+
+@example
+Getting rid of a file is called @@dfn@{deleting@} it.
+@end example
+
+@noindent
+produces
+
+@quotation
+Getting rid of a file is called @dfn{deleting} it.
+@end quotation
+
+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.
+
+@ignore
+@c node ctrl, , cite, Indicating
+@comment  node-name,  next,  previous,  up
+@c subsection @code{@@ctrl}@{@var{ctrl-char}@}
+@findex ctrl
+
+The @code{@@ctrl} command is seldom used.  It describes an ASCII
+control character by inserting the actual character into the Info
+file.
+
+Usually, in Texinfo, you talk what you type as keyboard entry by
+describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
+@kbd{C-a}.  Use @code{@@kbd} in this way when talking about a control
+character that is typed on the keyboard by the user.  When talking
+about a control character appearing in a file or a string, do not use
+@code{@@kbd} since the control character is not typed.  Also, do not
+use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
+to make it easier for a reader to understand.@refill
+
+@code{@@ctrl} is an idea from the beginnings of Texinfo which may not
+really fit in to the scheme of things.  But there may be times when
+you want to use the command.  The pattern is
+@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character
+whose control-equivalent is wanted.  For example, to specify
+@samp{control-f}, you would enter@refill
+
+@example
+@@ctrl@{f@}
+@end example
+
+@noindent
+produces
+
+@quotation
+@ctrl{f}
+@end quotation
+
+In the Info file, this generates the specified control character, output
+literally into the file.  This is done so a user can copy the specified
+control character (along with whatever else he or she wants) into another
+XEmacs buffer and use it.  Since the `control-h',`control-i', and
+`control-j' characters are formatting characters, they should not be
+indicated with @code{@@ctrl}.@refill
+
+In a printed manual, @code{@@ctrl} generates text to describe or
+identify that control character: an uparrow followed by the character
+@var{ch}.@refill
+@end ignore
+
+
+@node abbr
+@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@}
+@findex abbr
+
+@cindex Abbreviations, tagging
+You can use the @code{@@abbr} command for general abbreviations.  The
+abbreviation is given as the single argument in braces, as in
+@samp{@@abbr@{Comput.@}}.  As a matter of style, or for particular
+abbreviations, you may prefer to omit periods, as in
+@samp{@@abbr@{Mr@} Stallman}.
+
+@code{@@abbr} accepts an optional second argument, intended to be used
+for the meaning of the abbreviation.
+
+If the abbreviation ends with a lowercase letter and a period, and is
+not at the end of a sentence, and has no second argument, remember to
+use the @code{@@.} command (@pxref{Not Ending a
+Sentence}) to get the correct spacing.  However, you do not have to
+use @code{@@.} within the abbreviation itself; Texinfo automatically
+assumes periods within the abbreviation do not end a sentence.
+
+@cindex <abbr> and <abbrev> tags
+In @TeX{} and in the Info output, the first argument is printed as-is;
+if the second argument is present, it is printed in parentheses after
+the abbreviation.  In HTML and XML, the @code{<abbr>} tag is
+used; in Docbook, the @code{<abbrev>} tag is used.  For instance:
+
+@example
+@@abbr@{Comput. J., Computer Journal@}
+@end example
+
+@noindent produces:
+
+@display
+@abbr{Comput. J., Computer Journal}
+@end display
+
+For abbreviations consisting of all capital letters, you may prefer to
+use the @code{@@acronym} command instead.  See the next section for
+more on the usage of these two commands.
+
+
+@node acronym
+@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@}
+@findex acronym
+
+@cindex NASA, as acronym
+@cindex Acronyms, tagging
+Use the @code{@@acronym} command for abbreviations written in all
+capital letters, such as `@acronym{NASA}'.  The abbreviation is given as
+the single argument in braces, as in @samp{@@acronym@{NASA@}}.  As
+a matter of style, or for particular acronyms, you may prefer to
+use periods, as in @samp{@@acronym@{N.A.S.A.@}}.
+
+@code{@@acronym} accepts an optional second argument, intended to be
+used for the meaning of the acronym.
+
+If the acronym is at the end of a sentence, and if there is no second
+argument, remember to use the @code{@@.} or similar command
+(@pxref{Ending a Sentence}) to get the correct spacing.
+
+@cindex <acronym> tag
+In @TeX{}, the acronym is printed in slightly smaller font.  In the
+Info output, the argument is printed as-is.  In either format, if the
+second argument is present, it is printed in parentheses after the
+acronym.  In HTML, Docbook, and XML, the @code{<acronym>} tag is
+used.  
+
+For instance (since GNU is a recursive acronym, we use
+@code{@@acronym} recursively):
+
+@example
+@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@}
+@end example
+
+@noindent produces:
+
+@display
+@acronym{GNU, @acronym{GNU}'s Not Unix}
+@end display
+
+@cindex Family names, in all capitals
+In some circumstances, it is conventional to print family names in all
+capitals.  Don't use @code{@@acronym} for this, since a name is not an
+acronym.  Use @code{@@sc} instead (@pxref{Smallcaps}).
+
+@code{@@abbr} and @code{@@acronym} are closely related commands: they
+both signal to the reader that a shortened form is being used, and
+possibly give a meaning.  When choosing whether to use these two
+commands, please bear the following in mind.
+
+@itemize @minus
+@item
+In standard English usage, acronyms are a subset of abbreviations:
+they include pronounceable words like `@acronym{NATO}', `radar', and
+`snafu', and some sources also include syllable acronyms like
+`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable
+initialisms like `@acronym{FBI}'.
+
+@item
+In Texinfo, an acronym (but not an abbreviation) should consist only
+of capital letters and periods, no lowercase.
+
+@item
+In @TeX{}, an acronym (but not an abbreviation) is printed in a
+slightly smaller font.
+
+@item
+Some browsers place a dotted bottom border under abbreviations but not
+acronyms.
+
+@item
+It's not essential to use either of these commands for all
+abbreviations; use your judgment.  Text is perfectly readable without
+them.
+
+@end itemize
+
+
+@node indicateurl
+@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@}
+@findex indicateurl
+@cindex Uniform resource locator, indicating
+@cindex URL, indicating
+
+Use the @code{@@indicateurl} command to indicate a uniform resource
+locator on the World Wide Web.  This is analogous to @code{@@file},
+@code{@@var}, etc., and is purely for markup purposes.  It does not
+produce a link you can follow in HTML output (use the @code{@@uref}
+command for that, @pxref{uref,, @code{@@uref}}).  It is useful for
+url's which do not actually exist.  For example:
+
+@example
+For example, the url might be @@indicateurl@{http://example.org/path@}.
+@end example
+
+@noindent which produces:
+
+@display
+For example, the url might be @indicateurl{http://example.org/path}.
+@end display
+
+
+@node email
+@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
+@findex email
+
+Use the @code{@@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).
+
+@cindex Mailto link
+In Info, the address is shown in angle brackets, preceded by the text
+to display if any.  In @TeX{}, the angle brackets are omitted.  In
+HTML output, @code{@@email} produces a @samp{mailto} link that usually
+brings up a mail composition window.  For example:
+
+@example
+Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
+suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
+@end example
+@noindent produces
+@display
+Send bug reports to @email{bug-texinfo@@gnu.org},
+suggestions to the @email{bug-texinfo@@gnu.org, same place}.
+@end display
+
+
+@node Emphasis
+@section Emphasizing Text
+@cindex 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{@@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 effect on Info and only one of them,
+the @code{@@r} command, has any regular use.@refill
+
+@menu
+* emph & strong::               How to emphasize text in Texinfo.
+* Smallcaps::                   How to use the small caps font.
+* Fonts::                       Various font commands for printed output.
+@end menu
+
+@node emph & strong
+@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
+@cindex Emphasizing text, font for
+@findex emph
+@findex strong
+
+The @code{@@emph} and @code{@@strong} commands are for emphasis;
+@code{@@strong} is stronger.  In printed output, @code{@@emph} produces
+@emph{italics} and @code{@@strong} produces @strong{bold}.
+
+For example,
+
+@example
+@group
+@@strong@{Caution:@} @@samp@{rm * .[^.]*@}
+removes @@emph@{all@} files in the directory.
+@end group
+@end example
+
+@noindent
+produces the following in printed output and HTML:
+
+@quotation
+@strong{Caution}: @samp{rm * .[^.]*}
+removes @emph{all} files in the directory.
+@end quotation
+
+@noindent
+and the following in Info:
+
+@example
+*Caution:* `rm * .[^.]*' removes _all_
+files in the directory.
+@end example
+
+The @code{@@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 output, @code{@@emph} surrounds the text with underscores
+(@samp{_}), and @code{@@strong} puts asterisks around the text.
+
+@quotation Caution
+Do not use @code{@@strong} with the word @samp{Note}; Info will
+mistake the combination for a cross reference.  (It's usually
+redundant, anyway.)  Use a phrase such as @strong{Please notice} or
+@strong{Caution} instead, or the optional argument to
+@code{@@quotation}---@samp{Note} is allowable there.
+@end quotation
+
+
+@node Smallcaps
+@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
+@cindex Small caps font
+@findex sc @r{(small caps font)}
+
+Use the @samp{@@sc} command to set text in @sc{a small caps font}
+(where possible).  Write the text you want to be in small caps between
+braces in lower case, like this:
+
+@example
+Richard @@sc@{Stallman@} founded @@acronym@{GNU@}.
+@end example
+
+@noindent
+This produces:
+
+@display
+Richard @sc{Stallman} founded @acronym{GNU}.
+@end display
+
+As shown here, we recommend using @code{@@acronym} for actual
+acronyms (@pxref{acronym}), and reserving @code{@@sc} for special
+cases where you want small caps.  The output is not the same
+(@code{@@acronym} prints in a smaller text font, not the small caps
+font), but more importantly it describes the actual text more
+accurately.
+
+Family names are one case where small capitals are sometimes desirable,
+also as shown here.
+
+@cindex <small> tag
+@TeX{} typesets any uppercase letters between the braces of an
+@code{@@sc} command in full-size capitals; only lowercase letters are
+printed in the small caps font.  In the Info output, the argument to
+@code{@@sc} is printed in all upper case.  In HTML, the argument is
+uppercased and the output marked with the @code{<small>} tag to reduce
+the font size.
+
+Since it's redundant to mark all-uppercase text with @code{@@sc},
+@command{makeinfo} warns about such usage.
+
+We recommend using regular mixed case wherever possible.
+
+
+@node Fonts
+@subsection Fonts for Printing, Not Info
+@cindex Fonts for printing, not Info
+
+@findex fonttextsize
+@cindex Font size, reducing
+@cindex Reducing font size
+@cindex Smaller fonts
+Texinfo provides one command to change the size of the main body font
+in the @TeX{} output for a document: @code{@@fonttextsize}.  It has no
+effect at all in other output.  It takes a single argument on the
+remainder of the line, which must be either @samp{10} or @samp{11}.
+For example:
+
+@example
+@@fonttextsize 10
+@end example
+
+@cindex Printing cost, reducing
+The effect is to reduce the body font to a 10@dmn{pt} size (the
+default is 11@dmn{pt}).  Fonts for other elements, such as sections
+and chapters, are reduced accordingly.  This should only be used in
+conjunction with @code{@@smallbook} (@pxref{smallbook,,Printing
+``Small'' Books}) or similar, since 10@dmn{pt} fonts on standard paper
+(8.5x11 or A4) are too small.  One reason to use this command is to
+save pages, and hence printing cost, for physical books.
+
+Texinfo does not at present have commands to switch the font family
+to use, or more general size-changing commands.
+
+@cindex Styles, font
+Texinfo also provides a number of font commands that specify font changes
+in the printed manual and (where possible) in the HTML output, but
+have no effect in the Info file.  All the commands apply to an
+argument that follows, surrounded by braces.
+
+@table @code
+@item @@b
+@findex b @r{(bold font)}
+@cindex Bold font
+selects @b{bold} face;
+
+@item @@i
+@findex i @r{(italic font)}
+@cindex Italic font
+selects an @i{italic} font;
+
+@item @@r
+@findex r @r{(roman font)}
+@cindex Roman font
+@cindex Default font
+selects a @r{roman} font, which is the usual font in which text is
+printed.  It may or may not be seriffed.
+
+@item @@sansserif
+@findex sansserif @r{(sans serif font)}
+@cindex Sans serif font
+selects a @sansserif{sans serif} font;
+
+@item @@slanted
+@findex slanted @r{(slanted font)}
+@cindex Slanted font
+@cindex Oblique font
+selects a @slanted{slanted} font;
+
+@item @@t
+@findex t @r{(typewriter font)}
+@cindex Monospace font
+@cindex Fixed-width font
+@cindex Typewriter font
+selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
+
+@end table
+
+(The commands with longer names were invented much later than the
+others, at which time it did not seem desirable to use very short
+names for such an infrequently needed feature.)
+
+@cindex <lineannotation> Docbook tag
+Only the @code{@@r} command has much use: in example-like
+environments, you can use the @code{@@r} command to write comments in
+the standard roman font instead of the fixed-width font.  This looks
+better in printed output, and produces a @code{<lineannotation>} tag
+in Docbook output.
+
+For example,
+
+@example
+@group
+@@lisp
+(+ 2 2)    ; @@r@{Add two plus two.@}
+@@end lisp
+@end group
+@end example
+
+@noindent
+produces
+
+@lisp
+(+ 2 2)    ; @r{Add two plus two.}
+@end lisp
+
+In general, you should avoid using the other font commands.  Some of
+them are only useful when documenting functionality of specific font
+effects, such as in @TeX{} and related packages.
+
+
+@node Quotations and Examples
+@chapter 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 the output.
+
+@findex end
+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 @code{@@end} command that is also at the beginning of a line by
+itself.  For instance, you begin an example by writing @code{@@example}
+by itself at the beginning of a line and end the example by writing
+@code{@@end example} on a line by itself, at the beginning of that
+line, and with only one space between the @code{@@end} and the
+@code{example}.
+
+@menu
+* Block Enclosing Commands::    Different constructs for different purposes.
+* quotation::                   Writing a quotation.
+* example::                     Writing an example in a fixed-width font.
+* verbatim::                    Writing a verbatim example.
+* verbatiminclude::             Including a file verbatim.
+* lisp::                        Illustrating Lisp code.
+* small::                       Examples in a smaller font.
+* display::                     Writing an example in the current font.
+* format::                      Writing an example without narrowed margins.
+* exdent::                      Undo indentation on a line.
+* flushleft & flushright::      Pushing text flush left or flush right.
+* noindent::                    Preventing paragraph indentation.
+* indent::                      Forcing paragraph indentation.
+* cartouche::                   Drawing rounded rectangles around examples.
+@end menu
+
+
+@node Block Enclosing Commands
+@section Block Enclosing Commands
+
+Here are commands for quotations and examples, explained further in the
+following sections:
+
+@table @code
+@item @@quotation
+Indicate text that is quoted. The text is filled, indented (from both
+margins), and printed in a roman font by default.
+
+@item @@example
+Illustrate code, commands, and the like. The text is printed
+in a fixed-width font, and indented but not filled.
+
+@item @@verbatim
+Mark a piece of text that is to be printed verbatim; no character
+substitutions are made and all commands are ignored, until the next
+@code{@@end verbatim}.  The text is printed in a fixed-width font,
+and not indented or filled.  Extra spaces and blank lines are
+significant, and tabs are expanded.
+
+@item @@smallexample
+Same as @code{@@example}, except that in @TeX{} this command typesets
+text in a smaller font.
+
+@item @@lisp
+Like @code{@@example}, but specifically for illustrating Lisp code. The
+text is printed in a fixed-width font, and indented but not filled.
+
+@item @@smalllisp
+Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
+
+@item @@display
+Display illustrative text.  The text is indented but not filled, and
+no font is selected (so, by default, the font is roman).@refill
+
+@item @@smalldisplay
+Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
+
+@item @@format
+Like @code{@@display} (the text is not filled and no font is selected),
+but the text is not indented.
+
+@item @@smallformat
+Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
+@end table
+
+The @code{@@exdent} command is used within the above constructs to
+undo the indentation of a line.
+
+The @code{@@flushleft} and @code{@@flushright} commands are used to line
+up the left or right margins of unfilled text.@refill
+
+The @code{@@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 @code{@@cartouche} environment around one of the above
+constructs to highlight the example or quotation by drawing a box with
+rounded corners around it.  @xref{cartouche, , Drawing Cartouches Around
+Examples}.
+
+
+@node quotation
+@section @code{@@quotation}: Block quotations
+@cindex Quotations
+@findex quotation
+
+The text of a quotation is processed normally (regular font, text is
+filled) except that:
+
+@itemize @bullet
+@item
+the margins are closer to the center of the page, so the whole of the
+quotation is indented;
+
+@item
+and the first lines of paragraphs are indented no more than other lines.
+
+@end itemize
+
+@quotation
+This is an example of text written between an @code{@@quotation}
+command and an @code{@@end quotation} command.  An @code{@@quotation}
+command is most often used to indicate text that is excerpted from
+another (real or hypothetical) printed work.
+@end quotation
+
+Write an @code{@@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 @code{@@end quotation}.
+The @code{@@end quotation} line will likewise disappear from the
+output.
+
+@code{@@quotation} takes one optional argument, given on the remainder
+of the line.  This text, if present, is included at the beginning of
+the quotation in bold or otherwise emphasized, and followed with a
+@samp{:}.  For example:
+
+@example
+@@quotation Note
+This is
+a foo.
+@@end quotation
+@end example
+
+@noindent
+produces
+
+@quotation Note
+This is
+a foo.
+@end quotation
+
+If the @code{@@quotation} argument is exactly one of these words:
+
+@example
+Caution  Important  Note  Tip  Warning
+@end example
+
+@cindex <note> Docbook tag
+@cindex <blockquote> HTML tag
+@noindent then the Docbook output uses corresponding special tags
+(@code{<note>}, etc.) instead of the default @code{<blockquote>}.
+HTML output always uses @code{<blockquote>}.
+
+
+@node example
+@section @code{@@example}: Example Text
+@cindex Examples, formatting them
+@cindex Formatting examples
+@findex example
+
+The @code{@@example} environment is used to indicate an example that
+is not part of the running text, such as computer input or output.
+Write an @code{@@example} command at the beginning of a line by
+itself.  Mark the end of the example with an @code{@@end example}
+command, also written at the beginning of a line by itself.
+
+An @code{@@example} environment has the following characteristics:
+
+@itemize
+@item Each line in the input file is a line in the output; that is,
+the source text is not filled as it normally is.
+@item Extra spaces and blank lines are significant.
+@item The output is indented.
+@item The output uses a fixed-width font.
+@item Texinfo commands @emph{are} expanded; if you want the output to
+be the input verbatim, use the @code{@@verbatim} environment instead
+(@pxref{verbatim,,@code{@@verbatim}}).
+@end itemize
+
+For example,
+
+@example
+@@example
+cp foo @@var@{dest1@}; \
+ cp foo @@var@{dest2@}
+@@end example
+@end example
+
+@noindent
+produces
+
+@example
+cp foo @var{dest1}; \
+ cp foo @var{dest2}
+@end example
+
+The lines containing @code{@@example} and @code{@@end example} will
+disappear from the output.  To make the output look good, you should
+put a blank line before the @code{@@example} and another blank line
+after the @code{@@end example}.  Blank lines inside the beginning
+@code{@@example} and the ending @code{@@end example}, on the other
+hand, do appear in the output.
+
+@quotation Caution
+Do not use tabs in the lines of an example!  (Or anywhere else in
+Texinfo, except in verbatim environments.)  @TeX{} treats tabs as
+single spaces, and that is not what they look like.  In XEmacs, you can
+use @kbd{M-x untabify} to convert tabs in a region to multiple spaces.
+@end quotation
+
+Examples are often, logically speaking, ``in the middle'' of a
+paragraph, and the text that continues afterwards should not be
+indented, as in the example above.  The @code{@@noindent} command
+prevents a piece of text from being indented as if it were a new
+paragraph (@pxref{noindent,,@code{@@noindent}}.
+
+If you want to embed code fragments within sentences, instead of
+displaying them, use the @code{@@code} command or its relatives
+(@pxref{code,,@code{@@code}}).
+
+If you wish to write a ``comment'' on a line of an example in the
+normal roman font, you can use the @code{@@r} command (@pxref{Fonts}).
+
+
+@node verbatim
+@section @code{@@verbatim}: Literal Text
+@findex verbatim
+@cindex Verbatim environment
+
+Use the @code{@@verbatim} environment for printing of text that may
+contain special characters or commands that should not be interpreted,
+such as computer input or output (@code{@@example} interprets its text
+as regular Texinfo commands).  This is especially useful for including automatically
+generated files in a Texinfo manual.
+
+In general, the output will be just the same as the input.  No
+character substitutions are made, e.g., all spaces and blank lines are
+significant, including tabs.  In the printed manual, the text is
+typeset in a fixed-width font, and not indented or filled.
+
+Write a @code{@@verbatim} command at the beginning of a line by itself.
+This line will disappear from the output.  Mark the end of the verbatim
+block with a @code{@@end verbatim} command, also written at the
+beginning of a line by itself.  The @code{@@end verbatim} will also
+disappear from the output.
+
+For example:
+@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
+
+@example
+@exdent @t{@@verbatim}
+@exdent @t{@{}
+@exdent @key{TAB}@t{@@command with strange characters: @@'e}
+@exdent @t{expand@key{TAB}me}
+@exdent @t{@}}
+@exdent @t{@@end verbatim}
+@end example
+
+@noindent
+This produces:
+
+@verbatim
+{
+        @command with strange characters: @'e
+expand	me
+}
+@end verbatim
+
+Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
+produce no output, typically you should put a blank line before the
+@code{@@verbatim} and another blank line after the @code{@@end
+verbatim}.  Blank lines between the beginning @code{@@verbatim} and
+the ending @code{@@end verbatim} will appear in the output.
+
+@cindex Verbatim, small
+@cindex Small verbatim
+You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in
+an @code{@@smallformat} environment, as shown here:
+
+@c more cheating ...
+@smallexample
+@exdent @t{@@smallformat}
+@exdent @t{@@verbatim}
+@exdent @t{... still verbatim, but in a smaller font ...}
+@exdent @t{@@end verbatim}
+@exdent @t{@@end smallformat}
+@end smallexample
+
+Finally, a word of warning: it is not reliable to use
+@code{@@verbatim} inside other Texinfo constructs.
+
+
+@node verbatiminclude
+@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
+@cindex Verbatim, include file
+@cindex Including a file verbatim
+@findex verbatiminclude
+
+You can include the exact contents of a file in the document with the
+@code{@@verbatiminclude} command:
+
+@example
+@@verbatiminclude @var{filename}
+@end example
+
+The contents of @var{filename} is printed in a verbatim environment
+(@pxref{verbatim,,@code{@@verbatim}}).  Generally, the file is printed
+exactly as it is, with all special characters and white space
+retained.  No indentation is added; if you want indentation, enclose
+the @code{@@verbatiminclude} within @code{@@example}
+(@pxref{example,,@code{@@example}}).
+
+The name of the file is taken literally, with a single exception:
+@code{@@value@{@var{var}@}} references are expanded.  This makes it
+possible to include files in other directories within a distribution,
+for instance:
+
+@example
+@@verbatiminclude @@value@{top_srcdir@}/NEWS
+@end example
+
+@noindent (You still have to get @code{top_srcdir} defined in the
+first place.)
+
+For a method on printing the file contents in a smaller font size, see
+the end of the previous section on @code{@@verbatim}.
+
+
+@node lisp
+@section @code{@@lisp}: Marking a Lisp Example
+@findex lisp
+@cindex Lisp example
+
+The @code{@@lisp} command is used for Lisp code.  It is synonymous
+with the @code{@@example} command.
+
+@lisp
+This is an example of text written between an
+@code{@@lisp} command and an @code{@@end lisp} command.
+@end lisp
+
+Use @code{@@lisp} instead of @code{@@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.@footnote{It would be straightforward to extend Texinfo to work
+in a similar fashion for C, Fortran, or other languages.}
+
+Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
+itself.
+
+
+@node small
+@section @code{@@small@dots{}} Block Commands
+@cindex Small examples
+@cindex Examples in smaller fonts
+@cindex Lisp examples in smaller fonts
+@findex smalldisplay
+@findex smallexample
+@findex smallformat
+@findex smalllisp
+
+In addition to the regular @code{@@example} and @code{@@lisp} commands,
+Texinfo has ``small'' example-style commands.  These are
+@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
+@code{@@smalllisp}.
+
+In Info, the @code{@@small@dots{}} commands are equivalent to their
+non-small companion commands.
+
+In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in
+a smaller font than the non-small example commands.  Consequently,
+many examples containing long lines fit on a page without needing to
+be shortened.
+
+Mark the end of an @code{@@small@dots{}} block with a corresponding
+@code{@@end small@dots{}}.  For example, pair @code{@@smallexample} with
+@code{@@end smallexample}.
+
+Here is an example of the font used by the @code{@@small@dots{}}
+commands (in Info, the output will be the same as usual):
+
+@smallexample
+@dots{} to make sure that you have the freedom to
+distribute copies of free software (and charge for
+this service if you wish), that you receive source
+code or can get it if you want it, that you can
+change the software or use pieces of it in new free
+programs; and that you know you can do these things.
+@end smallexample
+
+The @code{@@small@dots{}} commands make it easier to prepare manuals
+without forcing you to edit examples by hand to fit them onto narrower
+pages.
+
+As a general rule, a printed document looks much better if you use
+only one of (for instance) @code{@@example} or @code{@@smallexample}
+consistently within a chapter.
+
+
+@node display
+@section @code{@@display} and @code{@@smalldisplay}
+@cindex Display formatting
+@findex display
+
+The @code{@@display} command begins a kind of example, where each line
+of input produces a line of output, and the output is indented.  It is
+thus like the @code{@@example} command except that, in a printed
+manual, @code{@@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 @code{@@display}
+command.
+
+@display
+This is an example of text written between an @code{@@display} command
+and an @code{@@end display} command.  The @code{@@display} command
+indents the text, but does not fill it.
+@end display
+
+@findex smalldisplay
+Texinfo also provides a command @code{@@smalldisplay}, which is like
+@code{@@display} but uses a smaller font in @code{@@smallbook} format.
+@xref{small}.
+
+The @code{@@table} command (@pxref{table}) does not work inside
+@code{@@display}.  Since @code{@@display} is line-oriented, it doesn't
+make sense to use them together.  If you want to indent a table, try
+@code{@@quotation} (@pxref{quotation}).
+
+
+@node format
+@section @code{@@format} and @code{@@smallformat}
+@findex format
+
+The @code{@@format} command is similar to @code{@@example} except
+that, in the printed manual, @code{@@format} does not select the
+fixed-width font and does not narrow the margins.
+
+@format
+This is an example of text written between an @code{@@format} command
+and an @code{@@end format} command.  As you can see
+from this example,
+the @code{@@format} command does not fill the text.
+@end format
+
+@findex smallformat
+Texinfo also provides a command @code{@@smallformat}, which is like
+@code{@@format} but uses a smaller font in @code{@@smallbook} format.
+@xref{small}.
+
+
+
+@node exdent
+@section @code{@@exdent}: Undoing a Line's Indentation
+@cindex Indentation undoing
+@findex exdent
+
+The @code{@@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
+@code{@@exdent} line is printed in the roman font.@refill
+
+@code{@@exdent} is usually used within examples.  Thus,@refill
+
+@example
+@group
+@@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 example
+@end group
+@end example
+
+@noindent
+produces
+
+@example
+@group
+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
+@end example
+
+In practice, the @code{@@exdent} command is rarely used.
+Usually, you un-indent text by ending the example and
+returning the page to its normal width.@refill
+
+
+@node flushleft & flushright
+@section @code{@@flushleft} and @code{@@flushright}
+@findex flushleft
+@findex flushright
+@cindex Ragged right
+@cindex Ragged left
+
+The @code{@@flushleft} and @code{@@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 @code{@@flushleft} and @code{@@flushright}
+commands are ended by @code{@@end flushleft} and @code{@@end
+flushright} commands on lines of their own.@refill
+
+@need 1500
+For example,
+
+@example
+@group
+@@flushleft
+This text is
+written flushleft.
+@@end flushleft
+@end group
+@end example
+
+@noindent
+produces
+
+@quotation
+@flushleft
+This text is
+written flushleft.
+@end flushleft
+@end quotation
+
+
+@code{@@flushright} produces the type of indentation often used in the
+return address of letters.  For example,
+
+@example
+@group
+@@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
+@end group
+@end example
+
+@noindent
+produces
+
+@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
+
+
+@node noindent
+@section @code{@@noindent}: Omitting Indentation
+@cindex Omitting indentation
+@cindex Suppressing indentation
+@cindex Indentation, omitting
+@findex 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.  You can prevent this on a case-by-case basis by writing
+@code{@@noindent} at the beginning of a line, preceding the continuation
+text.  You can also disable indentation for all paragraphs globally with
+@code{@@paragraphindent} (@pxref{paragraphindent, Paragraph Indenting}).
+
+It is best to write @code{@@noindent} on a line by itself, since in most
+environments, spaces following the command will not be ignored.  It's ok
+to use it at the beginning of a line, with text following, outside of
+any environment.
+
+@need 1500
+For example:
+
+@example
+@group
+@@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@}.)
+@end group
+@end example
+
+@noindent produces:
+
+@display
+
+@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}.)
+
+@end display
+
+To adjust the number of blank lines properly in the Info file output,
+remember that the line containing @code{@@noindent} does not generate a
+blank line, and neither does the @code{@@end example} line.
+
+In the Texinfo source file for this manual, each line that says
+`produces' is preceded by @code{@@noindent}.
+
+Do not put braces after an @code{@@noindent} command; they are not
+necessary, since @code{@@noindent} is a command used outside of
+paragraphs (@pxref{Command Syntax}).
+
+
+@node indent
+@section @code{@@indent}: Forcing Indentation
+@cindex Forcing indentation
+@cindex Inserting indentation
+@cindex Indentation, forcing
+@findex indent
+
+@indent
+To complement the @code{@@noindent} command (see the previous
+section), Texinfo provides the @code{@@indent} command that forces a
+paragraph to be indented.  This paragraph, for instance, is indented
+using an @code{@@indent} command.  The first paragraph of a section is
+the most likely place to use @code{@@indent}, to override the normal
+behavior of no indentation there (@pxref{paragraphindent}).
+
+It is best to write @code{@@indent} on a line by itself, since in most
+environments, spaces following the command will not be ignored.  The
+@code{@@indent} line will not generate a blank line in the Info output
+within an environment.
+
+However, it is ok to use it at the beginning of a line, with text
+following, outside of any environment.
+
+Do not put braces after an @code{@@indent} command; they are not
+necessary, since @code{@@indent} is a command used outside of
+paragraphs (@pxref{Command Syntax}).
+
+
+@node cartouche
+@section @code{@@cartouche}: Rounded Rectangles Around Examples
+@findex cartouche
+@cindex Box with rounded corners
+@cindex Rounded rectangles, around examples
+
+In a printed manual, the @code{@@cartouche} command draws a box with
+rounded corners around its contents.  In HTML, a normal rectangle is
+drawn (that's the best HTML can do).  @code{@@cartouche} has no effect
+in Info output.
+
+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.
+
+For example,
+
+@example
+@@cartouche
+@@example
+% pwd
+/usr/local/share/xemacs
+@@end example
+@@end cartouche
+@end example
+
+@noindent
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+The output from the example looks like this (if you're reading this in
+Info, you'll see the @code{@@cartouche} had no effect):
+
+@cartouche
+@example
+% pwd
+/usr/local/info
+@end example
+@end cartouche
+
+For proper output in HTML, it's necessary to put the
+@code{@@cartouche} around the @code{@@example}, and not the other way
+around.  This limitation of @command{makeinfo} may be removed one day.
+
+@code{@@cartouche} also implies @code{@@group} (@pxref{group}).
+
+@node Lists and Tables
+@chapter Lists and Tables
+@cindex Making lists and tables
+@cindex Lists and tables, making
+@cindex Tables and lists, making
+
+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.
+@end menu
+
+@node Introducing Lists
+@section 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.@refill
+
+Numbered lists and tables begin with the appropriate @@-command at the
+beginning of a line, and end with the corresponding @code{@@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.@refill
+
+Begin an enumerated list, for example, with an @code{@@enumerate}
+command and end the list with an @code{@@end enumerate} command.
+Begin an itemized list with an @code{@@itemize} command, followed on
+the same line by a formatting command such as @code{@@bullet}, and end
+the list with an @code{@@end itemize} command.@refill
+@findex end
+
+Precede each element of a list with an @code{@@item} or @code{@@itemx}
+command.@refill
+
+@sp 1
+@noindent
+Here is an itemized list of the different kinds of table and lists:@refill
+
+@itemize @bullet
+@item
+Itemized lists with and without bullets.
+
+@item
+Enumerated lists, using numbers or letters.
+
+@item
+Two-column tables with highlighting.
+@end itemize
+
+@sp 1
+@noindent
+Here is an enumerated list with the same items:@refill
+
+@enumerate
+@item
+Itemized lists with and without bullets.
+
+@item
+Enumerated lists, using numbers or letters.
+
+@item
+Two-column tables with highlighting.
+@end enumerate
+
+@sp 1
+@noindent
+And here is a two-column table with the same items and their
+@w{@@-commands}:@refill
+
+@table @code
+@item @@itemize
+Itemized lists with and without bullets.
+
+@item @@enumerate
+Enumerated lists, using numbers or letters.
+
+@item @@table
+@itemx @@ftable
+@itemx @@vtable
+Two-column tables, optionally with indexing.
+@end table
+
+
+@node itemize
+@section @code{@@itemize}: Making an Itemized List
+@cindex Itemization
+@findex itemize
+
+The @code{@@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.@refill
+
+@cindex @code{@@w}, for blank items
+Begin an itemized list by writing @code{@@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
+@code{@@bullet} after @code{@@itemize}, but you can use
+@code{@@minus}, or any command or character that results in a single
+character in the Info file.  If you don't want any mark at all, use
+@code{@@w}.  (When you write the mark command such as
+@code{@@bullet} after an @code{@@itemize} command, you may omit the
+@samp{@{@}}.)  If you don't specify a mark command, the default is
+@code{@@bullet}.
+
+Write the text of the indented paragraphs themselves after the
+@code{@@itemize}, up to another line that says @code{@@end
+itemize}.@refill
+
+@findex item
+At the beginning of each paragraph for which a mark in the margin is
+desired, write a line that starts with @code{@@item}.  It is ok to
+have text following the @code{@@item}.
+
+Usually, you should put a blank line before an @code{@@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.@refill
+
+Here is an example of the use of @code{@@itemize}, followed by the
+output it produces.  @code{@@bullet} produces an @samp{*} in Info and a
+round dot in @TeX{}.
+
+@example
+@group
+@@itemize @@bullet
+@@item
+Some text for foo.
+
+@@item
+Some text
+for bar.
+@@end itemize
+@end group
+@end example
+
+@noindent
+This produces:
+
+@quotation
+@itemize @bullet
+@item
+Some text for foo.
+
+@item
+Some text
+for bar.
+@end itemize
+@end quotation
+
+Itemized lists may be embedded within other itemized lists.  Here is a
+list marked with dashes embedded in a list marked with bullets:@refill
+
+@example
+@group
+@@itemize @@bullet
+@@item
+First item.
+
+@@itemize @@minus
+@@item
+Inner item.
+
+@@item
+Second inner item.
+@@end itemize
+
+@@item
+Second outer item.
+@@end itemize
+@end group
+@end example
+
+@noindent
+This produces:
+
+@quotation
+@itemize @bullet
+@item
+First item.
+
+@itemize @minus
+@item
+Inner item.
+
+@item
+Second inner item.
+@end itemize
+
+@item
+Second outer item.
+@end itemize
+@end quotation
+
+
+@node enumerate
+@section @code{@@enumerate}: Making a Numbered or Lettered List
+@cindex Enumeration
+@findex enumerate
+
+@code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
+@code{@@itemize}}), except that the labels on the items are
+successive integers or letters instead of bullets.
+
+Write the @code{@@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, @code{@@enumerate} starts the
+list with the number @samp{1}.  With a numeric argument, such as
+@samp{3}, the command starts the list with that number.  With an upper
+or lower case letter, such as @samp{a} or @samp{A}, the command starts
+the list with that letter.
+
+Write the text of the enumerated list in the same way as an itemized
+list: write a line starting with @code{@@item} at the beginning of
+each paragraph that you want enumerated.  It is ok to have text
+following the @code{@@item}.
+
+You should put a blank line between entries in the list.
+This generally makes it easier to read the Info file.
+
+@need 1500
+Here is an example of @code{@@enumerate} without an argument:
+
+@example
+@group
+@@enumerate
+@@item
+Underlying causes.
+
+@@item
+Proximate causes.
+@@end enumerate
+@end group
+@end example
+
+@noindent
+This produces:
+
+@enumerate
+@item
+Underlying causes.
+
+@item
+Proximate causes.
+@end enumerate
+@sp 1
+Here is an example with an argument of @kbd{3}:@refill
+@sp 1
+@example
+@group
+@@enumerate 3
+@@item
+Predisposing causes.
+
+@@item
+Precipitating causes.
+
+@@item
+Perpetuating causes.
+@@end enumerate
+@end group
+@end example
+
+@noindent
+This produces:
+
+@enumerate 3
+@item
+Predisposing causes.
+
+@item
+Precipitating causes.
+
+@item
+Perpetuating causes.
+@end enumerate
+@sp 1
+Here is a brief summary of the alternatives.  The summary is constructed
+using @code{@@enumerate} with an argument of @kbd{a}.@refill
+@sp 1
+@enumerate a
+@item
+@code{@@enumerate}
+
+Without an argument, produce a numbered list, starting with the number
+1.@refill
+
+@item
+@code{@@enumerate @var{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.@refill
+
+@item
+@code{@@enumerate @var{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.@refill
+
+@item
+@code{@@enumerate @var{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.@refill
+@end enumerate
+
+You can also nest enumerated lists, as in an outline.@refill
+
+@node Two-column Tables
+@section Making a Two-column Table
+@cindex Tables, making two-column
+@findex table
+
+@code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
+@code{@@itemize}}), but allows you to specify a name or heading line for
+each item.  The @code{@@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.
+@end menu
+
+@node table
+@subsection Using the @code{@@table} Command
+
+@cindex Definition lists, typesetting
+Use the @code{@@table} command to produce two-column tables.  It is
+usually listed for ``definition lists'' of various sorts, where you
+have a list of terms and a brief text with each one.
+
+Write the @code{@@table} command at the beginning of a line, after a
+blank line, and follow it on the same line with an argument that is a
+Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp},
+@code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}).
+
+This command will be applied to the text that goes into the first
+column of each item and thus determines how it will be highlighted.
+For example, @code{@@table @@code} will cause the text in the first
+column to be output as if it @code{@@code} command.
+
+@findex asis
+You may also use the @code{@@asis} command as an argument to
+@code{@@table}.  @code{@@asis} is a command that does nothing; if you
+use this command after @code{@@table}, the first column entries are
+output without added highlighting (``as is'').
+
+The @code{@@table} command works with other commands besides those
+explicitly mentioned here.  However, you can only use commands that
+normally take arguments in braces.  (In this case, however, you use
+the command name without an argument, because the subsequent
+@code{@@item}'s will supply the argument.)
+
+@findex item
+Begin each table entry with an @code{@@item} command at the beginning
+of a line.  Write the first column text on the same line as the
+@code{@@item} command.  Write the second column text on the line
+following the @code{@@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 the text on the same line as the @code{@@item}
+will be placed in the first column (including any footnotes).
+
+Normally, you should put a blank line before an @code{@@item} line.
+This puts a blank line in the Info file.  Except when the entries are
+very brief, a blank line looks better.
+
+End the table with a line consisting of @code{@@end table}, followed
+by a blank line.  @TeX{} will always start a new paragraph after the
+table, so the blank line is needed for the Info output to be analogous.
+
+@need 1500
+The following table, for example, highlights the text in the first
+column with an @code{@@samp} command:
+
+@example
+@group
+@@table @@samp
+@@item foo
+This is the text for
+@@samp@{foo@}.
+
+@@item bar
+Text for @@samp@{bar@}.
+@@end table
+@end group
+@end example
+
+@noindent
+This produces:
+
+@table @samp
+@item foo
+This is the text for
+@samp{foo}.
+@item bar
+Text for @samp{bar}.
+@end table
+
+If you want to list two or more named items with a single block of
+text, use the @code{@@itemx} command.  (@xref{itemx,,@code{@@itemx}}.)
+
+
+@node ftable vtable
+@subsection @code{@@ftable} and @code{@@vtable}
+@cindex Tables with indexes
+@cindex Indexing table entries automatically
+@findex ftable
+@findex vtable
+
+The @code{@@ftable} and @code{@@vtable} commands are the same as the
+@code{@@table} command except that @code{@@ftable} automatically enters
+each of the items in the first column of the table into the index of
+functions and @code{@@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 @code{@@item} commands are indexed, and they are indexed in
+exactly the form that they appear on that line.  @xref{Indices},
+for more information about indices.@refill
+
+Begin a two-column table using @code{@@ftable} or @code{@@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{@@code},
+exactly as you would for an @code{@@table} command; and end the table
+with an @code{@@end ftable} or @code{@@end vtable} command on a line by
+itself.
+
+See the example for @code{@@table} in the previous section.
+
+@node itemx
+@subsection @code{@@itemx}
+@cindex Two named items for @code{@@table}
+@findex itemx
+
+Use the @code{@@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 @code{@@item} for the first entry, and @code{@@itemx} for all
+subsequent entries; @code{@@itemx} must always follow an @code{@@item}
+command, with no blank line intervening.
+
+The @code{@@itemx} command works exactly like @code{@@item} except
+that it does not generate extra vertical space above the first column
+text.  If you have multiple consecutive @code{@@itemx} commands, do
+not insert any blank lines between them.
+
+For example,
+
+@example
+@group
+@@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
+@end group
+@end example
+
+@noindent
+This produces:
+
+@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.@refill
+@end table
+
+@noindent
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)@refill
+
+
+@node Multi-column Tables
+@section @code{@@multitable}: Multi-column Tables
+@cindex Tables, making multi-column
+@findex multitable
+
+@code{@@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 @code{@@multitable} line itself, and
+write each row of the actual table following an @code{@@item} command,
+with columns separated by an @code{@@tab} command.  Finally, @code{@@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.
+@end menu
+
+@node Multitable Column Widths
+@subsection Multitable Column Widths
+@cindex Multitable column widths
+@cindex Column widths, defining for multitables
+@cindex Widths, defining multitable column
+
+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 @code{@@multitable} command.
+
+@enumerate
+@item
+@findex columnfractions
+@cindex Line length, column widths as fraction of
+To specify column widths as fractions of the line length, write
+@code{@@columnfractions} and the decimal numbers (presumably less than
+1; a leading zero is allowed and ignored) after the
+@code{@@multitable} command, as in:
+
+@example
+@@multitable @@columnfractions .33 .33 .33
+@end example
+
+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.
+
+@item
+@cindex Prototype row, column widths defined by
+To specify a prototype row, write the longest entry for each column
+enclosed in braces after the @code{@@multitable} command.  For example:
+
+@example
+@@multitable @{some text for column one@} @{for column two@}
+@end example
+
+@noindent
+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{@@code} are
+particularly likely to be useful.
+
+@end enumerate
+
+
+@node Multitable Rows
+@subsection Multitable Rows
+@cindex Multitable rows
+@cindex Rows, of a multitable
+
+@findex item
+@findex tab
+After the @code{@@multitable} command defining the column widths (see
+the previous section), you begin each row in the body of a multitable
+with @code{@@item}, and separate the column entries with @code{@@tab}.
+Line breaks are not special within the table body, and you may break
+input lines in your source file as necessary.
+
+@findex headitem
+@cindex Heading row, in table
+@cindex <thead> HTML tag
+You can also use @code{@@headitem} instead of @code{@@item} to produce
+a @dfn{heading row}.  The @TeX{} output for such a row is in bold, and
+the HTML, XML, and Docbook output uses the @code{<thead>} tag.  In
+Info, the heading row is followed by a separator line made of dashes
+(@samp{-} characters).
+
+Here is a complete example of a multi-column table (the text is from
+@cite{The XEmacs Users' Manual}, @pxref{Split Window,, Splitting Windows,
+xemacs, XEmacs User's Manual}):
+
+@example
+@@multitable @@columnfractions .15 .45 .4
+@@headitem 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
+@end example
+
+@noindent
+produces:
+
+@multitable @columnfractions .15 .45 .4
+@headitem 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
+
+
+@node Special Displays
+@chapter Special Displays
+@cindex Special displays
+
+The commands in this chapter allow you to write text that is specially
+displayed (output format permitting), outside of the normal document
+flow.
+
+One set of such commands is for creating ``floats'', that is, figures,
+tables, and the like, set off from the main text, possibly numbered,
+captioned, and/or referred to from elsewhere in the document.  Images
+are often included in these displays.
+
+Another group of commands is for creating footnotes in Texinfo.
+
+@menu
+* Floats::                      Figures, tables, and the like.
+* Images::                      Including graphics and images.
+* Footnotes::                   Writing footnotes.
+@end menu
+
+
+@node Floats
+@section Floats
+@cindex Floats, in general
+
+A @dfn{float} is a display which is set off from the main text.  It is
+typically labelled as being a ``Figure'', ``Table'', ``Example'', or
+some similar type.
+
+@cindex Floating, not yet implemented
+A float is so-named because, in principle, it can be moved to the
+bottom or top of the current page, or to a following page, in the
+printed output.  (Floating does not make sense in other output
+formats.)  In the present version of Texinfo, however, this floating
+is unfortunately not yet implemented.  Instead, the floating material
+is simply output at the current location, more or less as if it were
+an @code{@@group} (@pxref{group,,@code{@@group}}).
+
+@menu
+* float::                       Producing floating material.
+* caption shortcaption::        Specifying descriptions for floats.
+* listoffloats::                A table of contents for floats.
+@end menu
+
+
+@node float
+@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material
+@findex float
+@cindex Float environment
+
+To produce floating material, enclose the material you want to be
+displayed separate between @code{@@float} and @code{@@end float}
+commands, on lines by themselves.
+
+Floating material uses @code{@@image} to display an already-existing
+graphic (@pxref{Images}), or @code{@@multitable} to display a table
+(@pxref{Multi-column Tables}).  However, the contents of the float can
+be anything.  Here's an example with simple text:
+
+@example
+@@float Figure,fig:ex1
+This is an example float.
+@@end float
+@end example
+
+@noindent And the output:
+
+@float Figure,fig:ex1
+This is an example float.
+@end float
+
+As shown in the example, @code{@@float} takes two arguments (separated
+by a comma), @var{type} and @var{label}.  Both are optional.
+
+@table @var
+@item type
+Specifies the sort of float this is; typically a word such as
+``Figure'', ``Table'', etc.  If not given, and @var{label} is, any
+cross-referencing will simply use a bare number.
+
+@item label
+Specifies a cross-reference label for this float.  If given, this
+float is automatically given a number, and will appear in any
+@code{@@listoffloats} output (@pxref{listoffloats}).  Cross-references
+to @var{label} are allowed.
+
+@cindex Floats, making unnumbered
+@cindex Unnumbered float, creating
+On the other hand, if @var{label} is not given, then the float will
+not be numbered and consequently will not appear in the
+@code{@@listoffloats} output or be cross-referenceable.
+@end table
+
+@noindent Normally, you specify both @var{type} and @var{label}, to get a
+labeled and numbered float.
+
+@cindex Floats, numbering of
+@cindex Numbering of floats
+In Texinfo, all floats are numbered the same way: with the chapter
+number (or appendix letter), a period, and the float number, which
+simply counts 1, 2, 3, @dots{}, and is reset at each chapter.  Each
+float type is counted independently.  
+
+Floats within an @code{@@unnumbered} are numbered, or outside of any
+chapter, are simply numbered consecutively from 1.
+
+These numbering conventions are not, at present, changeable.
+
+
+@node caption shortcaption
+@subsection @code{@@caption} & @code{@@shortcaption}
+@findex caption
+@findex shortcaption
+@cindex Captions, for floats
+@cindex Short captions, for lists of floats
+
+You may write an @code{@@caption} anywhere within a @code{@@float}
+environment, to define a caption for the float.  It is not allowed in
+any other context.  @code{@@caption} takes a single argument, enclosed
+in braces.  Here's an example:
+
+@example
+@@float
+An example float, with caption.
+@@caption@{Caption for example float.@}
+@@end float
+@end example
+
+@noindent The output is:
+
+@float
+An example float, with caption.
+@caption{Caption for example float.}
+@end float
+
+@code{@@caption} can appear anywhere within the float; it is not
+processed until the @code{@@end float}.  The caption text is usually a
+sentence or two, but may consist of several paragraphs if necessary.
+
+In the output, the caption always appears below the float; this is not
+currently changeable.  It is preceded by the float type and/or number,
+as specified to the @code{@@float} command (see the previous section).
+
+The @code{@@shortcaption} command likewise may be used only within
+@code{@@float}, and takes a single argument in braces.  The short
+caption text is used instead of the caption text in a list of floats
+(see the next section).  Thus, you can write a long caption for the
+main document, and a short title to appear in the list of floats.  For
+example:
+
+@example
+@@float
+... as above ...
+@@shortcaption@{Text for list of floats.@}
+@@end float
+@end example
+
+The text for @code{@@caption} and @code{@@shortcaption} may not
+contain comments (@code{@@c}), verbatim text (@code{@@verb}),
+environments such as @code{@@example}, or other complex constructs.
+
+
+@node listoffloats
+@subsection @code{@@listoffloats}: Tables of Contents for Floats
+@findex listoffloats
+@cindex List of floats
+@cindex Floats, list of
+@cindex Table of contents, for floats
+
+You can write a @code{@@listoffloats} command to generate a list of
+floats for a given float type (@pxref{float}), analogous to the
+document's overall table of contents.  Typically, it is written in its
+own @code{@@unnumbered} node to provide a heading and structure,
+rather like @code{@@printindex} (@pxref{Printing Indices & Menus}).
+
+@code{@@listoffloats} takes one optional argument, the float type.
+Here's an example:
+
+@example
+@@node List of Figures
+@@unnumbered List of Figures
+@@listoffloats Figure
+@end example
+
+@noindent And the output from @code{@@listoffloats}:
+
+@display
+@listoffloats Figure
+@end display
+
+Without any argument, @code{@@listoffloats} generates a list of
+floats for which no float type was specified, i.e., no first argument
+to the @code{@@float} command (@pxref{float}).
+
+Each line in the list of floats contains the float type (if any),
+the float number, and the caption, if any---the @code{@@shortcaption}
+argument, if it was specified, else the @code{@@caption} argument.
+In Info, the result is a menu where each float can be selected.  In
+HTML, each line is a link to the float.  In printed output, the page
+number is included.
+
+Unnumbered floats (those without cross-reference labels) are omitted
+from the list of floats.
+
+
+@node Images
+@section Inserting Images
+
+@cindex Images, inserting
+@cindex Pictures, inserting
+@findex image
+
+You can insert an image given in an external file with the
+@code{@@image} command.  Although images can be used anywhere,
+including the middle of a paragraph, we describe them in this chapter
+since they are most often part of a displayed figure or example.
+
+@menu
+* Image Syntax::
+* Image Scaling::
+@end menu
+
+
+@node Image Syntax
+@subsection Image Syntax
+
+Here is the synopsis of the @code{@@image} command:
+
+@example
+@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@}
+@end example
+
+@cindex Formats for images
+@cindex Image formats
+The @var{filename} argument is mandatory, and must not have an
+extension, because the different processors support different formats:
+
+@itemize @bullet
+@item
+@pindex eps image format
+@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
+format).
+@item
+@pindex pdftex@r{, and images}
+@pindex png image format
+@pindex jpeg image format
+@pindex pdf image inclusions
+pdf@TeX{} reads @file{@var{filename}.png}, @file{@var{filename}.jpg},
+@file{@var{filename}.jpeg}, or @file{@var{filename}.pdf} (in that
+order).  It also tries uppercase versions of the extensions.  The PDF
+format cannot support EPS images, so they must be converted first.
+@item
+@code{makeinfo} includes @file{@var{filename}.txt} verbatim for
+Info output (more or less as if it was an @code{@@example}).
+@item
+@code{makeinfo} uses the optional fifth argument @var{extension} to
+@code{@@image} for the filename extension, if it is specified.  For example:
+
+@pindex XPM image format
+@example
+@@image@{foo,,,,.xpm@}
+@end example
+
+@noindent
+will cause @code{makeinfo} to look for @file{foo.xpm} before any others.
+
+@end itemize
+
+The @var{width} and @var{height} arguments are described in the next
+section.
+
+For @TeX{} output, if an image is the only thing in a paragraph it
+will ordinarily be displayed on a line by itself, respecting the
+current environment indentation, but without the normal paragraph
+indentation.  If you want it centered, use @code{@@center}
+(@pxref{titlefont center sp,,@code{@@titlefont @@center @@sp}}).
+
+@cindex Alt attribute for images
+@cindex Images, alternate text for
+@findex - (in image alt string)
+For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for
+inline images to the optional @var{alttext} (fourth) argument to
+@code{@@image}, if supplied.  If not supplied, @code{makeinfo} uses
+the full file name of the image being displayed.  The @var{alttext} is
+taken as Texinfo text, so special characters such as @samp{"} and
+@samp{<} and @samp{&} are escaped in the HTML and XML output; also,
+you can get an empty @code{alt} string with @code{@@-} (a command
+that produces no output; @pxref{- and hyphenation}).
+
+For Info output, the @code{alt} string is also processed as Texinfo
+text and output.  In this case, @samp{\} is escaped as @samp{\\} and
+@samp{"} as @samp{\"}; no other escapes are done.
+
+@cindex PNG image format
+@cindex JPEG image format
+If you do not supply the optional @var{extension} (fifth) argument,
+@code{makeinfo} first tries @file{@var{filename}.png}; if that does
+not exist, it tries @file{@var{filename}.jpg}.  If that does not exist
+either, it complains.
+
+In Info output, @code{makeinfo} writes a reference to the binary image
+file (trying @var{filename} suffixed with @file{@var{extension}},
+@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order)
+if one exists.  It also literally includes the @file{.txt} file if one
+exists.  This way, Info readers which can display images (such as the
+XEmacs Info browser, running under X) can do so, whereas Info readers
+which can only use text (such as the standalone Info reader) can
+display the textual version.
+
+@cindex @samp{^@@^H} for images in Info
+The implementation of this is to put the following construct into the
+Info output:
+
+@example
+^@@^H[image src="@var{binaryfile}" text="@var{txtfile}"
+           alt="@var{alttext} ... ^@@^H]
+@end example
+
+@noindent where @samp{^@@} and @samp{^H} stand for the actual null and
+backspace control characters.  If one of the files is not present, the
+corresponding argument is omitted.
+
+The reason for mentioning this here is that older Info browsers (this
+feature was introduced in Texinfo version 4.6) will display the above
+literally, which, although not pretty, should not be harmful.
+
+
+@node Image Scaling
+@subsection Image Scaling
+
+@cindex Images, scaling
+@cindex Scaling images
+@cindex Width of images
+@cindex Height of images
+@cindex Aspect ratio of images
+@cindex Distorting images
+The optional @var{width} and @var{height} arguments to the
+@code{@@image} command (see the previous section) specify the size to
+scale the image to.  They are ignored for Info output.  If neither is
+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.
+
+@cindex Dimensions and image sizes
+The @var{width} and @var{height} may be specified using any valid @TeX{}
+dimension, namely:
+
+@table @asis
+@item pt
+@cindex Points (dimension)
+point (72.27pt = 1in)
+@item pc
+@cindex Picas
+pica (1pc = 12pt)
+@item bp
+@cindex Big points
+big point (72bp = 1in)
+@item in
+@cindex Inches
+inch
+@item cm
+@cindex Centimeters
+centimeter (2.54cm = 1in)
+@item mm
+@cindex Millimeters
+millimeter (10mm = 1cm)
+@item dd
+@cindex Did@^ot points
+did@^ot point (1157dd = 1238pt)
+@item cc
+@cindex Ciceros
+cicero (1cc = 12dd)
+@item sp
+@cindex Scaled points
+scaled point (65536sp = 1pt)
+@end table
+
+@pindex ridt.eps
+For example, the following will scale a file @file{ridt.eps} to one
+inch vertically, with the width scaled proportionately:
+
+@example
+@@image@{ridt,,1in@}
+@end example
+
+@pindex epsf.tex
+For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
+installed somewhere that @TeX{} can find it.  (The standard location is
+@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
+root of your @TeX{} directory tree.)  This file is included in the
+Texinfo distribution and is also available from
+@uref{ftp://tug.org/tex/epsf.tex}, among other places.
+
+@code{@@image} can be used within a line as well as for displayed
+figures.  Therefore, if you intend it to be displayed, be sure to leave
+a blank line before the command, or the output will run into the
+preceding text.
+
+Image scaling is presently implemented only in @TeX{}, not in HTML or
+any other sort of output.
+
+
+@node Footnotes
+@section Footnotes
+@cindex Footnotes
+@findex footnote
+
+A @dfn{footnote} is for a reference that documents or elucidates the
+primary text.@footnote{A footnote should complement or expand upon
+the primary text, but a reader should not need to read a footnote to
+understand the primary text.  For a thorough discussion of footnotes,
+see @cite{The Chicago Manual of Style}, which is published by the
+University of Chicago Press.}  Footnotes are distracting; use them
+sparingly, if at all.  Standard bibliographical references are better
+placed in a bibliography at the end of a document than in footnotes
+throughout.
+
+@menu
+* Footnote Commands::           How to write a footnote in Texinfo.
+* Footnote Styles::             Controlling how footnotes appear in Info.
+@end menu
+
+
+@node Footnote Commands
+@subsection Footnote Commands
+
+In Texinfo, footnotes are created with the @code{@@footnote} command.
+This command is followed immediately by a left brace, then by the text
+of the footnote, and then by a terminating right brace.  Footnotes may
+be of any length (they will be broken across pages if necessary), but
+are usually short.  The template is:
+
+@example
+ordinary text@@footnote@{@var{text of footnote}@}
+@end example
+
+As shown here, the @code{@@footnote} command should come right after the
+text being footnoted, with no intervening space; otherwise, the footnote
+marker might end up starting a line.
+
+For example, this clause is followed by a sample footnote@footnote{Here
+is the sample footnote.}; in the Texinfo source, it looks like
+this:
+
+@example
+@dots{}a sample footnote@@footnote@{Here is the sample
+footnote.@}; in the Texinfo source@dots{}
+@end example
+
+As you can see, the source includes two punctuation marks next to each
+other; in this case, @samp{.@};} is the sequence.  This is normal (the
+first ends the footnote and the second belongs to the sentence being
+footnoted), so don't worry that it looks odd.
+
+In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: @samp{(1)}.  The
+reference mark is followed by a cross-reference link to the footnote's
+text.
+
+In the HTML output, footnote references are marked with a small,
+superscripted number which is rendered as a hypertext link to the
+footnote text.
+
+By the way, footnotes in the argument of an @code{@@item} command for a
+@code{@@table} must be on the same line as the @code{@@item}
+(as usual).  @xref{Two-column Tables}.
+
+
+@node Footnote Styles
+@subsection Footnote Styles
+
+Info has two footnote styles, which determine where the text of the
+footnote is located:
+
+@itemize @bullet
+@cindex @samp{@r{End}} node footnote style
+@item
+In the `End' node style, all the footnotes for a single node
+are placed at the end of that node.  The footnotes are separated from
+the rest of the node by a line of dashes with the word
+@samp{Footnotes} within it.  Each footnote begins with an
+@samp{(@var{n})} reference mark.
+
+@need 700
+@noindent
+Here is an example of a single footnote in the end of node style:@refill
+
+@example
+@group
+--------- Footnotes ---------
+
+(1)  Here is a sample footnote.
+@end group
+@end example
+
+@cindex @samp{@r{Separate}} footnote style
+@item
+In the `Separate' node style, all the footnotes for a single
+node are placed in an automatically constructed node of
+their own.  In this style, a ``footnote reference'' follows
+each @samp{(@var{n})} reference mark in the body of the
+node.  The footnote reference is actually a cross reference
+which you use to reach the footnote node.
+
+The name of the node with the footnotes is constructed
+by appending @w{@samp{-Footnotes}} to the name of the node
+that contains the footnotes. (Consequently, the footnotes'
+node for the @file{Footnotes} node is
+@w{@file{Footnotes-Footnotes}}!)  The footnotes' node has an
+`Up' node pointer that leads back to its parent node.
+
+@noindent
+Here is how the first footnote in this manual looks after being
+formatted for Info in the separate node style:
+
+@smallexample
+@group
+File: texinfo.info  Node: Overview-Footnotes, Up: Overview
+
+(1) The first syllable of "Texinfo" is pronounced like "speck", not
+"hex". @dots{}
+@end group
+@end smallexample
+@end itemize
+
+Unless your document has long and important footnotes (as in, say,
+Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end}
+style, as it is simpler for readers to follow.
+
+@findex footnotestyle
+Use the @code{@@footnotestyle} command to specify an Info file's
+footnote style.  Write this command at the beginning of a line followed
+by an argument, either @samp{end} for the end node style or
+@samp{separate} for the separate node style.
+
+@need 700
+For example,
+
+@example
+@@footnotestyle end
+@end example
+@noindent
+or
+@example
+@@footnotestyle separate
+@end example
+
+Write an @code{@@footnotestyle} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file.  (If you
+include the @code{@@footnotestyle} command between the start-of-header
+and end-of-header lines, the region formatting commands will format
+footnotes as specified.)@refill
+
+If you do not specify a footnote style, the formatting commands use
+their default style.  Currently, @code{texinfo-format-buffer} and
+@code{texinfo-format-region} use the `separate' style and
+@code{makeinfo} uses the `end' style.
+
+
+@node Indices
+@chapter Indices
+@cindex 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.  Lastly, you can define your own new indices.
+
+@xref{Printing Indices & Menus}, for information on how to print
+indices.
+
+@menu
+* Index Entries::               Choose different words for index entries.
+* Predefined Indices::          Use different indices for different kinds
+                                 of entries.
+* Indexing Commands::           How to make an index entry.
+* Combining Indices::           How to combine indices.
+* New Indices::                 How to define your own indices.
+@end menu
+
+
+@node Index Entries
+@section Making Index Entries
+@cindex Index entries, making
+@cindex Entries, making index
+
+When you are making index entries, it is good practice to think of the
+different ways people may look for something.  Different people
+@emph{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.@refill
+
+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.@refill
+
+@xref{Printing Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info file.@refill
+
+
+@node Predefined Indices
+@section Predefined Indices
+
+Texinfo provides six predefined indices.  Here are their nominal
+meanings, abbreviations, and the corresponding index entry commands:
+
+@table @samp
+@item cp
+@cindex @code{cp} (concept) index
+(@code{@@cindex}) concept index, for general concepts.
+@item fn
+@cindex @code{fn} (function) index
+(@code{@@findex}) function index, for function and function-like
+names (such as entry points of libraries).
+@item ky
+@cindex @code{ky} (keystroke) index
+(@code{@@kindex}) keystroke index, for keyboard commands.
+@item pg
+@cindex @code{pg} (program) index
+(@code{@@pindex}) program index, for names of programs.
+@item tp
+@cindex @code{tp} (data type) index
+(@code{@@tindex}) data type index, for type names (such as structures
+defined in header files).
+@item vr
+@cindex @code{vr} (variable) index
+(@code{@@vindex}) variable index, for variable names (such as global
+variables of libraries).
+@end table
+
+@noindent
+Not every manual needs all of these, and most manuals use only two or
+three at most.  The present manual, for example, 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).
+
+You are not required to use the predefined indices strictly 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 @code{@@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.
+
+On the other hand, it is best not to stray too far from the meaning of
+the predefined indices.  Otherwise, in the event that your text is
+combined with other text from other manuals, the index entries will
+not match up.  Instead, define your own new index (@pxref{New
+Indices}).
+
+We recommend having a single index in the final document whenever
+possible, however many source indices you use, since then readers have
+only one place to look.  Two or more source indices can be combined
+into one output index using the @code{@@synindex} or
+@code{@@syncodeindex} commands (@pxref{Combining Indices}).
+
+
+@node Indexing Commands
+@section Defining the Entries of an Index
+@cindex Defining indexing entries
+@cindex Index entries
+@cindex Entries for an index
+@cindex Specifying index entries
+@cindex Creating index entries
+
+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.@refill
+
+An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the entry.@refill
+
+For example, this section begins with the following five entries for
+the concept index:@refill
+
+@example
+@@cindex Defining indexing entries
+@@cindex Index entries, defining
+@@cindex Entries for an index
+@@cindex Specifying index entries
+@@cindex Creating index entries
+@end example
+
+Each predefined index has its own indexing command---@code{@@cindex}
+for the concept index, @code{@@findex} for the function index, and so
+on, as listed in the previous section.
+
+@cindex Writing index entries
+@cindex Index entry writing
+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.
+
+@cindex Index font types
+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{@@code} font.  You may change the way part of an entry is
+printed with the usual Texinfo commands, such as @code{@@file} for
+file names (@pxref{Marking Text}), and @code{@@r} for the normal roman
+font (@pxref{Fonts}).
+
+@quotation Caution
+Do not use a colon in an index entry.  In Info, a colon separates the
+menu entry name from the node name, so a colon in the entry itself
+confuses Info.  @xref{Menu Parts}, for more information about the
+structure of a menu entry.
+@end quotation
+
+
+@node Combining Indices
+@section Combining Indices
+@cindex Combining indices
+@cindex Indices, combining them
+
+Sometimes you will want to combine two disparate indices such as
+functions and concepts, perhaps because you have few enough entries
+that a separate index would look silly.
+
+You could put functions into the concept index by writing
+@code{@@cindex} commands for them instead of @code{@@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{@@code}.
+
+@menu
+* syncodeindex::                How to merge two indices, using @code{@@code}
+                                 font for the merged-from index.
+* synindex::                    How to merge two indices, using the
+                                 default font of the merged-to index.
+@end menu
+
+@node syncodeindex
+@subsection @code{@@syncodeindex}
+@findex syncodeindex
+
+When you want to combine functions and concepts into one index, you
+should index the functions with @code{@@findex} and index the concepts
+with @code{@@cindex}, and use the @code{@@syncodeindex} command to
+redirect the function index entries into the concept index.@refill
+
+The @code{@@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:@refill
+
+@example
+@@syncodeindex @var{from} @var{to}
+@end example
+
+@cindex Predefined names for indices
+@cindex Two letter names for indices
+@cindex Indices, two letter names
+@cindex Names for indices
+For this purpose, the indices are given two-letter names:@refill
+
+@table @samp
+@item cp
+concept index
+@item fn
+function index
+@item vr
+variable index
+@item ky
+key index
+@item pg
+program index
+@item tp
+data type index
+@end table
+
+Write an @code{@@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:@refill
+
+@example
+@@syncodeindex fn cp
+@end example
+
+@noindent
+This will cause all entries designated for the function index to merge
+in with the concept index instead.@refill
+
+To merge both a variables index and a function index into a concept
+index, write the following:@refill
+
+@example
+@group
+@@syncodeindex vr cp
+@@syncodeindex fn cp
+@end group
+@end example
+
+@cindex Fonts for indices
+The @code{@@syncodeindex} command puts all the entries from the `from'
+index (the redirected index) into the @code{@@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{@@code} font as you would expect.@refill
+
+@node synindex
+@subsection @code{@@synindex}
+@findex synindex
+
+The @code{@@synindex} command is nearly the same as the
+@code{@@syncodeindex} command, except that it does not put the
+`from' index  entries into the @code{@@code} font; rather it puts
+them in the roman font.  Thus, you use @code{@@synindex} when you
+merge a concept index into a function index.@refill
+
+@xref{Printing Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info file.@refill
+
+
+@node New Indices
+@section Defining New Indices
+@cindex Defining new indices
+@cindex Indices, defining new
+@cindex New index defining
+@findex defindex
+@findex defcodeindex
+
+In addition to the predefined indices, you may use the
+@code{@@defindex} and @code{@@defcodeindex} commands to define new
+indices.  These commands create new indexing @@-commands with which
+you mark index entries.  The @code{@@defindex} command is used like
+this:
+
+@example
+@@defindex @var{name}
+@end example
+
+The name of an index should be a two letter word, such as @samp{au}.
+For example:
+
+@example
+@@defindex au
+@end example
+
+This defines a new index, called the @samp{au} index.  At the same
+time, it creates a new indexing command, @code{@@auindex}, that you
+can use to make index entries.  Use this 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 @samp{au} index entries.
+
+@example
+@@section Cognitive Semantics
+@@cindex kinesthetic image schemas
+@@auindex Johnson, Mark
+@@auindex Lakoff, George
+@end example
+
+@noindent
+(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
+
+In general, Texinfo constructs the new indexing command by
+concatenating the name of the index with @samp{index}; thus, defining
+an @samp{xy} index leads to the automatic creation of an
+@code{@@xyindex} command.
+
+Use the @code{@@printindex} command to print the index, as you do with
+the predefined indices.  For example:
+
+@example
+@group
+@@node Author Index
+@@unnumbered Author Index
+
+@@printindex au
+@end group
+@end example
+
+The @code{@@defcodeindex} is like the @code{@@defindex} command,
+except that, in the printed output, it prints entries in an
+@code{@@code} font by default instead of a roman font.  
+
+You should define new indices before the end-of-header line of a
+Texinfo file, and (of course) before any @code{@@synindex} or
+@code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
+
+
+@node Insertions
+@chapter Special Insertions
+@cindex Inserting special characters and symbols
+@cindex 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.
+
+@iftex
+These are:
+
+@itemize @bullet
+@item @samp{@@} and braces and commas.
+@item Whitespace within and around a sentence.
+@item Accents.
+@item Dots and bullets.
+@item The @TeX{} logo and the copyright symbol.
+@item The euro and pounds currency symbols.
+@item The degrees symbol.
+@item The minus sign.
+@item Mathematical expressions.
+@item Glyphs for evaluation, macros, errors, etc.
+@item Footnotes.
+@item Images.
+@end itemize
+@end iftex
+
+@menu
+* Atsign Braces Comma::         Inserting @@ and @{@} and ,.
+* Inserting Quote Characters::  Inserting left and right quotes, in code.
+* Inserting Space::             How to insert the right amount of space
+                                 within a sentence.
+* Inserting Accents::           How to insert accents and special characters.
+* Inserting Quotation Marks::   How to insert quotation marks.
+* Dots Bullets::                How to insert dots and bullets.
+* TeX and copyright::           How to insert the @TeX{} logo
+                                 and the copyright symbol.
+* euro::                        How to insert the Euro currency symbol.
+* pounds::                      How to insert the pounds currency symbol.
+* textdegree::                  How to insert the degrees symbol.
+* minus::                       How to insert a minus sign.
+* geq leq::                     How to insert greater/less-than-or-equal signs.
+* math::                        How to format a mathematical expression.
+* Click Sequences::             Inserting GUI usage sequences.
+* Glyphs::                      How to indicate results of evaluation,
+                                 expansion of macros, errors, etc.
+@end menu
+
+
+@node Atsign Braces Comma
+@section Inserting @@ and @{@} and @comma{}
+@cindex Special characters, inserting
+@cindex Commands to insert special characters
+
+@samp{@@} and curly braces are special characters in Texinfo.  To insert
+these characters so they appear in text, you must put an @samp{@@} in
+front of these characters to prevent Texinfo from misinterpreting
+them.
+
+The comma `,' is a special character only in one uncommon context:
+it separates arguments to commands that take multiple arguments.
+
+@menu
+* Inserting an Atsign::
+* Inserting Braces::
+* Inserting a Comma::
+@end menu
+
+
+@node Inserting an Atsign
+@subsection Inserting `@@' with @code{@@@@}
+@findex @@ @r{(literal @samp{@@})}
+@cindex Inserting @@ @r{(literal @samp{@@})}
+
+@code{@@@@} stands for a single @samp{@@} in either printed or Info
+output.
+
+Do not put braces after an @code{@@@@} command.
+
+
+@node Inserting Braces
+@subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}}
+@cindex Braces, inserting
+@findex @{ @r{(literal @samp{@{})}
+@findex @} @r{(literal @samp{@}})}
+
+@code{@@@{} stands for a single @samp{@{} in either printed or Info
+output.
+
+@code{@@@}} stands for a single @samp{@}} in either printed or Info
+output.
+
+Do not put braces after either an @code{@@@{} or an @code{@@@}}
+command.
+
+
+@node Inserting a Comma
+@subsection Inserting `,' with @code{@@comma@{@}}
+@cindex Commas, inserting
+@findex comma
+
+Ordinarily, a comma `,' is a normal character that can be simply typed
+in your input where you need it.
+
+However, Texinfo uses the comma as a special character in one uncommon
+context: some commands, such as @code{@@acronym} (@pxref{acronym}) and
+@code{@@xref} (@pxref{Cross References}), as well as user-defined
+macros (@pxref{Defining Macros}), can take more than one argument.  In
+these cases, the comma character is used to separate arguments.
+
+Since a comma character would confuse Texinfo's parsing for these
+commands, you must use the command @samp{@@comma@{@}} instead if you want
+to pass an actual comma.  Here are some examples:
+
+@example
+@@acronym@{ABC, A Bizarre @@comma@{@}@}
+@@xref@{Comma,, The @@comma@{@} symbol@}
+@@mymac@{One argument@@comma@{@} containing a comma@}
+@end example
+
+Although @comma{} can be used nearly anywhere, there is no need for it
+anywhere except in this unusual case.
+
+
+@node Inserting Quote Characters
+@section Inserting Quote Characters
+
+@cindex Inserting quote characters
+@cindex Quote characters, inserting
+
+As explained in the early section on general Texinfo input conventions
+(@pxref{Conventions}), Texinfo source files use the ASCII character
+@code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'}
+(39 decimal) to produce a right quote (').  Doubling these input
+characters (@code{``} and @code{''}) produces double quotes (`` and
+'').  These are the conventions used by @TeX{}.
+
+This works all right for text.  However, in examples of computer code,
+readers are especially likely to cut and paste the text
+verbatim---and, unfortunately, some document viewers will mangle these
+characters.  (The free PDF reader @command{xpdf} works fine, but other
+PDF readers, both free and nonfree, have problems.)
+
+If this is a concern for your document, Texinfo provides two special
+settings via @code{@@set}:
+
+@table @code
+@item @@set txicodequoteundirected
+causes the output for the @code{'} character to be the undirected
+single quote, like this:
+@set txicodequoteundirected
+@code{'}.
+@clear txicodequoteundirected
+
+@item @@set txicodequotebacktick
+Cause the output for the @code{`} character to be the standalone grave
+accent, like this:
+@set txicodequotebacktick
+@code{`}.
+@clear txicodequotebacktick
+
+@end table
+
+@code{xyza`'bc}
+
+If you want these settings for only part of the document,
+@code{@@clear} will restore the normal behavior, as in
+@code{@@clear@tie{}txicodequoteundirected}.
+
+These settings affect @code{@@code}, @code{@@example}, and
+@code{@@verbatim}; they do not affect @code{@@samp}.  (@xref{Useful
+Highlighting}.)
+
+
+@node Inserting Space
+@section Inserting Space
+
+@cindex Inserting space
+@cindex Spacing, inserting
+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.
+* frenchspacing::               Specifying end-of-sentence spacing.
+* dmn::                         How to format a dimension.
+@end menu
+
+
+@node Not Ending a Sentence
+@subsection Not Ending a Sentence
+
+@cindex Not ending a sentence
+@cindex Sentence non-ending punctuation
+@cindex Periods, inserting
+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
+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.
+
+@findex <colon> @r{(suppress end-of-sentence space)}
+Use the @code{@@:}@: command after a period, question mark,
+exclamation mark, or colon that should not be followed by extra space.
+For example, use @code{@@:}@: after periods that end abbreviations
+which are not at the ends of sentences.
+
+For example,
+
+@example
+foo vs.@@: bar
+foo vs. bar
+@end example
+
+@noindent
+@ifnottex
+produces
+@end ifnottex
+@iftex
+produces the following.  If you look carefully at this printed output,
+you will see a little extraneous space after @samp{vs.}@: in the second
+line.
+@end iftex
+
+@quotation
+foo vs.@: bar @*
+foo vs. bar
+@end quotation
+
+@noindent
+@code{@@:} has no effect on the Info and HTML output.  In Docbook and
+XML, the previous punctuation character (.?!:) is output as an entity
+instead of as the normal character: @samp{&period; &quest; &excl;
+&colon;}.  This gives further processors a chance to notice and not
+add the usual extra space.
+
+Do not put braces after @code{@@:} (or any non-alphabetic command).
+
+
+@node Ending a Sentence
+@subsection Ending a Sentence
+
+@cindex Ending a Sentence
+@cindex Sentence ending punctuation
+
+@findex .  @r{(end of sentence)}
+@findex ! @r{(end of sentence)}
+@findex ? @r{(end of sentence)}
+Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
+exclamation point, and @code{@@?}@: instead of a question mark at the end
+of a sentence that ends with a 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:
+
+@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.
+@end example
+
+@noindent
+@ifnottex
+produces
+@end ifnottex
+@iftex
+produces the following.  If you look carefully at this printed output,
+you will see a little more whitespace after the @samp{W} in the first
+line.
+@end iftex
+
+@quotation
+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.
+@end quotation
+
+In the Info file output, @code{@@.}@: is equivalent to a simple
+@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
+
+The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
+work well with the XEmacs sentence motion commands (@pxref{Sentences,,,
+xemacs, XEmacs User's Manual}).
+
+Do not put braces after any of these commands.
+
+
+@node Multiple Spaces
+@subsection Multiple Spaces
+
+@cindex Multiple spaces
+@cindex Whitespace, inserting
+@cindex Space, inserting horizontal
+@findex <space>
+@findex <tab>
+@findex <newline>
+
+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:
+@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
+which insert a single space into the output.  (Here,
+@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
+space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
+character and end-of-line, i.e., when @samp{@@} is the last character on
+a line.)
+
+For example,
+@example
+Spacey@@ @@ @@ @@
+example.
+@end example
+
+@noindent
+produces
+
+@example
+Spacey@ @ @ @
+example.
+@end example
+
+Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
+@code{@@multitable} (@pxref{Multi-column Tables}).
+
+Do not follow any of these commands with braces.
+
+To produce a non-breakable space, see @ref{tie, @code{@@tie}}.
+
+
+@node frenchspacing
+@subsection @code{@@frenchspacing} @var{val}: Control sentence spacing
+@findex frenchspacing
+@cindex French spacing
+@cindex Sentences, spacing after
+@cindex Space, after sentences
+
+In American typography, it is traditional and correct to put extra
+space at the end of a sentence, after a semi-colon, and so on.  This
+is the default in Texinfo.  In French typography (and many others),
+this extra space is wrong; all spaces are uniform.
+
+Therefore Texinfo provides the @code{@@frenchspacing} command to
+control the spacing after punctuation.  It reads the rest of the line
+as its argument, which must be the single word @samp{on} or @samp{off}
+(always these words, regardless of the language) of the document.
+Here is an example:
+
+@example
+@@frenchspacing on
+This is text. Two sentences. Three sentences. French spacing.
+
+@@frenchspacing off
+This is text. Two sentences. Three sentences. Non-French spacing.
+@end example
+
+@noindent produces (there will be no difference in Info):
+
+@frenchspacing on
+This is text. Two sentences. Three sentences. French spacing.
+
+@frenchspacing off
+This is text. Two sentences. Three sentences. Non-French spacing.
+
+@code{@@frenchspacing} mainly affects the printed output, including
+the output after @code{@@.}, @code{@@!}, and @code{@@?} (@pxref{Ending
+a Sentence}).
+
+In Info, usually space characters in the input are written unaltered
+to the output, and @code{@@frenchspacing} does not change this.  It
+does change the one case where @command{makeinfo} outputs a space on
+its own: when a sentence ends at a newline in the source.  Here's an
+example:
+
+@example
+Some sentence.
+Next sentence.
+@end example
+
+@noindent produces in Info output, with @code{@@frenchspacing off}
+(the default), two spaces between the sentences:
+
+@example
+Some sentence.  Next sentence.
+@end example
+
+@noindent With @code{@@frenchspacing on}, @command{makeinfo} outputs
+only a single space:
+
+@example
+Some sentence. Next sentence.
+@end example
+
+@code{@@frenchspacing} has no effect on the HTML or Docbook output;
+for XML, it outputs a transliteration of itself (@pxref{Output
+Formats}).
+
+
+@node dmn
+@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
+@cindex Thin space between number, dimension
+@cindex Dimension formatting
+@cindex Format a dimension
+@findex dmn
+
+At times, you may want to write @samp{12@dmn{pt}} or
+@samp{8.5@dmn{in}} with little or no space between the number and the
+abbreviation for the dimension.  You can use the @code{@@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 @code{@@dmn} command, write the number and then follow it
+immediately, with no intervening space, by @code{@@dmn}, and then by
+the dimension within braces.  For example,
+
+@example
+A4 paper is 8.27@@dmn@{in@} wide.
+@end example
+
+@noindent
+produces
+
+@quotation
+A4 paper is 8.27@dmn{in} wide.
+@end quotation
+
+Not everyone uses this style.  Some people prefer @w{@samp{8.27 in.@@:}}
+or @w{@samp{8.27 inches}} to @samp{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 @code{@@w} (@pxref{w}).  Also, if
+you write a period after an abbreviation within a sentence, you should
+write @samp{@@:} after the period to prevent @TeX{} from inserting extra
+whitespace, as shown here.  @xref{Not Ending a Sentence}.
+
+
+@node Inserting Accents
+@section Inserting Accents
+
+@cindex Inserting accents
+@cindex Accents, inserting
+@cindex Floating accents, inserting
+
+Here is a table with the commands Texinfo provides for inserting
+floating accents.  They all need an argument, the character to accent,
+which can either be given in braces as usual (@code{@@'@{e@}}), or, as
+a special case, the braces can be omitted, in which case the argument
+is the next character (@code{@@'e}).  This is to make the source as
+convenient as possible to type and read, since accented characters are
+very common in some languages.
+
+If the command is alphabetic, such as @code{@@dotaccent}, then there
+must be a space between the command name and argument if braces are
+not used.  If the command is non-alphabetic, such as @code{@@'}, then
+there must @emph{not} be a space; the argument is the very next
+character.
+
+Exception: the argument to @code{@@tieaccent} must be enclosed in
+braces (since it is two characters instead of one).
+
+@findex documentencoding
+To get the true accented characters output in Info, not just the ASCII
+transliterations, it is necessary to specify @code{@@documentencoding}
+with an encoding which supports the required characters
+(@pxref{documentencoding,,@code{@@documentencoding}}).  In this case,
+you can also use non-ASCII (e.g., pre-accented) characters in the
+source file.
+
+@findex " @r{(umlaut accent)}
+@cindex Umlaut accent
+@findex ' @r{(umlaut accent)}
+@cindex Acute accent
+@findex = @r{(macron accent)}
+@cindex Macron accent
+@findex ^ @r{(circumflex accent)}
+@cindex Circumflex accent
+@findex ` @r{(grave accent)}
+@cindex Grave accent
+@findex ~ @r{(tilde accent)}
+@cindex Tilde accent
+@findex , @r{(cedilla accent)}
+@cindex Cedilla accent
+@findex dotaccent
+@cindex Dot accent
+@findex H @r{(Hungarian umlaut accent)}
+@cindex Hungarian umlaut accent
+@findex ringaccent
+@cindex Ring accent
+@findex tieaccent
+@cindex Tie-after accent
+@findex u @r{(breve accent)}
+@cindex Breve accent
+@findex ubaraccent
+@cindex Underbar accent
+@findex udotaccent
+@cindex Underdot accent
+@findex v @r{(check accent)}
+@cindex Hacek accent
+@cindex Check accent
+@cindex Caron accent
+@multitable {@t{@@questiondown@{@}}} {Output} {hacek/check/caron accent}
+@headitem Command           @tab Output         @tab What
+@item @t{@@"o}              @tab @"o            @tab umlaut accent
+@item @t{@@'o}              @tab @'o            @tab acute accent
+@item @t{@@,@{c@}}          @tab @,{c}          @tab cedilla accent
+@item @t{@@=o}              @tab @=o            @tab macron/overbar accent
+@item @t{@@^o}              @tab @^o            @tab circumflex accent
+@item @t{@@`o}              @tab @`o            @tab grave accent
+@item @t{@@~o}              @tab @~o            @tab tilde accent
+@item @t{@@dotaccent@{o@}}  @tab @dotaccent{o}  @tab overdot accent
+@item @t{@@H@{o@}}          @tab @H{o}          @tab long Hungarian umlaut
+@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
+@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
+@item @t{@@u@{o@}}          @tab @u{o}          @tab breve accent
+@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
+@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
+@item @t{@@v@{o@}}          @tab @v{o}          @tab hacek/check/caron accent
+@end multitable
+
+This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
+@findex questiondown
+@cindex @questiondown{}
+@findex exclamdown
+@cindex @exclamdown{}
+@findex aa
+@cindex @aa{}
+@findex AA
+@cindex @AA{}
+@findex ae
+@cindex @ae{}
+@findex AE
+@cindex @AE{}
+@findex dotless
+@cindex @dotless{i} (dotless i)
+@cindex @dotless{j} (dotless j)
+@cindex Dotless i, j
+@findex l
+@cindex @l{}
+@findex L
+@cindex @L{}
+@findex o
+@cindex @o{}
+@findex O
+@cindex @O{}
+@findex oe
+@cindex @oe{}
+@findex OE
+@cindex @OE{}
+@cindex Romance ordinals
+@cindex Ordinals, Romance
+@cindex Feminine ordinal
+@findex ordf
+@cindex @ordf{}
+@cindex Masculine ordinal
+@findex ordm
+@cindex @ordm{}
+@findex ss
+@cindex @ss{}
+@cindex Es-zet
+@cindex Sharp S
+@cindex German S
+@multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S}
+@item @t{@@exclamdown@{@}}   @tab @exclamdown{}   @tab upside-down !
+@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
+@item @t{@@aa@{@} @@AA@{@}}  @tab @aa{} @AA{}     @tab a,A with circle
+@item @t{@@ae@{@} @@AE@{@}}  @tab @ae{} @AE{}     @tab ae,AE ligatures
+@item @t{@@dotless@{i@}}     @tab @dotless{i}     @tab dotless i
+@item @t{@@dotless@{j@}}     @tab @dotless{j}     @tab dotless j
+@item @t{@@l@{@} @@L@{@}}    @tab @l{} @L{}       @tab suppressed-L,l
+@item @t{@@o@{@} @@O@{@}}    @tab @o{} @O{}       @tab O,o with slash
+@item @t{@@oe@{@} @@OE@{@}}  @tab @oe{} @OE{}     @tab oe,OE ligatures
+@item @t{@@ordf@{@} @@ordm@{@}}  @tab @ordf{} @ordm{}     @tab Spanish ordinals
+@item @t{@@ss@{@}}           @tab @ss{}           @tab es-zet or sharp S
+@end multitable
+
+
+@node Inserting Quotation Marks
+@section Inserting Quotation Marks
+@cindex Inserting quotation marks
+@cindex Quotation marks, inserting
+
+@cindex Quotation characters (`'), in source
+Use doubled single-quote characters to begin and end quotations:
+@w{@t{`@w{}`@dots{}'@w{}'}}.  @TeX{} converts two single quotes to
+left- and right-hand doubled quotation marks,
+@c this comes out as "like this" in Info, which is just confusing.
+@iftex
+``like this'',
+@end iftex
+and Info converts doubled single-quote characters to ASCII
+double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
+
+You may occasionally need to produce two consecutive single quotes;
+for example, in documenting a computer language such as Maxima where
+@t{'@w{}'} is a valid command.  You can do this with the input
+@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into
+the double-quote characters.
+
+@cindex Unicode quotation characters
+@cindex Grave accent, vs. left quote
+The left quote character (@t{`}, ASCII code 96) used in Texinfo is a
+grave accent in ANSI and ISO character set standards.  We use it as a
+quote character because that is how @TeX{} is set up, by default.
+
+Texinfo supports several other quotation marks used in languages other
+than English.  Below is a table with the commands Texinfo provides for
+inserting quotation marks.
+
+@findex documentencoding
+@cindex UTF-8
+@cindex ISO 8859-15
+@cindex Latin 9
+@cindex ISO 8859-1
+@cindex Latin 1
+In order to get the symbols for the quotation marks in encoded Info
+output, it is necessary to specify @code{@@documentencoding UTF-8}.
+(@xref{documentencoding,,@code{@@documentencoding}}.)  Double
+guillemets are also present in ISO 8859-1 (aka Latin@tie{}1) and ISO
+8859-15 (aka Latin@tie{}9).
+
+@cindex European Computer Modern fonts
+@cindex EC fonts
+The standard @TeX{} fonts support the usual quotation marks used in
+English (the ones produced with single and doubled ASCII
+single-quotes).  For the other quotation marks, @TeX{} uses European
+Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
+These fonts are freely available, of course; you can download them
+from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other
+places.
+
+@cindex CM-Super fonts
+The free EC fonts are bitmap fonts created with Metafont.  Especially
+for on-line viewing, Type@tie{}1 (vector) versions of the fonts are
+preferable; these are available in the CM-Super font package
+(@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}).
+
+Both distributions include installation instructions.
+
+@cindex Single quotation marks
+@cindex Double quotation marks
+@cindex Left quotation marks
+@cindex Right quotation marks
+@findex quotedblleft
+@cindex ``
+@findex quoteleft
+@cindex `
+@findex quotedblright
+@cindex ''
+@findex quoteright
+@cindex '
+@cindex Double low-9 quotation mark
+@cindex Single low-9 quotation mark
+@findex quotedblbase
+@cindex @quotedblbase{} (double low-9 quotation mark)
+@findex quotesinglbase
+@cindex @quotesinglbase{} (single low-9 quotation mark)
+@cindex Angle quotation marks
+@cindex Guillemets
+@cindex Guillemots
+@cindex French quotation marks
+@cindex Quotation marks, French
+@cindex German quotation marks
+@cindex Quotation marks, German
+@cindex Double guillemets
+@cindex Single guillemets
+@cindex Double angle quotation marks
+@cindex Single angle quotation marks
+@cindex Left-pointing angle quotation marks
+@cindex Right-pointing angle quotation marks
+@cindex Double left-pointing angle quotation mark
+@cindex Double right-pointing angle quotation mark
+@cindex Single left-pointing angle quotation mark
+@cindex Single right-pointing angle quotation mark
+@findex guillemetleft
+@findex guillemotleft
+@cindex @guillemetleft{}
+@findex guillemetright
+@findex guillemotright
+@cindex @guillemetright{}
+@findex guilsinglleft
+@cindex @guilsinglleft{}
+@findex guilsinglright
+@cindex @guilsinglright{}
+@multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation mark (U+00BB)}
+@headitem Command                    @tab Glyph             @tab Unicode name (point)
+@item @verb{.@quotedblleft{} ``.}    @tab @quotedblleft{}   @tab Left double quotation mark (U+201C)
+@item @verb{.@quotedblright{} ''.}   @tab @quotedblright{}  @tab Right double quotation mark (U+201D)
+@item @verb{.@quoteleft{} `.}        @tab @quoteleft{}      @tab Left single quotation mark (U+2018)
+@item @verb{.@quoteright{} '.}       @tab @quoteright{}     @tab Right single quotation mark (U+2019)
+@item @t{@@quotedblbase@{@}}         @tab @quotedblbase{}   @tab Double low-9 quotation mark (U+201E)
+@item @t{@@quotesinglbase@{@}}       @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A)
+@item @t{@@guillemetleft@{@}}        @tab @guillemetleft{}  @tab Left-pointing double angle quotation mark (U+00AB)
+@item @t{@@guillemetright@{@}}       @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB)
+@item @t{@@guilsinglleft@{@}}        @tab @guilsinglleft{}  @tab Single left-pointing angle quotation mark (U+2039)
+@item @t{@@guilsinglright@{@}}       @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A)
+@end multitable
+
+For the double angle quotation marks, Adobe and @LaTeX{} glyph names
+are also supported:  @code{@@guillemotleft} and
+@code{@@guillemotright}.  These names are actually incorrect; a
+``guillemot'' is a bird species (a type of auk).
+
+Traditions for quotation mark usage vary to a great extent between
+languages (@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}).
+Texinfo does not provide commands for typesetting quotation marks
+according to the numerous traditions.  Therefore, you have to choose
+the commands appropriate for the language of your manual.  Sometimes
+aliases (@pxref{alias,,@code{@@alias}}) can simplify the usage and
+make the source code more readable.  For example, in German,
+@code{@@quotedblbase} is used for the left double quote, and the right
+double quote is actually @code{@@quotedblleft}, which is
+counter-intuitive.  Thus, in this case the following aliases would be
+convenient:
+
+@example
+@@alias lgqq = quotedblbase
+@@alias rgqq = quotedblleft
+@end example
+
+
+@node Dots Bullets
+@section Inserting Ellipsis and Bullets
+@cindex Dots, inserting
+@cindex Bullets, inserting
+@cindex Ellipsis, inserting
+@cindex Inserting ellipsis
+@cindex Inserting dots
+@cindex Special typesetting commands
+@cindex Typesetting commands for dots, etc.
+
+An @dfn{ellipsis} (a line of dots) is not typeset as a string of
+periods, so a special command is used for ellipsis in Texinfo.  The
+@code{@@bullet} command is special, too.  Each of these commands is
+followed by a pair of braces, @samp{@{@}}, 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.  @xref{Command Syntax, ,
+@@-Command Syntax}, for further information.)@refill
+
+@menu
+* dots::                        How to insert dots @dots{}
+* bullet::                      How to insert a bullet.
+@end menu
+
+
+@node dots
+@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
+@findex dots
+@findex enddots
+@cindex Inserting dots
+@cindex Dots, inserting
+
+Use the @code{@@dots@{@}} command to generate an ellipsis, which is
+three dots in a row, appropriately spaced @dots{} like so.  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 @code{@@enddots@{@}} command generates an
+end-of-sentence ellipsis, which has different spacing afterwards,
+@enddots{}  Look closely to see the difference.
+
+@iftex
+Here is an ellipsis: @dots{}
+Here are three periods in a row: ...
+
+In printed output, the three periods in a row are much closer together than
+the dots in the ellipsis.
+@end iftex
+
+
+@node bullet
+@subsection @code{@@bullet}@{@} (@bullet{})
+@findex bullet
+
+Use the @code{@@bullet@{@}} command to generate a large round dot, or
+the closest possible thing to one.  In Info, an asterisk is used.@refill
+
+Here is a bullet: @bullet{}
+
+When you use @code{@@bullet} in @code{@@itemize}, you do not need to
+type the braces, because @code{@@itemize} supplies them.
+(@xref{itemize, , @code{@@itemize}}.)@refill
+
+
+@node TeX and copyright
+@section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{}
+
+The logo `@TeX{}' is typeset in a special fashion and it needs an
+@@-command.  The copyright and registered symbols, `@copyright{}' and
+`@registeredsymbol{}', is also special.  Each of these commands is
+followed by a pair of braces, @samp{@{@}}, without any whitespace
+between the name of the command and the braces.
+
+@menu
+* tex::                         The @TeX{} logos.
+* copyright symbol::            The copyright symbol (c in a circle).
+* registered symbol::           The registered symbol (R in a circle).
+@end menu
+
+
+@node tex
+@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{})
+@findex TeX
+@findex LaTeX
+@cindex Logos, @TeX{}
+@cindex @TeX{} logo
+@cindex @LaTeX{} logo
+
+Use the @code{@@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 @samp{TeX}.
+
+Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}',
+which is even more special in printed manuals (and different from the
+incorrect @code{La@@TeX@{@}}.  In Info, the result is just
+@samp{LaTeX}.  (@LaTeX{} is another macro package built on top of
+@TeX{}, very loosely analogous to Texinfo in that it emphasizes
+logical structure, but much (much) larger.)
+
+The spelling of these commands are unusual among Texinfo commands in
+that they use both uppercase and lowercase letters.
+
+
+@node copyright symbol
+@subsection @code{@@copyright@{@}} (@copyright{})
+@findex copyright
+@cindex Copyright symbol
+
+Use the @code{@@copyright@{@}} command to generate the copyright
+symbol, `@copyright{}'.  Where possible, this is a @samp{c}
+inside a circle; in Info, this is @samp{(C)}.
+
+
+@node registered symbol
+@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{})
+@findex registeredsymbol
+@cindex Registered symbol
+
+Use the @code{@@registeredsymbol@{@}} command to generate the
+registered symbol, `@registeredsymbol{}'.  Where possible, this is an
+@samp{R} inside a circle; in Info, this is @samp{(R)}.
+
+
+@node euro
+@section @code{@@euro}@{@} (@euro{}): Euro Currency Symbol
+@findex euro
+@cindex Euro symbol
+
+Use the @code{@@euro@{@}} command to generate `@euro{}'.  Where
+possible, this is the symbol for the Euro currency, invented as part
+of the European economic unification.  In plain Info, it is the word
+@samp{Euro }.  A trailing space is included in the text
+transliteration since typically no space is desired after the symbol,
+so it would be inappropriate to have a space in the source document.
+
+Texinfo cannot magically synthesize support for the Euro symbol where
+the underlying system (fonts, software, whatever) does not support
+it.  Therefore, in many cases it is preferable to use the word
+``Euro''.  (In banking circles, the abbreviation for the Euro is EUR.)
+
+@cindex ISO 8859-15
+@cindex Latin 9
+In order to get the Euro symbol in encoded Info output, for example,
+it is necessary to specify @code{@@documentencoding ISO-8859-15}.
+(@xref{documentencoding,,@code{@@documentencoding}}.)  The Euro symbol
+is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more
+widely-used and supported ISO 8859-1 (Latin@tie{}1).
+
+@pindex feymr10
+@cindex Euro font
+The Euro symbol does not exist in the standard @TeX{} fonts (which
+were designed before the Euro was legislated into existence).
+Therefore, @TeX{} uses an additional font, named @code{feymr10} (along
+with other variables).  It is freely available, of course; you can
+download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym},
+among other places.  The distribution includes installation
+instructions.
+
+
+@node pounds
+@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
+@findex pounds
+@cindex Pounds symbol
+
+Use the @code{@@pounds@{@}} command to generate `@pounds{}'.  Where
+possible, this is the symbol for the currency pounds sterling.  In
+Info, it is a @samp{#}.
+
+
+@node textdegree
+@section @code{@@textdegree}@{@} (@textdegree{}): Degrees Symbol
+@findex textdegree
+@cindex Degree symbol
+
+Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'.
+Where possible, this is the normal symbol for degrees.  In plain text
+and Info output, it is an @samp{o}.
+
+
+@node minus
+@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
+@findex minus
+@cindex Minus sign
+
+@cindex Em dash, compared to minus sign
+@cindex Hyphen, compared to minus
+Use the @code{@@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:
+
+@display
+@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
+
+`-' is a hyphen generated with the character @samp{-},
+
+`---' is an em-dash for text.
+@end display
+
+@noindent
+In the fixed-width font used by Info, @code{@@minus@{@}} is the same
+as a hyphen.
+
+You should not use @code{@@minus@{@}} inside @code{@@code} or
+@code{@@example} because the width distinction is not made in the
+fixed-width font they use.
+
+When you use @code{@@minus} to specify the mark beginning each entry in
+an itemized list, you do not need to type the braces
+(@pxref{itemize, , @code{@@itemize}}).
+
+
+@node geq leq
+@section @code{@@geq@{@}} (@geq{}) and @code{@@leq@{@}} (@leq{}): Inserting relations
+@findex geq
+@findex leq
+
+Use the @code{@@geq@{@}} and @code{@@geq@{@}} commands to generate
+greater-than-or-equal and less-than-equal-signs, `@geq{}' and
+`@leq{}'.  In plain text and Info output, these are the ASCII
+sequences @samp{>=} and @samp{<=}.  The 
+
+
+@node math
+@section @code{@@math}: Inserting Mathematical Expressions
+@findex math
+@cindex Mathematical expressions
+@cindex Formulas, mathematical
+
+You can write a short mathematical expression with the @code{@@math}
+command.  Write the mathematical expression between braces, like this:
+
+@example
+@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
+@end example
+
+@iftex
+@noindent This produces the following in @TeX{}:
+
+@display
+@math{(a + b)(a + b) = a^2 + 2ab + b^2}
+@end display
+
+@noindent and the following in other formats:
+@end iftex
+@ifnottex
+@noindent This produces the following in Info and HTML:
+@end ifnottex
+
+@example
+(a + b)(a + b) = a^2 + 2ab + b^2
+@end example
+
+The @code{@@math} command has no special effect on the Info and HTML
+output.  @command{makeinfo} expands any @code{@@}-commands as usual,
+but it does not try to produce good mathematical formatting in any
+way.
+
+However, as far as the @TeX{} output is concerned, plain @TeX{}
+mathematical commands are allowed in @code{@@math}, starting with
+@samp{\}, and the plain @TeX{} math characters like @samp{^} and
+@samp{_} are also recognized.  In essence, @code{@@math} drops you
+into plain @TeX{} math mode.
+
+This allows you to conveniently write superscripts and subscripts (as
+in the above example), and also to use all the plain @TeX{} math
+control sequences for symbols, functions, and so on, and thus get
+proper formatting in the @TeX{} output, at least.
+
+It's best to use @samp{\} instead of @samp{@@} for any such
+mathematical commands; otherwise, @command{makeinfo} will complain.
+On the other hand, input with matching (but unescaped) braces, such as
+@samp{k_@{75@}}, is allowed inside @code{@@math}, although
+@command{makeinfo} would complain about the bare braces in regular
+input.
+
+Here's an example:
+
+@example
+@@math@{\sin 2\pi \equiv \cos 3\pi@}
+@end example
+
+@iftex
+@noindent which looks like this in @TeX{}:
+@display
+@math{\sin 2\pi \equiv \cos 3\pi}
+@end display
+
+@noindent and
+@end iftex
+@noindent which looks like the input in Info and HTML:
+@example
+\sin 2\pi \equiv \cos 3\pi
+@end example
+
+@findex \ @r{(literal \ in @code{@@math})}
+Since @samp{\} is an escape character inside @code{@@math}, you can use
+@code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
+but you'd get the literal @samp{\\} in Info).  @code{@@\} is not
+defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
+literal @samp{\}.
+
+@cindex Displayed equations
+@cindex Equations, displayed
+For displayed equations, you must at present use @TeX{} directly
+(@pxref{Raw Formatter Commands}).
+
+
+@node Click Sequences
+@section Click Sequences
+@cindex Click sequences
+@cindex Sequence of clicks
+@cindex GUI click sequence
+
+@findex clicksequence
+When documenting graphical interfaces, it is necessary to describe
+sequences such as `Click on @samp{File}, then choose @samp{Open}, then
+@dots{}'.  Texinfo offers commands @code{@@clicksequence} and
+@code{click} to represent this, typically used like this:
+
+@example
+@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
+@end example
+
+@noindent
+which produces:
+
+@display
+@dots{} @clicksequence{File @click{} Open} @dots{}
+@end display
+
+@findex click
+@findex arrow
+The @code{@@click} command produces a simple right arrow (@samp{->} in
+Info) by default; this glyph is also available independently via the
+command @code{@@arrow@{@}}.
+
+@findex clickstyle
+You can change the glyph produced by @code{@@click} with the command
+@code{@@clickstyle}, which takes a command name as its single argument
+on the rest of the line, much like @code{@@itemize} and friends
+(@pxref{itemize,,@code{@@itemize}}).  The command should produce a
+glyph, and the usual empty braces @samp{@{@}} are omitted.  Here's an
+example:
+
+@example
+@@clickstyle @@result
+@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
+@end example
+
+@noindent
+now produces:
+
+@display
+@clickstyle @result
+@dots{} @clicksequence{File @click{} Open} @dots{}
+@end display
+
+
+@node Glyphs
+@section Glyphs for Examples
+@cindex Glyphs
+@cindex Examples, glyphs for
+
+In Texinfo, code is often illustrated in examples that are delimited
+by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
+@code{@@end lisp}.  In such examples, you can indicate the results of
+evaluation or an expansion using @samp{@result{}} or
+@samp{@expansion{}}.  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.@refill
+
+@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.
+@end menu
+
+
+@node Glyphs Summary
+@subsection Glyphs Summary
+
+Here are the different glyph commands:@refill
+
+@table @asis
+@item @result{}
+@code{@@result@{@}} points to the result of an expression.@refill
+
+@item @expansion{}
+@code{@@expansion@{@}} shows the results of a macro expansion.@refill
+
+@item @print{}
+@code{@@print@{@}} indicates printed output.@refill
+
+@item @error{}
+@code{@@error@{@}} indicates that the following text is an error
+message.@refill
+
+@item @equiv{}
+@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
+
+@item @point{}
+@code{@@point@{@}} shows the location of point.@refill
+@end table
+
+@menu
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+@end menu
+
+
+@node result
+@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
+@cindex Result of an expression
+@cindex Indicating evaluation
+@cindex Evaluation glyph
+@cindex Value of an expression, indicating
+@findex result
+
+Use the @code{@@result@{@}} command to indicate the result of
+evaluating an expression.@refill
+
+@iftex
+The @code{@@result@{@}} command is displayed as @samp{@result{}} in
+the printed output and as @samp{=>} in other formats.
+@end iftex
+@ifnottex
+The @code{@@result@{@}} command is displayed as @samp{@result{}} in
+Info and HTML and as a true double stemmed arrow in the printed output.
+@end ifnottex
+
+Thus, the following,
+
+@lisp
+(cdr '(1 2 3))
+    @result{} (2 3)
+@end lisp
+
+@noindent
+may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
+
+
+@node expansion
+@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
+@cindex Expansion, indicating
+@cindex Macro expansion, indicating
+@findex expansion
+
+When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the
+@code{@@expansion@{@}} command.@refill
+
+@iftex
+The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
+in the printed output and as @samp{==>} in other formats.
+@end iftex
+@ifnottex
+The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
+in Info and HTML, and as a long arrow with a flat base in the printed
+output.
+@end ifnottex
+
+@need 700
+For example, the following
+
+@example
+@group
+@@lisp
+(third '(a b c))
+    @@expansion@{@} (car (cdr (cdr '(a b c))))
+    @@result@{@} c
+@@end lisp
+@end group
+@end example
+
+@noindent
+produces
+
+@lisp
+@group
+(third '(a b c))
+    @expansion{} (car (cdr (cdr '(a b c))))
+    @result{} c
+@end group
+@end lisp
+
+@noindent
+which may be read as:
+
+@quotation
+@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
+the result of evaluating the expression is @code{c}.
+@end quotation
+
+@noindent
+Often, as in this case, an example looks better if the
+@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented.
+
+
+@node Print Glyph
+@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
+@cindex Printed output, indicating
+@findex print
+
+Sometimes an expression will print output during its execution.  You
+can indicate the printed output with the @code{@@print@{@}} command.@refill
+
+@iftex
+The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
+HTML and as @samp{@print{}} in the printed output.
+@end iftex
+@ifnottex
+The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
+and HTML and (similarly) as a horizontal dash butting against a
+vertical bar in the printed output.
+@end ifnottex
+
+In the following example, the printed text is indicated with
+@samp{@print{}}, and the value of the expression follows on the
+last line.
+
+@lisp
+@group
+(progn (print 'foo) (print 'bar))
+    @print{} foo
+    @print{} bar
+    @result{} bar
+@end group
+@end lisp
+
+@noindent
+In a Texinfo source file, this example is written as follows:
+
+@lisp
+@group
+@@lisp
+(progn (print 'foo) (print 'bar))
+    @@print@{@} foo
+    @@print@{@} bar
+    @@result@{@} bar
+@@end lisp
+@end group
+@end lisp
+
+
+@node Error Glyph
+@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
+@cindex Error message, indicating
+@findex error
+
+A piece of code may cause an error when you evaluate it.  You can
+designate the error message with the @code{@@error@{@}} command.@refill
+
+@iftex
+The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
+and HTML and as @samp{@error{}} in the printed output.
+@end iftex
+@ifnottex
+The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
+and HTML and as the word `error' in a box in the printed output.
+@end ifnottex
+
+@need 700
+Thus,
+
+@example
+@@lisp
+(+ 23 'x)
+@@error@{@} Wrong type argument: integer-or-marker-p, x
+@@end lisp
+@end example
+
+@noindent
+produces
+
+@lisp
+(+ 23 'x)
+@error{} Wrong type argument: integer-or-marker-p, x
+@end lisp
+
+@noindent
+This indicates that the following error message is printed
+when you evaluate the expression:
+
+@lisp
+Wrong type argument: integer-or-marker-p, x
+@end lisp
+
+@samp{@error{}} itself is not part of the error message.
+
+
+@node Equivalence
+@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
+@cindex Equivalence, indicating
+@findex equiv
+
+Sometimes two expressions produce identical results.  You can indicate the
+exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
+
+@iftex
+The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
+HTML and as @samp{@equiv{}} in the printed output.
+@end iftex
+@ifnottex
+The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
+and HTML and as a standard mathematical equivalence sign (three
+parallel horizontal lines) in the printed output.
+@end ifnottex
+
+Thus,
+
+@example
+@@lisp
+(make-sparse-keymap) @@equiv@{@} (list 'keymap)
+@@end lisp
+@end example
+
+@noindent
+produces
+
+@lisp
+(make-sparse-keymap) @equiv{} (list 'keymap)
+@end lisp
+
+@noindent
+This indicates that evaluating @code{(make-sparse-keymap)} produces
+identical results to evaluating @code{(list 'keymap)}.
+
+
+@node Point Glyph
+@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
+@cindex Point, indicating in a buffer
+@findex point
+
+Sometimes you need to show an example of text in an XEmacs 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.@refill
+
+You can use the @samp{@@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 @emph{between}
+two characters where point is located.)@refill
+
+@iftex
+The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
+HTML and as @samp{@point{}} in the printed output.
+@end iftex
+@ifnottex
+The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
+and HTML and as a small five pointed star in the printed
+output.
+@end ifnottex
+
+The following example shows the contents of buffer @file{foo} before
+and after evaluating a Lisp command to insert the word @code{changed}.@refill
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the @point{}contents of foo.
+---------- Buffer: foo ----------
+
+@end group
+@end example
+
+@example
+@group
+(insert "changed ")
+    @result{} nil
+---------- Buffer: foo ----------
+This is the changed @point{}contents of foo.
+---------- Buffer: foo ----------
+
+@end group
+@end example
+
+In a Texinfo source file, the example is written like this:@refill
+
+@example
+@@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
+@end example
+
+
+@node Breaks
+@chapter Forcing and Preventing Breaks
+@cindex Forcing line and page breaks
+@cindex Making line and page breaks
+@cindex Preventing line and page breaks
+
+@cindex Line 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.
+
+@cindex White space, excessive
+@cindex Page breaks
+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::              Summary of break-related commands.
+* Line Breaks::                 Forcing line breaks.
+* - and hyphenation::           Helping @TeX{} with hyphenation points.
+* allowcodebreaks::             Controlling line breaks within @@code text.
+* w::                           Preventing unwanted line breaks in text.
+* tie::                         Inserting an unbreakable but varying space.
+* sp::                          Inserting blank lines.
+* page::                        Forcing the start of a new page.
+* group::                       Preventing unwanted page breaks.
+* need::                        Another way to prevent unwanted page breaks.
+@end menu
+
+
+@node Break Commands
+@section Break Commands
+
+The break commands create or allow line and paragraph breaks:
+
+@table @code
+@item @@*
+Force a line break.
+
+@item @@sp @var{n}
+Skip @var{n} blank lines.
+
+@item @@-
+Insert a discretionary hyphen.
+
+@item @@hyphenation@{@var{hy-phen-a-ted words}@}
+Define hyphen points in @var{hy-phen-a-ted words}.
+@end table
+
+These commands hold text together on a single line:
+
+@table @code
+@item @@w@{@var{text}@}
+Prevent @var{text} from being split and hyphenated across two lines.
+@item @@tie@{@}
+Insert a normal interword space at which a line break may not occur.
+@end table
+@iftex
+@sp 1
+@end iftex
+
+The pagination commands apply only to printed output, since Info
+files do not have pages.
+
+@table @code
+@item @@page
+Start a new page in the printed manual.
+
+@item @@group
+Hold text together that must appear on one printed page.
+
+@item @@need @var{mils}
+Start a new printed page if not enough space on this one.
+@end table
+
+
+@node Line Breaks
+@section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks
+@findex * @r{(force line break)}
+@findex / @r{(allow line break)}
+@cindex Line breaks
+@cindex Breaks in a line
+@cindex Force line break
+@cindex Allow line break
+
+The @code{@@*} command forces a line break in both the printed manual and
+in Info.  The @code{@@/} command allows a line break (printed manual only).
+
+Here is an example with @code{@@*}:
+
+@example
+This line @@* is broken @@*in two places.
+@end example
+
+@noindent produces
+
+@example
+@group
+This line
+is broken
+in two places.
+@end group
+@end example
+
+The @code{@@/} command can be useful within a url
+(@pxref{uref,,@code{@@uref}}), which tend to be long and are otherwise
+unbreakable.  For example:
+
+@example
+The official Texinfo home page is on the GNU web site:
+@@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}.
+@end example
+
+@noindent produces
+
+@display
+The official Texinfo home page is on the GNU web site:
+@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}.
+@end display
+
+@noindent Without the @code{@@/} commands, @TeX{} would have nowhere to
+break the line.  @code{@@/} has no effect in the online output.
+
+
+@node - and hyphenation
+@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate
+
+@findex - @r{(discretionary hyphen)}
+@findex hyphenation
+@cindex Hyphenation, helping @TeX{} do
+@cindex Fine-tuning, and hyphenation
+
+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:
+
+@table @code
+@item @@-
+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 (@pxref{Overfull
+hboxes}).  @TeX{} will not insert any hyphenation points itself into a
+word containing @code{@@-}.
+
+@item @@hyphenation@{@var{hy-phen-a-ted words}@}
+Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}.  As shown, you
+put a @samp{-} at each hyphenation point.  For example:
+@example
+@@hyphenation@{man-u-script man-u-scripts@}
+@end example
+@noindent @TeX{} only uses the specified hyphenation points when the
+words match exactly, so give all necessary variants, such as plurals.
+@end table
+
+Info, HTML, and other non-@TeX{} output is not hyphenated, so none of
+these commands have any effect there.
+
+
+@node allowcodebreaks
+@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code}
+
+@findex allowcodebreaks
+@cindex Breaks, within @code{@@code}
+@cindex -, breakpoint within @code{@@code}
+@cindex Hyphen, breakpoint within @code{@@code}
+@cindex Dash, breakpoint within @code{@@code}
+@cindex _, breakpoint within @code{@@code}
+@cindex Underscore, breakpoint within @code{@@code}
+
+Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
+@samp{_} characters within @code{@@code} and related commands
+(@pxref{code,,@code{@@code}}), more or less as if they were ``empty''
+hyphenation points.
+
+This is necessary as many manuals, especially for Lisp-family
+languages, must document very long identifiers.  On the other hand,
+other manuals don't have this problems, and you may not wish to allow
+a line break at the underscore in, for example, @code{SIZE_MAX}, or
+even worse, after any of the four underscores in @code{__typeof__}.
+
+So Texinfo provides this command:
+
+@example
+@@allowcodebreaks false
+@end example
+
+@noindent to prevent @TeX{} from breaking at @samp{-} or @samp{_} within
+@code{@@code}.  You can go back to allowing such breaks with
+@code{@@allowcodebreaks true}.  Write these commands on lines by
+themselves.
+
+These commands can be given anywhere in the document.  For example,
+you may have just one problematic paragraph where you need to turn off
+the breaks, but want them in general, or vice versa.
+
+This command has no effect in Info, HTML, and other non-@TeX{} output.
+
+
+@node w
+@section @code{@@w}@{@var{text}@}: Prevent Line Breaks
+@findex w @r{(prevent line break)}
+@cindex Line breaks, preventing
+
+@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
+within @var{text}, for both @TeX{} and @command{makeinfo}.
+
+@cindex Non-breakable space, fixed
+@cindex Unbreakable space, fixed
+Thus, you can use @code{@@w} to produce a non-breakable space, fixed at
+the width of a normal interword space:
+
+@example
+@@w@{ @} @@w@{ @} @@w@{ @} indentation.
+@end example
+
+@noindent produces:
+
+@display
+@w{ } @w{ } @w{ } indentation.
+@end display
+
+The space from @code{@@w@{@w{ }@}}, as well as being non-breakable,
+also will not stretch or shrink.  Sometimes that is what you want, for
+instance if you're doing manual indenting.  However, usually you want
+a normal interword space that does stretch and shrink (in the printed
+output); see the @code{@@tie} command in the next section.
+
+@cindex Hyphenation, preventing
+You can also use the @code{@@w} command to prevent @TeX{} from
+automatically hyphenating a long name or phrase that happens to fall
+near the end of a line.  @command{makeinfo} does not ever hyphenate
+words.
+
+@cindex Keyword expansion, preventing
+@cindex Version control keywords, preventing expansion of
+@cindex $Id expansion, preventing
+You can also use @code{@@w} to avoid unwanted keyword expansion in
+source control systems.  For example, to literally write @t{@w{$}Id$}
+in your document, use @code{@@w@{$@}Id$}.
+
+
+@node tie
+@section @code{@@tie@{@}}: Inserting an Unbreakable Space
+@findex tie @r{(unbreakable interword space)}
+@cindex Tied space
+@cindex Non-breakable space, variable
+@cindex Unbreakable space, variable
+
+The @code{@@tie@{@}} command produces a normal interword space at which
+a line break may not occur.  Always write it with following (empty)
+braces, as usual for commands used within a paragraph.  Here's an
+example:
+
+@example
+@@TeX@{@} was written by Donald E.@@tie@{@}Knuth.
+@end example
+
+@noindent produces:
+
+@display
+@TeX{} was written by Donald E.@tie{}Knuth.
+@end display
+
+There are two important differences between @code{@@tie@{@}} and
+@code{@@w@{@w{ }@}}:
+
+@itemize
+@item
+The space produced by @code{@@tie@{@}} will stretch and shrink slightly
+along with the normal interword spaces in the paragraph; the space
+produced by @code{@@w@{@w{ }@}} will not vary.
+
+@item
+@code{@@tie@{@}} allows hyphenation of the surrounding words, while
+@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical
+reasons, namely that it produces an @samp{\hbox}).
+
+@end itemize
+
+
+@node sp
+@section @code{@@sp} @var{n}: Insert Blank Lines
+@findex sp @r{(line spacing)}
+@cindex Space, inserting vertical
+@cindex Blank lines
+@cindex Line spacing
+
+A line beginning with and containing only @code{@@sp @var{n}}
+generates @var{n} blank lines of space in both the printed manual and
+the Info file.  @code{@@sp} also forces a paragraph break.  For
+example,
+
+@example
+@@sp 2
+@end example
+
+@noindent
+generates two blank lines.
+
+The @code{@@sp} command is most often used in the title page.@refill
+
+@ignore
+@c node br, page, sp, Breaks
+@comment  node-name,  next,  previous,  up
+@c section @code{@@br}: Generate Paragraph Breaks
+@findex br @r{(paragraph breaks)}
+@cindex Paragraph breaks
+@cindex Breaks in a paragraph
+
+The @code{@@br} command forces a paragraph break.  It inserts a blank
+line.  You can use the command within or at the end of a line.  If
+used within a line, the @code{@@br@{@}} command must be followed by
+left and right braces (as shown here) to mark the end of the
+command.@refill
+
+@need 700
+For example,
+
+@example
+@group
+This line @@br@{@}contains and is ended by paragraph breaks@@br
+and is followed by another line.
+@end group
+@end example
+
+@noindent
+produces
+
+@example
+@group
+This line
+
+contains and is ended by paragraph breaks
+
+and is followed by another line.
+@end group
+@end example
+
+The @code{@@br} command is seldom used.
+@end ignore
+
+
+@node page
+@section @code{@@page}: Start a New Page
+@cindex Page breaks
+@findex page
+
+A line containing only @code{@@page} starts a new page in a printed
+manual.  The command has no effect on Info files since they are not
+paginated.  An @code{@@page} command is often used in the @code{@@titlepage}
+section of a Texinfo file to start the copyright page.
+
+
+@node group
+@comment  node-name,  next,  previous,  up
+@section @code{@@group}: Prevent Page Breaks
+@cindex Group (hold text together vertically)
+@cindex Holding text together vertically
+@cindex Vertically holding text together
+@findex group
+
+The @code{@@group} command (on a line by itself) is used inside an
+@code{@@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 @code{@@end group}.
+These two lines produce no output of their own, and in the Info file
+output they have no effect at all.@refill
+
+@c Once said that these environments
+@c turn off vertical spacing between ``paragraphs''.
+@c Also, quotation used to work, but doesn't in texinfo-2.72
+Although @code{@@group} would make sense conceptually in a wide
+variety of contexts, its current implementation works reliably only
+within @code{@@example} and variants, and within @code{@@display},
+@code{@@format}, @code{@@flushleft} and @code{@@flushright}.
+@xref{Quotations and Examples}.  (What all these commands have in
+common is that each line of input produces a line of output.)  In
+other contexts, @code{@@group} can cause anomalous vertical
+spacing.@refill
+
+@need 750
+This formatting requirement means that you should write:
+
+@example
+@group
+@@example
+@@group
+@dots{}
+@@end group
+@@end example
+@end group
+@end example
+
+@noindent
+with the @code{@@group} and @code{@@end group} commands inside the
+@code{@@example} and @code{@@end example} commands.
+
+The @code{@@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 @code{@@group} and @code{@@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
+@code{@@end group} if you get incomprehensible error messages in
+@TeX{}.@refill
+
+@node need
+@comment  node-name,  next,  previous,  up
+@section @code{@@need @var{mils}}: Prevent Page Breaks
+@cindex Need space at page bottom
+@findex need
+
+A line containing only @code{@@need @var{n}} starts
+a new page in a printed manual if fewer than @var{n} mils (thousandths
+of an inch) remain on the current page.  Do not use
+braces around the argument @var{n}.  The @code{@@need} command has no
+effect on Info files since they are not paginated.@refill
+
+@need 800
+This paragraph is preceded by an @code{@@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:@refill
+
+@example
+@group
+@@need 800
+This paragraph is preceded by @dots{}
+@end group
+@end example
+
+The @code{@@need} command is useful for preventing orphans (single
+lines at the bottoms of printed pages).@refill
+
+
+@node Definition Commands
+@chapter Definition Commands
+@cindex Definition commands
+
+The @code{@@deffn} command and the other @dfn{definition commands}
+enable you to describe functions, variables, macros, commands, user
+options, special forms and other such artifacts in a uniform
+format.@refill
+
+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:
+@code{@@deffn} enters the name into the index of functions,
+@code{@@defvr} enters it into the index of variables, and so
+on (@pxref{Predefined Indices}).
+
+A manual need not and should not contain more than one definition for
+a given name.  An appendix containing a summary should use
+@code{@@table} rather than the definition commands.@refill
+
+@menu
+* Def Cmd Template::            Writing descriptions using definition commands.
+* Def Cmd Continuation Lines::  Continuing the heading over source lines.
+* Optional Arguments::          Handling optional and repeated arguments.
+* deffnx::                      Group two or more `first' lines.
+* Def Cmds in Detail::          Reference for all the definition commands.
+* Def Cmd Conventions::         Conventions for writing definitions.
+* Sample Function Definition::  An example.
+@end menu
+
+
+@node Def Cmd Template
+@section The Template for a Definition
+@cindex Definition template
+@cindex Template for a definition
+
+The @code{@@deffn} command is used for definitions of entities that
+resemble functions.  To write a definition using the @code{@@deffn}
+command, write the @code{@@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 @code{@@end deffn} command
+written on a line of its own.
+
+The other definition commands follow the same format: a line with the
+@code{@@def@dots{}} command and whatever arguments are appropriate for
+that command; the body of the definition; and a corresponding
+@code{@@end} line.
+
+The template for a definition looks like this:
+
+@example
+@group
+@@deffn @var{category} @var{name} @var{arguments}@dots{}
+@var{body-of-definition}
+@@end deffn
+@end group
+@end example
+
+@need 700
+@noindent
+For example,
+
+@example
+@group
+@@deffn Command forward-word count
+This command moves point forward @@var@{count@} words
+(or backward if @@var@{count@} is negative). @dots{}
+@@end deffn
+@end group
+@end example
+
+@noindent
+produces
+
+@quotation
+@deffn Command forward-word count
+This command moves point forward @var{count} words
+(or backward if @var{count} is negative). @dots{}
+@end deffn
+@end quotation
+
+Capitalize the category name like a title.  If the name of the
+category contains spaces, as in the phrase `Interactive Command',
+enclose it in braces.  For example:
+
+@example
+@group
+@@deffn @{Interactive Command@} isearch-forward
+@dots{}
+@@end deffn
+@end group
+@end example
+
+@noindent
+Otherwise, the second word will be mistaken for the name of the
+entity.  As a general rule, when any of the arguments in the heading
+line @emph{except} the last one are more than one word, you need to
+enclose them in braces.  This may also be necessary if the text
+contains commands, for example, @samp{@{declaraci@@'on@}} if you are
+writing in Spanish.
+
+Some of the definition commands are more general than others.  The
+@code{@@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.  Three predefined, specialized variations
+(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the
+category for you: ``Function'', ``Macro'', and ``Special Form''
+respectively.  (In Lisp, a special form is an entity much like a
+function.)  Similarly, the general @code{@@defvr} command is
+accompanied by several specialized variations for describing
+particular kinds of variables.
+
+@xref{Sample Function Definition}, for a detailed example of a
+function definition, including the use of @code{@@example} inside the
+definition.
+
+@cindex Macros in definition commands
+Unfortunately, due to implementation difficulties, macros are not expanded
+in @code{@@deffn} and all the other definition commands.
+
+
+@node Def Cmd Continuation Lines
+@section Definition Command Continuation Lines
+@cindex Continuation lines in definition commands
+@cindex Definition command headings, continuing
+@cindex @samp{@@} as continuation in definition commands
+
+The heading line of a definition command can get very long.
+Therefore, Texinfo has a special syntax allowing them to be continued
+over multiple lines of the source file: a lone @samp{@@} at the end of
+each line to be continued.  Here's an example:
+
+@example
+@@defun fn-name @@
+  arg1 arg2 arg3
+This is the basic continued defun.
+@@end defun
+@end example
+
+@noindent produces:
+
+@defun fn-name @
+  arg1 arg2 arg3
+This is the basic continued defun.
+@end defun
+
+@noindent
+As you can see, the continued lines are combined, as if they had been
+typed on one source line.
+
+Although this example only shows a one-line continuation,
+continuations may extend over any number of lines; simply put an
+@code{@@} at the end of each line to be continued.
+
+The @code{@@} character does not have to be the last character on the
+physical line: whitespace is allowed (and ignored) afterwards.
+
+@cindex Whitespace, collapsed around continuations
+@cindex Collapsing whitespace around continuations
+In general, any number of spaces or tabs around the @code{@@}
+continuation character, both on the line with the @code{@@} and on the
+continued line, are collapsed into a single space.  There is one
+exception: the Texinfo processors will not fully collapse whitespace
+around a continuation inside braces.  For example:
+
+@example
+@@deffn @{Category @@
+  Name@} @dots{}
+@end example
+
+@noindent The output (not shown) has excess space between `Category'
+and `Name'.  In this case, simply elide any unwanted whitespace in
+your input, or put the continuation @code{@@} outside braces.
+
+@code{@@} does not (currently) function as a continuation character in
+@emph{any} other context.  Ordinarily, @samp{@@} followed by a
+whitespace character (space, tab, newline) produces a normal interword
+space (@pxref{Multiple Spaces}).
+
+
+@node Optional Arguments
+@section Optional and Repeated Arguments
+@cindex Optional and repeated arguments
+@cindex Repeated and optional arguments
+@cindex Arguments, repeated and optional
+@cindex Syntax, optional & repeated arguments
+@cindex Meta-syntactic chars for arguments
+
+Some entities take optional or repeated arguments, which may be
+specified by a distinctive glyph that uses square brackets and
+ellipses.  For @w{example}, a special form often breaks its argument list
+into separate arguments in more complicated ways than a
+straightforward function.
+
+@c This is consistent with XEmacs Lisp Reference manual
+An argument enclosed within square brackets is optional.
+Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
+An argument followed by an ellipsis is optional
+and may be repeated more than once.
+@c This is consistent with XEmacs Lisp Reference manual
+Thus, @var{repeated-args}@samp{@dots{}} stands for zero or more
+arguments.  Parentheses are used when several arguments are grouped
+into additional levels of list structure in Lisp.
+
+Here is the @code{@@defspec} line of an example of an imaginary
+special form:
+
+@quotation
+@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
+@end defspec
+@tex
+\vskip \parskip
+@end tex
+@end quotation
+
+@noindent
+In this example, the arguments @var{from} and @var{to} are optional,
+but must both be present or both absent.  If they are present,
+@var{inc} may optionally be specified as well.  These arguments are
+grouped with the argument @var{var} into a list, to distinguish them
+from @var{body}, which includes all remaining elements of the
+form.@refill
+
+In a Texinfo source file, this @code{@@defspec} line is written like
+this (except it would not be split over two lines, as it is in this
+example).@refill
+
+@example
+@group
+@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
+    [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
+@end group
+@end example
+
+@noindent
+The function is listed in the Command and Variable Index under
+@samp{foobar}.@refill
+
+
+@node deffnx
+@section Two or More `First' Lines
+@cindex Two `First' Lines for @code{@@deffn}
+@cindex Grouping two definitions together
+@cindex Definitions grouped together
+@findex deffnx
+
+To create two or more `first' or header lines for a definition, follow
+the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
+The @code{@@deffnx} command works exactly like @code{@@deffn}
+except that it does not generate extra vertical white space between it
+and the preceding line.@refill
+
+@need 1000
+For example,
+
+@example
+@group
+@@deffn @{Interactive Command@} isearch-forward
+@@deffnx @{Interactive Command@} isearch-backward
+These two search commands are similar except @dots{}
+@@end deffn
+@end group
+@end example
+
+@noindent
+produces
+
+@deffn {Interactive Command} isearch-forward
+@deffnx {Interactive Command} isearch-backward
+These two search commands are similar except @dots{}
+@end deffn
+
+Each definition command has an `x' form: @code{@@defunx},
+@code{@@defvrx}, @code{@@deftypefunx}, etc.
+
+The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}).
+
+
+@node Def Cmds in Detail
+@section The Definition Commands
+
+Texinfo provides more than a dozen definition commands, all of which
+are described in this section.@refill
+
+The definition commands automatically enter the name of the entity in
+the appropriate index: for example, @code{@@deffn}, @code{@@defun},
+and @code{@@defmac} enter function names in the index of functions;
+@code{@@defvr} and @code{@@defvar} enter variable names in the index
+of variables.@refill
+
+Although the examples that follow mostly illustrate Lisp, the commands
+can be used for other programming languages.@refill
+
+@menu
+* Functions Commands::          Commands for functions and similar entities.
+* Variables Commands::          Commands for variables and similar entities.
+* Typed Functions::             Commands for functions in typed languages.
+* Typed Variables::             Commands for variables in typed languages.
+* Data Types::                  The definition command for data types.
+* Abstract Objects::            Commands for object-oriented programming.
+@end menu
+
+@node Functions Commands
+@subsection Functions and Similar Entities
+
+This section describes the commands for describing functions and similar
+entities:@refill
+
+@table @code
+@findex deffn
+@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
+The @code{@@deffn} command is the general definition command for
+functions, interactive commands, and similar entities that may take
+arguments.  You must choose a term to describe the category of entity
+being defined; for example, ``Function'' could be used if the entity is
+a function.  The @code{@@deffn} command is written at the beginning of a
+line and is followed on the same line by the category of entity being
+described, the name of this particular entity, and its arguments, if
+any.  Terminate the definition with @code{@@end deffn} on a line of its
+own.@refill
+
+@need 750
+For example, here is a definition:
+
+@example
+@group
+@@deffn Command forward-char nchars
+Move point forward @@var@{nchars@} characters.
+@@end deffn
+@end group
+@end example
+
+@noindent
+This shows a rather terse definition for a ``command'' named
+@code{forward-char} with one argument, @var{nchars}.
+
+@code{@@deffn} and prints argument names such as @var{nchars} in slanted
+type in the printed output, because we think of these names as
+metasyntactic variables---they stand for the actual argument values.
+Within the text of the description, however, write an argument name
+explicitly with @code{@@var} to refer to the value of the argument.
+In the example above, we used @samp{@@var@{nchars@}} in this way.
+
+In the unusual case when an argument name contains @samp{--}, or
+another character sequence which is treated specially
+(@pxref{Conventions}), use @code{@@var} around the argument.  This
+causes the name to be printed in slanted typewriter, instead of the
+regular slanted font, exactly as input.
+@c except for ?` and !`, but we won't explain that.
+
+The template for @code{@@deffn} is:
+
+@example
+@group
+@@deffn @var{category} @var{name} @var{arguments}@dots{}
+@var{body-of-definition}
+@@end deffn
+@end group
+@end example
+
+@findex defun
+@item @@defun @var{name} @var{arguments}@dots{}
+The @code{@@defun} command is the definition command for functions.
+@code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}.
+Terminate the definition with @code{@@end defun} on a line of its own.
+Thus, the template is:
+
+@example
+@group
+@@defun @var{function-name} @var{arguments}@dots{}
+@var{body-of-definition}
+@@end defun
+@end group
+@end example
+
+@findex defmac
+@item @@defmac @var{name} @var{arguments}@dots{}
+The @code{@@defmac} command is the definition command for macros.
+@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
+works like @code{@@defun}.
+
+@findex defspec
+@item @@defspec @var{name} @var{arguments}@dots{}
+The @code{@@defspec} command is the definition command for special
+forms.  (In Lisp, a special form is an entity much like a function,
+@pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.)
+@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
+@dots{}} and works like @code{@@defun}.
+@end table
+
+All these commands create entries in the index of functions.
+
+
+@node Variables Commands
+@subsection Variables and Similar Entities
+
+Here are the commands for defining variables and similar
+entities:@refill
+
+@table @code
+@findex defvr
+@item @@defvr @var{category} @var{name}
+The @code{@@defvr} command is a general definition command for
+something like a variable---an entity that records a value.  You must
+choose a term to describe the category of entity being defined; for
+example, ``Variable'' could be used if the entity is a variable.
+Write the @code{@@defvr} command at the beginning of a line and
+follow it on the same line by the category of the entity and the
+name of the entity.
+
+Capitalize the category name like a title.  If the name of the category
+contains spaces, as in the name ``User Option'', enclose it in braces.
+Otherwise, the second word will be mistaken for the name of the entity.
+For example,
+
+@example
+@group
+@@defvr @{User Option@} fill-column
+This buffer-local variable specifies
+the maximum width of filled lines.
+@dots{}
+@@end defvr
+@end group
+@end example
+
+Terminate the definition with @code{@@end defvr} on a line of its
+own.@refill
+
+The template is:
+
+@example
+@group
+@@defvr @var{category} @var{name}
+@var{body-of-definition}
+@@end defvr
+@end group
+@end example
+
+@code{@@defvr} creates an entry in the index of variables for @var{name}.
+
+@findex defvar
+@item @@defvar @var{name}
+The @code{@@defvar} command is the definition command for variables.
+@code{@@defvar} is equivalent to @samp{@@defvr Variable
+@dots{}}.@refill
+
+@need 750
+For example:
+
+@example
+@group
+@@defvar kill-ring
+@dots{}
+@@end defvar
+@end group
+@end example
+
+The template is:
+
+@example
+@group
+@@defvar @var{name}
+@var{body-of-definition}
+@@end defvar
+@end group
+@end example
+
+@code{@@defvar} creates an entry in the index of variables for
+@var{name}.@refill
+
+@findex defopt
+@item @@defopt @var{name}
+@cindex User options, marking
+The @code{@@defopt} command is the definition command for @dfn{user
+options}, i.e., variables intended for users to change according to
+taste; XEmacs has many such (@pxref{Variables,,, xemacs, XEmacs User's
+Manual}).  @code{@@defopt} is equivalent to @samp{@@defvr @{User
+Option@} @dots{}} and works like @code{@@defvar}.  It creates an entry
+in the index of variables.
+@end table
+
+
+@node Typed Functions
+@subsection Functions in Typed Languages
+
+The @code{@@deftypefn} command and its variations are for describing
+functions in languages in which you must declare types of variables and
+functions, such as C and C++.
+
+@table @code
+@findex deftypefn
+@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
+The @code{@@deftypefn} command is the general definition command for
+functions and similar entities that may take arguments and that are
+typed.  The @code{@@deftypefn} command is written at the beginning of
+a line and is followed on the same line by the category of entity
+being described, the type of the returned value, the name of this
+particular entity, and its arguments, if any.@refill
+
+@need 800
+@noindent
+For example,
+
+@example
+@group
+@@deftypefn @{Library Function@} int foobar
+  (int @@var@{foo@}, float @@var@{bar@})
+@dots{}
+@@end deftypefn
+@end group
+@end example
+
+@need 1000
+@noindent
+(where the text before the ``@dots{}'', shown above as two lines, would
+actually be a single line in a real Texinfo file) produces the following
+in Info:
+
+@smallexample
+@group
+-- Library Function: int foobar (int FOO, float BAR)
+@dots{}
+@end group
+@end smallexample
+@iftex
+
+In a printed manual, it produces:
+
+@quotation
+@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
+@dots{}
+@end deftypefn
+@end quotation
+@end iftex
+
+This means that @code{foobar} is a ``library function'' that returns an
+@code{int}, and its arguments are @var{foo} (an @code{int}) and
+@var{bar} (a @code{float}).@refill
+
+Since in typed languages, the actual names of the arguments are
+typically scattered among data type names and keywords, Texinfo cannot
+find them without help.  You can either (a)@tie{}write everything
+as straight text, and it will be printed in slanted type; (b)@tie{}use
+@code{@@var} for the variable names, which will uppercase the
+variable names in Info and use the slanted typewriter font in printed
+output; (c)@tie{}use @code{@@var} for the variable names and
+@code{@@code} for the type names and keywords, which will be dutifully
+obeyed.
+
+The template for @code{@@deftypefn} is:@refill
+
+@example
+@group
+@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
+@var{body-of-description}
+@@end deftypefn
+@end group
+@end example
+
+@noindent
+Note that if the @var{category} or @var{data type} is more than one
+word then it must be enclosed in braces to make it a single argument.@refill
+
+If you are describing a procedure in a language that has packages,
+such as Ada, you might consider using @code{@@deftypefn} in a manner
+somewhat contrary to the convention described in the preceding
+paragraphs.  For example:
+
+@example
+@group
+@@deftypefn stacks private push @@
+       (@@var@{s@}:in out stack; @@
+       @@var@{n@}:in integer)
+@dots{}
+@@end deftypefn
+@end group
+@end example
+
+@noindent
+(The @code{@@deftypefn} arguments are shown using continuations
+(@pxref{Def Cmd Continuation Lines}), but could be on a single line in
+a real Texinfo file.)
+
+In this instance, the procedure is classified as belonging to the
+package @code{stacks} rather than classified as a `procedure' and its
+data type is described as @code{private}.  (The name of the procedure
+is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
+
+@code{@@deftypefn} creates an entry in the index of functions for
+@var{name}.
+
+@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
+@findex deftypefun
+The @code{@@deftypefun} command is the specialized definition command
+for functions in typed languages.  The command is equivalent to
+@samp{@@deftypefn Function @dots{}}.  The template is:
+
+@example
+@group
+@@deftypefun @var{type} @var{name} @var{arguments}@dots{}
+@var{body-of-description}
+@@end deftypefun
+@end group
+@end example
+
+@code{@@deftypefun} creates an entry in the index of functions for
+@var{name}.
+
+@end table
+
+
+@node Typed Variables
+@subsection Variables in Typed Languages
+
+Variables in typed languages are handled in a manner similar to
+functions in typed languages.  @xref{Typed Functions}.  The general
+definition command @code{@@deftypevr} corresponds to
+@code{@@deftypefn} and the specialized definition command
+@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
+
+@table @code
+@findex deftypevr
+@item @@deftypevr @var{category} @var{data-type} @var{name}
+The @code{@@deftypevr} command is the general definition command for
+something like a variable in a typed language---an entity that records
+a value.  You must choose a term to describe the category of the
+entity being defined; for example, ``Variable'' could be used if the
+entity is a variable.@refill
+
+The @code{@@deftypevr} command is written at the beginning of a line
+and is followed on the same line by the category of the entity
+being described, the data type, and the name of this particular
+entity.@refill
+
+@need 800
+@noindent
+For example:
+
+@example
+@group
+@@deftypevr @{Global Flag@} int enable
+@dots{}
+@@end deftypevr
+@end group
+@end example
+
+@noindent
+produces the following in Info:
+
+@example
+@group
+-- Global Flag: int enable
+@dots{}
+@end group
+@end example
+@iftex
+
+@noindent
+and the following in a printed manual:
+
+@quotation
+@deftypevr {Global Flag} int enable
+@dots{}
+@end deftypevr
+@end quotation
+@end iftex
+
+@need 800
+The template is:
+
+@example
+@@deftypevr @var{category} @var{data-type} @var{name}
+@var{body-of-description}
+@@end deftypevr
+@end example
+
+@findex deftypevar
+@item @@deftypevar @var{data-type} @var{name}
+The @code{@@deftypevar} command is the specialized definition command
+for variables in typed languages.  @code{@@deftypevar} is equivalent
+to @samp{@@deftypevr Variable @dots{}}.  The template is:
+
+@example
+@group
+@@deftypevar @var{data-type} @var{name}
+@var{body-of-description}
+@@end deftypevar
+@end group
+@end example
+@end table
+
+These commands create entries in the index of variables.
+
+@node Data Types
+@subsection Data Types
+
+Here is the command for data types:@refill
+
+@table @code
+@findex deftp
+@item @@deftp @var{category} @var{name} @var{attributes}@dots{}
+The @code{@@deftp} command is the generic definition command for data
+types.  The command is written at the beginning of a line and is
+followed on the same line by the category, by the name of the type
+(which is a word like @code{int} or @code{float}), and then by names of
+attributes of objects of that type.  Thus, you could use this command
+for describing @code{int} or @code{float}, in which case you could use
+@code{data type} as the category.  (A data type is a category of
+certain objects for purposes of deciding which operations can be
+performed on them.)@refill
+
+In Lisp, for example,  @dfn{pair} names a particular data
+type, and an object of that type has two slots called the
+@sc{car} and the @sc{cdr}.  Here is how you would write the first line
+of a definition of @code{pair}.@refill
+
+@example
+@group
+@@deftp @{Data type@} pair car cdr
+@dots{}
+@@end deftp
+@end group
+@end example
+
+@need 950
+The template is:
+
+@example
+@group
+@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
+@var{body-of-definition}
+@@end deftp
+@end group
+@end example
+
+@code{@@deftp} creates an entry in the index of data types.
+@end table
+
+
+@node Abstract Objects
+@subsection Object-Oriented Programming
+
+@cindex Object-oriented programming
+
+Here are the commands for formatting descriptions about abstract
+objects, such as are used in object-oriented programming.  A class is
+a defined type of abstract object.  An instance of a class is a
+particular object that has the type of the class.  An instance
+variable is a variable that belongs to the class but for which each
+instance has its own value.
+
+@menu
+* Variables: Object-Oriented Variables.
+* Methods: Object-Oriented Methods.
+@end menu
+
+
+@node Object-Oriented Variables
+@subsubsection Object-Oriented Variables
+
+@cindex Variables, object-oriented
+
+These commands allow you to define different sorts of variables in
+object-oriented programming languages.
+
+@table @code
+@item @@defcv @var{category} @var{class} @var{name}
+@findex defcv
+The @code{@@defcv} command is the general definition command for
+variables associated with classes in object-oriented programming.  The
+@code{@@defcv} command is followed by three arguments: the category of
+thing being defined, the class to which it belongs, and its
+name.  For instance:
+
+@example
+@group
+@@defcv @{Class Option@} Window border-pattern
+@dots{}
+@@end defcv
+@end group
+@end example
+
+@noindent produces:
+@defcv {Class Option} Window border-pattern
+@dots{}
+@end defcv
+
+@code{@@defcv} creates an entry in the index of variables.
+
+@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
+@findex deftypecv
+The @code{@@deftypecv} command is the definition command for typed
+class variables in object-oriented programming.  It is analogous to
+@code{@@defcv} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable.  Ordinarily, the data type
+is a programming language construct that should be marked with
+@code{@@code}. For instance:
+
+@example
+@group
+@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern
+@dots{}
+@@end deftypecv
+@end group
+@end example
+
+@noindent produces:
+
+@deftypecv {Class Option} Window @code{int} border-pattern
+@dots{}
+@end deftypecv
+
+@code{@@deftypecv} creates an entry in the index of variables.
+
+@item @@defivar @var{class} @var{name}
+@findex defivar
+The @code{@@defivar} command is the definition command for instance
+variables in object-oriented programming.  @code{@@defivar} is
+equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}.  For
+instance:
+
+@example
+@group
+@@defivar Window border-pattern
+@dots{}
+@@end defivar
+@end group
+@end example
+
+@noindent produces:
+
+@defivar Window border-pattern
+@dots{}
+@end defivar
+
+@code{@@defivar} creates an entry in the index of variables.
+
+@item @@deftypeivar @var{class} @var{data-type} @var{name}
+@findex deftypeivar
+The @code{@@deftypeivar} command is the definition command for typed
+instance variables in object-oriented programming.  It is analogous to
+@code{@@defivar} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable.  Ordinarily, the data type
+is a programming language construct that should be marked with
+@code{@@code}. For instance:
+
+@example
+@group
+@@deftypeivar Window @@code@{int@} border-pattern
+@dots{}
+@@end deftypeivar
+@end group
+@end example
+
+@noindent produces:
+
+@deftypeivar Window @code{int} border-pattern
+@dots{}
+@end deftypeivar
+
+@code{@@deftypeivar} creates an entry in the index of variables.
+
+@end table
+
+@node Object-Oriented Methods
+@subsubsection Object-Oriented Methods
+
+@cindex Methods, object-oriented
+
+These commands allow you to define different sorts of function-like
+entities resembling methods in object-oriented programming languages.
+These entities take arguments, as functions do, but are associated with
+particular classes of objects.
+
+@table @code
+
+@findex defop
+@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
+The @code{@@defop} command is the general definition command for these
+method-like entities.
+
+For example, some systems have constructs called @dfn{wrappers} that
+are associated with classes as methods are, but that act more like
+macros than like functions.  You could use @code{@@defop Wrapper} to
+describe one of these.@refill
+
+Sometimes it is useful to distinguish methods and @dfn{operations}.
+You can think of an operation as the specification for a method.
+Thus, a window system might specify that all window classes have a
+method named @code{expose}; we would say that this window system
+defines an @code{expose} operation on windows in general.  Typically,
+the operation has a name and also specifies the pattern of arguments;
+all methods that implement the operation must accept the same
+arguments, since applications that use the operation do so without
+knowing which method will implement it.@refill
+
+Often it makes more sense to document operations than methods.  For
+example, window application developers need to know about the
+@code{expose} operation, but need not be concerned with whether a
+given class of windows has its own method to implement this operation.
+To describe this operation, you would write:@refill
+
+@example
+@@defop Operation windows expose
+@end example
+
+The @code{@@defop} command is written at the beginning of a line and
+is followed on the same line by the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if any.@refill
+
+The template is:
+@example
+@group
+@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
+@var{body-of-definition}
+@@end defop
+@end group
+@end example
+
+@code{@@defop} creates an entry, such as `@code{expose} on
+@code{windows}', in the index of functions.@refill
+
+@findex deftypeop
+@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
+The @code{@@deftypeop} command is the definition command for typed
+operations in object-oriented programming.  It is similar to
+@code{@@defop} with the addition of the @var{data-type} parameter to
+specify the return type of the method.  @code{@@deftypeop} creates an
+entry in the index of functions.
+
+@item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
+@findex defmethod
+The @code{@@defmethod} command is the definition command for methods
+in object-oriented programming.  A method is a kind of function that
+implements an operation for a particular class of objects and its
+subclasses.
+@ignore
+@c ADR: Who cares?!?
+@c KB: Oh, I don't know, I think this info is crucial!
+In the Lisp Machine, methods actually were functions, but
+they were usually defined with @code{defmethod}.
+@end ignore
+
+@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
+The command is written at the beginning of a line and is followed by
+the name of the class of the method, the name of the method, and its
+arguments, if any.@refill
+
+@noindent
+For example:
+@example
+@group
+@@defmethod @code{bar-class} bar-method argument
+@dots{}
+@@end defmethod
+@end group
+@end example
+
+@noindent
+illustrates the definition for a method called @code{bar-method} of
+the class @code{bar-class}.  The method takes an argument.
+
+@code{@@defmethod} creates an entry in the index of functions.
+
+@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
+@findex defmethod
+The @code{@@deftypemethod} command is the definition command for methods
+in object-oriented typed languages, such as C++ and Java.  It is similar
+to the @code{@@defmethod} command with the addition of the
+@var{data-type} parameter to specify the return type of the method.
+@code{@@deftypemethod} creates an entry in the index of functions.
+
+@end table
+
+
+@node Def Cmd Conventions
+@section Conventions for Writing Definitions
+@cindex Definition conventions
+@cindex Conventions for writing definitions
+
+When you write a definition using @code{@@deffn}, @code{@@defun}, or
+one of the other definition commands, please take care to use
+arguments that indicate the meaning, as with the @var{count} argument
+to the @code{forward-word} function.  Also, if the name of an argument
+contains the name of a type, such as @var{integer}, take care that the
+argument actually is of that type.@refill
+
+
+@node Sample Function Definition
+@section A Sample Function Definition
+@cindex Function definitions
+@cindex Command definitions
+@cindex Macro definitions
+@cindex Sample function definition
+
+A function definition uses the @code{@@defun} and @code{@@end defun}
+commands.  The name of the function follows immediately after the
+@code{@@defun} command and it is followed, on the same line, by the
+parameter list.@refill
+
+Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp
+Reference Manual}.
+
+@quotation
+@defun apply function &rest arguments
+@code{apply} calls @var{function} with @var{arguments}, just
+like @code{funcall} but with one difference: the last of
+@var{arguments} is a list of arguments to give to
+@var{function}, rather than a single argument.  We also say
+that this list is @dfn{appended} to the other arguments.
+
+@code{apply} returns the result of calling @var{function}.
+As with @code{funcall}, @var{function} must either be a Lisp
+function or a primitive function; special forms and macros
+do not make sense in @code{apply}.
+
+@example
+(setq f 'list)
+    @result{} list
+(apply f 'x 'y 'z)
+@error{} Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+    @result{} 10
+(apply '+ '(1 2 3 4))
+    @result{} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+    @result{} (a b c x y z)
+@end example
+
+An interesting example of using @code{apply} is found in the description
+of @code{mapcar}.@refill
+@end defun
+@end quotation
+
+@need 1200
+In the Texinfo source file, this example looks like this:
+
+@example
+@group
+@@defun apply function &rest arguments
+@@code@{apply@} calls @@var@{function@} with
+@@var@{arguments@}, just like @@code@{funcall@} but with one
+difference: the last of @@var@{arguments@} is a list of
+arguments to give to @@var@{function@}, rather than a single
+argument.  We also say that this list is @@dfn@{appended@}
+to the other arguments.
+@end group
+
+@group
+@@code@{apply@} returns the result of calling
+@@var@{function@}.  As with @@code@{funcall@},
+@@var@{function@} must either be a Lisp function or a
+primitive function; special forms and macros do not make
+sense in @@code@{apply@}.
+@end group
+
+@group
+@@example
+(setq f 'list)
+    @@result@{@} list
+(apply f 'x 'y 'z)
+@@error@{@} Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+    @@result@{@} 10
+(apply '+ '(1 2 3 4))
+    @@result@{@} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+    @@result@{@} (a b c x y z)
+@@end example
+@end group
+
+@group
+An interesting example of using @@code@{apply@} is found
+in the description of @@code@{mapcar@}.
+@@end defun
+@end group
+@end example
+
+@noindent
+In this manual, this function is listed in the Command and Variable
+Index under @code{apply}.@refill
+
+Ordinary variables and user options are described using a format like
+that for functions except that variables do not take arguments.
+
+
+@node Conditionals
+@chapter Conditionally Visible Text
+@cindex Conditionally visible text
+@cindex Text, conditionally visible
+@cindex Visibility of conditional text
+@cindex If text conditionally visible
+
+The @dfn{conditional commands} allow you to use different text for
+different output formats, or for general conditions that you define.
+For example, you can use them to specify different text for the
+printed manual and the Info output.
+
+The conditional commands comprise the following categories.
+
+@itemize @bullet
+@item
+Commands specific to an output format (Info, @TeX{}, HTML, @dots{}).
+
+@item
+Commands specific to any output format @emph{other} than a given
+one (not Info, not @TeX{}, @dots{}).
+
+@item
+`Raw' formatter text for any output format, passed straight
+through with no interpretation of @@-commands.
+
+@item
+Format-independent variable substitutions, and testing if a variable
+is set or clear.
+
+@end itemize
+
+@menu
+* Conditional Commands::        Text for a given format.
+* Conditional Not Commands::    Text for any format other than a given one.
+* Raw Formatter Commands::      Using raw formatter commands.
+* set clear value::             Variable tests and substitutions.
+* Conditional Nesting::         Using conditionals inside conditionals.
+@end menu
+
+
+@node Conditional Commands
+@section Conditional Commands
+
+Texinfo has an @code{@@if@var{format}} environment for each output
+format, to allow conditional inclusion of text for a particular output
+format.
+
+@findex ifinfo
+@code{@@ifinfo} begins segments of text that should be ignored by
+@TeX{} when it typesets the printed manual, and by @command{makeinfo}
+when not producing Info output.  The segment of text appears only in
+the Info file and, for historical compatibility, the plain text
+output.
+
+@findex ifdocbook
+@findex ifhtml
+@findex ifplaintext
+@findex iftex
+@findex ifxml
+The environments for the other formats are analogous:
+
+@table @code
+@item @@ifdocbook @dots{} @@end ifdocbook
+Text to appear only in the Docbook output.
+
+@item @@ifhtml @dots{} @@end ifhtml
+Text to appear only in the HTML output.
+
+@item @@ifplaintext @dots{} @@end ifplaintext
+Text to appear only in the plain text output.
+
+@item @@iftex @dots{} @@end iftex
+Text to appear only in the printed manual.
+
+@item @@ifxml @dots{} @@end ifxml
+Text to appear only in the XML output.
+@end table
+
+The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear
+on lines by themselves in your source file.
+
+Here is an example showing all these conditionals:
+
+@example
+@@iftex
+This text will appear only in the printed manual.
+@@end iftex
+@@ifinfo
+However, this text will appear only in Info and plain text.
+@@end ifinfo
+@@ifhtml
+And this text will only appear in HTML.
+@@end ifhtml
+@@ifplaintext
+Whereas this text will only appear in plain text.
+@@end ifplaintext
+@@ifxml
+Notwithstanding that this will only appear in XML.
+@@end ifxml
+@@ifdocbook
+Nevertheless, this will only appear in Docbook.
+@@end ifdocbook
+@end example
+
+@noindent
+The preceding example produces the following line:
+
+@iftex
+This text will appear only in the printed manual.
+@end iftex
+@ifinfo
+However, this text will appear only in Info and plain text.
+@end ifinfo
+@ifhtml
+And this text will only appear in HTML.
+@end ifhtml
+@ifplaintext
+Whereas this text will only appear in plain text.
+@end ifplaintext
+@ifxml
+Notwithstanding that this will only appear in XML.
+@end ifxml
+@ifdocbook
+Nevertheless, this will only appear in Docbook.
+@end ifdocbook
+
+@noindent
+Notice that you only see one of the input lines, depending on which
+version of the manual you are reading.
+
+
+@node Conditional Not Commands
+@section Conditional Not Commands
+@findex ifnotdocbook
+@findex ifnothtml
+@findex ifnotinfo
+@findex ifnotplaintext
+@findex ifnottex
+@findex ifnotxml
+
+You can specify text to be included in any output format @emph{other}
+than a given one with the @code{@@ifnot@dots{}} environments:
+
+@example
+@@ifnotdocbook @dots{} @@end ifnotdocbook
+@@ifnothtml @dots{} @@end ifnothtml
+@@ifnotinfo @dots{} @@end ifnotinfo
+@@ifnotplaintext @dots{} @@end ifnotplaintext
+@@ifnottex @dots{} @@end ifnottex
+@@ifnotxml @dots{} @@end ifnotxml
+@end example
+
+@noindent
+The @code{@@ifnot@dots{}} command and the @code{@@end} command must
+appear on lines by themselves in your actual source file.
+
+If the output file is being made in the given format, the
+region is @emph{ignored}.  Otherwise, it is included.
+
+There is one exception (for historical compatibility):
+@code{@@ifnotinfo} text is omitted for both Info and plain text
+output, not just Info.  To specify text which appears only in Info and
+not in plain text, use @code{@@ifnotplaintext}, like this:
+
+@example
+@@ifinfo
+@@ifnotplaintext
+This will be in Info, but not plain text.
+@@end ifnotplaintext
+@@end ifinfo
+@end example
+
+The regions delimited by these commands are ordinary Texinfo source as
+with @code{@@iftex}, not raw formatter source as with @code{@@tex}
+(@pxref{Raw Formatter Commands}).
+
+
+@node Raw Formatter Commands
+@section Raw Formatter Commands
+@cindex Raw formatter commands
+@cindex @TeX{} commands, using ordinary
+@cindex Ordinary @TeX{} commands, using
+@cindex Commands using raw @TeX{}
+@cindex Docbook, including raw
+@cindex HTML, including raw
+@cindex XML, including raw
+@cindex Plain @TeX{}
+
+Inside a region delineated by @code{@@iftex} and @code{@@end iftex},
+you can embed some raw @TeX{} commands.  The Texinfo processors will
+ignore such a region unless @TeX{} output is being produced.  You can
+write the @TeX{} commands as you would write them in a normal @TeX{}
+file, except that you must replace the @samp{\} used by @TeX{} with an
+@samp{@@}.  For example, in the @code{@@titlepage} section of a
+Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
+the copyright page.  (The @code{@@titlepage} command causes Info to
+ignore the region automatically, as it does with the @code{@@iftex}
+command.)
+
+However, most features of plain @TeX{} will not work within
+@code{@@iftex}, as they are overridden by Texinfo features.  The
+purpose of @code{@@iftex} is to provide conditional processing for the
+Texinfo source, not provide access to underlying formatting features.
+
+@findex tex
+You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
+commands, by delineating a region with the @code{@@tex} and @code{@@end
+tex} commands.  All plain @TeX{} commands and category codes are
+restored within an @code{@@tex} region.  The sole exception is that the
+@code{@@} character still introduces a command, so that @code{@@end tex}
+can be recognized properly.  As with @code{@@iftex}, Texinfo
+processors will ignore such a region unless @TeX{} output is being produced.
+
+@findex \gdef @r{within @code{@@tex}}
+In complex cases, you may wish to define new @TeX{} macros within
+@code{@@tex}.  You must use @code{\gdef} to do this, not @code{\def},
+because @code{@@tex} regions are processed in a @TeX{} group.
+
+@cindex Mathematical expressions
+As an example, here is a mathematical expression written in plain @TeX{}:
+
+@example
+@@tex
+$$ \chi^2 = \sum_@{i=1@}^N
+         \left (y_i - (a + b x_i)
+         \over \sigma_i\right)^2 $$
+@@end tex
+@end example
+
+@noindent
+The output of this example will appear only in a printed manual.  If
+you are reading this in Info, you will not see the equation that appears
+in the printed manual.
+@iftex
+In a printed manual, the above expression looks like
+this:
+@end iftex
+
+@tex
+$$ \chi^2 = \sum_{i=1}^N
+         \left(y_i - (a + b x_i)
+         \over \sigma_i\right)^2 $$
+@end tex
+
+@findex ifhtml
+@findex html
+Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
+a region to be included in HTML output only, and @code{@@html @dots{}
+@@end html} for a region of raw HTML.
+
+@findex ifxml
+@findex xml
+Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit
+a region to be included in XML output only, and @code{@@xml @dots{}
+@@end xml} for a region of raw XML.
+
+@findex ifdocbook
+@findex docbook
+Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook}
+to delimit a region to be included in Docbook output only, and
+@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook.
+
+In all cases, the exception to the raw processing is that @code{@@} is
+still an escape character, so the @code{@@end} command can be
+recognized.
+
+
+@node set clear value
+@section @code{@@set}, @code{@@clear}, and @code{@@value}
+
+You can direct the Texinfo formatting commands to format or ignore parts
+of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
+and @code{@@ifclear} commands.
+
+Here are brief descriptions of these commands, see the following
+sections for more details:
+
+@table @code
+@item @@set @var{flag} [@var{value}]
+Set the variable @var{flag}, to the optional @var{value} if specified.
+
+@item @@clear @var{flag}
+Undefine the variable @var{flag}, whether or not it was previously defined.
+
+@item @@ifset @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifset} command
+is formatted.  If @var{flag} is clear, text through the following
+@code{@@end ifset} command is ignored.
+
+@item @@ifclear @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifclear} command
+is ignored.  If @var{flag} is clear, text through the following
+@code{@@end ifclear} command is formatted.
+@end table
+
+@menu
+* set value::                   Expand a flag variable to a string.
+* ifset ifclear::               Format a region if a flag is set.
+* value Example::               An easy way to update edition information.
+@end menu
+
+
+@node set value
+@subsection @code{@@set} and @code{@@value}
+@findex set
+@findex value
+@findex clear
+
+You use the @code{@@set} command to specify a value for a flag, which
+is later expanded by the @code{@@value} command.
+
+A @dfn{flag} (aka @dfn{variable}) is an identifier.  It is best to use
+only letters and numerals in a flag name, not @samp{-} or
+@samp{_}---they will work in some contexts, but not all, due to
+limitations in @TeX{}.
+
+The value is the remainder of the input line, and can contain anything.
+
+Write the @code{@@set} command like this:
+
+@example
+@@set foo This is a string.
+@end example
+
+@noindent
+This sets the value of the flag @code{foo} to ``This is a string.''.
+
+The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
+command with the string to which @var{flag} is set.  Thus, when
+@code{foo} is set as shown above, the Texinfo formatters convert this:
+
+@example
+@group
+@@value@{foo@}
+@exdent @r{to this:}
+This is a string.
+@end group
+@end example
+
+You can write an @code{@@value} command within a paragraph; but you
+must write an @code{@@set} command on a line of its own.
+
+If you write the @code{@@set} command like this:
+
+@example
+@@set foo
+@end example
+
+@noindent
+without specifying a string, the value of @code{foo} is the empty string.
+
+If you clear a previously set flag with @code{@@clear @var{flag}}, a
+subsequent @code{@@value@{flag@}} command will report an error.
+
+For example, if you set @code{foo} as follows:
+
+@example
+@@set howmuch very, very, very
+@end example
+
+@noindent
+then the formatters transform
+
+@example
+@group
+It is a @@value@{howmuch@} wet day.
+@exdent @r{into}
+It is a very, very, very wet day.
+@end group
+@end example
+
+If you write
+
+@example
+@@clear howmuch
+@end example
+
+@noindent
+then the formatters transform
+
+@example
+@group
+It is a @@value@{howmuch@} wet day.
+@exdent @r{into}
+It is a @{No value for "howmuch"@} wet day.
+@end group
+@end example
+
+
+@node ifset ifclear
+@subsection @code{@@ifset} and @code{@@ifclear}
+
+@findex ifset
+When a @var{flag} is set, the Texinfo formatting commands format text
+between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
+ifset} commands.  When the @var{flag} is cleared, the Texinfo formatting
+commands do @emph{not} format the text.  @code{@@ifclear} operates
+analogously.
+
+Write the conditionally formatted text between @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, like this:
+
+@example
+@group
+@@ifset @var{flag}
+@var{conditional-text}
+@@end ifset
+@end group
+@end example
+
+For example, you can create one document that has two variants, such as
+a manual for a `large' and `small' model:
+
+@cindex Shrubbery
+@example
+You can use this machine to dig up shrubs
+without hurting them.
+
+@@set large
+
+@@ifset large
+It can also dig up fully grown trees.
+@@end ifset
+
+Remember to replant promptly @dots{}
+@end example
+
+@noindent
+In the example, the formatting commands will format the text between
+@code{@@ifset large} and @code{@@end ifset} because the @code{large}
+flag is set.
+
+When @var{flag} is cleared, the Texinfo formatting commands do
+@emph{not} format the text between @code{@@ifset @var{flag}} and
+@code{@@end ifset}; that text is ignored and does not appear in either
+printed or Info output.
+
+For example, if you clear the flag of the preceding example by writing
+an @code{@@clear large} command after the @code{@@set large} command
+(but before the conditional text), then the Texinfo formatting commands
+ignore the text between the @code{@@ifset large} and @code{@@end ifset}
+commands.  In the formatted output, that text does not appear; in both
+printed and Info output, you see only the lines that say, ``You can use
+this machine to dig up shrubs without hurting them.  Remember to replant
+promptly @dots{}''.
+
+@findex ifclear
+If a flag is cleared with an @code{@@clear @var{flag}} command, then
+the formatting commands format text between subsequent pairs of
+@code{@@ifclear} and @code{@@end ifclear} commands.  But if the flag
+is set with @code{@@set @var{flag}}, then the formatting commands do
+@emph{not} format text between an @code{@@ifclear} and an @code{@@end
+ifclear} command; rather, they ignore that text.  An @code{@@ifclear}
+command looks like this:
+
+@example
+@@ifclear @var{flag}
+@end example
+
+
+@node value Example
+@subsection @code{@@value} Example
+
+You can use the @code{@@value} command to minimize the number of
+places you need to change when you record an update to a manual.
+@xref{GNU Sample Texts}, for the full text of an example of using this
+to work with Automake distributions.
+
+This example is adapted from @ref{Top,, Overview, make, The GNU Make
+Manual}.
+
+@enumerate
+@item
+Set the flags:
+
+@example
+@group
+@@set EDITION 0.35 Beta
+@@set VERSION 3.63 Beta
+@@set UPDATED 14 August 1992
+@@set UPDATE-MONTH August 1992
+@end group
+@end example
+
+@item
+Write text for the @code{@@copying} section (@pxref{copying}):
+
+@example
+@group
+@@copying
+This is Edition @@value@{EDITION@},
+last updated @@value@{UPDATED@},
+of @@cite@{The GNU Make Manual@},
+for @@code@{make@}, version @@value@{VERSION@}.
+
+Copyright @dots{}
+
+Permission is granted @dots{}
+@@end copying
+@end group
+@end example
+
+@item
+Write text for the title page, for people reading the printed manual:
+
+@example
+@group
+@@titlepage
+@@title GNU Make
+@@subtitle A Program for Directing Recompilation
+@@subtitle Edition @@value@{EDITION@}, @dots{}
+@@subtitle @@value@{UPDATE-MONTH@}
+@@page
+@@insertcopying
+@dots{}
+@@end titlepage
+@end group
+@end example
+
+@noindent
+(On a printed cover, a date listing the month and the year looks less
+fussy than a date listing the day as well as the month and year.)
+
+@item
+Write text for the Top node, for people reading the Info file:
+
+@example
+@group
+@@ifnottex
+@@node Top
+@@top Make
+
+@@insertcopying
+@dots{}
+@@end ifnottex
+@end group
+@end example
+
+After you format the manual, the @code{@@value} constructs have been
+expanded, so the output contains text like this:
+
+@example
+@group
+This is Edition 0.35 Beta, last updated 14 August 1992,
+of `The GNU Make Manual', for `make', Version 3.63 Beta.
+@end group
+@end example
+@end enumerate
+
+When you update the manual, you change only the values of the flags; you
+do not need to edit the three sections.
+
+
+@node Conditional Nesting
+@section Conditional Nesting
+@cindex Conditionals, nested
+@cindex Nesting conditionals
+
+Conditionals can be nested; however, the details are a little tricky.
+The difficulty comes with failing conditionals, such as
+@code{@@ifhtml} when HTML is not being produced, where the included
+text is to be ignored.  However, it is not to be @emph{completely}
+ignored, since it is useful to have one @code{@@ifset} inside another,
+for example---that is a way to include text only if two conditions are
+met.  Here's an example:
+
+@example
+@@ifset somevar
+@@ifset anothervar
+Both somevar and anothervar are set.
+@@end ifset
+@@ifclear anothervar
+Somevar is set, anothervar is not.
+@@end ifclear
+@@end ifset
+@end example
+
+Technically, Texinfo requires that for a failing conditional, the
+ignored text must be properly nested with respect to that failing
+conditional.  Unfortunately, it's not always feasible to check that
+@emph{all} conditionals are properly nested, because then the
+processors could have to fully interpret the ignored text, which
+defeats the purpose of the command.  Here's an example illustrating
+these rules:
+
+@example
+@@ifset a
+@@ifset b
+@@ifclear ok  - ok, ignored
+@@end junky   - ok, ignored
+@@end ifset
+@@c WRONG - missing @@end ifset.
+@end example
+
+Finally, as mentioned above, all conditional commands must be on lines
+by themselves, with no text (even spaces) before or after.  Otherwise,
+the processors cannot reliably determine which commands to consider
+for nesting purposes.
+
+
+@node Internationalization
+@chapter Internationalization
+
+@cindex Internationalization
+Texinfo has some support for writing in languages other than English,
+although this area still needs considerable work.
+
+For a list of the various accented and special characters Texinfo
+supports, see @ref{Inserting Accents}.
+
+@menu
+* documentlanguage::            Declaring the current language.
+* documentencoding::            Declaring the input encoding.
+@end menu
+
+
+@node documentlanguage
+@section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language
+
+@findex documentlanguage
+@cindex Language, declaring
+@cindex Locale, declaring
+@cindex Document language, declaring
+
+The @code{@@documentlanguage} command declares the current document
+locale.  Write it on a line by itself, near the beginning of the
+file, but after @code{@@setfilename}
+(@pxref{setfilename,,@code{@@setfilename}}):
+
+@example
+@@documentlanguage @var{ll}[_@var{cc}]
+@end example
+
+Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following
+the command name, optionally followed by an underscore and two-letter
+ISO@tie{}3166 two-letter country code (@var{cc}).  If you have a
+multilingual document, the intent is to be able to use this command
+multiple times, to declare each language change.  If the command is
+not used at all, the default is @code{en_US} for US English.
+
+As with GNU Gettext (@pxref{Top,,,gettext, Gettext}), if the country
+code is omitted, the main dialect is assumed where possible.  For
+example, @code{de} is equivalent to @code{de_DE} (German as spoken in
+Germany).
+
+@cindex Document strings, translation of
+For Info and other online output, this command changes the translation
+of various @dfn{document strings} such as ``see'' in cross-references
+(@pxref{Cross References}), ``Function' in defuns (@pxref{Definition
+Commands}), and so on.  Some strings, such as ``Node:'', ``Next:'',
+``Menu:'', etc., are keywords in Info output, so are not translated
+there; they are translated in other output formats.
+
+@cindex @file{txi-@var{cc}.tex}
+For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to
+be read (if it exists).  If @code{@@setdocumentlanguage} argument
+contains the optional @samp{_@var{cc}} suffix, this is tried first.
+For example, with @code{@@setdocumentlanguage de_DE}, @TeX{} first
+looks for @file{txi-de_DE.tex}, then @file{txi-de.tex}.
+
+Such a @file{txi-*} file is intended to redefine the various English
+words used in @TeX{} output, such as `Chapter', `See', and so on.  We
+are aware that individual words like these cannot always be translated
+in isolation, and that a very different strategy would be required for
+ideographic (among other) scripts.  Help in improving Texinfo's
+language support is welcome.
+
+@cindex Hyphenation patterns, language-dependent
+It would also be desirable for this command to also change @TeX{}'s
+ideas of the current hyphenation patterns (via the @TeX{} primitive
+@code{\language}), but this is unfortunately not currently
+implemented.
+
+In September 2006, the W3C Internationalization Activity released a
+new recommendation for specifying languages:
+@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}.  When Gettext
+supports this new scheme, Texinfo will too.
+
+@cindex ISO 639-2 language codes
+@cindex ISO 3166 country codes
+@cindex Language codes
+@cindex Country codes
+Since the lists of language codes and country codes are updated
+relatively frequently, we don't attempt to list them here.  The valid
+language codes are on the official home page for ISO@tie{}639,
+@url{http://www.loc.gov/standards/iso639-2/}.  The country codes and
+the official web site for ISO@tie{}3166 can be found via
+@url{http://en.wikipedia.org/wiki/ISO_3166}.
+
+
+@node documentencoding
+@section @code{@@documentencoding @var{enc}}: Set Input Encoding
+
+@findex documentencoding
+@cindex Encoding, declaring
+@cindex Input encoding, declaring
+@cindex Character set, declaring
+@cindex Document input encoding
+
+The @code{@@documentencoding} command declares the input document
+encoding.  Write it on a line by itself, with a valid encoding
+specification following, near the beginning of the file but after
+@code{@@setfilename} (@pxref{setfilename,,@code{@@setfilename}}):
+
+@example
+@@documentencoding @var{enc}
+@end example
+
+At present, Texinfo supports only these encodings:
+
+@table @code
+@item US-ASCII
+This has no particular effect, but it's included for completeness.
+
+@itemx UTF-8
+The vast global character encoding, expressed in 8-bit bytes.
+The Texinfo processors have no deep knowledge of Unicode; for the most
+part, they just pass along the input they are given to the output.
+
+@itemx ISO-8859-1
+@itemx ISO-8859-15
+@item ISO-8859-2
+These specify the standard encodings for Western European (the first
+two) and Eastern European languages (the third), respectively.  ISO
+8859-15 replaces some little-used characters from 8859-1 (e.g.,
+precomposed fractions) with more commonly needed ones, such as the
+Euro symbol (@euro{}).
+
+A full description of the encodings is beyond our scope here;
+one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
+
+@item koi8-r
+This is the commonly used encoding for the Russian language.
+
+@item koi8-u
+This is the commonly used encoding for the Ukrainian language.
+
+@end table
+
+Specifying an encoding @var{enc} has the following effects:
+
+@opindex --enable-encoding
+@cindex Local Variables: section, for encoding
+@cindex Info output, and encoding
+In Info output, unless the option @option{--disable-encoding} is given
+to @command{makeinfo}, a so-called `Local Variables' section
+(@pxref{File Variables,,,xemacs,XEmacs User's Manual}) is output
+including @var{enc}.  This allows Info readers to set the encoding
+appropriately.
+
+@example
+Local Variables:
+coding: @var{enc}
+End:
+@end example
+
+Also, in Info and plain text output (barring
+@option{--disable-encoding}), accent constructs and special
+characters, such as @code{@@'e}, are output as the actual 8-bit
+character in the given encoding.
+
+@cindex HTML output, and encodings
+@cindex @code{http-equiv}, and charset specification
+@cindex @code{<meta>} HTML tag, and charset specification
+In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>}
+section of the HTML, that specifies @var{enc}.  Web servers and
+browsers cooperate to use this information so the correct encoding is
+used to display the page, if supported by the system.
+
+@example
+<meta http-equiv="Content-Type" content="text/html;
+     charset=@var{enc}">
+@end example
+
+In split HTML output, if @option{--transliterate-file-names} is
+given (@pxref{HTML Xref 8-bit Character Expansion}), the names of HTML
+files are formed by transliteration of the corresponding node names,
+using the specified encoding. 
+
+In XML and Docbook output, the given document encoding is written in
+the output file as usual with those formats.
+
+In @TeX{} output, the characters which are supported in the standard
+Computer Modern fonts are output accordingly.  (For example, this
+means using constructed accents rather than precomposed glyphs.)
+Using a missing character generates a warning message, as does
+specifying an unimplemented encoding.
+
+
+@node Defining New Texinfo Commands
+@chapter Defining New Texinfo Commands
+@cindex Macros
+@cindex Defining new Texinfo commands
+@cindex New Texinfo commands, defining
+@cindex Texinfo commands, defining new
+@cindex User-defined Texinfo commands
+
+Texinfo provides several ways to define new commands:
+
+@itemize @bullet
+@item
+A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
+sequence of text and/or existing commands (including other macros).  The
+macro can have any number of @dfn{parameters}---text you supply each
+time you use the macro.
+
+Incidentally, these macros have nothing to do with the @code{@@defmac}
+command, which is for documenting macros in the subject of the manual
+(@pxref{Def Cmd Template}).
+
+@item
+@samp{@@alias} is a convenient way to define a new name for an existing
+command.
+
+@item
+@samp{@@definfoenclose} allows you to define new commands with
+customized output in the Info file.
+
+@end itemize
+
+@menu
+* Defining Macros::             Defining and undefining new commands.
+* Invoking Macros::             Using a macro, once you've defined it.
+* Macro Details::               Limitations of Texinfo macros.
+* alias::                       Command aliases.
+* definfoenclose::              Customized highlighting.
+@end menu
+
+
+@node Defining Macros
+@section Defining Macros
+@cindex Defining macros
+@cindex Macro definitions
+
+@findex macro
+You use the Texinfo @code{@@macro} command to define a macro, like this:
+
+@example
+@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
+@var{text} @dots{} \@var{param1}\ @dots{}
+@@end macro
+@end example
+
+The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
+arguments supplied when the macro is subsequently used in the document
+(described in the next section).
+
+@cindex Macro names, valid characters in
+@cindex Names of macros, valid characters of
+For a macro to work consistently with @TeX{}, @var{macroname} must
+consist entirely of letters: no digits, hyphens, underscores, or other
+special characters.  So, we recommend using only letters.  However,
+@command{makeinfo} will accept anything except @samp{@{@}_^=};
+@samp{_} and @samp{^} are excluded so that macros can be called in
+@code{@@math} mode without a following space
+(@pxref{math,,@code{@@math}}).
+
+If a macro needs no parameters, you can define it either with an empty
+list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
+foo}).
+
+@cindex Body of a macro
+@cindex Mutually recursive macros
+@cindex Recursion, mutual
+The definition or @dfn{body} of the macro can contain most Texinfo
+commands, including previously-defined macros.  Not-yet-defined macro
+invocations are not allowed; thus, it is not possible to have mutually
+recursive Texinfo macros.  Also, a macro definition that defines another
+macro does not work in @TeX{} due to limitations in the design of
+@code{@@macro}.
+
+@cindex Parameters to macros
+In the macro body, instances of a parameter name surrounded by
+backslashes, as in @samp{\@var{param1}\} in the example above, are
+replaced by the corresponding argument from the macro invocation.  You
+can use parameter names any number of times in the body, including zero.
+
+@cindex Backslash in macros
+To get a single @samp{\} in the macro expansion, use @samp{\\}.  Any
+other use of @samp{\} in the body yields a warning.
+
+@cindex Spaces in macros
+@cindex Whitespace in macros
+The newlines after the @code{@@macro} line and before the @code{@@end
+macro} line are ignored, that is, not included in the macro body.  All
+other whitespace is treated according to the usual Texinfo rules.
+
+@cindex Recursive macro invocations
+@findex rmacro
+To allow a macro to be used recursively, that is, in an argument to a
+call to itself, you must define it with @samp{@@rmacro}, like this:
+
+@example
+@@rmacro rmac @{arg@}
+a\arg\b
+@@end rmacro
+@dots{}
+@@rmac@{1@@rmac@{text@}2@}
+@end example
+
+This produces the output `a1atextb2b'.  With @samp{@@macro} instead of
+@samp{@@rmacro}, an error message is given.
+
+@findex unmacro
+@cindex Macros, undefining
+@cindex Undefining macros
+You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
+It is not an error to undefine a macro that is already undefined.
+For example:
+
+@example
+@@unmacro foo
+@end example
+
+
+@node Invoking Macros
+@section Invoking Macros
+@cindex Invoking macros
+@cindex Expanding macros
+@cindex Running macros
+@cindex Macro invocation
+
+After a macro is defined (see the previous section), you can use
+(@dfn{invoke}) it in your document like this:
+
+@example
+@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
+@end example
+
+@noindent and the result will be just as if you typed the body of
+@var{macroname} at that spot.  For example:
+
+@example
+@@macro foo @{p, q@}
+Together: \p\ & \q\.
+@@end macro
+@@foo@{a, b@}
+@end example
+
+@noindent produces:
+
+@display
+Together: a & b.
+@end display
+
+@cindex Backslash, and macros
+Thus, the arguments and parameters are separated by commas and delimited
+by braces; any whitespace after (but not before) a comma is ignored.
+The braces are required in the invocation (but not the definition), even
+when the macro takes no arguments, consistent with all other Texinfo
+commands.  For example:
+
+@example
+@@macro argless @{@}
+No arguments here.
+@@end macro
+@@argless@{@}
+@end example
+
+@noindent produces:
+
+@display
+No arguments here.
+@end display
+
+@cindex Comma, in macro arguments
+Passing strings containing commas as macro arguments requires special
+care, since they should be properly @dfn{quoted} to prevent
+@command{makeinfo} from confusing them with argument separators.  To
+manually quote a comma, prepend it with a backslash character, like
+this: @code{\,}.  Alternatively, use the @code{@@comma} command
+(@pxref{Inserting a Comma}).  However, to facilitate use of macros,
+@command{makeinfo} implements a set of rules called @dfn{automatic
+quoting}:
+
+@enumerate 1
+@item If a macro takes only one argument, all commas in its invocation
+are quoted by default.  For example:
+
+@example
+@group
+@@macro FIXME@{text@}
+@@strong@{FIXME: \text\@}
+@@end macro
+
+@@FIXME@{A nice feature, though it can be dangerous.@}
+@end group
+@end example
+
+@noindent
+will produce the following output
+
+@example
+@strong{FIXME: A nice feature, though it can be dangerous.}
+@end example
+
+And indeed, it can.  Namely, @command{makeinfo}
+does not control number of arguments passed to one-argument
+macros, so be careful when you invoke them.
+
+@item If a macro invocation includes another command (including a
+recursive invocation of itself), any commas in the nested command
+invocation(s) are quoted by default.  For example, in
+
+@example
+@@say@{@@strong@{Yes, I do@}, person one@}
+@end example
+
+the comma after @samp{Yes} is implicitly quoted.  Here's another
+example, with a recursive macro:
+
+@example
+@group
+@@rmacro cat@{a,b@}
+\a\\b\
+@@end rmacro
+
+@@cat@{@@cat@{foo, bar@}, baz@}
+@end group
+@end example
+
+@noindent
+will produce the string @samp{foobarbaz}.
+
+@item Otherwise, a comma should be explicitly quoted, as above, to be
+treated as a part of an argument.
+@end enumerate
+
+@cindex Braces, in macro arguments
+Other characters that need to be quoted in macro arguments are
+curly braces and backslash.  For example
+
+@example
+@@@var{macname} @{\\\@{\@}\,@}
+@end example
+
+@noindent
+will pass the (almost certainly error-producing) argument
+@samp{\@{@},} to @var{macname}.  However, commas in parameters, even
+if escaped by a backslash, might cause trouble in @TeX{}.
+
+If the macro is defined to take a single argument, and is invoked
+without any braces, the entire rest of the line after the macro name is
+supplied as the argument.  For example:
+
+@example
+@@macro bar @{p@}
+Twice: \p\ & \p\.
+@@end macro
+@@bar aah
+@end example
+
+@noindent produces:
+
+@c Sorry for cheating, but let's not require macros to process the manual.
+@display
+Twice: aah & aah.
+@end display
+
+If the macro is defined to take a single argument, and is invoked with
+braces, the braced text is passed as the argument, regardless of
+commas.  For example:
+
+@example
+@@macro bar @{p@}
+Twice: \p\ & \p\.
+@@end macro
+@@bar@{a,b@}
+@end example
+
+@noindent produces:
+
+@display
+Twice: a,b & a,b.
+@end display
+
+
+@node Macro Details
+@section Macro Details and Caveats
+@cindex Macro details
+@cindex Details of macro usage
+@cindex Caveats for macro usage
+
+Due to unavoidable limitations, certain macro-related constructs cause
+problems with @TeX{}.  If you get macro-related errors when producing
+the printed version of a manual, try expanding the macros with
+@command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E}
+option (@pxref{Format with texi2dvi}).
+
+@itemize @bullet
+@item
+As mentioned earlier, macro names must consist entirely of letters.
+
+@item
+It is not advisable to redefine any @TeX{} primitive, plain, or
+Texinfo command name as a macro. Unfortunately this is a very large
+set of names, and the possible resulting errors are unpredictable.
+
+@item
+All macros are expanded inside at least one @TeX{} group.  This means
+that @code{@@set} and other such commands have no effect inside a
+macro.
+
+@item
+Commas in macro arguments, even if escaped by a backslash, don't
+always work.
+
+@item
+Macro arguments cannot cross lines.
+
+@item
+It is (usually) best to avoid comments inside macro definitions, but
+see the next item.
+
+@item
+Macros containing a command which must be on a line by itself, such as
+a conditional, cannot be invoked in the middle of a line.  In general,
+the interaction of newlines in the macro definitions and invocations
+depends on the precise commands and context.  You may be able to work
+around some problems with judicious use of @code{@@c}.  Suppose you
+define a macro that is always intended to be used on a line by itself:
+
+@example
+@@macro linemac
+@@cindex whatever
+@@c
+@@end macro
+...
+foo
+@@linemac
+bar
+@end example
+
+Without the @code{@@c}, there will be an unwanted blank line between
+the @samp{@@cindex whatever} and the @samp{bar} (one newline comes
+from the macro definition, one from after the invocation), causing a
+paragraph break.
+
+On the other hand, you wouldn't want the @code{@@c} if the macro was
+sometimes invoked in the middle of a line (the text after the
+invocation would be treated as a comment).
+
+@item
+In general, you can't arbitrarily substitute a macro call for Texinfo
+command arguments, even when the text is the same.  It might work with
+some commands, it fails with others.  Best not to do it at all.  For
+instance, this fails:
+
+@example
+@@macro offmacro
+off
+@@end macro
+@@headings @@offmacro
+@end example
+
+@noindent
+You would expect this to be equivalent to @code{@@headings off}, but
+for @TeX{}nical reasons, it fails with a mysterious error message
+(@code{Paragraph ended before @@headings was complete}).
+
+@item
+Macros cannot define macros in the natural way.  To do this, you must
+use conditionals and raw @TeX{}.  For example:
+
+@example
+@@ifnottex
+@@macro ctor @{name, arg@}
+@@macro \name\
+something involving \arg\ somehow
+@@end macro
+@@end macro
+@@end ifnottex
+@@tex
+\gdef\ctor#1@{\ctorx#1,@}
+\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
+@@end tex
+@end example
+
+@end itemize
+
+The @command{makeinfo} implementation also has limitations:
+
+@itemize
+@item
+@code{@@verbatim} and macros do not mix; for instance, you can't start
+a verbatim block inside a macro and end it outside.
+(@xref{verbatim}.)  Starting any environment inside a macro and ending
+it outside may or may not work, for that matter.
+
+@item
+Macros that completely define macros are ok, but it's not possible to
+have incorrectly nested macro definitions.  That is, @code{@@macro}
+and @code{@@end macro} (likewise for @code{@@rmacro}) must be
+correctly paired.  For example, you cannot start a macro definition
+within a macro, and then end the nested definition outside the macro.
+
+@item
+@code{@@rmacro} is a kludge.
+
+@end itemize
+
+One more limitation is common to both implementations: white space is
+ignored at the beginnings of lines.
+
+Future major revisions of Texinfo may ease some of these limitations
+(by introducing a new macro syntax).
+
+
+@node alias
+@section @samp{@@alias @var{new}=@var{existing}}
+@cindex Aliases, command
+@cindex Command aliases
+@findex alias
+
+The @samp{@@alias} command defines a new command to be just like an
+existing one.  This is useful for defining additional markup names, thus
+preserving semantic information in the input even though the output
+result may be the same.
+
+Write the @samp{@@alias} command on a line by itself, followed by the
+new command name, an equals sign, and the existing command name.
+Whitespace around the equals sign is ignored.  Thus:
+@example
+@@alias @var{new} = @var{existing}
+@end example
+
+For example, if your document contains citations for both books and
+some other media (movies, for example), you might like to define a
+macro @code{@@moviecite@{@}} that does the same thing as an ordinary
+@code{@@cite@{@}} but conveys the extra semantic information as well.
+You'd do this as follows:
+
+@example
+@@alias moviecite = cite
+@end example
+
+Macros do not always have the same effect as aliases, due to vagaries
+of argument parsing.  Also, aliases are much simpler to define than
+macros.  So the command is not redundant.  (It was also heavily used
+in the Jargon File!)
+
+Aliases must not be recursive, directly or indirectly.
+
+It is not advisable to redefine any @TeX{} primitive, plain, or
+Texinfo command name as an alias.  Unfortunately this is a very large
+set of names, and the possible resulting errors are completely random.
+
+
+@node definfoenclose
+@section @samp{definfoenclose}: Customized Highlighting
+@cindex Highlighting, customized
+@cindex Customized highlighting
+@findex definfoenclose
+
+A @code{@@definfoenclose} command may be used to define a highlighting
+command for Info, but not for @TeX{}.  A command defined using
+@code{@@definfoenclose} marks text by enclosing it in strings that
+precede and follow the text.  You can use this to get closer control of
+your Info output.
+
+Presumably, if you define a command with @code{@@definfoenclose} for Info,
+you will create a corresponding command for @TeX{}, either in
+@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
+your document.
+
+Write a @code{@@definfoenclose} command on a line and follow it with
+three arguments separated by commas.  The first argument to
+@code{@@definfoenclose} is the @@-command name (without the @code{@@});
+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.  If
+you do not want a start delimiter but do want an end delimiter, you must
+follow the command name with two commas in a row; otherwise, the Info
+formatting commands will naturally misinterpret the end delimiter string
+you intended as the start delimiter string.
+
+If you do a @code{@@definfoenclose} on the name of a predefined macro
+(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
+enclosure definition will override the built-in definition.
+
+An enclosure command defined this way takes one argument in braces; this
+is intended for new markup commands (@pxref{Marking Text}).
+
+@findex phoo
+For example, you can write:
+
+@example
+@@definfoenclose phoo,//,\\
+@end example
+
+@noindent
+near the beginning of a Texinfo file to define @code{@@phoo} as an Info
+formatting command that inserts `//' before and `\\' after the argument
+to @code{@@phoo}.  You can then write @code{@@phoo@{bar@}} wherever you
+want `//bar\\' highlighted in Info.
+
+Also, for @TeX{} formatting, you could write
+
+@example
+@@iftex
+@@global@@let@@phoo=@@i
+@@end iftex
+@end example
+
+@noindent
+to define @code{@@phoo} as a command that causes @TeX{} to typeset the
+argument to @code{@@phoo} in italics.
+
+Each definition applies to its own formatter: one for @TeX{}, the other
+for @code{texinfo-format-buffer} or @code{texinfo-format-region}.  The
+@code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
+the raw @TeX{} commands do need to be in @samp{@@iftex}.
+
+@findex headword
+Here is another example: write
+
+@example
+@@definfoenclose headword, , :
+@end example
+
+@noindent
+near the beginning of the file, to define @code{@@headword} as an Info
+formatting command that inserts nothing before and a colon after the
+argument to @code{@@headword}.
+
+@samp{@@definfoenclose} definitions must not be recursive, directly or
+indirectly.
+
+
+@node Hardcopy
+@chapter Formatting and Printing Hardcopy
+@cindex Format and print hardcopy
+@cindex Printing hardcopy
+@cindex Hardcopy, printing it
+@cindex Making a printed manual
+@cindex Sorting indices
+@cindex Indices, sorting
+@cindex @TeX{} index sorting
+@pindex texindex
+
+There are three major shell commands for making a printed manual from a
+Texinfo file: one for converting the Texinfo file into a file that will be
+printed, a second for sorting indices, and a third for printing the
+formatted document.  When you use the shell commands, you can either
+work directly in the operating system shell or work within a shell
+inside XEmacs.
+
+If you are using XEmacs, you can use commands provided by Texinfo
+mode instead of shell commands.  In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
+@menu
+* Use TeX::                     Use @TeX{} to format for hardcopy.
+* Format with tex/texindex::    How to format with explicit shell commands.
+* Format with texi2dvi::        A simpler way to format.
+* Print with lpr::              How to print.
+* Within XEmacs::                How to format and print from an XEmacs shell.
+* Texinfo Mode Printing::       How to format and print in Texinfo mode.
+* Compile-Command::             How to print using XEmacs's compile command.
+* Requirements Summary::        @TeX{} formatting requirements summary.
+* Preparing for TeX::           What to do before you use @TeX{}.
+* Overfull hboxes::             What are and what to do with overfull hboxes.
+* smallbook::                   How to print small format books and manuals.
+* A4 Paper::                    How to print on A4 or A5 paper.
+* pagesizes::                   How to print with customized page sizes.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+                                 of pages and how to print scaled up output.
+* PDF Output::                  Portable Document Format output.
+* Obtaining TeX::               How to Obtain @TeX{}.
+@end menu
+
+@node Use TeX
+@section Use @TeX{}
+
+The typesetting program called @TeX{} is used for formatting a Texinfo
+file.  @TeX{} is a very powerful typesetting program and, if used correctly,
+does an exceptionally good job.  (@xref{Obtaining TeX, , How to Obtain
+@TeX{}}, for information on how to obtain @TeX{}.)
+
+The standalone @code{makeinfo} program and XEmacs functions
+@code{texinfo-format-region} and @code{texinfo-format-buffer} commands
+read the very same @@-commands in the Texinfo file as does @TeX{}, but
+process them differently to make an Info file (@pxref{Creating an Info
+File}).
+
+
+@node Format with tex/texindex
+@section Format with @code{tex} and @code{texindex}
+@cindex Shell formatting with @code{tex} and @code{texindex}
+@cindex Formatting with @code{tex} and @code{texindex}
+@cindex DVI file
+
+You can format the Texinfo file with the shell command @code{tex}
+followed by the name of the Texinfo file.  For example:
+
+@example
+tex foo.texi
+@end example
+
+@noindent
+@TeX{} will produce a @dfn{DVI file} as well as several auxiliary
+files containing information for indices, cross references, etc.  The
+DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
+any device (see the following sections).
+
+@pindex texindex
+The @code{tex} formatting command itself does not sort the indices; it
+writes an output file of unsorted index data.  To generate a printed
+index after running the @command{tex} command, you first need a sorted
+index to work from.  The @command{texindex} command sorts indices.
+(The source file @file{texindex.c} comes as part of the standard
+Texinfo distribution, among other places.)  (@command{texi2dvi} runs
+@command{tex} and @command{texindex} as necessary.)
+
+@cindex Names of index files
+@cindex Index file names
+The @code{tex} formatting command outputs unsorted index files under
+names that obey a standard convention: the name of your main input file
+with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
+Web2c}) extension removed, followed by the two letter names of indices.
+For example, the raw index output files for the input file
+@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
+@file{foo.tp}, @file{foo.pg} and @file{foo.ky}.  Those are exactly the
+arguments to give to @code{texindex}.
+
+@need 1000
+@cindex Wildcards
+@cindex Globbing
+Instead of specifying all the unsorted index file names explicitly, you
+can use @samp{??} as shell wildcards and give the command in this
+form:
+
+@example
+texindex foo.??
+@end example
+
+@noindent
+This command will run @code{texindex} on all the unsorted index files,
+including any that you have defined yourself using @code{@@defindex}
+or @code{@@defcodeindex}.  (You may execute @samp{texindex foo.??}
+even if there are similarly named files with two letter extensions
+that are not index files, such as @samp{foo.el}.  The @code{texindex}
+command reports but otherwise ignores such files.)
+
+For each file specified, @code{texindex} generates a sorted index file
+whose name is made by appending @samp{s} to the input file name.  The
+@code{@@printindex} command looks for a file with that name
+(@pxref{Printing Indices & Menus}).  @code{texindex} does not alter the
+raw index output file.
+
+After you have sorted the indices, you need to rerun @code{tex} on the
+Texinfo file.  This regenerates the DVI file, this time with
+up-to-date index entries.
+
+Finally, you may need to run @code{tex} one more time, to get the page
+numbers in the cross-references correct.
+
+To summarize, this is a five step process:
+
+@enumerate
+@item
+Run @code{tex} on your Texinfo file.  This generates a DVI file (with
+undefined cross-references and no indices), and the raw index files
+(with two letter extensions).
+
+@item
+Run @code{texindex} on the raw index files.  This creates the
+corresponding sorted index files (with three letter extensions).
+
+@item
+Run @code{tex} again on your Texinfo file.  This regenerates the DVI
+file, this time with indices and defined cross-references, but with page
+numbers for the cross-references from last time, generally incorrect.
+
+@item
+Sort the indices again, with @code{texindex}.
+
+@item
+Run @code{tex} one last time.  This time the correct page numbers are
+written for the cross-references.
+@end enumerate
+
+@pindex texi2dvi
+Alternatively, it's a one-step process: run @code{texi2dvi}
+(@pxref{Format with texi2dvi}).
+
+You need not run @code{texindex} each time after you run @code{tex}.  If
+you do not, on the next run, the @code{tex} formatting command will use
+whatever sorted index files happen to exist from the previous use of
+@code{texindex}.  This is usually ok while you are debugging.
+
+@cindex Auxiliary files, avoiding
+@findex novalidate
+@cindex Pointer validation, suppressing
+@cindex Chapters, formatting one at a time
+Sometimes you may wish to print a document while you know it is
+incomplete, or to print just one chapter of a document.  In that case,
+the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
+when cross-references are not satisfied are just nuisances.  You can
+avoid them with the @code{@@novalidate} command, which you must give
+@emph{before} the @code{@@setfilename} command
+(@pxref{setfilename,,@code{@@setfilename}}).  Thus, the beginning of
+your file would look approximately like this:
+
+@example
+\input texinfo
+@@novalidate
+@@setfilename myfile.info
+@dots{}
+@end example
+
+@noindent @code{@@novalidate} also turns off validation in
+@code{makeinfo}, just like its @code{--no-validate} option
+(@pxref{Pointer Validation}).
+
+
+@node Format with texi2dvi
+@section Format with @code{texi2dvi}
+@pindex texi2dvi @r{(shell script)}
+
+The @code{texi2dvi} command automatically runs both @TeX{} and
+@command{texindex} as many times as necessary to produce a DVI file
+with sorted indices and all cross-references resolved.  It is
+therefore simpler than manually executing the
+@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
+described in the previous section.
+
+To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
+@samp{prompt$ } is your shell prompt):
+
+@example
+prompt$ @kbd{texi2dvi foo.texi}
+@end example
+
+As shown in this example, the input filenames to @code{texi2dvi} must
+include any extension (@samp{.texi}, @samp{.texinfo}, etc.).  Under
+MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
+texi2dvi foo.texi} instead of relying on the operating system to invoke
+the shell on the @samp{texi2dvi} script.
+
+@opindex --command @r{(@command{texi2dvi})}
+One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}.
+This inserts @var{cmd} on a line by itself after the
+@code{@@setfilename} in a temporary copy of the input file before
+running @TeX{}.  With this, you can specify different printing
+formats, such as @code{@@smallbook} (@pxref{smallbook}),
+@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
+(@pxref{pagesizes}), without actually changing the document source.
+(You can also do this on a site-wide basis with @file{texinfo.cnf};
+@pxref{Preparing for TeX,,Preparing for @TeX{}}).
+
+@opindex --pdf @r{(@command{texi2dvi})}
+With the @option{--pdf} option, @command{texi2dvi} produces PDF output
+instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
+instead of @command{tex}.  Alternatively, the command
+@command{texi2pdf} is an abbreviation for running @samp{texi2dvi
+--pdf}.  The command @command{pdftexi2dvi} is also supported as a
+convenience to AUC-@TeX{} users, since the latter merely prepends
+@samp{pdf} to DVI producing tools to have PDF producing tools.
+
+@cindex @LaTeX{}, processing with @command{texi2dvi}
+@command{texi2dvi} can also be used to process @LaTeX{} files; simply
+run @samp{texi2dvi filename.ext}.
+
+@opindex --language @r{(@command{texi2dvi})}
+Normally @command{texi2dvi} is able to guess the input file language
+by its contents and file name suffix. If, however, it fails to do so
+you can specify the input language using
+@option{--language=@var{lang}} command line option, where @var{lang}
+is either @samp{latex} or @samp{texinfo}.
+
+@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if
+they are available; these extended versions of @TeX{} are not
+required, and the DVI (or PDF) output is identical, but they simplify
+the @TeX{} programming in some cases, and provide additional tracing
+information when debugging @file{texinfo.tex}.
+
+@opindex --translate-file @r{(@command{texi2dvi})}
+Several options are provided for handling documents, written in
+character sets other than ASCII. The
+@option{--translate-file=@var{file}} option instructs
+@command{texi2dvi} to translate input into internal @TeX{} character
+set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX
+files, TCX files: Character translations, web2c, Web2c: A @TeX{}
+implementation}).
+
+@opindex --recode @r{(@command{texi2dvi})}
+The options @option{--recode} and @option{--recode-from=@var{enc}}
+allow conversion of an input document before running @TeX{}. The
+@option{--recode} option recodes the document from encoding specified
+by @samp{@@documentencoding} command
+(@pxref{documentencoding,,@code{documentencoding}}) to plain 7-bit
+@samp{texinfo} encoding.
+
+@opindex --recode-from @r{(@command{texi2dvi})}
+The option @option{--recode-from=@var{enc}} recodes the document from
+@var{enc} encoding to the encoding specified by
+@samp{@@documentencoding}. This is useful, for example, if the
+document is written in @samp{UTF-8} encoding and an equivalent 8-bit
+encoding is supported by @command{makeinfo}.
+
+Both @option{--recode} and @option{--recode-from=@var{enc}} use
+@command{recode} utility to perform the conversion. If
+@command{recode} fails to process the file, @command{texi2dvi} prints
+a warning and continues using unmodified input file.
+
+For a list of other options, run @samp{texi2dvi --help}.
+
+
+@node Print with lpr
+@section Shell Print Using @code{lpr -d}
+@pindex lpr @r{(DVI print command)}
+
+The precise command to print a DVI file depends on your system
+installation.  Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
+-d foo.dvi}.
+
+For example, the following commands will (perhaps) suffice to sort the
+indices, format, and print the @cite{Bison Manual}:
+
+@example
+@group
+tex bison.texinfo
+texindex bison.??
+tex bison.texinfo
+lpr -d bison.dvi
+@end group
+@end example
+
+@noindent
+(Remember that the shell commands may be different at your site; but
+these are commonly used versions.)
+
+Using the @code{texi2dvi} shell script (see the previous section):
+
+@example
+@group
+texi2dvi bison.texinfo
+lpr -d bison.dvi
+# or perhaps dvips bison.dvi -o
+@end group
+@end example
+
+@cindex Shell printing, on MS-DOS/MS-Windows
+@cindex Printing DVI files, on MS-DOS/MS-Windows
+@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
+@code{lpr} is a standard program on Unix systems, but it is usually
+absent on MS-DOS/MS-Windows.  Some network packages come with a
+program named @code{lpr}, but these are usually limited to sending files
+to a print server over the network, and generally don't support the
+@samp{-d} option.  If you are unfortunate enough to work on one of these
+systems, you have several alternative ways of printing DVI files:
+
+@itemize @bullet{}
+@item Find and install a Unix-like @code{lpr} program, or its clone.
+If you can do that, you will be able to print DVI files just like
+described above.
+
+@item Send the DVI files to a network printer queue for DVI files.
+Some network printers have special queues for printing DVI files.  You
+should be able to set up your network software to send files to that
+queue.  In some cases, the version of @code{lpr} which comes with your
+network software will have a special option to send a file to specific
+queues, like this:
+
+@example
+lpr -Qdvi -hprint.server.domain bison.dvi
+@end example
+
+@item Convert the DVI file to a Postscript or PCL file and send it to your
+local printer.  @xref{Invoking Dvips,,, dvips, Dvips}, and the man
+pages for @code{dvilj}, for detailed description of these tools.  Once
+the DVI file is converted to the format your local printer understands
+directly, just send it to the appropriate port, usually @samp{PRN}.
+@end itemize
+
+
+@node Within XEmacs
+@section From an XEmacs Shell
+@cindex Print, format from XEmacs shell
+@cindex Format, print from XEmacs shell
+@cindex Shell, format, print from
+@cindex XEmacs shell, format, print from
+
+You can give formatting and printing commands from a shell within
+XEmacs.  To create a shell within XEmacs, type @kbd{M-x shell}.  In this
+shell, you can format and print the document.  @xref{Hardcopy, , Format
+and Print Hardcopy}, for details.
+
+You can switch to and from the shell buffer while @code{tex} is
+running and do other editing.  If you are formatting a long document
+on a slow machine, this can be very convenient.@refill
+
+You can also use @code{texi2dvi} from an XEmacs shell.  For example,
+here is how to use @code{texi2dvi} to format and print @cite{Using and
+Porting GNU CC} from a shell within XEmacs:
+
+@example
+@group
+texi2dvi gcc.texinfo
+lpr -d gcc.dvi
+@end group
+@end example
+
+See the next section for more information about formatting
+and printing in Texinfo mode.
+
+
+@node Texinfo Mode Printing
+@section Formatting and Printing in Texinfo Mode
+@cindex Region printing in Texinfo mode
+@cindex Format and print in Texinfo mode
+@cindex Print and format in Texinfo mode
+
+Texinfo mode provides several predefined key commands for @TeX{}
+formatting and printing.  These include commands for sorting indices,
+looking at the printer queue, killing the formatting job, and
+recentering the display of the buffer in which the operations
+occur.@refill
+
+@table @kbd
+@item C-c C-t C-b
+@itemx M-x texinfo-tex-buffer
+Run @code{texi2dvi} on the current buffer.@refill
+
+@item C-c C-t C-r
+@itemx M-x texinfo-tex-region
+Run @TeX{} on the current region.@refill
+
+@item C-c C-t C-i
+@itemx M-x texinfo-texindex
+Sort the indices of a Texinfo file formatted with
+@code{texinfo-tex-region}.@refill
+
+@item C-c C-t C-p
+@itemx M-x texinfo-tex-print
+Print a DVI file that was made with @code{texinfo-tex-region} or
+@code{texinfo-tex-buffer}.@refill
+
+@item C-c C-t C-q
+@itemx M-x tex-show-print-queue
+Show the print queue.@refill
+
+@item C-c C-t C-d
+@itemx M-x texinfo-delete-from-print-queue
+Delete a job from the print queue; you will be prompted for the job
+number shown by a preceding @kbd{C-c C-t C-q} command
+(@code{texinfo-show-tex-print-queue}).@refill
+
+@item C-c C-t C-k
+@itemx M-x tex-kill-job
+Kill the currently running @TeX{} job started by either
+@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
+process running in the Texinfo shell buffer.@refill
+
+@item C-c C-t C-x
+@itemx M-x texinfo-quit-job
+Quit a @TeX{} formatting job that has stopped because of an error by
+sending an @key{x} to it.  When you do this, @TeX{} preserves a record
+of what it did in a @file{.log} file.@refill
+
+@item C-c C-t C-l
+@itemx M-x tex-recenter-output-buffer
+Redisplay the shell buffer in which the @TeX{} printing and formatting
+commands are run to show its most recent output.@refill
+@end table
+
+@need 1000
+Thus, the usual sequence of commands for formatting a buffer is as
+follows (with comments to the right):@refill
+
+@example
+@group
+C-c C-t C-b             @r{Run @code{texi2dvi} on the buffer.}
+C-c C-t C-p             @r{Print the DVI file.}
+C-c C-t C-q             @r{Display the printer queue.}
+@end group
+@end example
+
+The Texinfo mode @TeX{} formatting commands start a subshell in XEmacs
+called the @file{*tex-shell*}.  The @code{texinfo-tex-command},
+@code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
+commands are all run in this shell.
+
+You can watch the commands operate in the @samp{*tex-shell*} buffer,
+and you can switch to and from and use the @samp{*tex-shell*} buffer
+as you would any other shell buffer.@refill
+
+@need 1500
+The formatting and print commands depend on the values of several variables.
+The default values are:@refill
+
+@example
+@group
+    @r{Variable}                              @r{Default value}
+
+texinfo-texi2dvi-command                  "texi2dvi"
+texinfo-tex-command                       "tex"
+texinfo-texindex-command                  "texindex"
+texinfo-delete-from-print-queue-command   "lprm"
+texinfo-tex-trailer                       "@@bye"
+tex-start-of-header                       "%**start"
+tex-end-of-header                         "%**end"
+tex-dvi-print-command                     "lpr -d"
+tex-show-queue-command                    "lpq"
+@end group
+@end example
+
+You can change the values of these variables with the @kbd{M-x
+set-variable} command (@pxref{Examining, , Examining and Setting
+Variables, xemacs, XEmacs User's Manual}), or with your @file{init.el}
+initialization file (@pxref{Init File, , , xemacs, The XEmacs
+Manual}).
+
+@cindex Customize XEmacs package (@t{Development/Docs/Texinfo})
+Beginning with version 20, XEmacs offers a user-friendly interface,
+called @dfn{Customize}, for changing values of user-definable variables.
+@xref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs
+User's Manual}, for more details about this.  The Texinfo variables can
+be found in the @samp{Development/Docs/Texinfo} group, once you invoke
+the @kbd{M-x customize} command.
+
+
+@node Compile-Command
+@section Using the Local Variables List
+@cindex Local variables
+@cindex Compile command for formatting
+@cindex Format with the compile command
+
+Yet another way to apply the @TeX{} formatting command to a Texinfo file
+is to put that command in a @dfn{local variables list} at the end of the
+Texinfo file.  You can then specify the @code{tex} or @code{texi2dvi}
+commands as a @code{compile-command} and have XEmacs run it by typing
+@kbd{M-x compile}.  This creates a special shell called the
+@file{*compilation*} buffer in which XEmacs runs the compile command.
+For example, at the end of the @file{gdb.texinfo} file, after the
+@code{@@bye}, you could put the following:@refill
+
+@example
+@group
+Local Variables:
+compile-command: "texi2dvi gdb.texinfo"
+End:
+@end group
+@end example
+
+@noindent
+This technique is most often used by programmers who also compile programs
+this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill
+
+
+@node Requirements Summary
+@section @TeX{} Formatting Requirements Summary
+@cindex Requirements for formatting
+@cindex Minimal requirements for formatting
+@cindex Formatting requirements
+
+Every Texinfo file that is to be input to @TeX{} must begin with a
+@code{\input} command and must contain an @code{@@setfilename} command:
+
+@example
+\input texinfo
+@@setfilename @var{arg-not-used-by-@@TeX@{@}}
+@end example
+
+@noindent
+The first command instructs @TeX{} to load the macros it needs to
+process a Texinfo file and the second command opens auxiliary files.
+
+Every Texinfo file must end with a line that terminates @TeX{}'s
+processing and forces out unfinished pages:
+
+@example
+@@bye
+@end example
+
+Strictly speaking, these lines are all a Texinfo file needs to be
+processed successfully by @TeX{}.
+
+Usually, however, the beginning includes an @code{@@settitle} command to
+define the title of the printed manual, an @code{@@setchapternewpage}
+command, a title page, a copyright page, and permissions.  Besides an
+@code{@@bye}, the end of a file usually includes indices and a table of
+contents.  (And of course most manuals contain a body of text as well.)
+
+For more information, see:
+
+@itemize @bullet
+@item @ref{settitle, , @code{@@settitle}}.
+@item @ref{setchapternewpage, , @code{@@setchapternewpage}}.
+@item @ref{Headings, ,Page Headings}.
+@item @ref{Titlepage & Copyright Page}.
+@item @ref{Printing Indices & Menus}.
+@item @ref{Contents}.
+@end itemize
+
+
+@node Preparing for TeX
+@section Preparing for @TeX{}
+@cindex Preparing for @TeX{}
+@cindex @TeX{} input initialization
+@cindex @b{.profile} initialization file
+@cindex @b{.cshrc} initialization file
+@cindex Initialization file for @TeX{} input
+
+@TeX{} needs to know where to find the @file{texinfo.tex} file that the
+@samp{\input texinfo} command on the first line reads.  The
+@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
+included in all standard GNU distributions.  The latest version is
+always available from the Texinfo source repository:
+@smalldisplay
+@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD}
+@end smalldisplay
+
+@pindex texinfo.tex@r{, installing}
+
+Usually, the installer has put the @file{texinfo.tex} file in the
+default directory that contains @TeX{} macros when GNU Texinfo, XEmacs or
+other GNU software is installed.  In this case, @TeX{} will find the
+file and you do not need to do anything special.  If this has not been
+done, you can put @file{texinfo.tex} in the current directory when you
+run @TeX{}, and @TeX{} will find it there.
+
+@pindex epsf.tex@r{, installing}
+Also, you should install @file{epsf.tex}, if it is not already installed
+from another distribution.  More details are at the end of the description
+of the @code{@@image} command (@pxref{Images}).
+
+@cindex European Computer Modern fonts, installing
+@cindex EC fonts, installing
+@cindex CM-Super fonts, installing
+To be able to use quotation marks other than those used in English
+you'll need to install European Computer Modern fonts and optionally
+CM-Super fonts, unless they are already installed (@pxref{Inserting
+Quotation Marks}).
+
+@pindex feymr10@r{, installing}
+@cindex Euro font, installing
+If you intend to use the @code{@@euro} command, you should install the
+Euro font, if it is not already installed.  @xref{euro}.
+
+@pindex texinfo.cnf @r{installation}
+@cindex Customizing of @TeX{} for Texinfo
+@cindex Site-wide Texinfo configuration file
+Optionally, you may create an additional @file{texinfo.cnf}, and install
+it as well.  This file is read by @TeX{} when the @code{@@setfilename}
+command is executed (@pxref{setfilename,, @code{@@setfilename}}).  You can put any
+commands you like there, according to local site-wide conventions.  They
+will be read by @TeX{} when processing any Texinfo document.  For
+example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
+(@pxref{A4 Paper}), then all Texinfo documents will be processed with
+that page size in effect.  If you have nothing to put in
+@file{texinfo.cnf}, you do not need to create it.
+
+@cindex Environment variable @code{TEXINPUTS}
+@vindex TEXINPUTS
+If neither of the above locations for these system files suffice for
+you, you can specify the directories explicitly.  For
+@file{texinfo.tex}, you can do this by writing the complete path for the
+file after the @code{\input} command.  Another way, that works for both
+@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
+might read), is to set the @code{TEXINPUTS} environment variable in your
+@file{.cshrc} or @file{.profile} file.
+
+Which you use of @file{.cshrc} or @file{.profile} depends on
+whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
+@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
+command interpreter.  The latter read the @file{.cshrc} file for
+initialization information, and the former read @file{.profile}.
+
+In a @file{.cshrc} file, you could use the following @code{csh} command
+sequence:
+
+@example
+setenv TEXINPUTS .:/home/me/mylib:
+@end example
+
+@need 1000
+In a @file{.profile} file, you could use the following @code{sh} command
+sequence:
+
+@example
+@group
+TEXINPUTS=.:/home/me/mylib:
+export TEXINPUTS
+@end group
+@end example
+
+On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
+of the @samp{;} character, instead of @samp{:}, as directory separator
+on these systems.}:
+
+@example
+@group
+set TEXINPUTS=.;d:/home/me/mylib;c:
+@end group
+@end example
+
+@noindent
+It is customary for DOS/Windows users to put such commands in the
+@file{autoexec.bat} file, or in the Windows Registry.
+
+@noindent
+These settings would cause @TeX{} to look for @file{\input} file first
+in the current directory, indicated by the @samp{.}, then in a
+hypothetical user @samp{me}'s @file{mylib} directory, and finally in
+the system directories.  (A leading, trailing, or doubled @samp{:}
+indicates searching the system directories at that point.)
+
+@cindex Dumping a .fmt file
+@cindex Format file, dumping
+Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
+web2c, Web2c}) so that @TeX{} can load Texinfo faster.  (The
+disadvantage is that then updating @file{texinfo.tex} requires
+redumping.)  You can do this by running this command, assuming
+@file{epsf.tex} is findable by @TeX{}:
+
+@example
+initex texinfo @@dump
+@end example
+
+@noindent
+(@code{dump} is a @TeX{} primitive.)  Then, move @file{texinfo.fmt} to
+wherever your @code{.fmt} files are found; typically, this will be in the
+subdirectory @file{web2c} of your @TeX{} installation.
+
+
+@node Overfull hboxes
+@section Overfull ``hboxes''
+@cindex Overfull @samp{hboxes}
+@cindex @samp{hboxes}, overfull
+@cindex Final output
+
+@TeX{} is sometimes unable to typeset a line without extending it into
+the right margin.  This can occur when @TeX{} comes upon what it
+interprets as a long word that it cannot hyphenate, such as an
+electronic mail network address or a very long title.  When this
+happens, @TeX{} prints an error message like this:
+
+@example
+Overfull @@hbox (20.76302pt too wide)
+@end example
+
+@findex hbox
+@noindent
+(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
+@samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
+
+@TeX{} also provides the line number in the Texinfo source file and
+the text of the offending line, which is marked at all the places that
+@TeX{} considered hyphenation.
+@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
+for more information about typesetting errors.
+
+If the Texinfo file has an overfull hbox, you can rewrite the sentence
+so the overfull hbox does not occur, or you can decide to leave it.  A
+small excursion into the right margin often does not matter and may not
+even be noticeable.
+
+If you have many overfull boxes and/or an antipathy to rewriting, you
+can coerce @TeX{} into greatly increasing the allowable interword
+spacing, thus (if you're lucky) avoiding many of the bad line breaks,
+like this:
+
+@findex \emergencystretch
+@example
+@@tex
+\global\emergencystretch = .9\hsize
+@@end tex
+@end example
+
+@noindent
+(You should adjust the fraction as needed.)  This huge value for
+@code{\emergencystretch} cannot be the default, since then the typeset
+output would generally be of noticeably lower quality; the default
+is @samp{.15\hsize}.  @code{\hsize} is the @TeX{} dimension
+containing the current line width.
+
+@cindex Black rectangle in hardcopy
+@cindex Rectangle, black in hardcopy
+@cindex Box, ugly black in hardcopy
+@cindex Ugly black rectangles in hardcopy
+For what overfull boxes you have, however, @TeX{} will print a large,
+ugly, black rectangle beside the line that contains the overfull hbox
+unless told otherwise.  This is so you will notice the location of the
+problem if you are correcting a draft.
+
+@findex finalout
+To prevent such a monstrosity from marring your final printout, write
+the following in the beginning of the Texinfo file on a line of its own,
+before the @code{@@titlepage} command:
+
+@example
+@@finalout
+@end example
+
+
+@node smallbook
+@section Printing ``Small'' Books
+@findex smallbook
+@cindex Small book size
+@cindex Book, printing small
+@cindex Page sizes for books
+@cindex Size of printed book
+
+By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
+format.  However, you can direct @TeX{} to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the title page:@refill
+
+@example
+@@smallbook
+@end example
+
+@noindent
+(Since many books are about 7 by 9.25 inches, this command might better
+have been called the @code{@@regularbooksize} command, but it came to be
+called the @code{@@smallbook} command by comparison to the 8.5 by 11
+inch format.)
+
+If you write the @code{@@smallbook} command between the
+start-of-header and end-of-header lines, the Texinfo mode @TeX{}
+region formatting command, @code{texinfo-tex-region}, will format the
+region in ``small'' book size (@pxref{Start of Header}).@refill
+
+@xref{small}, for information about
+commands that make it easier to produce examples for a smaller manual.
+
+@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
+@TeX{}}, for other ways to format with @code{@@smallbook} that do not
+require changing the source file.
+
+
+@node A4 Paper
+@section Printing on A4 Paper
+@cindex A4 paper, printing on
+@cindex A5 paper, printing on
+@cindex Paper size, A4
+@cindex European A4 paper
+@findex afourpaper
+
+You can tell @TeX{} to format a document for printing on European size
+A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
+command.  Write the command on a line by itself near the beginning of
+the Texinfo file, before the title page.  For example, this is how you
+would write the header for this manual:
+
+@example
+@group
+\input texinfo    @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename texinfo
+@@settitle Texinfo
+@@afourpaper
+@@c %**end of header
+@end group
+@end example
+
+@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
+@TeX{}}, for other ways to format for different paper sizes that do not
+require changing the source file.
+
+@findex afourlatex
+@findex afourwide
+You may or may not prefer the formatting that results from the command
+@code{@@afourlatex}.  There's also @code{@@afourwide} for A4 paper in
+wide format.
+
+@node pagesizes
+@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes
+@findex pagesizes
+@cindex Custom page sizes
+@cindex Page sizes, customized
+@cindex Text width and height
+@cindex Width of text area
+@cindex Height of text area
+@cindex Depth of text area
+
+You can explicitly specify the height and (optionally) width of the main
+text area on the page with the @code{@@pagesizes} command.  Write this
+on a line by itself near the beginning of the Texinfo file, before the
+title page.  The height comes first, then the width if desired,
+separated by a comma.  Examples:
+
+@example
+@@pagesizes 200mm,150mm  @c for b5 paper
+@end example
+@noindent and
+@example
+@@pagesizes 11.5in      @c for legal paper
+@end example
+
+@cindex B5 paper, printing on
+@cindex Legal paper, printing on
+This would be reasonable for printing on B5-size paper.  To emphasize,
+this command specifies the size of the @emph{text area}, not the size of
+the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
+8.5@dmn{in} for legal).
+
+@cindex Margins on page, not controllable
+To make more elaborate changes, such as changing any of the page
+margins, you must define a new command in @file{texinfo.tex} (or
+@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
+
+@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
+@TeX{}}, for other ways to specify @code{@@pagesizes} that do not
+require changing the source file.
+
+@code{@@pagesizes} is ignored by @code{makeinfo}.
+
+
+@node Cropmarks and Magnification
+@section Cropmarks and Magnification
+@findex cropmarks
+@cindex Cropmarks for printing
+@cindex Printing cropmarks
+You can (attempt to) direct @TeX{} to print cropmarks at the corners of
+pages with the @code{@@cropmarks} command.  Write the @code{@@cropmarks}
+command on a line by itself between @code{@@iftex} and @code{@@end
+iftex} lines near the beginning of the Texinfo file, before the title
+page, like this:@refill
+
+@example
+@group
+@@iftex
+@@cropmarks
+@@end iftex
+@end group
+@end example
+
+This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the @code{@@smallbook} command.
+(Printers will not produce cropmarks for regular sized output that is
+printed on regular sized paper.)  Since different printing machines work
+in different ways, you should explore the use of this command with a
+spirit of adventure.  You may have to redefine the command in
+@file{texinfo.tex}.
+
+@findex \mag @r{(raw @TeX{} magnification)}
+@cindex Magnified printing
+@cindex Larger or smaller pages
+You can attempt to direct @TeX{} to typeset pages larger or smaller than
+usual with the @code{\mag} @TeX{} command.  Everything that is typeset
+is scaled proportionally larger or smaller.  (@code{\mag} stands for
+``magnification''.)  This is @emph{not} a Texinfo @@-command, but is a
+plain @TeX{} command that is prefixed with a backslash.  You have to
+write this command between @code{@@tex} and @code{@@end tex}
+(@pxref{Raw Formatter Commands}).
+
+Follow the @code{\mag} command with an @samp{=} and then a number that
+is 1000 times the magnification you desire.  For example, to print pages
+at 1.2 normal size, write the following near the beginning of the
+Texinfo file, before the title page:
+
+@example
+@group
+@@tex
+\mag=1200
+@@end tex
+@end group
+@end example
+
+With some printing technologies, you can print normal-sized copies that
+look better than usual by giving a larger-than-normal master to your
+print shop.  They do the reduction, thus effectively increasing the
+resolution.
+
+Depending on your system, DVI files prepared with a
+nonstandard-@code{\mag} may not print or may print only with certain
+magnifications.  Be prepared to experiment.
+
+
+@node PDF Output
+@section PDF Output
+@cindex PDF output
+
+@pindex pdftex
+The simplest way to generate PDF output from Texinfo source is to run
+the convenience script @command{texi2pdf} (or @command{pdftexi2dvi});
+this simply executes the @command{texi2dvi} script with the
+@option{--pdf} option (@pxref{Format with texi2dvi}).  If for some
+reason you want to process the document by hand, simply run the
+@command{pdftex} program instead of plain @command{tex}.  That is, run
+@samp{pdftex foo.texi} instead of @samp{tex foo.texi}.
+
+@dfn{PDF} stands for `Portable Document Format'. It was invented by
+Adobe Systems some years ago for document interchange, based on their
+PostScript language.  Related links:
+
+@itemize
+@item
+GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF
+reader}.  (It can also preview PostScript documents.)
+
+@item
+A freely available standalone @uref{http://www.foolabs.com/xpdf/,
+PDF reader} for the X window system.
+
+@item
+@uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}.
+
+@end itemize
+
+At present, Texinfo does not provide
+@samp{@@ifpdf} or @samp{@@pdf} commands as for the other output
+formats, since PDF documents contain many internal links that would be
+hard or impossible to get right at the Texinfo source level.
+
+PDF files require special software to be displayed, unlike the plain
+ASCII formats (Info, HTML) that Texinfo supports.  They also tend to
+be much larger than the DVI files output by @TeX{} by default.
+Nevertheless, a PDF file does define an actual typeset document in a
+self-contained file, so it has its place.
+
+
+@node Obtaining TeX
+@section How to Obtain @TeX{}
+@cindex Obtaining @TeX{}
+@cindex @TeX{}, how to obtain
+
+@c !!! Here is information about obtaining TeX.  Update it whenever.
+@c !!! Also consider updating TeX.README on ftp.gnu.org.
+@c     Updated by RJC on 1 March 1995, conversation with MacKay.
+@c     Updated by kb@cs.umb.edu on 29 July 1996.
+@c     Updated by kb@cs.umb.edu on 25 April 1997.
+@c     Updated by kb@cs.umb.edu on 27 February 1998.
+@TeX{} is freely redistributable.  You can obtain @TeX{} for Unix
+systems via anonymous ftp or on physical media.  The core material
+consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
+
+Instructions for retrieval by anonymous ftp and information on other
+available distributions:
+@uref{http://tug.org/unixtex.ftp}.
+
+The Free Software Foundation provides a core distribution on its Source
+Code CD-ROM suitable for printing Texinfo manuals.  To order it, contact:
+
+@display
+@group
+Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor
+Boston, MA @ @ 02110-1301
+USA
+Telephone: @w{+1-617-542-5942}
+Fax: (including Japan) @w{+1-617-542-2652}
+Free Dial Fax (in Japan):
+@w{ } @w{ } @w{ } 0031-13-2473 (KDD)
+@w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
+Electronic mail: @code{gnu@@gnu.org}
+@end group
+@end display
+
+Many other @TeX{} distributions are available; see
+@uref{http://tug.org/}.
+
+
+@node Creating and Installing Info Files
+@chapter Creating and Installing Info Files
+
+This chapter describes how to create and install Info files.  @xref{Info
+Files}, for general information about the file format itself.
+
+@menu
+* Creating an Info File::
+* Installing an Info File::
+@end menu
+
+
+@node Creating an Info File
+@section Creating an Info File
+@cindex Creating an Info file
+@cindex Info, creating an online file
+@cindex Formatting a file for Info
+
+@code{makeinfo} is a program that converts a Texinfo file into an Info
+file, HTML file, or plain text.  @code{texinfo-format-region} and
+@code{texinfo-format-buffer} are XEmacs functions that convert
+Texinfo to Info.
+
+For information on installing the Info file in the Info system,
+@pxref{Installing an Info File}.
+
+@menu
+* makeinfo advantages::         @code{makeinfo} provides better error checking.
+* Invoking makeinfo::           How to run @code{makeinfo} from a shell.
+* makeinfo options::            Specify fill-column and other options.
+* Pointer Validation::          How to check that pointers point somewhere.
+* makeinfo in XEmacs::           How to run @code{makeinfo} from XEmacs.
+* texinfo-format commands::     Two Info formatting commands written
+                                 in XEmacs Lisp are an alternative
+                                 to @code{makeinfo}.
+* Batch Formatting::            How to format for Info in XEmacs Batch mode.
+* Tag and Split Files::         How tagged and split files help Info
+                                 to run better.
+@end menu
+
+
+@node makeinfo advantages
+@subsection @code{makeinfo} Preferred
+
+The @code{makeinfo} utility creates an Info file from a Texinfo source
+file more quickly than either of the XEmacs formatting commands and
+provides better error messages.  We recommend it.  @code{makeinfo} is a
+C program that is independent of XEmacs.  You do not need to run XEmacs to
+use @code{makeinfo}, which means you can use @code{makeinfo} on machines
+that are too small to run XEmacs.  You can run @code{makeinfo} in any one
+of three ways: from an operating system shell, from a shell inside
+XEmacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
+command in Texinfo mode in XEmacs.
+
+The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
+commands are useful if you cannot run @code{makeinfo}.  Also, in some
+circumstances, they format short regions or buffers more quickly than
+@code{makeinfo}.
+
+
+@node Invoking makeinfo
+@subsection Running @code{makeinfo} from a Shell
+@pindex makeinfo
+
+To create an Info file from a Texinfo file, invoke @command{makeinfo}
+followed by the name of the Texinfo file.  Thus, to create the Info
+file for Bison, type the following to the shell:
+
+@example
+makeinfo bison.texinfo
+@end example
+
+(You can run a shell inside XEmacs by typing @kbd{M-x shell}.)
+
+@command{makeinfo} has many options to control its actions and output;
+see the next section.
+
+You can give @command{makeinfo} more than one input file name; each is
+processed in turn.  If an input file name is @samp{-}, or no input
+file names are given at all, standard input is read.
+
+
+@node makeinfo options
+@subsection Options for @code{makeinfo}
+@cindex @code{makeinfo} options
+@cindex Options for @code{makeinfo}
+
+The @command{makeinfo} program accepts many options.  Perhaps the most
+commonly needed are those that change the output format.  By default,
+@command{makeinfo} outputs Info files.
+
+Each command line option is a word preceded by @samp{--} or a letter
+preceded by @samp{-}.  You can use abbreviations for the long option
+names as long as they are unique.
+
+For example, you could use the following shell command to create an Info
+file for @file{bison.texinfo} in which each line is filled to only 68
+columns:
+
+@example
+makeinfo --fill-column=68 bison.texinfo
+@end example
+
+You can write two or more options in sequence, like this:@refill
+
+@example
+makeinfo --no-split --fill-column=70 @dots{}
+@end example
+
+@noindent
+This would keep the Info file together as one possibly very long
+file and would also set the fill column to 70.
+
+The options are:
+
+@table @code
+
+@item -D @var{var}
+@opindex -D @var{var}
+Cause the variable @var{var} to be defined.  This is equivalent to
+@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
+
+@item --commands-in-node-names
+@opindex --commands-in-node-names
+Allow @code{@@}-commands in node names.  This is not recommended, as it
+can probably never be implemented in @TeX{}.  It also makes
+@code{makeinfo} much slower.  Also, this option is ignored when
+@samp{--no-validate} is used.  @xref{Pointer Validation}, for more
+details.
+
+@item --css-include=@var{file}
+@opindex --css-include
+Include the contents of @var{file}, which should contain cascading
+style sheets specifications, in the @samp{<style>} block of the HTML
+output.  @xref{HTML CSS}.  If @var{file} is @samp{-}, read standard
+input.
+
+@item --css-ref=@var{url}
+@opindex --css-ref
+In HTML mode, add a @samp{<link>} tag to the HTML output which
+references a cascading style sheet at @var{url}. This allows using
+standalone style sheets.
+
+@item --disable-encoding
+@itemx --enable-encoding
+@opindex --disable-encoding
+@opindex --enable-encoding
+By default, or with @option{--enable-encoding}, output accented and
+special characters in Info or plain text output based on
+@samp{@@documentencoding}.  With @option{--disable-encoding}, 7-bit
+ASCII transliterations are output.
+@xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting
+Accents}.
+
+@item --docbook
+@opindex --docbook
+Generate Docbook output rather than Info.
+
+@item --document-language=@var{lang}
+@opindex --document-language
+@vindex LANG
+Use @var{lang} to translate Texinfo keywords which end up in the
+output document.  The default is the locale specified by the
+@code{@@documentlanguage} command if there is one
+(@pxref{documentlanguage}).
+
+@item --error-limit=@var{limit}
+@itemx -e @var{limit}
+@opindex --error-limit=@var{limit}
+@opindex -e @var{limit}
+Set the maximum number of errors that @code{makeinfo} will report
+before exiting (on the assumption that continuing would be useless);
+default 100.
+
+@item --fill-column=@var{width}
+@itemx -f @var{width}
+@opindex --fill-column=@var{width}
+@opindex -f @var{width}
+Specify the maximum number of columns in a line; this is the right-hand
+edge of a line.  Paragraphs that are filled will be filled to this
+width.  (Filling is the process of breaking up and connecting lines so
+that lines are the same length as or shorter than the number specified
+as the fill column.  Lines are broken between words.) The default value
+is 72.  Ignored with @samp{--html}.
+
+@item --footnote-style=@var{style}
+@itemx -s @var{style}
+@opindex --footnote-style=@var{style}
+@opindex -s @var{style}
+Set the footnote style to @var{style}, either @samp{end} for the end
+node style (the default) or @samp{separate} for the separate node style.
+The value set by this option overrides the value set in a Texinfo file
+by an @code{@@footnotestyle} command (@pxref{Footnotes}).  When the
+footnote style is @samp{separate}, @code{makeinfo} makes a new node
+containing the footnotes found in the current node.  When the footnote
+style is @samp{end}, @code{makeinfo} places the footnote references at
+the end of the current node.  Ignored with @samp{--html}.
+
+@item --force
+@itemx -F
+@opindex --force
+@opindex -F
+Ordinarily, if the input file has errors, the output files are not
+created.  With this option, they are preserved.
+
+@item --help
+@itemx -h
+@opindex --help
+@opindex -h
+Print a usage message listing all available options, then exit successfully.
+
+@item --html
+@opindex --html
+Generate HTML output rather than Info.  @xref{Generating HTML}.  By
+default, the HTML output is split into one output file per Texinfo
+source node, and the split output is written into a subdirectory with
+the name of the top-level info file.
+
+@item -I @var{dir}
+@opindex -I @var{dir}
+Append @var{dir} to the directory search list for finding files that
+are included using the @code{@@include} command.  By default,
+@code{makeinfo} searches only the current directory.  If @var{dir} is
+not given, the current directory @file{.} is appended.  Note that
+@var{dir} can actually be a list of several directories separated by the
+usual path separator character (@samp{:} on Unix, @samp{;} on
+MS-DOS/MS-Windows).
+
+@item --ifdocbook
+@opindex --ifdocbook
+@itemx --ifhtml
+@opindex --ifhtml
+@itemx --ifinfo
+@opindex --ifinfo
+@itemx --ifplaintext
+@opindex --ifplaintext
+@itemx --iftex
+@opindex --iftex
+@itemx --ifxml
+@opindex --ifxml
+For the specified format, process @samp{@@if@var{format}} and
+@samp{@@@var{format}} commands even if not generating the given output
+format.  For instance, if @option{--iftex} is specified, then
+@samp{@@iftex} and @samp{@@tex} blocks will be read.  
+
+@item --internal-links=@var{file} 
+@opindex --internal-links=@var{file}
+In HTML mode, output a tab separated file containing three columns:
+the internal link to an indexed item or item in the table of contents, 
+the name of the index (or "toc") in which it occurs, and the term
+which was indexed or entered.
+
+@item --macro-expand=@var{file}
+@itemx -E @var{file}
+@opindex --macro-expand=@var{file}
+@opindex -E @var{file}
+Output the Texinfo source with all the macros expanded to the named
+file.  Normally, the results of macro expansion are used internally by
+@code{makeinfo} and then discarded.  This option is used by
+@command{texi2dvi}.
+
+@item --no-headers
+@item --plaintext
+@opindex --no-headers
+@opindex --plaintext
+@cindex Plain text output
+@cindex ASCII text output
+@cindex Generating plain text files
+@cindex @file{INSTALL} file, generating
+@cindex Node separators, omitting
+@cindex Menus, omitting
+Do not include menus or node separator lines in the output, and
+implicitly @option{--enable-encoding} (see above).  This results in a
+simple plain text file that you can (for example) send in email
+without complications, or include in a distribution (as in an
+@file{INSTALL} file).
+
+@cindex Navigation links, omitting
+For HTML output, likewise omit menus.  And if @samp{--no-split} is also
+specified, do not include a navigation links at the top of each node
+(these are never included in the default case of split output).
+@xref{Generating HTML}.
+
+In both cases, ignore @code{@@setfilename} and write to standard
+output by default---can be overridden with @option{-o}.
+
+@item --no-ifdocbook
+@opindex --no-ifdocbook
+@itemx --no-ifhtml
+@opindex --no-ifhtml
+@itemx --no-ifinfo
+@opindex --no-ifinfo
+@itemx --no-ifplaintext
+@opindex --no-ifplaintext
+@itemx --no-iftex
+@opindex --no-iftex
+@itemx --no-ifxml
+@opindex --no-ifxml
+Do not process @samp{@@if@var{format}} and @samp{@@@var{format}}
+commands, and do process @samp{@@ifnot@var{format}}, even if
+generating the given format.  For instance, if @option{--no-ifhtml} is
+specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be
+read, and @samp{@@ifnothtml} blocks will be.
+
+@item --no-number-footnotes
+@opindex --no-number-footnotes
+Suppress automatic footnote numbering.  By default, @code{makeinfo}
+numbers each footnote sequentially in a single node, resetting the
+current footnote number to 1 at the start of each node.
+
+@item --no-number-sections
+@opindex --no-number-sections
+Do not output chapter, section, and appendix numbers.
+You need to specify this if your manual is not hierarchically-structured.
+
+@item --no-split
+@opindex --no-split
+@cindex Splitting of output files
+@cindex Output file splitting
+Suppress the splitting stage of @code{makeinfo}.  By default, large
+output files (where the size is greater than 70k bytes) are split into
+smaller subfiles.  For Info output, each one is approximately 50k bytes.
+For HTML output, each file contains one node (@pxref{Generating HTML}).
+
+@item --no-pointer-validate
+@itemx --no-validate
+@opindex --no-pointer-validate
+@opindex --no-validate
+@cindex Pointer validation, suppressing
+Suppress the pointer-validation phase of @code{makeinfo}---a dangerous
+thing to do.  This can also be done with the @code{@@novalidate}
+command (@pxref{Use TeX,,Use @TeX{}}).  Normally, after a Texinfo file
+is processed, some consistency checks are made to ensure that cross
+references can be resolved, etc.  @xref{Pointer Validation}.
+
+@item --no-warn
+@opindex --no-warn
+Suppress warning messages (but @emph{not} error messages).
+
+@item --number-sections
+@opindex --number-sections
+Output chapter, section, and appendix numbers as in printed manuals.
+This is the default.  It works only with hierarchically-structured
+manuals.
+
+@item --output=@var{file}
+@itemx -o @var{file}
+@opindex --output=@var{file}
+@opindex -o @var{file}
+Specify that the output should be directed to @var{file} and not to the
+file name specified in the @code{@@setfilename} command found in the
+Texinfo source (@pxref{setfilename}).  If @var{file} is @samp{-}, output
+goes to standard output and @samp{--no-split} is implied.  For split
+HTML output, @var{file} is the name for the directory into which all
+HTML nodes are written (@pxref{Generating HTML}).
+
+@item -P @var{dir}
+@opindex -P @var{dir}
+Prepend @var{dir} to the directory search list for @code{@@include}.
+If @var{dir} is not given, the current directory @file{.} is prepended.
+See @samp{-I} for more details.
+
+@item --paragraph-indent=@var{indent}
+@itemx -p @var{indent}
+@opindex --paragraph-indent=@var{indent}
+@opindex -p @var{indent}
+Set the paragraph indentation style to @var{indent}.  The value set by
+this option overrides the value set in a Texinfo file by an
+@code{@@paragraphindent} command (@pxref{paragraphindent}).  The value
+of @var{indent} is interpreted as follows:
+
+@table @asis
+@item @samp{asis}
+Preserve any existing indentation at the starts of paragraphs.
+
+@item @samp{0} or @samp{none}
+Delete any existing indentation.
+
+@item @var{num}
+Indent each paragraph by @var{num} spaces.
+@end table
+
+@item --split-size=@var{num}
+@opindex --split-size=@var{num}
+Keep Info files to at most @var{num} characters; default is 300,000.
+
+@item --transliterate-file-names
+@opindex --transliterate-file-names
+Enable transliteration of 8-bit characters in node names for the
+purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}.
+
+@item -U @var{var}
+Cause @var{var} to be undefined.  This is equivalent to
+@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
+
+@item --verbose
+@opindex --verbose
+Cause @code{makeinfo} to display messages saying what it is doing.
+Normally, @code{makeinfo} only outputs messages if there are errors or
+warnings.
+
+@item --version
+@itemx -V
+@opindex --version
+@opindex -V
+Print the version number, then exit successfully.
+
+@item --xml
+@opindex --xml
+Generate XML output rather than Info.
+
+@end table
+
+@vindex TEXINFO_OUTPUT_FORMAT
+@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT}
+@command{makeinfo} also reads the environment variable
+@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not
+overridden by a command line option.  The possible values are:
+
+@example
+docbook  html  info  plaintext  xml
+@end example
+
+If not set, Info output is the default.
+
+
+@node Pointer Validation
+@subsection Pointer Validation
+@cindex Pointer validation with @code{makeinfo}
+@cindex Validation of pointers
+
+If you do not suppress pointer validation with the @samp{--no-validate}
+option or the @code{@@novalidate} command in the source file (@pxref{Use
+TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
+Info file.  Mostly, this means ensuring that nodes you have referenced
+really exist.  Here is a complete list of what is checked:
+
+@enumerate
+@item
+If a `Next', `Previous', or `Up' node reference is a reference to a
+node in the current file and is not an external reference such as to
+@file{(dir)}, then the referenced node must exist.@refill
+
+@item
+In every node, if the `Previous' node is different from the `Up' node,
+then the node pointed to by the `Previous' field must have a `Next'
+field which points back to this node.@refill
+
+@item
+Every node except the `Top' node must have an `Up' pointer.@refill
+
+@item
+The node referenced by an `Up' pointer must itself reference the current
+node through a menu item, unless the node referenced by `Up'
+has the form `(@var{file})'.
+
+@item
+If the `Next' reference of a node is not the same as the `Next' reference
+of the `Up' reference, then the node referenced by the `Next' pointer
+must have a `Previous' pointer that points back to the current node.
+This rule allows the last node in a section to point to the first node
+of the next chapter.@refill
+
+@item
+Every node except `Top' should be referenced by at least one other node,
+either via the `Previous' or `Next' links, or via a menu or a
+cross-reference.@refill
+@end enumerate
+
+@cindex @@-commands in @@node, limited support
+Some Texinfo documents might fail during the validation phase because
+they use commands like @code{@@value} and @code{@@definfoenclose} in
+node definitions and cross-references inconsistently.  (Your best bet
+is to avoid using @@-commands in node names.)  Consider the
+following example:
+
+@example
+@group
+@@set nodename Node 1
+
+@@node @@value@{nodename@}, Node 2, Top, Top
+
+This is node 1.
+
+@@node Node 2, , Node 1, Top
+
+This is node 2.
+@end group
+@end example
+
+@noindent
+Here, the node ``Node 1'' was referenced both verbatim and through
+@code{@@value}.
+
+By default, @code{makeinfo} fails such cases, because node names are not
+fully expanded until they are written to the output file.  You should
+always try to reference nodes consistently; e.g., in the above example,
+the second @code{@@node} line should have also used @code{@@value}.
+However, if, for some reason, you @emph{must} reference node names
+inconsistently, and @code{makeinfo} fails to validate the file, you can
+use the @samp{--commands-in-node-names} option to force @code{makeinfo}
+to perform the expensive expansion of all node names it finds in the
+document.  This might considerably slow down the program, though;
+twofold increase in conversion time was measured for large documents
+such as the Jargon file.
+
+@cindex @@value in @@node lines
+The support for @code{@@}-commands in @code{@@node} directives is not
+general enough to be freely used.  For example, if the example above
+redefined @code{nodename} somewhere in the document, @code{makeinfo}
+will fail to convert it, even if invoked with the
+@samp{--commands-in-node-names} option.
+
+@samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
+option is given.
+
+
+@node makeinfo in XEmacs
+@subsection Running @code{makeinfo} Within XEmacs
+@cindex Running @code{makeinfo} in XEmacs
+@cindex @code{makeinfo} inside XEmacs
+@cindex Shell, running @code{makeinfo} in
+
+You can run @code{makeinfo} in XEmacs Texinfo mode by using either the
+@code{makeinfo-region} or the @code{makeinfo-buffer} commands.  In
+Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
+C-m C-b} by default.@refill
+
+@table @kbd
+@item C-c C-m C-r
+@itemx M-x makeinfo-region
+Format the current region for Info.@refill
+@findex makeinfo-region
+
+@item C-c C-m C-b
+@itemx M-x makeinfo-buffer
+Format the current buffer for Info.@refill
+@findex makeinfo-buffer
+@end table
+
+When you invoke @code{makeinfo-region} the output goes to a temporary
+buffer.  When you invoke @code{makeinfo-buffer} output goes to the
+file set with @code{@@setfilename} (@pxref{setfilename}).
+
+The XEmacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
+run the @code{makeinfo} program in a temporary shell buffer.  If
+@code{makeinfo} finds any errors, XEmacs displays the error messages in
+the temporary buffer.@refill
+
+@cindex Errors, parsing
+@cindex Parsing errors
+@findex next-error
+You can parse the error messages by typing @kbd{C-x `}
+(@code{next-error}).  This causes XEmacs to go to and position the
+cursor on the line in the Texinfo source that @code{makeinfo} thinks
+caused the error.  @xref{Compilation, , Running @code{make} or
+Compilers Generally, xemacs, XEmacs User's Manual}, for more
+information about using the @code{next-error} command.@refill
+
+In addition, you can kill the shell in which the @code{makeinfo}
+command is running or make the shell buffer display its most recent
+output.@refill
+
+@table @kbd
+@item C-c C-m C-k
+@itemx M-x makeinfo-kill-job
+@findex makeinfo-kill-job
+Kill the current running @code{makeinfo} job
+(from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
+
+@item C-c C-m C-l
+@itemx M-x makeinfo-recenter-output-buffer
+@findex makeinfo-recenter-output-buffer
+Redisplay the @code{makeinfo} shell buffer to display its most recent
+output.@refill
+@end table
+
+@noindent
+(Note that the parallel commands for killing and recentering a @TeX{}
+job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}.  @xref{Texinfo Mode
+Printing}.)@refill
+
+You can specify options for @code{makeinfo} by setting the
+@code{makeinfo-options} variable with either the @kbd{M-x
+customize} or the @kbd{M-x set-variable} command, or by setting the
+variable in your @file{init.el} initialization file.
+
+For example, you could write the following in your @file{init.el} file:@refill
+
+@example
+@group
+(setq makeinfo-options
+     "--paragraph-indent=0 --no-split
+      --fill-column=70 --verbose")
+@end group
+@end example
+
+@noindent
+@c If you write these three cross references using xref, you see
+@c three references to the same named manual, which looks strange.
+@iftex
+For more information, see @ref{makeinfo options, , Options for
+@code{makeinfo}}, as well as ``Easy Customization Interface,'' ``Examining
+and Setting Variables,'' and ``Init File'' in @cite{The XEmacs
+Manual}.
+@end iftex
+@ifnottex
+For more information, see@*
+@ref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs User's Manual},@*
+@ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@*
+@ref{Init File, , , xemacs, XEmacs User's Manual}, and@*
+@ref{makeinfo options, , Options for @code{makeinfo}}.
+@end ifnottex
+
+@node texinfo-format commands
+@subsection The @code{texinfo-format@dots{}} Commands
+
+In XEmacs in Texinfo mode, you can format part or all of a Texinfo
+file with the @code{texinfo-format-region} command.  This formats the
+current region and displays the formatted text in a temporary buffer
+called @samp{*Info Region*}.@refill
+
+Similarly, you can format a buffer with the
+@code{texinfo-format-buffer} command.  This command creates a new
+buffer and generates the Info file in it.  Typing @kbd{C-x C-s} will
+save the Info file under the name specified by the
+@code{@@setfilename} line which must be near the beginning of the
+Texinfo file.@refill
+
+@table @kbd
+@item C-c C-e C-r
+@itemx @code{texinfo-format-region}
+@findex texinfo-format-region
+Format the current region for Info.
+
+@item C-c C-e C-b
+@itemx @code{texinfo-format-buffer}
+@findex texinfo-format-buffer
+Format the current buffer for Info.
+@end table
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands provide you with some error checking, and other functions can
+provide you with further help in finding formatting errors.  These
+procedures are described in an appendix; see @ref{Catching Mistakes}.
+However, the @code{makeinfo} program is often faster and
+provides better error checking (@pxref{makeinfo in XEmacs}).@refill
+
+@node Batch Formatting
+@comment  node-name,  next,  previous,  up
+@subsection Batch Formatting
+@cindex Batch formatting for Info
+@cindex Info batch formatting
+
+You can format Texinfo files for Info using @code{batch-texinfo-format}
+and XEmacs Batch mode.  You can run XEmacs in Batch mode from any shell,
+including a shell inside of XEmacs.  (@xref{Command Arguments,,,
+xemacs, XEmacs User's Manual}.)
+
+Here is a shell command to format all the files that end in
+@file{.texinfo} in the current directory:
+
+@example
+xemacs -batch -funcall batch-texinfo-format *.texinfo
+@end example
+
+@noindent
+XEmacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of them.@refill
+
+Run @code{batch-texinfo-format} only with XEmacs in Batch mode as shown;
+it is not interactive.  It kills the Batch mode XEmacs on completion.@refill
+
+@code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
+and want to format several Texinfo files at once.  When you use Batch
+mode, you create a new XEmacs process.  This frees your current XEmacs, so
+you can continue working in it.  (When you run
+@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
+use that XEmacs for anything else until the command finishes.)@refill
+
+@node Tag and Split Files
+@comment  node-name,  next,  previous,  up
+@subsection Tag Files and Split Files
+@cindex Making a tag table automatically
+@cindex Tag table, making automatically
+
+If a Texinfo file has more than 30,000 bytes,
+@code{texinfo-format-buffer} automatically creates a tag table
+for its Info file;  @code{makeinfo} always creates a tag table.  With
+a @dfn{tag table}, Info can jump to new nodes more quickly than it can
+otherwise.@refill
+
+@cindex Indirect subfiles
+In addition, if the Texinfo file contains more than about 300,000
+bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
+large Info file into shorter @dfn{indirect} subfiles of about 300,000
+bytes each.  Big files are split into smaller files so that XEmacs does
+not need to make a large buffer to hold the whole of a large Info
+file; instead, XEmacs allocates just enough memory for the small, split-off
+file that is needed at the time.  This way, XEmacs avoids wasting
+memory when you run Info.  (Before splitting was implemented, Info
+files were always kept short and @dfn{include files} were designed as
+a way to create a single, large printed manual out of the smaller Info
+files.  @xref{Include Files}, for more information.  Include files are
+still used for very large documents, such as @cite{The XEmacs Lisp
+Reference Manual}, in which each chapter is a separate file.)@refill
+
+When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off.  The split-off files are called
+@dfn{indirect} files.@refill
+
+The split-off files have names that are created by appending @w{@samp{-1}},
+@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
+@code{@@setfilename} command.  The shortened version of the original file
+continues to have the name specified by @code{@@setfilename}.@refill
+
+At one stage in writing this document, for example, the Info file was saved
+as the file @file{test-texinfo} and that file looked like this:@refill
+
+@example
+@group
+Info file: test-texinfo,    -*-Text-*-
+produced by texinfo-format-buffer
+from file: new-texinfo-manual.texinfo
+
+^_
+Indirect:
+test-texinfo-1: 102
+test-texinfo-2: 50422
+@end group
+@group
+test-texinfo-3: 101300
+^_^L
+Tag table:
+(Indirect)
+Node: overview^?104
+Node: info file^?1271
+@end group
+@group
+Node: printed manual^?4853
+Node: conventions^?6855
+@dots{}
+@end group
+@end example
+
+@noindent
+(But @file{test-texinfo} had far more nodes than are shown here.)  Each of
+the split-off, indirect files, @file{test-texinfo-1},
+@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
+after the line that says @samp{Indirect:}.  The tag table is listed after
+the line that says @samp{Tag table:}. @refill
+
+In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect files,
+not counting the file list itself, the tag table, or the permissions
+text in each file.  In the tag table, the number following the node name
+records the location of the beginning of the node, in bytes from the
+beginning of the (unsplit) output.
+
+If you are using @code{texinfo-format-buffer} to create Info files,
+you may want to run the @code{Info-validate} command.  (The
+@code{makeinfo} command does such a good job on its own, you do not
+need @code{Info-validate}.)  However, you cannot run the @kbd{M-x
+Info-validate} node-checking command on indirect files.  For
+information on how to prevent files from being split and how to
+validate the structure of the nodes, see @ref{Using Info-validate}.
+
+
+@node Installing an Info File
+@section Installing an Info File
+@cindex Installing an Info file
+@cindex Info file installation
+@cindex @file{dir} directory for Info installation
+
+Info files are usually kept in the @file{info} directory.  You can read
+Info files using the standalone Info program or the Info reader built
+into XEmacs.  (@inforef{Top, info, info}, for an introduction to Info.)
+
+@menu
+* Directory File::              The top level menu for all Info files.
+* New Info File::               Listing a new Info file.
+* Other Info Directories::      How to specify Info files that are
+                                 located in other directories.
+* Installing Dir Entries::      How to specify what menu entry to add
+                                 to the Info directory.
+* Invoking install-info::       @code{install-info} options.
+@end menu
+
+
+@node Directory File
+@subsection The Directory File @file{dir}
+
+For Info to work, the @file{info} directory must contain a file that
+serves as a top level directory for the Info system.  By convention,
+this file is called @file{dir}.  (You can find the location of this file
+within XEmacs by typing @kbd{C-h i} to enter Info and then typing
+@kbd{C-x C-f} to see the pathname to the @file{info} directory.)
+
+The @file{dir} file is itself an Info file.  It contains the top level
+menu for all the Info files in the system.  The menu looks like
+this:@refill
+
+@example
+@group
+* Menu:
+* Info:    (info).     Documentation browsing system.
+* XEmacs:  (xemacs).   The extensible, self-documenting
+                       text editor.
+* Texinfo: (texinfo).  With one source file, make
+                       either a printed manual using
+                       @@TeX@{@} or an Info file.
+@dots{}
+@end group
+@end example
+
+Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses.  (The menu entry does not need to
+specify the `Top' node, since Info goes to the `Top' node if no node
+name is mentioned.  @xref{Other Info Files, , Nodes in Other Info
+Files}.)@refill
+
+Thus, the @samp{Info} entry points to the `Top' node of the
+@file{info} file and the @samp{XEmacs} entry points to the `Top' node
+of the @file{xemacs} file.@refill
+
+In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the @code{dir} file.  For example, the line for the `Top'
+node of the XEmacs manual looks like this in Info:@refill
+
+@example
+File: xemacs  Node: Top, Up: (DIR), Next: Distrib
+@end example
+
+@noindent
+In this case, the @file{dir} file name is written in upper case
+letters---it can be written in either upper or lower case.  This is not
+true in general, it is a special case for @file{dir}.
+
+
+@node New Info File
+@subsection Listing a New Info File
+@cindex Adding a new Info file
+@cindex Listing a new Info file
+@cindex New Info file, listing it in @file{dir} file
+@cindex Info file, listing a new
+@cindex @file{dir} file listing
+
+To add a new Info file to your system, you must write a menu entry to
+add to the menu in the @file{dir} file in the @file{info} directory.
+For example, if you were adding documentation for GDB, you would write
+the following new entry:@refill
+
+@example
+* GDB: (gdb).           The source-level C debugger.
+@end example
+
+@noindent
+The first part of the menu entry is the menu entry name, followed by a
+colon.  The second part is the name of the Info file, in parentheses,
+followed by a period.  The third part is the description.
+
+The name of an Info file often has a @file{.info} extension.  Thus, the
+Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
+The Info reader programs automatically try the file name both with and
+without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
+try the @file{.inf} extension as well.}; so it is better to avoid
+clutter and not to write @samp{.info} explicitly in the menu entry.  For
+example, the GDB menu entry should use just @samp{gdb} for the file
+name, not @samp{gdb.info}.
+
+
+@node Other Info Directories
+@subsection Info Files in Other Directories
+@cindex Installing Info in another directory
+@cindex Info installed in another directory
+@cindex Another Info directory
+@cindex @file{dir} files and Info directories
+
+If an Info file is not in the @file{info} directory, there are three
+ways to specify its location:@refill
+
+@enumerate
+@item
+Write the pathname in the @file{dir} file as the second part of the menu.
+
+@item
+If you are using XEmacs, list the name of the file in a second @file{dir}
+file, in its directory; and then add the name of that directory to the
+@code{Info-directory-list} variable in your personal or site
+initialization file.
+
+This variable tells XEmacs where to look for @file{dir} files (the files
+must be named @file{dir}).  XEmacs merges the files named @file{dir} from
+each of the listed directories.  (In XEmacs version 18, you can set the
+@code{Info-directory} variable to the name of only one
+directory.)@refill
+
+@item
+Specify the Info directory name in the @code{INFOPATH} environment
+variable in your @file{.profile} or @file{.cshrc} initialization file.
+(Only you and others who set this environment variable will be able to
+find Info files whose location is specified this way.)
+@end enumerate
+
+For example, to reach a test file in the @file{/home/bob/info}
+directory, you could add an entry like this to the menu in the
+standard @file{dir} file:@refill
+
+@example
+* Test: (/home/bob/info/info-test).  Bob's own test file.
+@end example
+
+@noindent
+In this case, the absolute file name of the @file{info-test} file is
+written as the second part of the menu entry.@refill
+
+Alternatively, you could write the following in your @file{init.el} file:
+
+@vindex Info-directory-list
+@example
+@group
+(require 'info)
+(setq Info-directory-list
+ (cons (expand-file-name "/home/bob/info")
+       Info-directory-list))
+@end group
+@end example
+
+This tells XEmacs to merge the system @file{dir} file with the @file{dir}
+file in @file{/home/bob/info}.  Thus, Info will list the
+@file{/home/bob/info/info-test} file as a menu entry in the
+@file{/home/bob/info/dir} file.  XEmacs does the merging only when
+@kbd{M-x info} is first run, so if you want to set
+@code{Info-directory-list} in an XEmacs session where you've already run
+@code{info}, you must @code{(setq Info-dir-contents nil)} to force XEmacs
+to recompose the @file{dir} file.
+
+@vindex INFOPATH
+@cindex Environment variable @code{INFOPATH}
+Finally, you can tell Info where to look by setting the @code{INFOPATH}
+environment variable in your shell startup file, such as @file{.cshrc},
+@file{.profile} or @file{autoexec.bat}.  If you use a Bourne-compatible
+shell such as @code{sh} or @code{bash} for your shell command
+interpreter, you set the @code{INFOPATH} environment variable in the
+@file{.profile} initialization file; but if you use @code{csh} or
+@code{tcsh}, you set the variable in the @file{.cshrc} initialization
+file.  On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
+your @file{autoexec.bat} file or in the Registry.  Each type of shell
+uses a different syntax.
+
+@itemize @bullet
+@item
+In a @file{.cshrc} file, you could set the @code{INFOPATH}
+variable as follows:@refill
+
+@smallexample
+setenv INFOPATH .:~/info:/usr/local/xemacs/info
+@end smallexample
+
+@item
+In a @file{.profile} file, you would achieve the same effect by
+writing:@refill
+
+@smallexample
+INFOPATH=.:$HOME/info:/usr/local/xemacs/info
+export INFOPATH
+@end smallexample
+
+@item
+@pindex autoexec.bat
+In a @file{autoexec.bat} file, you write this command@footnote{Note the
+use of @samp{;} as the directory separator, and a different syntax for
+using values of other environment variables.}:
+
+@smallexample
+set INFOPATH=.;%HOME%/info;c:/usr/local/xemacs/info
+@end smallexample
+@end itemize
+
+@noindent
+The @samp{.} indicates the current directory as usual.  XEmacs uses the
+@code{INFOPATH} environment variable to initialize the value of XEmacs's
+own @code{Info-directory-list} variable.  The stand-alone Info reader
+merges any files named @file{dir} in any directory listed in the
+@env{INFOPATH} variable into a single menu presented to you in the node
+called @samp{(dir)Top}.
+
+@cindex Colon, last in @env{INFOPATH}
+However you set @env{INFOPATH}, if its last character is a
+colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
+is replaced by the default (compiled-in) path.  This gives you a way to
+augment the default path with new directories without having to list all
+the standard places.  For example (using @code{sh} syntax):
+
+@example
+INFOPATH=/local/info:
+export INFOPATH
+@end example
+
+@noindent
+will search @file{/local/info} first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
+@cindex @file{dir} file, creating your own
+When you create your own @file{dir} file for use with
+@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
+copying an existing @file{dir} file and replace all the text after the
+@samp{* Menu:} with your desired entries.  That way, the punctuation and
+special CTRL-_ characters that Info needs will be present.
+
+
+@node Installing Dir Entries
+@subsection Installing Info Directory Files
+
+When you install an Info file onto your system, you can use the program
+@code{install-info} to update the Info directory file @file{dir}.
+Normally the makefile for the package runs @code{install-info}, just
+after copying the Info file into its proper installed location.
+
+@findex dircategory
+@findex direntry
+In order for the Info file to work with @code{install-info}, you include
+the commands @code{@@dircategory} and
+@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
+file.  Use @code{@@direntry} to specify the menu entries to add to the
+Info directory file, and use @code{@@dircategory} to specify which part
+of the Info directory to put it in.  Here is how these commands are used
+in this manual:
+
+@smallexample
+@@dircategory Texinfo documentation system
+@@direntry
+* Texinfo: (texinfo).           The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
+@dots{}
+@@end direntry
+@end smallexample
+
+Here's what this produces in the Info file:
+
+@smallexample
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo).           The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
+@dots{}
+END-INFO-DIR-ENTRY
+@end smallexample
+
+@noindent
+The @code{install-info} program sees these lines in the Info file, and
+that is how it knows what to do.
+
+Always use the @code{@@direntry} and @code{@@dircategory} commands near
+the beginning of the Texinfo input, before the first @code{@@node}
+command.  If you use them later on in the input, @code{install-info}
+will not notice them.
+
+@code{install-info} will automatically reformat the description of the
+menu entries it is adding.  As a matter of convention, the description
+of the main entry (above, @samp{The GNU documentation format}) should
+start at column 32, starting at zero (as in
+@code{what-cursor-position} in XEmacs).  This will make it align with
+most others.  Description for individual utilities best start in
+column 48, where possible.  For more information about formatting see
+the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
+@ref{Invoking install-info}.
+
+If you use @code{@@dircategory} more than once in the Texinfo source,
+each usage specifies the `current' category; any subsequent
+@code{@@direntry} commands will add to that category.
+
+@cindex Free Software Directory
+@cindex Dir categories, choosing
+@cindex Categories, choosing
+When choosing a category name for the @code{@@dircategory} command, we
+recommend consulting the @uref{http://www.gnu.org/directory,
+Free Software Directory}.  If your program is not listed there,
+or listed incorrectly or incompletely, please report the situation to
+the directory maintainers (@email{bug-directory@@gnu.org}) so that the
+category names can be kept in sync.
+
+Here are a few examples (see the @file{util/dir-example} file in the
+Texinfo distribution for large sample @code{dir} file):
+
+@display
+XEmacs
+Localization
+Printing
+Software development
+Software libraries
+Text creation and manipulation
+@end display
+
+@cindex Invoking nodes, including in dir file
+Each `Invoking' node for every program installed should have a
+corresponding @code{@@direntry}.  This lets users easily find the
+documentation for the different programs they can run, as with the
+traditional @command{man} system.
+
+
+@node Invoking install-info
+@subsection Invoking @command{install-info}
+@pindex install-info
+
+@code{install-info} inserts menu entries from an Info file into the
+top-level @file{dir} file in the Info system (see the previous sections
+for an explanation of how the @file{dir} file works).  @code{install-info} 
+also removes menu entries from the @file{dir} file.  It's most often
+run as part of software installation, or when constructing a @file{dir} file
+for all manuals on a system.  Synopsis:
+
+@example
+install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
+@end example
+
+If @var{info-file} or @var{dir-file} are not specified, the options
+(described below) that define them must be.  There are no compile-time
+defaults, and standard input is never used.  @code{install-info} can
+read only one Info file and write only one @file{dir} file per invocation.
+
+@cindex @file{dir}, created by @code{install-info}
+If @var{dir-file} (however specified) does not exist,
+@code{install-info} creates it if possible (with no entries).
+
+@cindex Compressed dir files, reading
+@cindex Bzipped dir files, reading
+@cindex LZMA-compressed dir files, reading
+@cindex Dir files, compressed
+If any input file is compressed with @code{gzip} (@pxref{Top,,,gzip,
+Gzip}), @code{install-info} automatically uncompresses it
+for reading.  And if @var{dir-file} is compressed, @code{install-info}
+also automatically leaves it compressed after writing any changes.
+If @var{dir-file} itself does not exist, @code{install-info} tries to
+open @file{@var{dir-file}.gz}, @file{@var{dir-file}.bz2}, and 
+@file{@var{dir-file}.lzma}, in that order.
+
+Options:
+
+@table @code
+@item --add-once
+Specifies that the entry or entries will only be put into a single section.
+
+@item --align=@var{column}
+@opindex --align=@var{column}
+Specifies the column that the second and subsequent lines of menu entry's 
+description will be formatted to begin at.  The default for this option is 
+@samp{35}.  It is used in conjunction with the @samp{--max-width} option.
+@var{column} starts counting at 1.
+
+@item --append-new-sections
+Instead of alphabetizing new sections, place them at the end of the DIR file.
+
+@item --calign=@var{column}
+@opindex --calign=@var{column}
+Specifies the column that the first line of menu entry's description will 
+be formatted to begin at.  The default for this option is @samp{33}.  It is 
+used in conjunction with the @samp{--max-width} option.
+When the name of the menu entry exceeds this column, entry's description 
+will start on the following line.
+@var{column} starts counting at 1.
+
+@item --debug
+@opindex --debug
+Report what is being done.
+
+@item --delete
+@opindex --delete
+Delete the entries in @var{info-file} from @var{dir-file}.  The file
+name in the entry in @var{dir-file} must be @var{info-file} (except for
+an optional @samp{.info} in either one).  Don't insert any new entries.
+Any empty sections that result from the removal are also removed.
+
+@item --description=@var{text}
+@opindex --description=@var{text}
+Specify the explanatory portion of the menu entry.  If you don't specify
+a description (either via @samp{--entry}, @samp{--item} or this option),
+the description is taken from the Info file itself.
+
+@item --dir-file=@var{name}
+@opindex --dir-file=@var{name}
+Specify file name of the Info directory file.  This is equivalent to
+using the @var{dir-file} argument.
+
+@item --dry-run
+@opindex --dry-run
+Same as @samp{--test}.
+
+@item --entry=@var{text}
+@opindex --entry=@var{text}
+Insert @var{text} as an Info directory entry; @var{text} should have the
+form of an Info menu item line plus zero or more extra lines starting
+with whitespace.  If you specify more than one entry, they are all
+added.  If you don't specify any entries, they are determined from
+information in the Info file itself.
+
+@item --help
+@opindex --help
+Display a usage message with basic usage and all available options,
+then exit successfully.
+
+@item --info-file=@var{file}
+@opindex --info-file=@var{file}
+Specify Info file to install in the directory.  This is
+equivalent to using the @var{info-file} argument.
+
+@item --info-dir=@var{dir}
+@opindex --info-dir=@var{dir}
+Specify the directory where the directory file @file{dir} resides.
+Equivalent to @samp{--dir-file=@var{dir}/dir}.
+
+@item --infodir=@var{dir}
+@opindex --infodir=@var{dir}
+Same as @samp{--info-dir}.
+
+@item --item=@var{text}
+@opindex --item=@var{text}
+Same as @samp{--entry=@var{text}}.  An Info directory entry is actually
+a menu item.
+
+@item --keep-old
+@opindex --keep-old
+Do not replace pre-existing menu entries.  When @samp{--remove} is specified, 
+this option means that empty sections are not removed.
+
+@item --max-width=@var{column}
+@opindex --max-width=@var{column}
+Specifies the column that the menu entry's description will be word-wrapped
+at.  @var{column} starts counting at 1.
+
+@item --maxwidth=@var{column}
+@opindex --maxwidth=@var{column}
+Same as @samp{--max-width}.
+
+@item --menuentry=@var{text}
+@opindex --menuentry=@var{text}
+Same as @samp{--name}.
+
+@item --name=@var{text}
+@opindex --name=@var{text}
+Specify the name portion of the menu entry.  If the @var{text} does
+not start with an asterisk @samp{*}, it is presumed to be the text
+after the @samp{*} and before the parentheses that specify the Info
+file.  Otherwise @var{text} is taken verbatim, and is taken as
+defining the text up to and including the first period (a space is
+appended if necessary).  If you don't specify the name (either via
+@samp{--entry}, @samp{--item} or this option), it is taken from the
+Info file itself.  If the Info does not contain the name, the basename
+of the Info file is used.
+
+@item --no-indent
+@opindex --no-indent
+Suppress formatting of new entries into the @file{dir} file.
+
+@item --quiet
+@opindex --quiet
+@itemx --silent
+@opindex --silent
+Suppress warnings, etc., for silent operation.
+
+@item --remove
+@opindex --remove
+Same as @samp{--delete}.
+
+@item --remove-exactly
+@opindex --remove-exactly
+Also like @samp{--delete}, but only entries if the Info file name
+matches exactly; @code{.info} and/or @code{.gz} suffixes are
+@emph{not} ignored.
+
+@item --section=@var{sec}
+@opindex --section=@var{sec}
+Put this file's entries in section @var{sec} of the directory.  If you
+specify more than one section, all the entries are added in each of the
+sections.  If you don't specify any sections, they are determined from
+information in the Info file itself.  If the Info file doesn't specify
+a section, the menu entries are put into the Miscellaneous section.
+
+@item --section @var{regex} @var{sec}
+@opindex --section @var{regex} @var{sec}
+Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
+
+@code{install-info} tries to detect when this alternate syntax is used, 
+but does not always guess correctly.  Here is the heuristic that 
+@code{install-info} uses:
+@enumerate
+@item
+If the second argument to @code{--section} starts with a hyphen, the
+original syntax is presumed.
+@item
+If the second argument to @code{--section} is a file that can be
+opened, the original syntax is presumed.
+@item
+Otherwise the alternate syntax is used.
+@end enumerate
+
+When heuristic fails because your section title starts with a hyphen, or it 
+happens to be a filename that can be opened, the syntax should be changed 
+to @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
+
+
+@item --regex=@var{regex}
+@opindex  --regex=@var{regex}
+Put this file's entries into any section that matches @var{regex}.  If
+more than one section matches, all of the entries are added in each of the
+sections.  Specify @var{regex} using basic regular expression syntax, more 
+or less as used with @command{grep}, for example.
+
+@item --test
+@opindex --test
+Suppress updating of the directory file.
+
+@item --version
+@opindex --version
+@cindex Version number, for install-info
+Display version information and exit successfully.
+
+@end table
+
+
+@node Generating HTML
+@chapter Generating HTML
+@cindex HTML output
+
+@command{makeinfo} generates Info output by default, but given the
+@option{--html} option, it will generate HTML, for web browsers and
+other programs.  This chapter gives some details on such HTML output.
+
+
+@command{makeinfo} can also write in XML and Docbook format, but we do
+not as yet describe these further.  @xref{Output Formats}, for a brief
+overview of all the output formats.
+
+@menu
+* HTML Translation::       Details of the HTML output.
+* HTML Splitting::         How HTML output is split.
+* HTML CSS::               Influencing HTML output with Cascading Style Sheets.
+* HTML Xref::              Cross-references in HTML output.
+@end menu
+
+
+@node HTML Translation
+@section HTML Translation
+
+@command{makeinfo} will include segments of Texinfo source between
+@code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not
+any of the other conditionals, by default).  Source between
+@code{@@html} and @code{@@end html} is passed without change to the
+output (i.e., suppressing the normal escaping of input @samp{<},
+@samp{>} and @samp{&} characters which have special significance in
+HTML).  @xref{Conditional Commands}.
+
+@opindex --footnote-style@r{, ignored in HTML output}
+The @option{--footnote-style} option is currently ignored for HTML output;
+footnotes are always linked to the end of the output file.
+
+@cindex Navigation bar, in HTML output
+By default, a navigation bar is inserted at the start of each node,
+analogous to Info output.  The @samp{--no-headers} option suppresses
+this if used with @samp{--no-split}.  Header @code{<link>} elements in
+split output can support info-like navigation with browsers like Lynx
+and @w{Emacs W3} which implement this HTML@tie{}1.0 feature.
+
+@cindex HTML output, browser compatibility of
+The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866).
+One exception is that HTML@tie{}3.2 tables are generated from the
+@code{@@multitable} command, but tagged to degrade as well as possible
+in browsers without table support.  The HTML@tie{}4 @samp{lang}
+attribute on the @samp{<html>} attribute is also used.  (Please report
+output from an error-free run of @code{makeinfo} which has browser
+portability problems as a bug.)
+
+
+@node HTML Splitting
+@section HTML Splitting
+@cindex Split HTML output
+@cindex HTML output, split
+
+When splitting output (which is the default), @command{makeinfo}
+writes HTML output into (generally) one output file per Texinfo source
+@code{@@node}.
+
+The output file name is the node name with special characters replaced
+by @samp{-}'s, so it can work as a filename.  In the unusual case of
+two different nodes having the same name after this treatment, they
+are written consecutively to the same file, with HTML anchors so each
+can be referred to separately.  If @command{makeinfo} is run on a
+system which does not distinguish case in filenames, nodes which are
+the same except for case will also be folded into the same output
+file.
+
+When splitting, the HTML output files are written into a subdirectory,
+with the name chosen as follows:
+@enumerate
+@item 
+@command{makeinfo} first tries the subdirectory with the base name
+from @code{@@setfilename} (that is, any extension is removed).  For
+example, HTML output for @code{@@setfilename gcc.info} would be
+written into a subdirectory named @samp{gcc}.
+
+@item
+If that directory cannot be created for any reason, then
+@command{makeinfo} tries appending @samp{.html} to the directory name.
+For example, output for @code{@@setfilename texinfo} would be written
+to @samp{texinfo.html}.
+
+@item
+If the @samp{@var{name}.html} directory can't be
+created either, @code{makeinfo} gives up.
+
+@end enumerate
+
+@noindent In any case, the top-level output file within the directory
+is always named @samp{index.html}.
+
+Monolithic output (@code{--no-split}) is named according to
+@code{@@setfilename} (with any @samp{.info} extension is replaced with
+@samp{.html}) or @code{--output} (the argument is used literally).
+
+
+@node HTML CSS
+@section HTML CSS
+@cindex HTML, and CSS
+@cindex CSS, and HTML output
+@cindex Cascading Style Sheets, and HTML output
+
+Cascading Style Sheets (CSS for short) is an Internet standard for
+influencing the display of HTML documents: see
+@uref{http://www.w3.org/Style/CSS/}.
+
+By default, @command{makeinfo} includes a few simple CSS commands to
+better implement the appearance of some of the environments.  Here 
+are two of them, as an example:
+
+@example
+pre.display @{ font-family:inherit @}
+pre.smalldisplay @{ font-family:inherit; font-size:smaller @}
+@end example
+
+A full explanation of CSS is (far) beyond this manual; please see the
+reference above.  In brief, however, this specification tells the web
+browser to use a `smaller' font size for @code{@@smalldisplay} text,
+and to use the `inherited' font (generally a regular roman typeface)
+for both @code{@@smalldisplay} and @code{@@display}.  By default, the
+HTML @samp{<pre>} command uses a monospaced font.
+
+You can influence the CSS in the HTML output with two
+@command{makeinfo} options: @option{--css-include=@var{file}} and
+@option{--css-ref=@var{url}}.
+
+The option @option{--css-ref=@var{url}} adds to each output HTML file
+a @samp{<link>} tag referencing a CSS at the given @var{url}. This
+allows using external style sheets.
+
+The option @option{--css-include=@var{file}} includes the contents
+@var{file} in the HTML output, as you might expect.  However, the
+details are somewhat tricky, as described in the following, to provide
+maximum flexibility. 
+
+@cindex @@import specifications, in CSS files
+The CSS file may begin with so-called @samp{@@import} directives,
+which link to external CSS specifications for browsers to use when
+interpreting the document.  Again, a full description is beyond our
+scope here, but we'll describe how they work syntactically, so we can
+explain how @command{makeinfo} handles them.
+
+@cindex Comments, in CSS files
+There can be more than one @samp{@@import}, but they have to come
+first in the file, with only whitespace and comments interspersed, no
+normal definitions.  (Technical exception: an @samp{@@charset}
+directive may precede the @samp{@@import}'s.  This does not alter
+@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if
+present.)  Comments in CSS files are delimited by @samp{/* ... */}, as
+in C.  An @samp{@@import} directive must be in one of these two forms:
+
+@example
+@@import url(http://example.org/foo.css);
+@@import "http://example.net/bar.css";
+@end example
+
+As far as @command{makeinfo} is concerned, the crucial characters are
+the @samp{@@} at the beginning and the semicolon terminating the
+directive.  When reading the CSS file, it simply copies any such
+@samp{@@}-directive into the output, as follows:
+
+@itemize
+@item If @var{file} contains only normal CSS declarations, it is
+included after @command{makeinfo}'s default CSS, thus overriding it.
+
+@item If @var{file} begins with @samp{@@import} specifications (see
+below), then the @samp{import}'s are included first (they have to come
+first, according to the standard), and then @command{makeinfo}'s
+default CSS is included.  If you need to override @command{makeinfo}'s
+defaults from an @samp{@@import}, you can do so with the @samp{!@:
+important} CSS construct, as in:
+@example
+pre.smallexample @{ font-size: inherit ! important @}
+@end example
+
+@item If @var{file} contains both @samp{@@import} and inline CSS
+specifications, the @samp{@@import}'s are included first, then
+@command{makeinfo}'s defaults, and lastly the inline CSS from
+@var{file}.
+
+@item Any @@-directive other than @samp{@@import} and @samp{@@charset}
+is treated as a CSS declaration, meaning @command{makeinfo} includes
+its default CSS and then the rest of the file.
+
+@end itemize
+
+If the CSS file is malformed or erroneous, @command{makeinfo}'s output
+is unspecified.  @command{makeinfo} does not try to interpret the
+meaning of the CSS file in any way; it just looks for the special
+@samp{@@} and @samp{;} characters and blindly copies the text into the
+output.  Comments in the CSS file may or may not be included in the
+output.
+
+
+@node HTML Xref
+@section HTML Cross-references
+@cindex HTML cross-references
+@cindex Cross-references, in HTML output
+
+Cross-references between Texinfo manuals in HTML format amount, in the
+end, to a standard HTML @code{<a>} link, but the details are
+unfortunately complex.  This section describes the algorithm used in
+detail, so that Texinfo can cooperate with other programs, such as
+@command{texi2html}, by writing mutually compatible HTML files.
+
+This algorithm may or may not be used for links @emph{within} HTML
+output for a Texinfo file.  Since no issues of compatibility arise in
+such cases, we do not need to specify this.
+
+We try to support references to such ``external'' manuals in both
+monolithic and split forms.  A @dfn{monolithic} (mono) manual is
+entirely contained in one file, and a @dfn{split} manual has a file
+for each node.  (@xref{HTML Splitting}.)
+
+@cindex Dumas, Patrice
+Acknowledgement: this algorithm was primarily devised by Patrice Dumas
+in 2003--04.
+
+@menu
+* Link Basics:       HTML Xref Link Basics.
+* Node Expansion:    HTML Xref Node Name Expansion.
+* Command Expansion: HTML Xref Command Expansion.
+* 8-bit Expansion:   HTML Xref 8-bit Character Expansion.
+* Mismatch:          HTML Xref Mismatch.
+@end menu
+
+
+@node HTML Xref Link Basics
+@subsection HTML Cross-reference Link Basics
+@cindex HTML cross-reference link basics
+
+For our purposes, an HTML link consists of four components: a host
+name, a directory part, a file part, and a target part.  We
+always assume the @code{http} protocol.  For example:
+
+@example
+http://@var{host}/@var{dir}/@var{file}.html#@var{target}
+@end example
+
+The information to construct a link comes from the node name and
+manual name in the cross-reference command in the Texinfo source
+(@pxref{Cross References}), and from @dfn{external information}, which
+is currently simply hardwired.  In the future, it may come from an
+external data file.
+
+We now consider each part in turn.
+
+The @var{host} is hardwired to be the local host.  This could either
+be the literal string @samp{localhost}, or, according to the rules for
+HTML links, the @samp{http://localhost/} could be omitted entirely.
+
+The @var{dir} and @var{file} parts are more complicated, and depend on
+the relative split/mono nature of both the manual being processed and
+the manual that the cross-reference refers to.  The underlying idea is
+that there is one directory for Texinfo manuals in HTML, and a given
+@var{manual} is either available as a monolithic file
+@file{@var{manual}.html}, or a split subdirectory
+@file{@var{manual}/*.html}.  Here are the cases:
+
+@itemize @bullet
+@item
+If the present manual is split, and the referent manual is also split,
+the directory is @samp{../@var{referent/}} and the file is the
+expanded node name (described later).
+
+@item
+If the present manual is split, and the referent manual is mono, the
+directory is @samp{../} and the file is @file{@var{referent}.html}.
+
+@item
+If the present manual is mono, and the referent manual is split, the
+directory is @file{@var{referent}/} and the file is the expanded node
+name.
+
+@item
+If the present manual is mono, and the referent manual is also mono,
+the directory is @file{./} (or just the empty string), and the file is
+@file{@var{referent}.html}.
+
+@end itemize
+
+One exception: the algorithm for node name expansion prefixes the
+string @samp{g_t} when the node name begins with a non-letter.  This
+kludge (due to XHTML rules) is not necessary for filenames, and is
+therefore omitted.
+
+Any directory part in the filename argument of the source
+cross-reference command is ignored.  Thus, @code{@@xref@{,,,../foo@}}
+and @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name.
+This is because any such attempted hardwiring of the directory is very
+unlikely to be useful for both Info and HTML output.
+
+Finally, the @var{target} part is always the expanded node name.
+
+Whether the present manual is split or mono is determined by user
+option; @command{makeinfo} defaults to split, with the
+@option{--no-split} option overriding this.
+
+Whether the referent manual is split or mono is another bit of the
+external information.  For now, @command{makeinfo} simply assumes the
+referent manual is the same as the present manual.
+
+There can be a mismatch between the format of the referent manual that
+the generating software assumes, and the format it's actually present
+in.  @xref{HTML Xref Mismatch}.
+
+
+@node HTML Xref Node Name Expansion
+@subsection HTML Cross-reference Node Name Expansion
+@cindex HTML cross-reference node name expansion
+@cindex node name expansion, in HTML cross-references
+@cindex expansion, of node names in HTML cross-references
+
+As mentioned in the previous section, the key part of the HTML
+cross-reference algorithm is the conversion of node names in the
+Texinfo source into strings suitable for XHTML identifiers and
+filenames.  The restrictions are similar for each: plain ASCII
+letters, numbers, and the @samp{-} and @samp{_} characters are all
+that can be used.  (Although HTML anchors can contain most characters,
+XHTML is more restrictive.)
+
+Cross-references in Texinfo can actually refer either to nodes or
+anchors (@pxref{anchor}), but anchors are treated identically to nodes
+in this context, so we'll continue to say ``node'' names for
+simplicity.
+
+(@@-commands and 8-bit characters are not presently handled by
+@command{makeinfo} for HTML cross-references.  See the next section.)
+
+A special exception: the Top node (@pxref{The Top Node}) is always
+mapped to the file @file{index.html}, to match web server software.
+However, the HTML @emph{target} is @samp{Top}.  Thus (in the split case):
+
+@example
+@@xref@{Top, Introduction,, xemacs, XEmacs User's Manual@}.
+@result{} <a href="xemacs/index.html#Top">
+@end example
+
+@enumerate
+@item
+The standard ASCII letters (a-z and A-Z) are not modified.  All other
+characters are changed as specified below.
+
+@item
+The standard ASCII numbers (0-9) are not modified except when a number
+is the first character of the node name.  In that case, see below.
+
+@item
+Multiple consecutive space, tab and newline characters are transformed
+into just one space.  (It's not possible to have newlines in node
+names with the current implementation, but we specify it anyway, just
+in case.)
+
+@item
+Leading and trailing spaces are removed.
+
+@item
+After the above has been applied, each remaining space character is
+converted into a @samp{-} character.
+
+@item
+Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}},
+where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
+This includes @samp{_}, which is mapped to @samp{_005f}.
+
+@item
+If the node name does not begin with a letter, the literal string
+@samp{g_t} is prefixed to the result.  (Due to the rules above, that
+string can never occur otherwise; it is an arbitrary choice, standing
+for ``GNU Texinfo''.)  This is necessary because XHTML requires that
+identifiers begin with a letter.
+
+@end enumerate
+
+For example:
+
+@example
+@@node A  node --- with _'%
+@result{} A-node-_002d_002d_002d-with-_005f_0027_0025
+@end example
+
+Notice in particular:
+
+@itemize @bullet
+@item @samp{_} @result{} @samp{_005f}
+@item @samp{-} @result{} @samp{_002d}
+@item @samp{A  node} @result{} @samp{A-node}
+@end itemize
+
+On case-folding computer systems, nodes differing only by case will be
+mapped to the same file.  
+
+In particular, as mentioned above, Top always maps to the file
+@file{index.html}.  Thus, on a case-folding system, Top and a node
+named `Index' will both be written to @file{index.html}.
+
+Fortunately, the targets serve to distinguish these cases, since HTML
+target names are always case-sensitive, independent of operating
+system.
+
+
+@node HTML Xref Command Expansion
+@subsection HTML Cross-reference Command Expansion
+@cindex HTML cross-reference command expansion
+
+In standard Texinfo, node names may not contain @@-commands.
+@command{makeinfo} has an option @option{--commands-in-node-names}
+which partially supports it (@pxref{Invoking makeinfo}), but it is not
+robust and not recommended.
+
+Thus, @command{makeinfo} does not fully implement this part of the
+HTML cross-reference algorithm, but it is documented here for the sake
+of completeness.
+
+First, comments are removed.
+
+Next, any @code{@@value} commands (@pxref{set value}) and macro invocations
+(@pxref{Invoking Macros}) are fully expanded.
+
+Then, for the following commands, the command name and braces are removed,
+the text of the argument is recursively transformed:
+@example
+@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
+@@emph @@env @@file @@indicateurl @@kbd @@key
+@@samp @@sc @@slanted @@strong @@t @@var @@w
+@end example
+
+@noindent For @code{@@sc}, any letters are capitalized.
+
+The following commands are replaced by constant text, as shown.  If
+any of these commands have non-empty arguments, as in
+@code{@@TeX@{bad@}}, it is an error, and the result is unspecified.
+`(space)' means a space character, `(nothing)' means the empty string,
+etc.  The notation `U+@var{xxxx}' means Unicode code point @var{xxxx}
+(in hex, as usual).  There are further transformations of many of
+these expansions for the final file or target name, such as space
+characters to @samp{-}, etc., according to the other rules.
+
+@multitable @columnfractions .3 .5
+@item @code{@@(newline)}        @tab (space)
+@item @code{@@(space)}          @tab (space)
+@item @code{@@(tab)}            @tab (space)
+@item @code{@@!}                @tab @samp{!}
+@item @code{@@*}                @tab (space)
+@item @code{@@-}                @tab (nothing)
+@item @code{@@.}                @tab @samp{.}
+@item @code{@@:}                @tab (nothing)
+@item @code{@@?}                @tab @samp{?}
+@item @code{@@@@}               @tab @samp{@@}
+@item @code{@@@{}               @tab @samp{@{}
+@item @code{@@@}}               @tab @samp{@}}
+@item @code{@@LaTeX}            @tab @samp{LaTeX}
+@item @code{@@TeX}              @tab @samp{TeX}
+@item @code{@@arrow}            @tab U+2192
+@item @code{@@bullet}           @tab U+2022
+@item @code{@@comma}            @tab @samp{,}
+@item @code{@@copyright}        @tab U+00A9
+@item @code{@@dots}             @tab U+2026
+@item @code{@@enddots}          @tab @samp{...}
+@item @code{@@equiv}            @tab U+2261
+@item @code{@@error}            @tab @samp{error-->}
+@item @code{@@euro}             @tab U+20AC
+@item @code{@@exclamdown}       @tab U+00A1
+@item @code{@@expansion}        @tab U+2192
+@item @code{@@geq}              @tab U+2265
+@item @code{@@leq}              @tab U+2264
+@item @code{@@minus}            @tab U+2212
+@item @code{@@ordf}             @tab U+00AA
+@item @code{@@ordm}             @tab U+00BA
+@item @code{@@point}            @tab U+2605
+@item @code{@@pounds}           @tab U+00A3
+@item @code{@@print}            @tab U+22A3
+@item @code{@@questiondown}     @tab U+00BF
+@item @code{@@registeredsymbol} @tab U+00AE
+@item @code{@@result}           @tab U+21D2
+@item @code{@@textdegree}       @tab U+00B0
+@item @code{@@tie}              @tab (space)
+@end multitable
+
+Quotation mark commands are likewise replaced by their Unicode values
+(@pxref{Inserting Quotation Marks}).
+
+An @code{@@acronym} or @code{@@abbr} command is replaced by the first
+argument, followed by the second argument in parentheses, if present.
+@xref{acronym}.
+
+An @code{@@email} command is replaced by the @var{text} argument if
+present, else the address.  @xref{email}.
+
+An @code{@@image} command is replaced by the filename (first)
+argument.  @xref{Images}.
+
+A @code{@@verb} command is replaced by its transformed argument.
+@xref{verb}.
+
+Any other command is an error, and the result is unspecified.
+
+
+@node HTML Xref 8-bit Character Expansion
+@subsection HTML Cross-reference 8-bit Character Expansion
+@cindex HTML cross-reference 8-bit character expansion
+@cindex 8-bit characters, in HTML cross-references
+@cindex Expansion of 8-bit characters in HTML cross-references
+@cindex Transliteration of 8-bit characters in HTML cross-references
+
+Usually, characters other than plain 7-bit ASCII are transformed into
+the corresponding Unicode code point(s) in Normalization Form C, which
+uses precomposed characters where available.  (This is the
+normalization form recommended by the W3C and other bodies.)  This
+holds when that code point is 0xffff or less, as it almost always is.
+
+These will then be further transformed by the rules above into the
+string @samp{_@var{xxxx}}, where @var{xxxx} is the code point in hex.
+
+For example, combining this rule and the previous section:
+
+@example
+@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@}
+@result{} A-TeX-B_0306-_2605_002e_002e_002e
+@end example
+
+Notice: 1)@tie{}@code{@@enddots} expands to three periods which in
+turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B'
+with a breve accent, which does not exist as a pre-accented Unicode
+character, therefore expands to @samp{B_0306} (B with combining
+breve).
+
+When the Unicode code point is above 0xffff, the transformation is
+@samp{__@var{xxxxxx}}, that is, two leading underscores followed by
+six hex digits.  Since Unicode has declared that their highest code
+point is 0x10ffff, this is sufficient.  (We felt it was better to
+define this extra escape than to always use six hex digits, since the
+first two would nearly always be zeros.)
+
+This method works fine if the node name consists mostly of ASCII
+characters and contains only few 8-bit ones. If the document is
+written in a language whose script is not based on the Latin alphabet
+(such as, e.g. Ukrainian), it will create file names consisting
+entirely of @samp{_@var{xxxx}} notations, which is inconvenient.
+
+To handle such cases, @command{makeinfo} offers
+@option{--transliterate-file-names} command line option. This option
+enables @dfn{transliteration} of node names into ASCII characters for
+the purposes of file name creation and referencing. The
+transliteration is based on phonetic principle, which makes the
+produced file names easily readable.
+
+For the definition of Unicode Normalization Form C, see Unicode report
+UAX#15, @uref{http://www.unicode.org/reports/tr15/}.  Many related
+documents and implementations are available elsewhere on the web.
+
+
+@node HTML Xref Mismatch
+@subsection HTML Cross-reference Mismatch
+@cindex HTML cross-reference mismatch
+@cindex Mismatched HTML cross-reference source and target
+
+As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
+software has to guess whether a given manual being cross-referenced is
+available in split or monolithic form---and, inevitably, it might
+guess wrong.  However, it is possible when the referent manual itself
+is generated, it is possible to handle at least some mismatches.
+
+In the case where we assume the referent is split, but it is actually
+available in mono, the only recourse would be to generate a
+@file{manual/} subdirectory full of HTML files which redirect back to
+the monolithic @file{manual.html}.  Since this is essentially the same
+as a split manual in the first place, it's not very appealing.
+
+On the other hand, in the case where we assume the referent is mono,
+but it is actually available in split, it is possible to use
+JavaScript to redirect from the putatively monolithic
+@file{manual.html} to the different @file{manual/node.html} files.
+Here's an example:
+
+@example
+function redirect() @{
+  switch (location.hash) @{
+    case "#Node1":
+      location.replace("manual/Node1.html#Node1"); break;
+    case "#Node2" :
+      location.replace("manual/Node2.html#Node2"); break;
+    @dots{}
+    default:;
+  @}
+@}
+@end example
+
+Then, in the @code{<body>} tag of @file{manual.html}:
+
+@example
+<body onLoad="redirect();">
+@end example
+
+Once again, this is something the software which generated the
+@emph{referent} manual has to do in advance, it's not something the
+software generating the actual cross-reference in the present manual
+can control.
+
+Ultimately, we hope to allow for an external configuration file to
+control which manuals are available from where, and how.
+
+
+@ignore
+-- not yet --
+
+external information
+--------------------
+
+The information for the reference is searched in the file
+`htmlxref.cnf' present in the following directories:
+<srcdir>/.texinfo/, ~/.texinfo/,  SYSCONFDIR/texinfo/,
+DATADIR/texinfo/
+The first match should be used.
+
+The file is line-oriented, with the following format:
+  <manualname> <whitespace> <keyword> <whitespace> <urlprefix>
+with <keyword> being "mono" or "split". Thus
+texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/
+texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
+
+If the keyword is 'split', that is the target is split, the urlprefix gives 
+the directory and host name.
+If the keyword is 'mono', that is the target is mono, the urlprefix gives 
+directory, host and file name.
+
+'#' followed by a space begins comments. '#' followed by another character
+cannot begin comments as there are # in urls.
+
+@end ignore
+
+
+@node Command List
+@appendix @@-Command List
+@cindex Alphabetical @@-command list
+@cindex List of  @@-commands
+@cindex @@-command list
+@cindex Reference to @@-commands
+
+Here is an alphabetical list of the @@-commands in Texinfo.  Square
+brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
+@samp{@dots{}}, indicates repeated text.
+
+More specifics on the general syntax of different @@-commands are
+given in the section below.
+
+@menu
+* Command Syntax::    General syntax for varieties of @@-commands.
+@end menu
+
+@sp 1
+@table @code
+@item @@@var{whitespace}
+An @code{@@} followed by a space, tab, or newline produces a normal,
+stretchable, interword space.  @xref{Multiple Spaces}.
+
+@item @@!
+Produce an exclamation point that ends a sentence (usually after an
+end-of-sentence capital letter).  @xref{Ending a Sentence}.
+
+@item @@"
+@itemx @@'
+Generate an umlaut or acute accent, respectively, over the next
+character, as in @"o and @'o.  @xref{Inserting Accents}.
+
+@item @@*
+Force a line break.  @xref{Line Breaks}.
+
+@item @@,@{@var{c}@}
+Generate a cedilla accent under @var{c}, as in @,{c}.  @xref{Inserting
+Accents}.
+
+@item @@-
+Insert a discretionary hyphenation point.  @xref{- and hyphenation}.
+
+@item @@.
+Produce a period that ends a sentence (usually after an
+end-of-sentence capital letter).  @xref{Ending a Sentence}.
+
+@item @@/
+Produces no output, but allows a line break.  @xref{Line Breaks}.
+
+@item @@:
+Tell @TeX{} to refrain from inserting extra whitespace after an
+immediately preceding period, question mark, exclamation mark, or
+colon, as @TeX{} normally would.  @xref{Not Ending a Sentence}.
+
+@item @@=
+Generate a macron (bar) accent over the next character, as in @=o.
+@xref{Inserting Accents}.
+
+@item @@?
+Produce a question mark that ends a sentence (usually after an
+end-of-sentence capital letter).  @xref{Ending a Sentence}.
+
+@item @@@@
+Stands for an at sign, @samp{@@}.
+@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
+
+@item @@\
+Stands for a backslash (@samp{\}) inside @code{@@math}.
+@xref{math,,@code{math}}.
+
+@item @@^
+@itemx @@`
+Generate a circumflex (hat) or grave accent, respectively, over the next
+character, as in @^o and @`e.
+@xref{Inserting Accents}.
+
+@item @@@{
+Stands for a left brace, @samp{@{}.
+@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
+
+@item @@@}
+Stands for a right-hand brace, @samp{@}}.@*
+@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
+
+@item @@~
+Generate a tilde accent over the next character, as in @~N.
+@xref{Inserting Accents}.
+
+@item @@AA@{@}
+@itemx @@aa@{@}
+Generate the uppercase and lowercase Scandinavian A-ring letters,
+respectively: @AA{}, @aa{}.  @xref{Inserting Accents}.
+
+@item @@abbr@{@var{abbreviation}@}
+Indicate a general abbreviation, such as `Comput.'.  @xref{abbr,,
+@code{abbr}}.
+
+@item @@acronym@{@var{acronym}@}
+Indicate an acronym in all capital letters, such as `NASA'.
+@xref{acronym,, @code{acronym}}.
+
+@item @@AE@{@}
+@itemx @@ae@{@}
+Generate the uppercase and lowercase AE ligatures, respectively:
+@AE{}, @ae{}.  @xref{Inserting Accents}.
+
+@itemx @@afivepaper
+Change page dimensions for the A5 paper size.  @xref{A4 Paper}.
+
+@item @@afourlatex
+@itemx @@afourpaper
+@itemx @@afourwide
+Change page dimensions for the A4 paper size.  @xref{A4 Paper}.
+
+@item @@alias @var{new}=@var{existing}
+Make the command @samp{@@@var{new}} a synonym for the existing command
+@samp{@@@var{existing}}.  @xref{alias}.
+
+@item @@anchor@{@var{name}@}
+Define @var{name} as the current location for use as a cross-reference
+target.  @xref{anchor,, @code{@@anchor}}.
+
+@item @@appendix @var{title}
+Begin an appendix.  The title appears in the table of contents.  In
+Info, the title is underlined with asterisks.  @xref{unnumbered &
+appendix, , The @code{@@unnumbered} and @code{@@appendix} Commands}.
+
+@item @@appendixsec @var{title}
+@itemx @@appendixsection @var{title}
+Begin an appendix section within an appendix.  The section title
+appears in the table of contents.  In Info, the title is underlined
+with equal signs.  @code{@@appendixsection} is a longer spelling of
+the @code{@@appendixsec} command.  @xref{unnumberedsec appendixsec
+heading, , Section Commands}.
+
+@item @@appendixsubsec @var{title}
+Begin an appendix subsection.  The title appears in the table of
+contents.  In Info, the title is underlined with hyphens.
+@xref{unnumberedsubsec appendixsubsec subheading, , Subsection
+Commands}.
+
+@item @@appendixsubsubsec @var{title}
+Begin an appendix subsubsection.  The title appears in the table of
+contents.  In Info, the title is underlined with periods.
+@xref{subsubsection,, The `subsub' Commands}.
+
+@item @@arrow@{@}
+Generate a right arrow glyph: @samp{@arrow{}}.  Used by default
+for @code{@@click}.  @xref{Click Sequences}.
+
+@item @@asis
+Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
+print the table's first column without highlighting (``as is'').
+@xref{Two-column Tables}.
+
+@item @@author @var{author}
+Typeset @var{author} flushleft and underline it.  @xref{title
+subtitle author, , The @code{@@title} and @code{@@author}
+Commands}.@refill
+
+@item @@b@{@var{text}@}
+Set @var{text} in a @b{bold} font.  No effect in Info.  @xref{Fonts}.
+
+@ignore
+@item @@br
+Force a paragraph break.  If used within a line, follow @code{@@br}
+with braces.  @xref{br, , @code{@@br}}.@refill
+@end ignore
+
+@item @@bullet@{@}
+Generate a large round dot, @bullet{} (@samp{*} in Info).  Often used
+with @code{@@table}.  @xref{bullet, , @code{@@bullet}}.
+
+@item @@bye
+Stop formatting a file.  The formatters do not see anything in the 
+input file following @code{@@bye}.  @xref{Ending a File}.
+
+@item @@c @var{comment}
+Begin a comment in Texinfo.  The rest of the line does not appear in
+any output.  A synonym for
+@code{@@comment}.  @xref{Comments}.
+
+@item @@caption
+Define the full caption for a @code{@@float}.  @xref{caption shortcaption}.
+
+@item @@cartouche
+Highlight an example or quotation by drawing a box with rounded
+corners around it.  Pair with @code{@@end cartouche}.  No effect in
+Info.  @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
+
+@item @@center @var{line-of-text}
+Center the line of text following the command.
+@xref{titlefont center sp, , @code{@@center}}.@refill
+
+@item @@centerchap @var{line-of-text}
+Like @code{@@chapter}, but centers the chapter title.  @xref{chapter,,
+@code{@@chapter}}.
+
+@item @@chapheading @var{title}
+Print an unnumbered chapter-like heading, but omit from the table of
+contents.  In Info, the title is underlined with asterisks.
+@xref{majorheading & chapheading, , @code{@@majorheading} and
+@code{@@chapheading}}.
+
+@item @@chapter @var{title}
+Begin a numbered chapter.  The chapter title appears in the table of
+contents.  In Info, the title is underlined with asterisks.
+@xref{chapter, , @code{@@chapter}}.
+
+@item @@cindex @var{entry}
+Add @var{entry} to the index of concepts.  @xref{Index Entries, ,
+Defining the Entries of an Index}.@refill
+
+@item @@cite@{@var{reference}@}
+Highlight the name of a book or other reference that has no companion
+Info file.  @xref{cite, , @code{@@cite}}.
+
+@item @@click@{@}
+Represent a single ``click'' in a GUI.  Used within
+@code{@@clicksequence}.  @xref{Click Sequences}.
+
+@item @@clicksequence@{@var{action} @@click@{@} @var{action}@}
+Represent a sequence of clicks in a GUI.  @xref{Click Sequences}.
+
+@item @@clickstyle @@@var{cmd}
+Execute @@@var{cmd} for each @code{@@click}; the default is
+@code{@@arrow}.  The usual following empty braces on @@@var{cmd} are
+omitted.  @xref{Click Sequences}.
+
+@item @@clear @var{flag}
+Unset @var{flag}, preventing the Texinfo formatting commands from
+formatting text between subsequent pairs of @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, and preventing
+@code{@@value@{@var{flag}@}} from expanding to the value to which
+@var{flag} is set.
+@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
+
+@item @@code@{@var{sample-code}@}
+Indicate an expression, a syntactically complete token of a program,
+or a program name.  Unquoted in Info output.  @xref{code, ,
+@code{@@code}}.
+
+@item @@comma@{@}
+Insert a comma `,' character; only needed when a literal comma would
+be taken as an argument separator.  @xref{Inserting a Comma}.
+
+@item @@command@{@var{command-name}@}
+Indicate a command name, such as @command{ls}.
+@xref{command,, @code{@@command}}.
+
+@item @@comment @var{comment}
+Begin a comment in Texinfo.  The rest of the line does not appear in
+any output.  A synonym for @code{@@c}.
+@xref{Comments}.
+
+@item @@contents
+Print a complete table of contents.  Has no effect in Info, which uses
+menus instead.  @xref{Contents, , Generating a Table of
+Contents}.@refill
+
+@item @@copyright@{@}
+Generate the copyright symbol @copyright{}.  @xref{copyright symbol,,
+@code{@@copyright@{@}}}.
+
+@ignore
+@item @@ctrl@{@var{ctrl-char}@}
+Describe an ASCII control character.  Insert actual control character
+into Info file.  @xref{ctrl, , @code{@@ctrl}}.
+@end ignore
+
+@item @@defcodeindex @var{index-name}
+Define a new index and its indexing command.  Print entries in an
+@code{@@code} font.  @xref{New Indices, , Defining New Indices}.
+
+@item @@defcv @var{category} @var{class} @var{name}
+@itemx @@defcvx @var{category} @var{class} @var{name}
+Format a description for a variable associated with a class in
+object-oriented programming.  Takes three arguments: the category of
+thing being defined, the class to which it belongs, and its name.
+@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
+@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
+@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
+Format a description for a function, interactive command, or similar
+entity that may take arguments.  @code{@@deffn} takes as arguments the
+category of entity being described, the name of this particular
+entity, and its arguments, if any.  @xref{Definition Commands}.@refill
+
+@item @@defindex @var{index-name}
+Define a new index and its indexing command.  Print entries in a roman
+font.  @xref{New Indices, , Defining New Indices}.@refill
+
+@item @@definfoenclose @var{newcmd}, @var{before}, @var{after}
+Must be used within @code{@@ifinfo}; create a new command
+@code{@@@var{newcmd}} for Info that marks text by enclosing it in
+strings that precede and follow the text.  @xref{definfoenclose}.
+
+@item @@defivar @var{class} @var{instance-variable-name}
+@itemx @@defivarx @var{class} @var{instance-variable-name}
+Format a description for an instance variable in object-oriented
+programming.  The command is equivalent to @samp{@@defcv @{Instance
+Variable@} @dots{}}.  @xref{Definition Commands}, and @ref{deffnx,,
+Def Cmds in Detail}.
+
+@item @@defmac @var{macroname} @var{arguments}@dots{}
+@itemx @@defmacx @var{macroname} @var{arguments}@dots{}
+Format a description for a macro; equivalent to @samp{@@deffn Macro
+@dots{}}.  @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
+Detail}.
+
+@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
+@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
+Format a description for a method in object-oriented programming;
+equivalent to @samp{@@defop Method @dots{}}.  @xref{Definition
+Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
+@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
+@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
+Format a description for an operation in object-oriented programming.
+@code{@@defop} takes as arguments the name of the category of
+operation, the name of the operation's class, the name of the
+operation, and its arguments, if any.  @xref{Definition Commands}, and
+@ref{Abstract Objects}.
+
+@item @@defopt @var{option-name}
+@itemx @@defoptx @var{option-name}
+Format a description for a user option; equivalent to @samp{@@defvr
+@{User Option@} @dots{}}.  @xref{Definition Commands}, and
+@ref{deffnx,, Def Cmds in Detail}.
+
+@item @@defspec @var{special-form-name} @var{arguments}@dots{}
+@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
+Format a description for a special form; equivalent to @samp{@@deffn
+@{Special Form@} @dots{}}.  @xref{Definition Commands}, and
+@ref{deffnx,, Def Cmds in Detail}.
+
+@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
+@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
+Format a description for a data type; its arguments are the category,
+the name of the type (e.g., @samp{int}) , and then the names of
+attributes of objects of that type.  @xref{Definition Commands}, and
+@ref{Data Types}.
+
+@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
+@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name}
+Format a description for a typed class variable in object-oriented programming.
+@xref{Definition Commands}, and @ref{Abstract Objects}.
+
+@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
+@itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
+Format a description for a function or similar entity that may take
+arguments and that is typed.  @code{@@deftypefn} takes as arguments the
+category of entity being described, the type, the name of the
+entity, and its arguments, if any.  @xref{Definition Commands}, and
+@ref{deffnx,, Def Cmds in Detail}.
+
+@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
+@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
+Format a description for a function in a typed language.
+The command is equivalent to @samp{@@deftypefn Function @dots{}}.
+@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
+@item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
+@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
+Format a description for a typed instance variable in object-oriented
+programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
+
+@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
+@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
+Format a description for a typed method in object-oriented programming.
+@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
+@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
+@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
+Format a description for a typed operation in object-oriented programming.
+@xref{Definition Commands}, and @ref{Abstract Objects}.
+
+@item @@deftypevar @var{data-type} @var{variable-name}
+@itemx @@deftypevarx @var{data-type} @var{variable-name}
+Format a description for a variable in a typed language.  The command is
+equivalent to @samp{@@deftypevr Variable @dots{}}.  @xref{Definition
+Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
+@item @@deftypevr @var{category} @var{data-type} @var{name}
+@itemx @@deftypevrx @var{category} @var{data-type} @var{name}
+Format a description for something like a variable in a typed
+language---an entity that records a value.  Takes as arguments the
+category of entity being described, the type, and the name of the
+entity.  @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
+Detail}.
+
+@item @@defun @var{function-name} @var{arguments}@dots{}
+@itemx @@defunx @var{function-name} @var{arguments}@dots{}
+Format a description for a function; equivalent to
+@samp{@@deffn Function @dots{}}.  @xref{Definition Commands}, and
+@ref{deffnx,, Def Cmds in Detail}.
+
+@item @@defvar @var{variable-name}
+@itemx @@defvarx @var{variable-name}
+Format a description for a variable; equivalent to @samp{@@defvr
+Variable @dots{}}.  @xref{Definition Commands}, and @ref{deffnx,, Def
+Cmds in Detail}.
+
+@item @@defvr @var{category} @var{name}
+@itemx @@defvrx @var{category} @var{name}
+Format a description for any kind of variable.  @code{@@defvr} takes
+as arguments the category of the entity and the name of the entity.
+@xref{Definition Commands},
+and @ref{deffnx,, Def Cmds in Detail}.
+
+@item @@detailmenu
+Mark the (optional) detailed node listing in a master menu.
+@xref{Master Menu Parts}.
+
+@item @@dfn@{@var{term}@}
+Indicate the introductory or defining use of a term.  @xref{dfn, ,
+@code{@@dfn}}.
+
+@item @@dircategory @var{dirpart}
+Specify a part of the Info directory menu where this file's entry should
+go.  @xref{Installing Dir Entries}.
+
+@item @@direntry
+Begin the Info directory menu entry for this file.  Pair with
+@code{@@end direntry}.  @xref{Installing Dir Entries}.
+
+@item @@display
+Begin a kind of example.  Like @code{@@example} (indent text, do not
+fill), but do not select a new font.  Pair with @code{@@end display}.
+@xref{display, , @code{@@display}}.
+
+@item @@dmn@{@var{dimension}@}
+Format a unit of measure, as in 12@dmn{pt}.  Causes @TeX{} to insert a
+thin space before @var{dimension}.  No effect in Info.
+@xref{dmn, , @code{@@dmn}}.
+
+@item @@docbook
+Enter Docbook completely.  Pair with @code{@@end docbook}.  @xref{Raw
+Formatter Commands}.
+
+@item @@documentdescription
+Set the document description text, included in the HTML output.  Pair
+with @code{@@end documentdescription}.  @xref{documentdescription,,
+@code{@@documentdescription}}.
+
+@item @@documentencoding @var{enc}
+Declare the input encoding to be @var{enc}.
+@xref{documentencoding,, @code{@@documentencoding}}.
+
+@item @@documentlanguage @var{CC}
+Declare the document language as the two-character ISO-639 abbreviation
+@var{CC}.  @xref{documentlanguage,, @code{@@documentlanguage}}.
+
+@item @@dotaccent@{@var{c}@}
+Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
+@xref{Inserting Accents}.
+
+@item @@dots@{@}
+Generate an ellipsis, @samp{@dots{}}.
+@xref{dots, , @code{@@dots}}.@refill
+
+@item @@email@{@var{address}[, @var{displayed-text}]@}
+Indicate an electronic mail address.
+@xref{email, , @code{@@email}}.
+
+@item @@emph@{@var{text}@}
+Emphasize @var{text}, by using @emph{italics} where possible, and
+enclosing in asterisks in Info.  @xref{Emphasis, , Emphasizing Text}.
+
+@item @@end @var{environment}
+Ends @var{environment}, as in @samp{@@end example}.  @xref{Formatting
+Commands,,@@-commands}.
+
+@item @@env@{@var{environment-variable}@}
+Indicate an environment variable name, such as @env{PATH}.
+@xref{env,, @code{@@env}}.
+
+@item @@enddots@{@}
+Generate an end-of-sentence ellipsis, like this: @enddots{}
+@xref{dots,,@code{@@dots@{@}}}.
+
+@item @@enumerate [@var{number-or-letter}]
+Begin a numbered list, using @code{@@item} for each entry.
+Optionally, start list with @var{number-or-letter}.  Pair with
+@code{@@end enumerate}.  @xref{enumerate, ,
+@code{@@enumerate}}.@refill
+
+@item @@equiv@{@}
+Indicate to the reader the exact equivalence of two forms with a
+glyph: @samp{@equiv{}}.  @xref{Equivalence}.@refill
+
+@item @@euro@{@}
+Generate the Euro currency sign.
+@xref{euro,,@code{@@euro@{@}}}.
+
+@item @@error@{@}
+Indicate to the reader with a glyph that the following text is
+an error message: @samp{@error{}}.  @xref{Error Glyph}.@refill
+
+@item  @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
+@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
+Specify page footings resp.@: headings for even-numbered (left-hand)
+pages.  @xref{Custom Headings, ,
+How to Make Your Own Headings}.@refill
+
+@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
+@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
+Specify page footings resp.@: headings for every page.  Not relevant to
+Info.  @xref{Custom Headings, , How to Make Your Own Headings}.
+
+@item @@example
+Begin an example.  Indent text, do not fill, and select fixed-width
+font.  Pair with @code{@@end example}.  @xref{example,, @code{@@example}}.
+
+@item @@exampleindent @var{indent}
+Indent example-like environments by @var{indent} number of spaces
+(perhaps 0).  @xref{exampleindent,, Paragraph Indenting}.
+
+@item @@exclamdown@{@}
+Generate an upside-down exclamation point.  @xref{Inserting Accents}.
+
+@item @@exdent @var{line-of-text}
+Remove any indentation a line might have.  @xref{exdent, ,
+Undoing the Indentation of a Line}.@refill
+
+@item @@expansion@{@}
+Indicate the result of a macro expansion to the reader with a special
+glyph: @samp{@expansion{}}.
+@xref{expansion, , @expansion{} Indicating an Expansion}.@refill
+
+@item @@file@{@var{filename}@}
+Highlight the name of a file, buffer, node, directory, etc.  @xref{file, ,
+@code{@@file}}.
+
+@item @@finalout
+Prevent @TeX{} from printing large black warning rectangles beside
+over-wide lines.  @xref{Overfull hboxes}.@refill
+
+@item @@findex @var{entry}
+Add @var{entry} to the index of functions.  @xref{Index Entries, ,
+Defining the Entries of an Index}.@refill
+
+@item @@float
+Environment to define floating material.  Pair with @code{@@end float}.
+@xref{Floats}.
+
+@item @@flushleft
+@itemx @@flushright
+Do not fill text; left (right) justify every line while leaving the
+right (left) end ragged.  Leave font as is.  Pair with @code{@@end
+flushleft} (@code{@@end flushright}).  @code{@@flushright} analogous.
+@xref{flushleft & flushright, , @code{@@flushleft} and
+@code{@@flushright}}.
+
+@item @@footnote@{@var{text-of-footnote}@}
+Enter a footnote.  Footnote text is printed at the bottom of the page
+by @TeX{}; Info may format in either `End' node or `Separate' node style.
+@xref{Footnotes}.
+
+@item @@footnotestyle @var{style}
+Specify an Info file's footnote style, either @samp{end} for the end
+node style or @samp{separate} for the separate node style.
+@xref{Footnotes}.
+
+@item @@format
+Begin a kind of example.  Like @code{@@display}, but do not indent.
+Pair with @code{@@end format}.  @xref{example,, @code{@@example}}.
+
+@item @@ftable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of functions.  Pair with @code{@@end ftable}.  The same as
+@code{@@table}, except for indexing.  @xref{ftable vtable, ,
+@code{@@ftable} and @code{@@vtable}}.@refill
+
+@item @@geq@{@}
+Generate a greater-than-or-equal sign, `@geq{}'.  @xref{geq leq}.
+
+@item @@group
+Disallow page breaks within following text.  Pair with @code{@@end
+group}.  Ignored in Info.  @xref{group, , @code{@@group}}.
+
+@item @@H@{@var{c}@}
+Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
+
+@item @@heading @var{title}
+Print an unnumbered section-like heading, but omit from the table of
+contents.  In Info, the title is underlined with equal signs.
+@xref{unnumberedsec appendixsec heading, , Section Commands}.
+
+@item @@headings @var{on-off-single-double}
+Turn page headings on or off, and/or specify single-sided or double-sided
+page headings for printing.  @xref{headings on off, , The
+@code{@@headings} Command}.
+
+@item @@headitem
+Begin a heading row in a multitable.  @xref{Multitable Rows}.
+
+@item @@html
+Enter HTML completely.  Pair with @code{@@end html}.  @xref{Raw
+Formatter Commands}.
+
+@item @@hyphenation@{@var{hy-phen-a-ted words}@}
+Explicitly define hyphenation points.  @xref{- and hyphenation,,
+@code{@@-} and @code{@@hyphenation}}.
+
+@item @@i@{@var{text}@}
+Set @var{text} in an @i{italic} font.  No effect in Info.  @xref{Fonts}.
+
+@item @@ifclear @var{txivar}
+If the Texinfo variable @var{txivar} is not set, format the following
+text.  Pair with @code{@@end ifclear}.  @xref{set clear value, ,
+@code{@@set} @code{@@clear} @code{@@value}}.
+
+@item @@ifdocbook
+@itemx @@ifhtml
+@itemx @@ifinfo
+Begin text that will appear only in the given output format.
+@code{@@ifinfo} output appears in both Info and (for historical
+compatibility) plain text output.  Pair with @code{@@end ifdocbook}
+resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
+@xref{Conditionals}.
+
+@item @@ifnotdocbook
+@itemx @@ifnothtml
+@itemx @@ifnotplaintext
+@itemx @@ifnottex
+@itemx @@ifnotxml
+Begin text to be ignored in one output format but not the others.
+@code{@@ifnothtml} text is omitted from HTML output, etc.  Pair with
+the corresponding @code{@@end ifnot@var{format}}.
+@xref{Conditionals}.
+
+@itemx @@ifnotinfo
+Begin text to appear in output other than Info and (for historical
+compatibility) plain text.  Pair with @code{@@end ifnotinfo}.
+@xref{Conditionals}.
+
+@item @@ifplaintext
+Begin text that will appear only in the plain text output.
+Pair with @code{@@end ifplaintext}.  @xref{Conditionals}.
+
+@item @@ifset @var{txivar}
+If the Texinfo variable @var{txivar} is set, format the following
+text.  Pair with @code{@@end ifset}.  @xref{set clear value, ,
+@code{@@set} @code{@@clear} @code{@@value}}.
+
+@item @@iftex
+Begin text to appear only in the @TeX{} output.  Pair with @code{@@end
+iftex}.  @xref{Conditionals, , Conditionally Visible Text}.@refill
+
+@item @@ifxml
+Begin text that will appear only in the XML output.  Pair with
+@code{@@end ifxml}.  @xref{Conditionals}.
+
+@item @@ignore
+Begin text that will not appear in any output.  Pair with @code{@@end
+ignore}.  @xref{Comments, , Comments and Ignored Text}.
+
+@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
+Include graphics image in external @var{filename} scaled to the given
+@var{width} and/or @var{height}, using @var{alt} text and looking for
+@samp{@var{filename}.@var{ext}} in HTML.  @xref{Images}.
+
+@item @@include @var{filename}
+Read the contents of Texinfo source file @var{filename}.  @xref{Include Files}.
+
+@item @@indicateurl@{@var{indicateurl}@}
+Indicate text that is a uniform resource locator for the World Wide
+Web.  @xref{indicateurl, , @code{@@indicateurl}}.
+
+@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
+Make a cross reference to an Info file for which there is no printed
+manual.  @xref{inforef, , Cross references using
+@code{@@inforef}}.@refill
+
+@item \input @var{macro-definitions-file}
+Use the specified macro definitions file.  This command is used only
+in the first line of a Texinfo file to cause @TeX{} to make use of the
+@file{texinfo} macro definitions file.  The backslash in @code{\input}
+is used instead of an @code{@@} because @TeX{} does not
+recognize @code{@@} until after it has read the definitions file.
+@xref{Texinfo File Header}.
+
+@item @@item
+Indicate the beginning of a marked paragraph for @code{@@itemize} and
+@code{@@enumerate}; indicate the beginning of the text of a first column
+entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
+@xref{Lists and Tables}.
+
+@item @@itemize @var{mark-generating-character-or-command}
+Begin an unordered list: indented paragraphs with a mark, such as
+@code{@@bullet}, inside the left margin at the beginning of each
+item.  Pair with @code{@@end itemize}.  @xref{itemize, ,
+@code{@@itemize}}.
+
+@item @@itemx
+Like @code{@@item} but do not generate extra vertical space above the
+item text.  Thus, when several items have the same description, use
+@code{@@item} for the first and @code{@@itemx} for the others.
+@xref{itemx, , @code{@@itemx}}.
+
+@item @@kbd@{@var{keyboard-characters}@}
+Indicate characters of input to be typed by users.  @xref{kbd, ,
+@code{@@kbd}}.
+
+@item @@kbdinputstyle @var{style}
+Specify when @code{@@kbd} should use a font distinct from
+@code{@@code}.  @xref{kbd, , @code{@@kbd}}.
+
+@item @@key@{@var{key-name}@}
+Indicate the name of a key on a keyboard.  @xref{key, , @code{@@key}}.
+
+@item @@kindex @var{entry}
+Add @var{entry} to the index of keys.
+@xref{Index Entries, , Defining the Entries of an Index}.@refill
+
+@item @@L@{@}
+@itemx @@l@{@}
+Generate the uppercase and lowercase Polish suppressed-L letters,
+respectively: @L{}, @l{}.
+
+@item @@LaTeX@{@}
+Generate the @LaTeX{} logo.  @xref{tex, , @TeX{} and @LaTeX{}}.
+
+@item @@leq@{@}
+Generate a less-than-or-equal sign, `@leq{}'.  @xref{geq leq}.
+
+@item @@lisp
+Begin an example of Lisp code.  Indent text, do not fill, and select
+fixed-width font.  Pair with @code{@@end lisp}.  @xref{lisp, , @code{@@lisp}}.
+
+@item @@listoffloats
+Produce a table-of-contents-like listing of @code{@@float}s.
+@xref{listoffloats}.
+
+@item @@lowersections
+Change subsequent chapters to sections, sections to subsections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
+@code{@@lowersections}}.@refill
+
+@item @@macro @var{macroname} @{@var{params}@}
+Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
+Pair with @code{@@end macro}.  @xref{Defining Macros}.
+
+@item @@majorheading @var{title}
+Print an unnumbered chapter-like heading, but omit from
+the table of contents.  This generates more vertical whitespace before
+the heading than the @code{@@chapheading} command.  @xref{majorheading
+& chapheading, , @code{@@majorheading} and @code{@@chapheading}}.
+
+@item @@math@{@var{mathematical-expression}@}
+Format a mathematical expression.
+@xref{math, , @code{@@math} - Inserting Mathematical Expressions}.
+
+@item @@menu
+Mark the beginning of a menu of nodes.  No effect in a printed manual.
+Pair with @code{@@end menu}.  @xref{Menus}.
+
+@item @@minus@{@}
+Generate a minus sign, `@minus{}'.  @xref{minus, , @code{@@minus}}.
+
+@item @@multitable @var{column-width-spec}
+Begin a multi-column table.  Begin each row with @code{@@item} or
+@code{@@headitem}, and separate columns with @code{@@tab}.  Pair with
+@code{@@end multitable}.  @xref{Multitable Column Widths}.
+
+@item @@need @var{n}
+Start a new page in a printed manual if fewer than @var{n} mils
+(thousandths of an inch) remain on the current page.  @xref{need, ,
+@code{@@need}}.
+
+@item @@node @var{name}, @var{next}, @var{previous}, @var{up}
+Begin a new node.  @xref{node, , @code{@@node}}.
+
+@item @@noindent
+Prevent text from being indented as if it were a new paragraph.
+@xref{noindent, , @code{@@noindent}}.
+
+@item @@novalidate
+Suppress validation of node references and omit creation of auxiliary
+files with @TeX{}.  Use before @code{@@setfilename}.  @xref{Pointer
+Validation}.
+
+@item @@O@{@}
+@itemx @@o@{@}
+Generate the uppercase and lowercase O-with-slash letters, respectively:
+@O{}, @o{}.
+
+@item  @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
+@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
+Specify page footings resp.@: headings for odd-numbered (right-hand)
+pages.  @xref{Custom Headings, ,
+How to Make Your Own Headings}.@refill
+
+@item @@OE@{@}
+@itemx @@oe@{@}
+Generate the uppercase and lowercase OE ligatures, respectively:
+@OE{}, @oe{}.  @xref{Inserting Accents}.
+
+@item @@option@{@var{option-name}@}
+Indicate a command-line option, such as @option{-l} or @option{--help}.
+@xref{option,, @code{@@option}}.
+
+@item @@page
+Start a new page in a printed manual.  No effect in Info.
+@xref{page, , @code{@@page}}.@refill
+
+@item @@pagesizes [@var{width}][, @var{height}]
+Change page dimensions.  @xref{pagesizes}.
+
+@item @@paragraphindent @var{indent}
+Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
+source file indentation if @var{indent} is @code{asis}.
+@xref{paragraphindent,, Paragraph Indenting}.
+
+@item @@pindex @var{entry}
+Add @var{entry} to the index of programs.  @xref{Index Entries, , Defining
+the Entries of an Index}.@refill
+
+@item @@point@{@}
+Indicate the position of point in a buffer to the reader with a
+glyph: @samp{@point{}}.  @xref{Point Glyph, , Indicating
+Point in a Buffer}.@refill
+
+@item @@pounds@{@}
+Generate the pounds sterling currency sign.
+@xref{pounds,,@code{@@pounds@{@}}}.
+
+@item @@print@{@}
+Indicate printed output to the reader with a glyph:
+@samp{@print{}}.  @xref{Print Glyph}.@refill
+
+@item @@printindex @var{index-name}
+Generate the alphabetized index for @var{index-name} (using two columns in a printed
+manual).  @xref{Printing Indices & Menus}.
+
+@item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
+Make a reference that starts with a lower case `see' in a printed
+manual.  Use within parentheses only.  Only the first argument is
+mandatory.  @xref{pxref, , @code{@@pxref}}.
+
+@item @@questiondown@{@}
+Generate an upside-down question mark.  @xref{Inserting Accents}.
+
+@item @@quotation
+Narrow the margins to indicate text that is quoted from another work.
+Takes optional argument of prefix text.  Pair with @code{@@end
+quotation}.  @xref{quotation, , @code{@@quotation}}.
+
+@item @@r@{@var{text}@}
+Set @var{text} in the regular @r{roman} font.  No effect in Info.
+@xref{Fonts}.
+
+@item @@raisesections
+Change subsequent sections to chapters, subsections to sections, and so
+on.  @xref{Raise/lower sections, , @code{@@raisesections} and
+@code{@@lowersections}}.@refill
+
+@item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
+Make a plain reference that does not start with any special text.
+Follow command with a punctuation mark.  Only the first argument is
+mandatory.  @xref{ref, , @code{@@ref}}.
+
+@item @@refill
+This command used to refill and indent the paragraph after all the
+other processing has been done.  It is no longer needed, since all
+formatters now automatically refill as needed, but you may still see
+it in the source to some manuals, as it does no harm.
+
+@item @@registeredsymbol@{@}
+Generate the legal symbol @registeredsymbol{}.  @xref{registered
+symbol,, @code{@@registeredsymbol@{@}}}.
+
+@item @@result@{@}
+Indicate the result of an expression to the reader with a special
+glyph: @samp{@result{}}.  @xref{result, , @code{@@result}}.@refill
+
+@item @@ringaccent@{@var{c}@}
+Generate a ring accent over the next character, as in @ringaccent{o}.
+@xref{Inserting Accents}.
+
+@item @@samp@{@var{text}@}
+Indicate a literal example of a sequence of characters, in general.
+Quoted in Info output.  @xref{samp, , @code{@@samp}}.
+
+@item @@sansserif@{@var{text}@}
+Set @var{text} in a @sansserif{sans serif} font if possible.  No
+effect in Info.  @xref{Fonts}.
+
+@item @@sc@{@var{text}@}
+Set @var{text} in a small caps font in printed output, and uppercase
+in Info.  @xref{Smallcaps}.
+
+@item @@section @var{title}
+Begin a section within a chapter.  The section title appears in the
+table of contents.  In Info, the title is underlined with equal signs.
+Within @code{@@chapter} and @code{@@appendix}, the section title is
+numbered; within @code{@@unnumbered}, the section is unnumbered.
+@xref{section, , @code{@@section}}.
+
+@item @@set @var{txivar} [@var{string}]
+Define the Texinfo variable @var{txivar}, optionally to the value
+@var{string}.  @xref{set clear value, , @code{@@set} @code{@@clear}
+@code{@@value}}.
+
+@item @@setchapternewpage @var{on-off-odd}
+Specify whether chapters start on new pages, and if so, whether on
+odd-numbered (right-hand) new pages.  @xref{setchapternewpage, ,
+@code{@@setchapternewpage}}.
+
+@item @@setcontentsaftertitlepage
+Put the table of contents after the @samp{@@end titlepage} even if the
+@code{@@contents} command is at the end.  @xref{Contents}.
+
+@item @@setfilename @var{info-file-name}
+Provide a name to be used for the output files.  This command is essential
+for @TeX{} formatting as well, even though it produces no output of
+its own.  @xref{setfilename, , @code{@@setfilename}}.
+
+@item @@setshortcontentsaftertitlepage
+Place the short table of contents after the @samp{@@end titlepage}
+command even if the @code{@@shortcontents} command is at the end.
+@xref{Contents}.
+
+@item @@settitle @var{title}
+Specify the title for page headers in a printed manual, and the
+default document description for HTML @samp{<head>}.  @xref{settitle,,
+@code{@@settitle}}.
+
+@item @@shortcaption
+Define the short caption for a @code{@@float}.  @xref{caption shortcaption}.
+
+@item @@shortcontents
+Print a short table of contents, with chapter-level entries only.  Not
+relevant to Info, which uses menus rather than tables of contents.
+@xref{Contents, , Generating a Table of Contents}.
+
+@item @@shorttitlepage @var{title}
+Generate a minimal title page.  @xref{titlepage,,@code{@@titlepage}}.
+
+@item @@slanted@{@var{text}@}
+Set @var{text} in a @slanted{slanted} font if possible.  No effect
+in Info.  @xref{Fonts}.
+
+@item @@smallbook
+Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
+rather than the regular 8.5 by 11 inch format.  @xref{smallbook, ,
+Printing Small Books}.  Also, see @ref{small}.
+
+@item @@smalldisplay
+Begin a kind of example.  Like @code{@@smallexample} (narrow margins, no
+filling), but do not select the fixed-width font.  Pair with @code{@@end
+smalldisplay}.  @xref{small}.
+
+@item @@smallexample
+Begin an example.  Do not fill, select fixed-width font, narrow the
+margins.  Where possible, print text in a smaller font than with
+@code{@@example}.  Pair with @code{@@end smallexample}.  @xref{small}.
+
+@item @@smallformat
+Begin a kind of example.  Like @code{@@smalldisplay}, but do not narrow
+the margins.  Pair with @code{@@end smallformat}.  @xref{small}.
+
+@item @@smalllisp
+Begin an example of Lisp code.  Same as @code{@@smallexample}.  Pair
+with @code{@@end smalllisp}.  @xref{small}.
+
+@item @@sp @var{n}
+Skip @var{n} blank lines.  @xref{sp, , @code{@@sp}}.@refill
+
+@item @@ss@{@}
+Generate the German sharp-S es-zet letter, @ss{}.  @xref{Inserting Accents}.
+
+@item @@strong @{@var{text}@}
+Emphasize @var{text} more strongly than @code{@@emph}, by using
+@strong{boldface} where possible; enclosed in asterisks in Info.
+@xref{emph & strong, , Emphasizing Text}.
+
+@item @@subheading @var{title}
+Print an unnumbered subsection-like heading, but omit from the table
+of contents of a printed manual.  In Info, the title is underlined
+with hyphens.  @xref{unnumberedsubsec appendixsubsec subheading, ,
+@code{@@unnumberedsubsec} @code{@@appendixsubsec}
+@code{@@subheading}}.
+
+@item @@subsection @var{title}
+Begin a subsection within a section.  The subsection title appears in
+the table of contents.  In Info, the title is underlined with hyphens.
+Same context-dependent numbering as @code{@@section}.  @xref{subsection, ,
+@code{@@subsection}}.
+
+@item @@subsubheading @var{title}
+Print an unnumbered subsubsection-like heading, but omit from the
+table of contents of a printed manual.  In Info, the title is
+underlined with periods.  @xref{subsubsection, , The `subsub'
+Commands}.
+
+@item @@subsubsection @var{title}
+Begin a subsubsection within a subsection.  The subsubsection title
+appears in the table of contents.  In Info, the title is underlined
+with periods.  Same context-dependent numbering as @code{@@section}.
+@xref{subsubsection, , The `subsub' Commands}.
+
+@item @@subtitle @var{title}
+In a printed manual, set a subtitle in a normal sized font flush to
+the right-hand side of the page.  Not relevant to Info, which does not
+have title pages.  @xref{title subtitle author, , @code{@@title}
+@code{@@subtitle} and @code{@@author} Commands}.
+
+@item @@summarycontents
+Print a short table of contents.  Synonym for @code{@@shortcontents}.
+@xref{Contents, , Generating a Table of Contents}.
+
+@item @@syncodeindex @var{from-index} @var{to-index}
+Merge the index named in the first argument into the index named in
+the second argument, formatting the entries from the first index with
+@code{@@code} .  @xref{Combining Indices}.@refill
+
+@item @@synindex @var{from-index} @var{to-index}
+Merge the index named in the first argument into the index named in
+the second argument.  Do not change the font of @var{from-index}
+entries.  @xref{Combining Indices}.
+
+@item @@t@{@var{text}@}
+Set @var{text} in a @t{fixed-width}, typewriter-like font.  No effect
+in Info.  @xref{Fonts}.
+
+@item @@tab
+Separate columns in a row of a multitable.  @xref{Multitable Rows}.
+
+@item @@table @var{formatting-command}
+Begin a two-column table (description list), using @code{@@item} for
+each entry.  Write each first column entry on the same line as
+@code{@@item}.  First column entries are printed in the font resulting
+from @var{formatting-command}.  Pair with @code{@@end table}.
+@xref{Two-column Tables, , Making a Two-column Table}.  Also see
+@ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, and
+@ref{itemx, , @code{@@itemx}}.
+
+@item @@TeX@{@}
+Generate the @TeX{} logo.  @xref{tex, , @TeX{} and @LaTeX{}}.
+
+@item @@tex
+Enter @TeX{} completely.  Pair with @code{@@end tex}.  @xref{Raw
+Formatter Commands}.
+
+@item @@thischapter
+@itemx @@thischaptername
+@itemx @@thischapternum
+@itemx @@thisfile
+@itemx @@thispage
+@itemx @@thistitle
+Only allowed in a heading or footing.  Stands for, respectively, the
+number and name of the current chapter (in the format `Chapter 1:
+Title'), the current chapter name only, the current chapter number
+only, the filename, the current page number, and the title of the
+document, respectively.  @xref{Custom Headings, , How to Make Your Own
+Headings}.
+
+@item @@tie@{@}
+Generate a normal interword space at which a line break is not allowed.
+@xref{tie,, @code{@@tie@{@}}}.
+
+@item @@tieaccent@{@var{cc}@}
+Generate a tie-after accent over the next two characters @var{cc}, as in
+`@tieaccent{oo}'.  @xref{Inserting Accents}.
+
+@item @@tindex @var{entry}
+Add @var{entry} to the index of data types.  @xref{Index Entries, ,
+Defining the Entries of an Index}.@refill
+
+@item @@title @var{title}
+In a printed manual, set a title flush to the left-hand side of the
+page in a larger than normal font and underline it with a black rule.
+Not relevant to Info, which does not have title pages.  @xref{title
+subtitle author, , The @code{@@title} @code{@@subtitle} and
+@code{@@author} Commands}.@refill
+
+@item @@titlefont@{@var{text}@}
+In a printed manual, print @var{text} in a larger than normal font.
+@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
+and @code{@@sp} Commands}.
+
+@item @@titlepage
+Begin the title page.  Write the command on a line of its own, paired
+with @code{@@end titlepage}.  Nothing between @code{@@titlepage} and
+@code{@@end titlepage} appears in Info.  @xref{titlepage, ,
+@code{@@titlepage}}.@refill
+
+@item @@today@{@}
+Insert the current date, in `1 Jan 1900' style.  @xref{Custom
+Headings, , How to Make Your Own Headings}.@refill
+
+@item @@top @var{title}
+Mark the topmost @code{@@node} in the file, which must be defined on
+the line immediately preceding the @code{@@top} command.  The title is
+formatted as a chapter-level heading.  The entire top node, including
+the @code{@@node} and @code{@@top} lines, are normally enclosed with
+@code{@@ifnottex ... @@end ifnottex}.  In @TeX{} and
+@code{texinfo-format-buffer}, the @code{@@top} command is merely a
+synonym for @code{@@unnumbered}.  @xref{makeinfo Pointer Creation, ,
+Creating Pointers with @code{makeinfo}}.
+
+@item @@u@{@var{c}@}
+@itemx @@ubaraccent@{@var{c}@}
+@itemx @@udotaccent@{@var{c}@}
+Generate a breve, underbar, or underdot accent, respectively, over or
+under the character @var{c}, as in @u{o}, @ubaraccent{o},
+@udotaccent{o}.  @xref{Inserting Accents}.
+
+@item @@unnumbered @var{title}
+Begin a chapter that appears without chapter numbers of any kind.  The
+title appears in the table of contents.  In Info, the title is
+underlined with asterisks.  @xref{unnumbered & appendix, ,
+@code{@@unnumbered} and @code{@@appendix}}.
+
+@item @@unnumberedsec @var{title}
+Begin a section that appears without section numbers of any kind.  The
+title appears in the table of contents of a printed manual.  In Info,
+the title is underlined with equal signs.  @xref{unnumberedsec
+appendixsec heading, , Section Commands}.
+
+@item @@unnumberedsubsec @var{title}
+Begin an unnumbered subsection.  The title appears in the table of
+contents.  In Info, the title is underlined with hyphens.
+@xref{unnumberedsubsec appendixsubsec subheading, ,
+@code{@@unnumberedsubsec} @code{@@appendixsubsec}
+@code{@@subheading}}.
+
+@item @@unnumberedsubsubsec @var{title}
+Begin an unnumbered subsubsection.  The title appears in the table of
+contents.  In Info, the title is underlined with periods.
+@xref{subsubsection, , The `subsub' Commands}.
+
+@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
+@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
+Define a cross reference to an external uniform resource locator,
+e.g., for the World Wide Web.  @xref{uref, , @code{@@uref}}.
+
+@item @@v@{@var{c}@}
+Generate check accent over the character @var{c}, as in @v{o}.
+@xref{Inserting Accents}.
+
+@item @@value@{@var{txivar}@}
+Insert the value, if any, of the Texinfo variable @var{txivar},
+previously defined by @code{@@set}.  @xref{set clear value, ,
+@code{@@set} @code{@@clear} @code{@@value}}.
+
+@item @@var@{@var{metasyntactic-variable}@}
+Highlight a metasyntactic variable, which is something that stands for
+another piece of text.  @xref{var, , Indicating Metasyntactic
+Variables}.
+
+@item @@verb@{@var{delim} @var{literal} @var{delim}@}
+Output @var{literal}, delimited by the single character @var{delim},
+exactly as is (in the fixed-width font), including any whitespace or
+Texinfo special characters.  @xref{verb,,@code{verb}}.
+
+@item @@verbatim
+Output the text of the environment exactly as is (in the fixed-width
+font).  Pair with @code{@@end verbatim}.  @xref{verbatim,,@code{verbatim}}.
+
+@item @@verbatiminclude @var{filename}
+Output the contents of @var{filename} exactly as is (in the fixed-width font).
+@xref{verbatiminclude,,@code{verbatiminclude}}.
+
+@item @@vindex @var{entry}
+Add @var{entry} to the index of variables.  @xref{Index Entries, ,
+Defining the Entries of an Index}.@refill
+
+@item @@vskip @var{amount}
+In a printed manual, insert whitespace so as to push text on the
+remainder of the page towards the bottom of the page.  Used in
+formatting the copyright page with the argument @samp{0pt plus
+1filll}.  (Note spelling of @samp{filll}.)  @code{@@vskip} may be used
+only in contexts ignored for Info.  @xref{Copyright}.
+
+@item @@vtable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of variables.  Pair with @code{@@end vtable}.  The same as
+@code{@@table}, except for indexing.  @xref{ftable vtable, ,
+@code{@@ftable} and @code{@@vtable}}.@refill
+
+@item @@w@{@var{text}@}
+Disallow line breaks within @var{text}.  @xref{w, , @code{@@w}}.
+
+@item @@xml
+Enter XML completely.  Pair with @code{@@end xml}.  @xref{Raw
+Formatter Commands}.
+
+@item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
+Make a reference that starts with `See' in a printed manual.  Follow
+command with a punctuation mark.  Only the first argument is
+mandatory.  @xref{xref, , @code{@@xref}}.
+
+@end table
+
+
+@node Command Syntax
+@section @@-Command Syntax
+@cindex @@-command syntax
+@cindex Syntax, of @@-commands
+@cindex Command syntax
+
+The character @samp{@@} is used to start special Texinfo commands.
+(It has the same meaning that @samp{\} has in plain @TeX{}.)  Texinfo
+has four types of @@-command:@refill
+
+@table @asis
+@item 1. Non-alphabetic commands.
+These commands consist of an @@ followed by a punctuation mark or
+other character that is not part of the alphabet.  Non-alphabetic
+commands are almost always part of the text within a paragraph.  The
+non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}},
+@code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and
+many more.
+
+@item 2. Alphabetic commands that do not require arguments.
+These commands start with @@ followed by a word followed by left- and
+right-hand braces.  These commands insert special symbols in the
+document; they do not require arguments.  For example,
+@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
+@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
+and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
+
+@item 3. Alphabetic commands that require arguments within braces.
+These commands start with @@ followed by a letter or a word, followed by an
+argument within braces.  For example, the command @code{@@dfn} indicates
+the introductory or defining use of a term; it is used as follows: @samp{In
+Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
+
+@item 4. Alphabetic commands that occupy an entire line.
+These commands occupy an entire line.  The line starts with @@,
+followed by the name of the command (a word); for example, @code{@@center}
+or @code{@@cindex}.  If no argument is needed, the word is followed by
+the end of the line.  If there is an argument, it is separated from
+the command name by a space.  Braces are not used.@refill
+@end table
+
+@cindex Braces and argument syntax
+Thus, the alphabetic commands fall into classes that have
+different argument syntaxes.  You cannot tell to which class a command
+belongs by the appearance of its name, but you can tell by the
+command's meaning: if the command stands for a glyph, it is in
+class 2 and does not require an argument; if it makes sense to use the
+command together with other text as part of a paragraph, the command
+is in class 3 and must be followed by an argument in braces;
+otherwise, it is in class 4 and uses the rest of the line as its
+argument.@refill
+
+The purpose of having a different syntax for commands of classes 3 and
+4 is to make Texinfo files easier to read, and also to help the GNU
+XEmacs paragraph and filling commands work properly.  There is only one
+exception to this rule: the command @code{@@refill}, which is always
+used at the end of a paragraph immediately following the final period
+or other punctuation character.  @code{@@refill} takes no argument and
+does @emph{not} require braces.  @code{@@refill} never confuses the
+XEmacs paragraph commands because it cannot appear at the beginning of
+a line.  It is also no longer needed, since all formatters now refill
+paragraphs automatically.
+
+
+@node Tips
+@appendix Tips and Hints
+
+Here are some tips for writing Texinfo documentation:@refill
+
+@cindex Tips
+@cindex Usage tips
+@cindex Hints
+@itemize @bullet
+@item
+Write in the present tense, not in the past or the future.
+
+@item
+Write actively!  For example, write ``We recommend that @dots{}'' rather
+than ``It is recommended that @dots{}''.
+
+@item
+Use 70 or 72 as your fill column.  Longer lines are hard to read.
+
+@item
+Include a copyright notice and copying permissions.
+@end itemize
+
+@subsubheading Index, Index, Index!
+
+Write many index entries, in different ways.
+Readers like indices; they are helpful and convenient.
+
+Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards.  In either
+case, write an entry before the paragraph to which it applies.  This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+Here are more hints we have found valuable:
+
+@itemize @bullet
+@item
+Write each index entry differently, so each entry refers to a different
+place in the document.
+
+@item
+Write index entries only where a topic is discussed significantly.  For
+example, it is not useful to index ``debugging information'' in a
+chapter on reporting bugs.  Someone who wants to know about debugging
+information will certainly not find it in that chapter.
+
+@item
+Consistently capitalize the first word of every concept index entry,
+or else consistently use lower case.  Terse entries often call for
+lower case; longer entries for capitalization.  Whichever case
+convention you use, please use one or the other consistently!  Mixing
+the two styles looks bad.
+
+@item
+Always capitalize or use upper case for those words in an index for
+which this is proper, such as names of countries or acronyms.  Always
+use the appropriate case for case-sensitive names, such as those in C or
+Lisp.
+
+@item
+Write the indexing commands that refer to a whole section immediately
+after the section command, and write the indexing commands that refer to
+a paragraph before that paragraph.
+
+In the example that follows, a blank line comes after the index
+entry for ``Leaping'':
+
+@example
+@group
+@@section The Dog and the Fox
+@@cindex Jumping, in general
+@@cindex Leaping
+
+@@cindex Dog, lazy, jumped over
+@@cindex Lazy dog jumped over
+@@cindex Fox, jumps over dog
+@@cindex Quick fox jumps over dog
+The quick brown fox jumps over the lazy dog.
+@end group
+@end example
+
+@noindent
+(Note that the example shows entries for the same concept that are
+written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
+readers can look up the concept in different ways.)
+@end itemize
+
+@subsubheading Blank Lines
+
+@itemize @bullet
+@item
+Insert a blank line between a sectioning command and the first following
+sentence or paragraph, or between the indexing commands associated with
+the sectioning command and the first following sentence or paragraph, as
+shown in the tip on indexing.  Otherwise, a formatter may fold title and
+paragraph together.
+
+@item
+Always insert a blank line before an @code{@@table} command and after an
+@code{@@end table} command; but never insert a blank line after an
+@code{@@table} command or before an @code{@@end table} command.
+
+@need 1000
+For example,
+
+@example
+@group
+Types of fox:
+
+@@table @@samp
+@@item Quick
+Jump over lazy dogs.
+@end group
+
+@group
+@@item Brown
+Also jump over lazy dogs.
+@@end table
+
+@end group
+@group
+@@noindent
+On the other hand, @dots{}
+@end group
+@end example
+
+Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
+itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
+same way.
+@end itemize
+
+@subsubheading Complete Phrases
+
+Complete phrases are easier to read than @dots{}
+
+@itemize @bullet
+@item
+Write entries in an itemized list as complete sentences; or at least, as
+complete phrases.  Incomplete expressions @dots{} awkward @dots{} like
+this.
+
+@item
+Write the prefatory sentence or phrase for a multi-item list or table as
+a complete expression.  Do not write ``You can set:''; instead, write
+``You can set these variables:''.  The former expression sounds cut off.
+@end itemize
+
+@subsubheading Editions, Dates and Versions
+
+Include edition numbers, version numbers, and dates in the
+@code{@@copying} text (for people reading the Texinfo file, and for the
+legal copyright in the output files).  Then use @code{@@insertcopying}
+in the @code{@@titlepage} section (for people reading the printed
+output) and the Top node (for people reading the online output).
+
+It is easiest to do this using @code{@@set} and @code{@@value}.
+@xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
+
+
+@subsubheading Definition Commands
+
+Definition commands are @code{@@deffn}, @code{@@defun},
+@code{@@defmac}, and the like, and enable you to write descriptions in
+a uniform format.@refill
+
+@itemize @bullet
+@item
+Write just one definition command for each entity you define with a
+definition command.  The automatic indexing feature creates an index
+entry that leads the reader to the definition.
+
+@item
+Use @code{@@table} @dots{} @code{@@end table} in an appendix that
+contains a summary of functions, not @code{@@deffn} or other definition
+commands.
+@end itemize
+
+@subsubheading Capitalization
+
+@itemize @bullet
+@item
+Capitalize ``Texinfo''; it is a name.  Do not write the @samp{x} or
+@samp{i} in upper case.
+
+@item
+Capitalize ``Info''; it is a name.
+
+@item
+Write @TeX{} using the @code{@@TeX@{@}} command.  Note the uppercase
+@samp{T} and @samp{X}.  This command causes the formatters to
+typeset the name according to the wishes of Donald Knuth, who wrote
+@TeX{}.
+@end itemize
+
+@subsubheading Spaces
+
+Do not use spaces to format a Texinfo file, except inside of
+@code{@@example} @dots{} @code{@@end example} and other literal
+environments and commands.
+
+@need 700
+For example, @TeX{} fills the following:
+
+@example
+@group
+   @@kbd@{C-x v@}
+   @@kbd@{M-x vc-next-action@}
+      Perform the next logical operation
+      on the version-controlled file
+      corresponding to the current buffer.
+@end group
+@end example
+
+@need 950
+@noindent
+so it looks like this:
+
+@iftex
+@quotation
+   @kbd{C-x v}
+   @kbd{M-x vc-next-action}
+      Perform the next logical operation on the version-controlled file
+      corresponding to the current buffer.
+@end quotation
+@end iftex
+@ifnottex
+@quotation
+`C-x v' `M-x vc-next-action' Perform the next logical operation on the
+version-controlled file corresponding to the current buffer.
+@end quotation
+@end ifnottex
+
+@noindent
+In this case, the text should be formatted with
+@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
+
+
+@subsubheading @@code, @@samp, @@var, and @samp{---}
+
+@itemize @bullet
+@item
+Use @code{@@code} around Lisp symbols, including command names.
+For example,
+
+@example
+The main function is @@code@{vc-next-action@}, @dots{}
+@end example
+
+@item
+Avoid putting letters such as @samp{s} immediately after an
+@samp{@@code}.  Such letters look bad.
+
+@item
+Use @code{@@var} around meta-variables.  Do not write angle brackets
+around them.
+
+@item
+Use three hyphens in a row, @samp{---}, to indicate a long dash.  @TeX{}
+typesets these as a long dash and the Info formatters reduce three
+hyphens to two.
+@end itemize
+
+@subsubheading Periods Outside of Quotes
+
+Place periods and other punctuation marks @emph{outside} of quotations,
+unless the punctuation is part of the quotation.  This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
+
+For example, you should write the following sentence with the period
+outside the end quotation marks:
+
+@example
+Evidently, @samp{au} is an abbreviation for ``author''.
+@end example
+
+@noindent
+since @samp{au} does @emph{not} serve as an abbreviation for
+@samp{author.} (with a period following the word).
+
+@subsubheading Introducing New Terms
+
+@itemize @bullet
+@item
+Introduce new terms so that a reader who does not know them can
+understand them from context; or write a definition for the term.
+
+For example, in the following, the terms ``check in'', ``register'' and
+``delta'' are all appearing for the first time; the example sentence should be
+rewritten so they are understandable.
+
+@quotation
+The major function assists you in checking in a file to your
+version control system and registering successive sets of changes to
+it as deltas.
+@end quotation
+
+@item
+Use the @code{@@dfn} command around a word being introduced, to indicate
+that the reader should not expect to know the meaning already, and
+should expect to learn the meaning from this passage.
+@end itemize
+
+@subsubheading @@pxref
+
+@c !!! maybe include this in the tips on pxref
+@ignore
+By the way, it is okay to use pxref with something else in front of
+it within the parens, as long as the pxref is followed by the close
+paren, and the material inside the parens is not part of a larger
+sentence.  Also, you can use xref inside parens as part of a complete
+sentence so long as you terminate the cross reference with punctuation.
+@end ignore
+Absolutely never use @code{@@pxref} except in the special context for
+which it is designed: inside parentheses, with the closing parenthesis
+following immediately after the closing brace.  One formatter
+automatically inserts closing punctuation and the other does not.  This
+means that the output looks right both in printed output and in an Info
+file, but only when the command is used inside parentheses.
+
+@subsubheading Invoking from a Shell
+
+You can invoke programs such as XEmacs, GCC, and @code{gawk} from a
+shell.  The documentation for each program should contain a section that
+describes this.  Unfortunately, if the node names and titles for these
+sections are all different, they are difficult for users to find.
+
+So, there is a convention to name such sections with a phrase beginning
+with the word `Invoking', as in `Invoking XEmacs'; this way, users can
+find the section easily.
+
+
+@subsubheading ANSI C Syntax
+
+When you use @code{@@example} to describe a C function's calling
+conventions, use the ANSI C syntax, like this:@refill
+
+@example
+void dld_init (char *@@var@{path@});
+@end example
+
+@noindent
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with
+@code{@@var}.@refill
+
+@need 800
+Avoid the obsolete style that looks like this:@refill
+
+@example
+#include <dld.h>
+
+dld_init (path)
+char *path;
+@end example
+
+Also, it is best to avoid writing @code{#include} above the
+declaration just to indicate that the function is declared in a
+header file.  The practice may give the misimpression that the
+@code{#include} belongs near the declaration of the function.  Either
+state explicitly which header file holds the declaration or, better
+yet, name the header file used for a group of functions at the
+beginning of the section that describes the functions.@refill
+
+@subsubheading Bad Examples
+
+Here are several examples of bad writing to avoid:
+
+In this example, say, `` @dots{} you must @code{@@dfn}@{check
+in@} the new version.''  That flows better.
+
+@quotation
+When you are done editing the file, you must perform a
+@code{@@dfn}@{check in@}.
+@end quotation
+
+In the following example, say, ``@dots{} makes a unified interface such as VC
+mode possible.''
+
+@quotation
+SCCS, RCS and other version-control systems all perform similar
+functions in broadly similar ways (it is this resemblance which makes
+a unified control mode like this possible).
+@end quotation
+
+And in this example, you should specify what `it' refers to:
+
+@quotation
+If you are working with other people, it assists in coordinating
+everyone's changes so they do not step on each other.
+@end quotation
+
+@subsubheading And Finally @dots{}
+
+@itemize @bullet
+@item
+Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
+sound in the name `Bach'.  But pronounce Texinfo as in `speck':
+``teckinfo''.
+
+@item
+Write notes for yourself at the very end of a Texinfo file after the
+@code{@@bye}.  None of the formatters process text after the
+@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
+@code{@@end ignore}.
+@end itemize
+
+
+@node Sample Texinfo Files
+@appendix Sample Texinfo Files
+@cindex Sample Texinfo files
+
+The first example is from the first chapter (@pxref{Short Sample}),
+given here in its entirety, without commentary.  The second
+includes the full texts to be used in GNU manuals.
+
+@menu
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+* Verbatim Copying License::
+* All-permissive Copying License::
+@end menu
+
+
+@node Short Sample Texinfo File
+@section Short Sample
+@cindex Sample Texinfo file, no comments
+
+Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter.  @xref{Short
+Sample}.
+
+In a nutshell: The @command{makeinfo} program transforms a Texinfo
+source file such as this into an Info file or HTML; and @TeX{} typesets
+it for a printed manual.
+
+
+@sp 1
+@example
+\input texinfo   @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+
+@@copying
+This is a short example of a complete Texinfo file.
+
+Copyright @copyright{} 2005 Free Software Foundation, Inc.
+@@end copying
+
+@@titlepage
+@@title Sample Title
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@c Output the table of the contents at the beginning.
+@@contents
+
+@@ifnottex
+@@node Top
+@@top GNU Sample
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* First Chapter::    The first chapter is the
+                      only chapter in this sample.
+* Index::            Complete index.
+@@end menu
+
+
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
+
+This is the first chapter.
+@@cindex index entry, another
+
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
+
+
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@bye
+@end example
+
+
+@node GNU Sample Texts
+@section GNU Sample Texts
+
+@cindex GNU sample texts
+@cindex Sample texts, GNU
+@cindex Full texts, GNU
+
+Following is a sample Texinfo document with the full texts that should
+be used in GNU manuals.
+
+As well as the legal texts, it also serves as a practical example of how
+many elements in a GNU system can affect the manual.  If you're not
+familiar with all these different elements, don't worry.  They're not
+required and a perfectly good manual can be written without them.
+They're included here nonetheless because many manuals do (or could)
+benefit from them.
+
+@xref{Short Sample}, for a minimal example of a Texinfo file.
+@xref{Beginning a File}, for a full explanation of that minimal
+example.
+
+Here are some notes on the example:
+
+@itemize @bullet
+@item
+@cindex $Id
+@cindex CVS $Id
+@cindex RCS $Id
+@cindex Documentation identification
+@cindex Identification of documentation
+The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs,
+Concurrent Versions System}) or RCS
+(@url{http://www.gnu.org/software/rcs}) version control systems, which
+expand it into a string such as:
+@example
+$Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
+@end example
+(This is useful in all sources that use version control, not just manuals.)
+You may wish to include the @samp{$Id:} comment in the @code{@@copying}
+text, if you want a completely unambiguous reference to the
+documentation version.
+
+If you want to literally write @t{@w{$}Id$}, use @code{@@w}:
+@code{@@w@{$@}Id$}.  Unfortunately, this technique does not currently
+work in plain text output, since it's not clear what should be done.
+We hope to find a solution in a future release.
+
+@item
+@pindex automake@r{, and version info}
+@vindex UPDATED @r{Automake variable}
+@vindex VERSION @r{Automake variable}
+@pindex time-stamp.el
+The @file{version.texi} in the @code{@@include} command is maintained
+automatically by Automake (@pxref{Top,, Introduction, automake, GNU
+Automake}).  It sets the @samp{VERSION} and @samp{UPDATED} values used
+elsewhere.  If your distribution doesn't use Automake, but you do use
+XEmacs, you may find the time-stamp.el package helpful (@pxref{Time
+Stamps,,,xemacs,XEmacs User's Manual}).
+
+@item
+The @code{@@syncodeindex} command reflects the recommendation to use
+only one index where possible, to make it easier for readers to look up
+index entries.
+
+@item
+The @code{@@dircategory} is for constructing the Info directory.
+@xref{Installing Dir Entries}, which includes a variety of recommended
+category names.
+
+@item
+The `Invoking' node is a GNU standard to help users find the basic
+information about command-line usage of a given program.  @xref{Manual
+Structure Details,,,standards, GNU Coding Standards}.
+
+@item
+@cindex GNU Free Documentation License, including entire
+@cindex Free Documentation License, including entire
+It is best to include the entire GNU Free Documentation License in a GNU
+manual, unless the manual is only a few pages long.  Of course this
+sample is even shorter than that, but it includes the FDL anyway in
+order to show one conventional way to do so.  The @file{fdl.texi} file
+is available on the GNU machines and in the Texinfo and other GNU
+source distributions.
+
+The FDL provides for omitting itself under certain conditions, but in
+that case the sample texts given here have to be modified.  @xref{GNU
+Free Documentation License}.
+
+@item
+If the FSF is not the copyright holder, then use the appropriate name.
+
+@item
+If your manual is not published on paper by the FSF, then omit the
+last sentence in the Back-Cover Text that talks about copies from GNU
+Press.
+
+@item
+If your manual has Invariant Sections (again, see the license itself
+for details), then change the text here accordingly.
+
+@item
+For documents that express your personal views, feelings or experiences,
+it is more appropriate to use a license permitting only verbatim
+copying, rather than the FDL.  @xref{Verbatim Copying License}.
+
+@end itemize
+
+Here is the sample document:
+
+@verbatim
+\input texinfo   @c -*-texinfo-*-
+@comment $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
+@comment %**start of header
+@setfilename sample.info
+@include version.texi
+@settitle GNU Sample @value{VERSION}
+@syncodeindex pg cp
+@comment %**end of header
+@copying
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
+which is an example in the Texinfo documentation.
+
+Copyright @copyright{} 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual.  Buying copies from the FSF
+supports it in developing GNU and promoting software freedom.''
+@end quotation
+@end copying
+
+@dircategory Texinfo documentation system
+@direntry
+* sample: (sample)Invoking sample.
+@end direntry
+
+@titlepage
+@title GNU Sample
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author A.U. Thor (@email{bug-texinfo@@gnu.org})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top GNU Sample
+
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
+@end ifnottex
+
+@menu
+* Invoking sample::
+* Copying This Manual::
+* Index::
+@end menu
+
+
+@node Invoking sample
+@chapter Invoking sample
+
+@pindex sample
+@cindex invoking @command{sample}
+
+This is a sample manual.  There is no sample program to
+invoke, but if there was, you could see its basic usage
+and command line options here.
+
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+@end verbatim
+
+
+@node Verbatim Copying License
+@section Verbatim Copying License
+
+@cindex Verbatim copying license
+@cindex License for verbatim copying
+
+For software manuals and other documentation, it is important to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
+
+On the other hand, for documents that express your personal views,
+feelings or experiences, it is more appropriate to use a license
+permitting only verbatim copying.
+
+Here is sample text for such a license permitting verbatim copying only.
+This is just the license text itself.  For a complete sample document,
+see the previous sections.
+
+@verbatim
+@copying
+This document is a sample for allowing verbatim copying only.
+
+Copyright @copyright{} 2005 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to make and distribute verbatim copies
+of this entire document without royalty provided the
+copyright notice and this permission notice are preserved.
+@end quotation
+@end copying
+@end verbatim
+
+
+@node All-permissive Copying License
+@section All-permissive Copying License
+
+@cindex All-permissive copying license
+@cindex License for all-permissive copying
+
+For software manuals and other documentation, it is important to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
+
+On the other hand, for small supporting files, short manuals (under 300
+lines long) and rough documentation (README files, INSTALL files, etc.),
+the full FDL would be overkill.  They can use a simple all-permissive
+license.
+
+Here is sample text for such an all-permissive license.  This is just
+the license text itself.  For a complete sample document, see the
+previous sections.
+
+@example
+Copyright @copyright{} 2005 Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
+@end example
+
+
+@node Include Files
+@appendix Include Files
+@cindex Include files
+
+When @TeX{} or an Info formatting command sees an @code{@@include}
+command in a Texinfo file, it processes the contents of the file named
+by the command and incorporates them into the DVI or Info file being
+created.  Index entries from the included file are incorporated into
+the indices of the output file.
+
+Include files let you keep a single large document as a collection of
+conveniently small parts.
+
+@menu
+* Using Include Files::         How to use the @code{@@include} command.
+* texinfo-multiple-files-update::  How to create and update nodes and
+                                     menus when using included files.
+* Include Files Requirements::  @code{texinfo-multiple-files-update} needs.
+* Sample Include File::         A sample outer file with included files
+                                     within it; and a sample included file.
+* Include Files Evolution::     How use of the @code{@@include} command
+                                     has changed over time.
+@end menu
+
+@node Using Include Files
+@section How to Use Include Files
+@findex include
+
+To include another file within a Texinfo file, write the
+@code{@@include} command at the beginning of a line and follow it on
+the same line by the name of a file to be included.  For example:
+
+@example
+@@include buffers.texi
+@end example
+
+The name of the file is taken literally, with a single exception:
+@code{@@value@{@var{var}@}} references are expanded.  This makes it
+possible to reliably include files in other directories in a
+distribution.  @xref{verbatiminclude,,@code{@@verbatiminclude}}, for
+an example.
+
+An included file should simply be a segment of text that you expect to
+be included as is into the overall or @dfn{outer} Texinfo file; it
+should not contain the standard beginning and end parts of a Texinfo
+file.  In particular, you should not start an included file with a
+line saying @samp{\input texinfo}; if you do, that phrase is inserted
+into the output file as is.  Likewise, you should not end an included
+file with an @code{@@bye} command; nothing after @code{@@bye} is
+formatted.
+
+In the past, you were required to write an @code{@@setfilename} line at the
+beginning of an included file, but no longer.  Now, it does not matter
+whether you write such a line.  If an @code{@@setfilename} line exists
+in an included file, it is ignored.@refill
+
+Conventionally, an included file begins with an @code{@@node} line that
+is followed by an @code{@@chapter} line.  Each included file is one
+chapter.  This makes it easy to use the regular node and menu creating
+and updating commands to create the node pointers and menus within the
+included file.  However, the simple XEmacs node and menu creating and
+updating commands do not work with multiple Texinfo files.  Thus you
+cannot use these commands to fill in the `Next', `Previous', and `Up'
+pointers of the @code{@@node} line that begins the included file.  Also,
+you cannot use the regular commands to create a master menu for the
+whole file.  Either you must insert the menus and the `Next',
+`Previous', and `Up' pointers by hand, or you must use the XEmacs
+Texinfo mode command, @code{texinfo-multiple-files-update}, that is
+designed for @code{@@include} files.@refill
+
+When an included file does not have any node lines in it, the
+multiple files update command does not try to create a menu entry
+for it.  Consequently, you can include any file, such as a
+version or an update file without node lines, not just files that
+are chapters.  Small includable files like this are created by
+Automake (@pxref{GNU Sample Texts}).
+
+
+@node texinfo-multiple-files-update
+@section @code{texinfo-multiple-files-update}
+@findex texinfo-multiple-files-update
+
+XEmacs Texinfo mode provides the @code{texinfo-multiple-files-update}
+command.  This command creates or updates `Next', `Previous', and `Up'
+pointers of included files as well as those in the outer or overall
+Texinfo file, and it creates or updates a main menu in the outer file.
+Depending whether you call it with optional arguments, the command
+updates only the pointers in the first @code{@@node} line of the
+included files or all of them:@refill
+
+@table @kbd
+@item M-x texinfo-multiple-files-update
+Called without any arguments:@refill
+
+@itemize @minus
+@item
+Create or update the `Next', `Previous', and `Up' pointers of the
+first @code{@@node} line in each file included in an outer or overall
+Texinfo file.@refill
+
+@item
+Create or update the `Top' level node pointers of the outer or
+overall file.@refill
+
+@item
+Create or update a main menu in the outer file.@refill
+@end itemize
+
+@item C-u M-x texinfo-multiple-files-update
+Called with @kbd{C-u} as a prefix argument:
+
+@itemize @minus{}
+@item
+Create or update pointers in the first @code{@@node} line in each
+included file.
+
+@item
+Create or update the `Top' level node pointers of the outer file.
+
+@item
+Create and insert a master menu in the outer file.  The master menu
+is made from all the menus in all the included files.@refill
+@end itemize
+
+@item C-u 8 M-x texinfo-multiple-files-update
+Called with a numeric prefix argument, such as @kbd{C-u 8}:
+
+@itemize @minus
+@item
+Create or update @strong{all} the `Next', `Previous', and `Up' pointers
+of all the included files.@refill
+
+@item
+Create or update @strong{all} the menus of all the included
+files.@refill
+
+@item
+Create or update the `Top' level node pointers of the outer or
+overall file.@refill
+
+@item
+And then create a master menu in the outer file.  This is similar to
+invoking @code{texinfo-master-menu} with an argument when you are
+working with just one file.@refill
+@end itemize
+@end table
+
+Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just @w{@kbd{C-u}}, the
+@code{texinfo-multiple-files-update} command inserts a master menu;
+with a numeric prefix argument, such as @kbd{C-u 8}, the command
+updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
+master menu.@refill
+
+
+@node Include Files Requirements
+@section Include Files Requirements
+@cindex Include files requirements
+@cindex Requirements for include files
+
+If you plan to use the @code{texinfo-multiple-files-update} command,
+the outer Texinfo file that lists included files within it should
+contain nothing but the beginning and end parts of a Texinfo file, and
+a number of @code{@@include} commands listing the included files.  It
+should not even include indices, which should be listed in an included
+file of their own.@refill
+
+Moreover, each of the included files must contain exactly one highest
+level node (conventionally, @code{@@chapter} or equivalent),
+and this node must be the first node in the included file.
+Furthermore, each of these highest level nodes in each included file
+must be at the same hierarchical level in the file structure.
+Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
+@code{@@unnumbered} node.  Thus, normally, each included file contains
+one, and only one, chapter or equivalent-level node.@refill
+
+The outer file should contain only @emph{one} node, the `Top' node.  It
+should @emph{not} contain any nodes besides the single `Top' node.  The
+@code{texinfo-multiple-files-update} command will not process
+them.@refill
+
+
+@node Sample Include File
+@section Sample File with @code{@@include}
+@cindex Sample @code{@@include} file
+@cindex Include file sample
+@cindex @code{@@include} file sample
+
+Here is an example of an outer Texinfo file with @code{@@include} files
+within it before running @code{texinfo-multiple-files-update}, which
+would insert a main or master menu:
+
+@example
+@group
+\input texinfo @@c -*-texinfo-*-
+@c %**start of header
+@@setfilename include-example.info
+@@settitle Include Example
+@c %**end of header
+@end group
+
+... @xref{Sample Texinfo Files}, for
+examples of the rest of the frontmatter ...
+
+@group
+@@ifnottex
+@@node Top
+@@top Include Example
+@@end ifnottex
+@end group
+
+@group
+@@include foo.texinfo
+@@include bar.texinfo
+@@include concept-index.texinfo
+@@bye
+@end group
+@end example
+
+An included file, such as @file{foo.texinfo}, might look like this:
+
+@example
+@group
+@@node First
+@@chapter First Chapter
+
+Contents of first chapter @dots{}
+@end group
+@end example
+
+The full contents of @file{concept-index.texinfo} might be as simple as this:
+
+@example
+@group
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
+@end group
+@end example
+
+The outer Texinfo source file for @cite{The XEmacs Lisp Reference
+Manual} is named @file{elisp.texi}.  This outer file contains a master
+menu with 417 entries and a list of 41 @code{@@include}
+files.
+
+
+@node Include Files Evolution
+@section Evolution of Include Files
+
+When Info was first created, it was customary to create many small
+Info files on one subject.  Each Info file was formatted from its own
+Texinfo source file.  This custom meant that XEmacs did not need to
+make a large buffer to hold the whole of a large Info file when
+someone wanted information; instead, XEmacs allocated just enough
+memory for the small Info file that contained the particular
+information sought.  This way, XEmacs could avoid wasting memory.@refill
+
+References from one file to another were made by referring to the file
+name as well as the node name. (@xref{Other Info Files, , Referring to
+Other Info Files}.  Also, see @ref{Four and Five Arguments, ,
+@code{@@xref} with Four and Five Arguments}.)@refill
+
+Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files.  In a printed
+manual, all the references were within the same document, so @TeX{}
+could automatically determine the references' page numbers.  The Info
+formatting commands used include files only for creating joint
+indices; each of the individual Texinfo files had to be formatted for
+Info individually.  (Each, therefore, required its own
+@code{@@setfilename} line.)@refill
+
+However, because large Info files are now split automatically, it is
+no longer necessary to keep them small.@refill
+
+Nowadays, multiple Texinfo files are used mostly for large documents,
+such as @cite{The XEmacs Lisp Reference Manual}, and for projects
+in which several different people write different sections of a
+document simultaneously.@refill
+
+In addition, the Info formatting commands have been extended to work
+with the @code{@@include} command so as to create a single large Info
+file that is split into smaller files if necessary.  This means that
+you can write menus and cross references without naming the different
+Texinfo files.@refill
+
+
+@node Headings
+@appendix Page Headings
+@cindex Headings
+@cindex Footings
+@cindex Page numbering
+@cindex Page headings
+@cindex Formatting headings and footings
+
+Most printed manuals contain headings along the top of every page
+except the title and copyright pages.  Some manuals also contain
+footings.  (Headings and footings have no meaning to Info, which is
+not paginated.)@refill
+
+@menu
+* Headings Introduced::         Conventions for using page headings.
+* Heading Format::              Standard page heading formats.
+* Heading Choice::              How to specify the type of page heading.
+* Custom Headings::             How to create your own headings and footings.
+@end menu
+
+@node Headings Introduced
+@section Headings Introduced
+
+Texinfo provides standard page heading formats for manuals that are
+printed on one side of each sheet of paper and for manuals that are
+printed on both sides of the paper.  Typically, you will use these
+formats, but you can specify your own format if you wish.@refill
+
+In addition, you can specify whether chapters should begin on a new
+page, or merely continue the same page as the previous chapter; and if
+chapters begin on new pages, you can specify whether they must be
+odd-numbered pages.@refill
+
+By convention, a book is printed on both sides of each sheet of paper.
+When you open a book, the right-hand page is odd-numbered, and
+chapters begin on right-hand pages---a preceding left-hand page is
+left blank if necessary.  Reports, however, are often printed on just
+one side of paper, and chapters begin on a fresh page immediately
+following the end of the preceding chapter.  In short or informal
+reports, chapters often do not begin on a new page at all, but are
+separated from the preceding text by a small amount of whitespace.@refill
+
+The @code{@@setchapternewpage} command controls whether chapters begin
+on new pages, and whether one of the standard heading formats is used.
+In addition, Texinfo has several heading and footing commands that you
+can use to generate your own heading and footing formats.@refill
+
+In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part.  Any part, or a whole line, may be left
+blank.  Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set flushright.@refill
+
+@node Heading Format
+@comment  node-name,  next,  previous,  up
+@section Standard Heading Formats
+
+Texinfo provides two standard heading formats, one for manuals printed
+on one side of each sheet of paper, and the other for manuals printed
+on both sides of the paper.
+
+By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains blank.@refill
+
+The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page
+number.@refill
+
+@need 950
+A single-sided page looks like this:
+
+@example
+@group
+  _______________________
+ |                       |
+ | chapter   page number |
+ |                       |
+ | Start of text ...     |
+ | ...                   |
+ |                       |
+@end group
+@end example
+
+The standard format for two-sided printing depends on whether the page
+number is even or odd.  By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right.  (@TeX{} will adjust the
+widths of the left- and right-hand margins.  Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly---sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)@refill
+
+In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
+@code{@@settitle} command).  The left part of the right-hand
+(odd-numbered) page contains the name of the chapter, the central part
+is blank, and the right part contains the page number.@refill
+
+@need 750
+Two pages, side by side as in an open book, look like this:@refill
+
+@example
+@group
+  _______________________     _______________________
+ |                       |   |                       |
+ | page number     title |   | chapter   page number |
+ |                       |   |                       |
+ | Start of text ...     |   | More  text ...        |
+ | ...                   |   | ...                   |
+ |                       |   |                       |
+@end group
+@end example
+
+@noindent
+The chapter name is preceded by the word ``Chapter'', the chapter number
+and a colon.  This makes it easier to keep track of where you are in the
+manual.@refill
+
+@node Heading Choice
+@comment  node-name,  next,  previous,  up
+@section Specifying the Type of Heading
+
+@TeX{} does not begin to generate page headings for a standard Texinfo
+file until it reaches the @code{@@end titlepage} command.  Thus, the
+title and copyright pages are not numbered.  The @code{@@end
+titlepage} command causes @TeX{} to begin to generate page headings
+according to a standard format specified by the
+@code{@@setchapternewpage} command that precedes the
+@code{@@titlepage} section.@refill
+
+@need 1000
+There are four possibilities:@refill
+
+@table @asis
+@item No @code{@@setchapternewpage} command
+Cause @TeX{} to specify the single-sided heading format, with chapters
+on new pages. This is the same as @code{@@setchapternewpage on}.@refill
+
+@item @code{@@setchapternewpage on}
+Specify the single-sided heading format, with chapters on new pages.@refill
+
+@item @code{@@setchapternewpage off}
+Cause @TeX{} to start a new chapter on the same page as the last page of
+the preceding chapter, after skipping some vertical whitespace.  Also
+cause @TeX{} to typeset for single-sided printing.  (You can override
+the headers format with the @code{@@headings double} command; see
+@ref{headings on off, , The @code{@@headings} Command}.)@refill
+
+@item @code{@@setchapternewpage odd}
+Specify the double-sided heading format, with chapters on new pages.@refill
+@end table
+
+@noindent
+Texinfo lacks an @code{@@setchapternewpage even} command.@refill
+
+@node Custom Headings
+@comment  node-name,  next,  previous,  up
+@section How to Make Your Own Headings
+
+You can use the standard headings provided with Texinfo or specify
+your own.  By default, Texinfo has no footers, so if you specify them,
+the available page size for the main text will be slightly reduced.
+
+Texinfo provides six commands for specifying headings and
+footings:
+@itemize @bullet
+@item
+@code{@@everyheading} @code{@@everyfooting} generate page headers and
+footers that are the same for both even- and odd-numbered pages.
+@item
+@code{@@evenheading} and @code{@@evenfooting} command generate headers
+and footers for even-numbered (left-hand) pages.
+@item
+@code{@@oddheading} and @code{@@oddfooting} generate headers and footers
+for odd-numbered (right-hand) pages.
+@end itemize
+
+Write custom heading specifications in the Texinfo file immediately
+after the @code{@@end titlepage} command.
+You must cancel the predefined heading commands with the
+@code{@@headings off} command before defining your own
+specifications.
+
+@need 1000
+Here is how to tell @TeX{} to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:
+
+@example
+@group
+@@headings off
+@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
+@end group
+@end example
+
+@noindent
+You need to divide the left part from the central part and the central
+part from the right part by inserting @samp{@@|} between parts.
+Otherwise, the specification command will not be able to tell where
+the text for one part ends and the next part begins.
+
+Each part can contain text or @@-commands.  The text
+is printed as if the part were within an ordinary paragraph in the
+body of the page.  The @@-commands replace
+themselves with the page number, date, chapter name, or
+whatever.
+
+@need 950
+Here are the six heading and footing commands:
+
+@table @code
+@item @@everyheading @var{left} @@| @var{center} @@| @var{right}
+@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
+@findex everyheading
+@findex everyfooting
+The `every' commands specify the format for both even- and odd-numbered
+pages.  These commands are for documents that are printed on one side
+of each sheet of paper, or for documents in which you want symmetrical
+headers or footers.
+
+@item @@evenheading @var{left} @@| @var{center} @@| @var{right}
+@itemx @@oddheading  @var{left} @@| @var{center} @@| @var{right}
+@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
+@itemx @@oddfooting  @var{left} @@| @var{center} @@| @var{right}
+@findex evenheading
+@findex evenfooting
+@findex oddheading
+@findex oddfooting
+The `even' and `odd' commands specify the format for even-numbered
+pages and odd-numbered pages.  These commands are for books and
+manuals that are printed on both sides of each sheet of paper.
+@end table
+
+Use the @samp{@@this@dots{}} series of @@-commands to
+provide the names of chapters
+and sections and the page number.  You can use the
+@samp{@@this@dots{}} commands in the left, center, or right portions
+of headers and footers, or anywhere else in a Texinfo file so long as
+they are between @code{@@iftex} and @code{@@end iftex} commands.
+
+@need 1000
+Here are the @samp{@@this@dots{}} commands:
+
+@table @code
+@item @@thispage
+@findex thispage
+Expands to the current page number.
+
+@item @@thissectionname
+@findex thissectionname
+Expands to the name of the current section.
+
+@item @@thissectionnum
+@findex thissectionnum
+Expands to the number of the current section.
+
+@item @@thissection
+@findex thissection
+Expands to the number and name of the current section, in the format
+`Section 1: Title'.
+
+@item @@thischaptername
+@findex thischaptername
+Expands to the name of the current chapter.
+
+@item @@thischapternum
+@findex thischapternum
+Expands to the number of the current chapter, or letter of the current
+appendix.
+
+@item @@thischapter
+@findex thischapter
+Expands to the number and name of the current
+chapter, in the format `Chapter 1: Title'.
+
+@item @@thistitle
+@findex thistitle
+Expands to the name of the document, as specified by the
+@code{@@settitle} command.
+
+@item @@thisfile
+@findex thisfile
+For @code{@@include} files only: expands to the name of the current
+@code{@@include} file.  If the current Texinfo source file is not an
+@code{@@include} file, this command has no effect.  This command does
+@emph{not} provide the name of the current Texinfo source file unless
+it is an @code{@@include} file.  (@xref{Include Files}, for more
+information about @code{@@include} files.)
+@end table
+
+@noindent
+You can also use the @code{@@today@{@}} command, which expands to the
+current date, in `1 Jan 1900' format.
+@findex today
+
+Other @@-commands and text are printed in a header or footer just as
+if they were in the body of a page.  It is useful to incorporate text,
+particularly when you are writing drafts:
+
+@example
+@group
+@@headings off
+@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
+@@everyfooting @@| @@| Version: 0.27: @@today@{@}
+@end group
+@end example
+
+Beware of overlong titles: they may overlap another part of the
+header or footer and blot it out.
+
+If you have very short chapters and/or sections, several of them can
+appear on a single page.  You can specify which chapters and sections
+you want @code{@@thischapter}, @code{@@thissection} and other such
+macros to refer to on such pages as follows:
+
+@table @code
+@item @@everyheadingmarks @var{ref}
+@itemx @@everyfootingmarks @var{ref}
+@findex everyheadingmarks
+@findex everyfootingmarks
+The @var{ref} argument can be either @code{top} (the @code{@@this...}
+commands will refer to the chapter/section at the top of a page) or
+@code{bottom} (the commands will reflect the situation at the bottom
+of a page).  These @samp{@@every...} commands specify what to do on
+both even- and odd-numbered pages.
+
+@item @@evenheadingmarks @var{ref}
+@itemx @@oddheadingmarks @var{ref}
+@itemx @@evenfootingmarks @var{ref}
+@itemx @@oddfootingmarks @var{ref}
+@findex evenheadingmarks
+@findex oddheadingmarks
+@findex evenfootingmarks
+@findex oddfootingmarks
+These @samp{@@even...} and @samp{@@odd...} commands specify what to do
+on only even- or odd-numbered pages, respectively.  The @var{ref}
+argument is the same as with the @samp{@@every...} commands.
+@end table
+
+Write these commands immediately after the @code{@@...contents}
+commands, or after the @code{@@end titlepage} command if you don't
+have a table of contents or if it is printed at the end of your
+manual.
+
+By default the @code{@@this...} commands reflect the situation at the
+bottom of a page both in headings and in footings.
+
+
+@node Catching Mistakes
+@appendix Formatting Mistakes
+@cindex Structure, catching mistakes in
+@cindex Nodes, catching mistakes
+@cindex Catching mistakes
+@cindex Correcting mistakes
+@cindex Mistakes, catching
+@cindex Problems, catching
+@cindex Debugging the Texinfo structure
+
+Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
+
+XEmacs has two tools for catching the @@-command mistakes and two for
+catching structuring mistakes.@refill
+
+For finding problems with @@-commands, you can run @TeX{} or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write it.@refill
+
+For finding problems with the structure of nodes and chapters, you can use
+@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
+command and you can use the @kbd{M-x Info-validate} command.@refill
+
+@menu
+* makeinfo Preferred::          @code{makeinfo} finds errors.
+* Debugging with Info::         How to catch errors with Info formatting.
+* Debugging with TeX::          How to catch errors with @TeX{} formatting.
+* Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
+* Using occur::                 How to list all lines containing a pattern.
+* Running Info-Validate::       How to find badly referenced nodes.
+@end menu
+
+
+@node makeinfo Preferred
+@section @code{makeinfo} Find Errors
+
+The @code{makeinfo} program does an excellent job of catching errors
+and reporting them---far better than @code{texinfo-format-region} or
+@code{texinfo-format-buffer}.  In addition, the various functions for
+automatically creating and updating node pointers and menus remove
+many opportunities for human error.@refill
+
+If you can, use the updating commands to create and insert pointers
+and menus.  These prevent many errors.  Then use @code{makeinfo} (or
+its Texinfo mode manifestations, @code{makeinfo-region} and
+@code{makeinfo-buffer}) to format your file and check for other
+errors.  This is the best way to work with Texinfo.  But if you
+cannot use @code{makeinfo}, or your problem is very puzzling, then you
+may want to use the tools described in this appendix.@refill
+
+@node Debugging with Info
+@comment  node-name,  next,  previous,  up
+@section Catching Errors with Info Formatting
+@cindex Catching errors with Info formatting
+@cindex Debugging with Info formatting
+
+After you have written part of a Texinfo file, you can use the
+@code{texinfo-format-region} or the @code{makeinfo-region} command to
+see whether the region formats properly.@refill
+
+Most likely, however, you are reading this section because for some
+reason you cannot use the @code{makeinfo-region} command; therefore, the
+rest of this section presumes that you are using
+@code{texinfo-format-region}.@refill
+
+If you have made a mistake with an @@-command,
+@code{texinfo-format-region} will stop processing at or after the
+error and display an error message.  To see where in the buffer the
+error occurred, switch to the @samp{*Info Region*} buffer; the cursor
+will be in a position that is after the location of the error.  Also,
+the text will not be formatted after the place where the error
+occurred (or more precisely, where it was detected).@refill
+
+For example, if you accidentally end a menu with the command @code{@@end
+menus} with an `s' on the end, instead of with @code{@@end menu}, you
+will see an error message that says:@refill
+
+@example
+@@end menus is not handled by texinfo
+@end example
+
+@noindent
+The cursor will stop at the point in the buffer where the error
+occurs, or not long after it.  The buffer will look like this:@refill
+
+@example
+@group
+---------- Buffer: *Info Region* ----------
+* Menu:
+
+* Using texinfo-show-structure::  How to use
+                                 `texinfo-show-structure'
+                                 to catch mistakes.
+* Running Info-Validate::         How to check for
+                                 unreferenced nodes.
+@@end menus
+@point{}
+---------- Buffer: *Info Region* ----------
+@end group
+@end example
+
+The @code{texinfo-format-region} command sometimes provides slightly
+odd error messages.  For example, the following cross reference fails to format:@refill
+
+@example
+(@@xref@{Catching Mistakes, for more info.)
+@end example
+
+@noindent
+In this case, @code{texinfo-format-region} detects the missing closing
+brace but displays a message that says @samp{Unbalanced parentheses}
+rather than @samp{Unbalanced braces}.  This is because the formatting
+command looks for mismatches between braces as if they were
+parentheses.@refill
+
+Sometimes @code{texinfo-format-region} fails to detect mistakes.  For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:@refill
+
+@example
+(@@xref@{Catching Mistakes), for more info.@}
+@end example
+
+@noindent
+Formatting produces:
+@example
+(*Note for more info.: Catching Mistakes)
+@end example
+
+The only way for you to detect this error is to realize that the
+reference should have looked like this:@refill
+
+@example
+(*Note Catching Mistakes::, for more info.)
+@end example
+
+Incidentally, if you are reading this node in Info and type @kbd{f
+@key{RET}} (@code{Info-follow-reference}), you will generate an error
+message that says:
+
+@example
+No such node: "Catching Mistakes) The only way @dots{}
+@end example
+
+@noindent
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a @key{RET} immediately
+after typing the Info @kbd{f} command, Info will attempt to go to the
+referenced node.  If you type @kbd{f catch @key{TAB} @key{RET}}, Info
+will complete the node name of the correctly written example and take
+you to the `Catching Mistakes' node.  (If you try this, you can return
+from the `Catching Mistakes' node by typing @kbd{l}
+(@code{Info-last}).)
+
+@c !!! section on using Elisp debugger ignored.
+@ignore
+Sometimes @code{texinfo-format-region} will stop long after the
+original error; this is because it does not discover the problem until
+then.  In this case, you will need to backtrack.@refill
+
+@c menu
+@c * Using the XEmacs Lisp Debugger::  How to use the XEmacs Lisp debugger.
+@c end menu
+
+@c node Using the XEmacs Lisp Debugger
+@c appendixsubsec Using the XEmacs Lisp Debugger
+@c index Using the XEmacs Lisp debugger
+@c index XEmacs Lisp debugger
+@c index Debugger, using the XEmacs Lisp
+
+If an error is especially elusive, you can turn on the XEmacs Lisp
+debugger and look at the backtrace; this tells you where in the
+@code{texinfo-format-region} function the problem occurred.  You can
+turn on the debugger with the command:@refill
+
+@example
+M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
+@end example
+
+@noindent
+and turn it off with
+
+@example
+M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
+@end example
+
+Often, when you are using the debugger, it is easier to follow what is
+going on if you use the XEmacs Lisp files that are not byte-compiled.
+The byte-compiled sources send octal numbers to the debugger that may
+look mysterious.  To use the uncompiled source files, load
+@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
+command.@refill
+
+The debugger will not catch an error if @code{texinfo-format-region}
+does not detect one.  In the example shown above,
+@code{texinfo-format-region} did not find the error when the whole
+list was formatted, but only when part of the list was formatted.
+When @code{texinfo-format-region} did not find an error, the debugger
+did not find one either. @refill
+
+However, when @code{texinfo-format-region} did report an error, it
+invoked the debugger.  This is the backtrace it produced:@refill
+
+@example
+---------- Buffer: *Backtrace* ----------
+Signalling: (search-failed "[@},]")
+ re-search-forward("[@},]")
+ (while ...)
+ (let ...)
+ texinfo-format-parse-args()
+ (let ...)
+ texinfo-format-xref()
+ funcall(texinfo-format-xref)
+ (if ...)
+ (let ...)
+ (if ...)
+ (while ...)
+ texinfo-format-scan()
+ (save-excursion ...)
+ (let ...)
+ texinfo-format-region(103370 103631)
+* call-interactively(texinfo-format-region)
+---------- Buffer: *Backtrace* ----------
+@end example
+
+The backtrace is read from the bottom up.
+@code{texinfo-format-region} was called interactively; and it, in
+turn, called various functions, including @code{texinfo-format-scan},
+@code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
+Inside the function @code{texinfo-format-parse-args}, the function
+@code{re-search-forward} was called; it was this function that could
+not find the missing right-hand brace.@refill
+
+@xref{Lisp Debug, , Debugging XEmacs Lisp, xemacs, XEmacs User's Manual},
+for more information.@refill
+@end ignore
+
+@node Debugging with TeX
+@comment  node-name,  next,  previous,  up
+@section Catching Errors with @TeX{} Formatting
+@cindex Catching errors with @TeX{} formatting
+@cindex Debugging with @TeX{} formatting
+
+You can also catch mistakes when you format a file with @TeX{}.@refill
+
+Usually, you will want to do this after you have run
+@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
+the same file, because @code{texinfo-format-buffer} sometimes displays
+error messages that make more sense than @TeX{}.  (@xref{Debugging
+with Info}, for more information.)@refill
+
+For example, @TeX{} was run on a Texinfo file, part of which is shown
+here:@refill
+
+@example
+---------- Buffer: texinfo.texi ----------
+name of the Texinfo file as an extension.  The
+@@samp@{??@} are `wildcards' that cause the shell to
+substitute all the raw index files.  (@@xref@{sorting
+indices, for more information about sorting
+indices.)@@refill
+---------- Buffer: texinfo.texi ----------
+@end example
+
+@noindent
+(The cross reference lacks a closing brace.)
+@TeX{} produced the following output, after which it stopped:@refill
+
+@example
+---------- Buffer: *tex-shell* ----------
+Runaway argument?
+@{sorting indices, for more information about sorting
+indices.) @@refill @@ETC.
+! Paragraph ended before @@xref was complete.
+<to be read again>
+                  @@par
+l.27
+
+?
+---------- Buffer: *tex-shell* ----------
+@end example
+
+In this case, @TeX{} produced an accurate and
+understandable error message:
+
+@example
+Paragraph ended before @@xref was complete.
+@end example
+
+@noindent
+@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
+@samp{l.27} means that @TeX{} detected the problem on line 27 of the
+Texinfo file.  The @samp{?} is the prompt @TeX{} uses in this
+circumstance.@refill
+
+Unfortunately, @TeX{} is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went wrong.@refill
+
+In any case, if you run into a problem like this, you can do one of three
+things.@refill
+
+@enumerate
+@item
+You can tell @TeX{} to continue running and ignore just this error by
+typing @key{RET} at the @samp{?} prompt.@refill
+
+@item
+You can tell @TeX{} to continue running and to ignore all errors as best
+it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
+
+This is often the best thing to do.  However, beware: the one error
+may produce a cascade of additional error messages as its consequences
+are felt through the rest of the file.  To stop @TeX{} when it is
+producing such an avalanche of error messages, type @kbd{C-c} (or
+@kbd{C-c C-c}, if you are running a shell inside XEmacs).
+
+@item
+You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
+at the @samp{?} prompt.@refill
+@end enumerate
+
+If you are running @TeX{} inside XEmacs, you need to switch to the shell
+buffer and line at which @TeX{} offers the @samp{?} prompt.
+
+Sometimes @TeX{} will format a file without producing error messages even
+though there is a problem.  This usually occurs if a command is not ended
+but @TeX{} is able to continue processing anyhow.  For example, if you fail
+to end an itemized list with the @code{@@end itemize} command, @TeX{} will
+write a DVI file that you can print out.  The only error message that
+@TeX{} will give you is the somewhat mysterious comment that@refill
+
+@example
+(@@end occurred inside a group at level 1)
+@end example
+
+@noindent
+However, if you print the DVI file, you will find that the text
+of the file that follows the itemized list is entirely indented as if
+it were part of the last item in the itemized list.  The error message
+is the way @TeX{} says that it expected to find an @code{@@end}
+command somewhere in the file; but that it could not determine where
+it was needed.@refill
+
+Another source of notoriously hard-to-find errors is a missing
+@code{@@end group} command.  If you ever are stumped by
+incomprehensible errors, look for a missing @code{@@end group} command
+first.@refill
+
+If the Texinfo file lacks header lines,
+@TeX{} may stop in the
+beginning of its run and display output that looks like the following.
+The @samp{*} indicates that @TeX{} is waiting for input.@refill
+
+@example
+This is TeX, Version 3.14159 (Web2c 7.0)
+(test.texinfo [1])
+*
+@end example
+
+@noindent
+In this case, simply type @kbd{\end @key{RET}} after the asterisk.  Then
+write the header lines in the Texinfo file and run the @TeX{} command
+again. (Note the use of the backslash, @samp{\}.  @TeX{} uses @samp{\}
+instead of @samp{@@}; and in this circumstance, you are working
+directly with @TeX{}, not with Texinfo.)@refill
+
+@node Using texinfo-show-structure
+@comment  node-name,  next,  previous,  up
+@section Using @code{texinfo-show-structure}
+@cindex Showing the structure of a file
+@findex texinfo-show-structure
+
+It is not always easy to keep track of the nodes, chapters, sections, and
+subsections of a Texinfo file.  This is especially true if you are revising
+or adding to a Texinfo file that someone else has written.@refill
+
+In XEmacs, in Texinfo mode, the @code{texinfo-show-structure}
+command lists all the lines that begin with the @@-commands that
+specify the structure: @code{@@chapter}, @code{@@section},
+@code{@@appendix}, and so on.  With an argument (@w{@kbd{C-u}}
+as prefix argument, if interactive),
+the command also shows the @code{@@node} lines.  The
+@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
+Texinfo mode, by default.@refill
+
+The lines are displayed in a buffer called the @samp{*Occur*} buffer,
+indented by hierarchical level.  For example, here is a part of what was
+produced by running @code{texinfo-show-structure} on this manual:@refill
+
+@example
+@group
+Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
+unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+in buffer texinfo.texi.
+@dots{}
+4177:@@chapter Nodes
+4198:    @@heading Two Paths
+4231:    @@section Node and Menu Illustration
+4337:    @@section The @@code@{@@@@node@} Command
+4393:        @@subheading Choosing Node and Pointer Names
+4417:        @@subsection How to Write an @@code@{@@@@node@} Line
+4469:        @@subsection @@code@{@@@@node@} Line Tips
+@dots{}
+@end group
+@end example
+
+This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
+with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
+commands respectively.  If you move your cursor into the @samp{*Occur*}
+window, you can position the cursor over one of the lines and use the
+@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
+the corresponding spot in the Texinfo file.  @xref{Other Repeating
+Search, , Using Occur, xemacs, XEmacs User's Manual}, for more
+information about @code{occur-mode-goto-occurrence}.@refill
+
+The first line in the @samp{*Occur*} window describes the @dfn{regular
+expression} specified by @var{texinfo-heading-pattern}.  This regular
+expression is the pattern that @code{texinfo-show-structure} looks for.
+@xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual},
+for more information.@refill
+
+When you invoke the @code{texinfo-show-structure} command, XEmacs will
+display the structure of the whole buffer.  If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
+region.  (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.)  This is
+how the example used above was generated.  (To see the whole buffer
+again, use @kbd{C-x n w} (@code{widen}).)@refill
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
+@code{@@node} as well as the lines beginning with the @@-sign commands
+for @code{@@chapter}, @code{@@section}, and the like.@refill
+
+You can remind yourself of the structure of a Texinfo file by looking at
+the list in the @samp{*Occur*} window; and if you have mis-named a node
+or left out a section, you can correct the mistake.@refill
+
+@node Using occur
+@comment  node-name,  next,  previous,  up
+@section Using @code{occur}
+@cindex Occurrences, listing with @code{@@occur}
+@findex occur
+
+Sometimes the @code{texinfo-show-structure} command produces too much
+information.  Perhaps you want to remind yourself of the overall structure
+of a Texinfo file, and are overwhelmed by the detailed list produced by
+@code{texinfo-show-structure}.  In this case, you can use the @code{occur}
+command directly.  To do this, type@refill
+
+@example
+@kbd{M-x occur}
+@end example
+
+@noindent
+and then, when prompted, type a @dfn{regexp}, a regular expression for
+the pattern you want to match.  (@xref{Regexps, , Regular Expressions,
+xemacs, XEmacs User's Manual}.)  The @code{occur} command works from the
+current location of the cursor in the buffer to the end of the buffer.
+If you want to run @code{occur} on the whole buffer, place the cursor at
+the beginning of the buffer.@refill
+
+For example, to see all the lines that contain the word
+@samp{@@chapter} in them, just type @samp{@@chapter}.  This will
+produce a list of the chapters.  It will also list all the sentences
+with @samp{@@chapter} in the middle of the line.@refill
+
+If you want to see only those lines that start with the word
+@samp{@@chapter}, type @samp{^@@chapter} when prompted by
+@code{occur}.  If you want to see all the lines that end with a word
+or phrase, end the last word with a @samp{$}; for example,
+@samp{catching mistakes$}.  This can be helpful when you want to see
+all the nodes that are part of the same chapter or section and
+therefore have the same `Up' pointer.@refill
+
+@xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual},
+for more information.@refill
+
+@node Running Info-Validate
+@comment  node-name,  next,  previous,  up
+@section Finding Badly Referenced Nodes
+@findex Info-validate
+@cindex Nodes, checking for badly referenced
+@cindex Checking for badly referenced nodes
+@cindex Looking for badly referenced nodes
+@cindex Finding badly referenced nodes
+@cindex Badly referenced nodes
+
+You can use the @code{Info-validate} command to check whether any of
+the `Next', `Previous', `Up' or other node pointers fail to point to a
+node.  This command checks that every node pointer points to an
+existing node.  The @code{Info-validate} command works only on Info
+files, not on Texinfo files.@refill
+
+The @code{makeinfo} program validates pointers automatically, so you
+do not need to use the @code{Info-validate} command if you are using
+@code{makeinfo}.  You only may need to use @code{Info-validate} if you
+are unable to run @code{makeinfo} and instead must create an Info file
+using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
+if you write an Info file from scratch.@refill
+
+@menu
+* Using Info-validate::         How to run @code{Info-validate}.
+* Unsplit::                     How to create an unsplit file.
+* Tagifying::                   How to tagify a file.
+* Splitting::                   How to split a file manually.
+@end menu
+
+@node Using Info-validate
+@subsection Running @code{Info-validate}
+@cindex Running @code{Info-validate}
+@cindex Info validating a large file
+@cindex Validating a large file
+
+To use @code{Info-validate}, visit the Info file you wish to check and
+type:@refill
+
+@example
+M-x Info-validate
+@end example
+
+@noindent
+Note that the @code{Info-validate} command requires an upper case
+`I'.  You may also need to create a tag table before running
+@code{Info-validate}.  @xref{Tagifying}.
+
+If your file is valid, you will receive a message that says ``File appears
+valid''.  However, if you have a pointer that does not point to a node,
+error messages will be displayed in a buffer called @samp{*problems in
+info file*}.@refill
+
+For example, @code{Info-validate} was run on a test file that contained
+only the first node of this manual.  One of the messages said:@refill
+
+@example
+In node "Overview", invalid Next: Texinfo Mode
+@end example
+
+@noindent
+This meant that the node called @samp{Overview} had a `Next' pointer that
+did not point to anything (which was true in this case, since the test file
+had only one node in it).@refill
+
+Now suppose we add a node named @samp{Texinfo Mode} to our test case
+but we do not specify a `Previous' for this node.  Then we will get
+the following error message:@refill
+
+@example
+In node "Texinfo Mode", should have Previous: Overview
+@end example
+
+@noindent
+This is because every `Next' pointer should be matched by a
+`Previous' (in the node where the `Next' points) which points back.@refill
+
+@code{Info-validate} also checks that all menu entries and cross references
+point to actual nodes.@refill
+
+@code{Info-validate} requires a tag table and does not work with files
+that have been split.  (The @code{texinfo-format-buffer} command
+automatically splits large files.)  In order to use @code{Info-validate}
+on a large file, you must run @code{texinfo-format-buffer} with an
+argument so that it does not split the Info file; and you must create a
+tag table for the unsplit file.
+
+@node Unsplit
+@comment  node-name,  next,  previous,  up
+@subsection Creating an Unsplit File
+@cindex Creating an unsplit file
+@cindex Unsplit file creation
+
+You can run @code{Info-validate} only on a single Info file that has a
+tag table.  The command will not work on the indirect subfiles that
+are generated when a master file is split.  If you have a large file
+(longer than 300,000 bytes or so), you need to run the
+@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
+a way that it does not create indirect subfiles.  You will also need
+to create a tag table for the Info file.  After you have done this,
+you can run @code{Info-validate} and look for badly referenced
+nodes.@refill
+
+The first step is to create an unsplit Info file.  To prevent
+@code{texinfo-format-buffer} from splitting a Texinfo file into
+smaller Info files, give a prefix to the @kbd{M-x
+texinfo-format-buffer} command:@refill
+
+@example
+C-u M-x texinfo-format-buffer
+@end example
+
+@noindent
+or else
+
+@example
+C-u C-c C-e C-b
+@end example
+
+@noindent
+When you do this, Texinfo will not split the file and will not create
+a tag table for it. @refill
+@cindex Making a tag table manually
+@cindex Tag table, making manually
+
+@node Tagifying
+@subsection Tagifying a File
+
+After creating an unsplit Info file, you must create a tag table for
+it.  Visit the Info file you wish to tagify and type:@refill
+
+@example
+M-x Info-tagify
+@end example
+
+@noindent
+(Note the upper case @samp{I} in @code{Info-tagify}.)  This creates an
+Info file with a tag table that you can validate.@refill
+
+The third step is to validate the Info file:@refill
+
+@example
+M-x Info-validate
+@end example
+
+@noindent
+(Note the upper case @samp{I} in @code{Info-validate}.)
+In brief, the steps are:@refill
+
+@example
+@group
+C-u M-x texinfo-format-buffer
+M-x Info-tagify
+M-x Info-validate
+@end group
+@end example
+
+After you have validated the node structure, you can rerun
+@code{texinfo-format-buffer} in the normal way so it will construct a
+tag table and split the file automatically, or you can make the tag
+table and split the file manually.@refill
+
+@node Splitting
+@comment  node-name,  next,  previous,  up
+@subsection Splitting a File Manually
+@cindex Splitting an Info file manually
+@cindex Info file, splitting manually
+
+You should split a large file or else let the
+@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
+for you automatically.  (Generally you will let one of the formatting
+commands do this job for you.  @xref{Creating an Info File}.)@refill
+
+The split-off files are called the indirect subfiles.@refill
+
+Info files are split to save memory.  With smaller files, XEmacs does not
+have make such a large buffer to hold the information.@refill
+
+If an Info file has more than 30 nodes, you should also make a tag
+table for it. @xref{Using Info-validate}, for information
+about creating a tag table.  (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually.  Most likely, you
+will do this for a large, unsplit file on which you have run
+@code{Info-validate}.)@refill
+
+@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
+@ignore
+Before running @code{Info-split}, you need to load the @code{info} library
+into XEmacs by giving the command @kbd{M-x load-library @key{RET} info
+@key{RET}}.
+@end ignore
+
+Visit the Info file you wish to tagify and split and type the two
+commands:@refill
+
+@example
+M-x Info-tagify
+M-x Info-split
+@end example
+
+@noindent
+(Note that the @samp{I} in @samp{Info} is upper case.)@refill
+
+When you use the @code{Info-split} command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles.  This file should be
+saved in place of the original visited file.  The indirect subfiles are
+written in the same directory the original file is in, with names generated
+by appending @samp{-} and a number to the original file name.@refill
+
+The primary file still functions as an Info file, but it contains just
+the tag table and a directory of subfiles.@refill
+
+
+@ignore
+The simple description in the command summary seems sufficient to me
+these days, so ignore this appendix.  --karl, 13mar04.
+
+@node Refilling Paragraphs
+@appendix Refilling Paragraphs
+@cindex Refilling paragraphs
+@cindex Filling paragraphs
+@cindex Paragraphs, filling
+@findex refill
+
+The @code{@@refill} command refills and, optionally, indents the first
+line of a paragraph.@footnote{Perhaps the command should have been
+called the @code{@@refillandindent} command, but @code{@@refill} is
+shorter and the name was chosen before indenting was possible.} The
+@code{@@refill} command is no longer important, but we describe it here
+because you once needed it.  You will see it in many old Texinfo
+files.@refill
+
+Without refilling, paragraphs containing long @@-constructs may look
+bad after formatting because the formatter removes @@-commands and
+shortens some lines more than others.  In the past, neither the
+@code{texinfo-format-region} command nor the
+@code{texinfo-format-buffer} command refilled paragraphs
+automatically.  The @code{@@refill} command had to be written at the
+end of every paragraph to cause these formatters to fill them.  (Both
+@TeX{} and @code{makeinfo} have always refilled paragraphs
+automatically.)  Now, all the Info formatters automatically fill and
+indent those paragraphs that need to be filled and indented.@refill
+
+The @code{@@refill} command causes @code{texinfo-format-region} and
+@code{texinfo-format-buffer} to refill a paragraph in the Info file
+@emph{after} all the other processing has been done.  For this reason,
+you can not use @code{@@refill} with a paragraph containing either
+@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
+override those two commands.@refill
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands now automatically append @code{@@refill} to the end of each
+paragraph that should be filled.  They do not append @code{@@refill} to
+the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
+and therefore do not refill or indent them.@refill
+
+@end ignore
+
+
+@c These are no longer ``new'', and the explanations
+@c are all given elsewhere anyway, I think.  --karl, 25apr97.
+@c So ignore the entire appendix.
+@ignore
+@c node New Features, Command and Variable Index, Obtaining TeX, Top
+@c appendix Second Edition Features
+
+@tex
+% Widen the space for the first column so three control-character
+% strings fit in the first column.  Switched back to default .8in
+% value at end of chapter.
+\global\tableindent=1.0in
+@end tex
+
+The second edition of the Texinfo manual describes more than 20 new
+Texinfo mode commands and more than 50 previously undocumented Texinfo
+@@-commands.  This edition is more than twice the length of the first
+edition.@refill
+
+Here is a brief description of the new commands.@refill
+
+@c menu
+* New Texinfo Mode Commands::   The updating commands are especially useful.
+* New Commands::                Many newly described @@-commands.
+@c end menu
+
+@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
+@c appendixsec New Texinfo Mode Commands
+
+Texinfo mode provides commands and features especially designed for
+working with Texinfo files.  More than 20 new commands have been
+added, including commands for automatically creating and updating
+both nodes and menus.  This is a tedious task when done by hand.@refill
+
+The keybindings are intended to be somewhat mnemonic.@refill
+
+@c subheading Update all nodes and menus
+
+The @code{texinfo-master-menu} command is the primary command:
+
+@table @kbd
+@item C-c C-u m
+@itemx M-x texinfo-master-menu
+Create or update a master menu.
+With @kbd{C-u} as a prefix argument,
+first create or update all nodes
+and regular menus.
+@end table
+
+@c subheading Update Pointers
+
+@noindent
+Create or update `Next', `Previous', and `Up' node pointers.@refill
+
+@noindent
+@xref{Updating Nodes and Menus}.
+
+@table @kbd
+@item C-c C-u C-n
+@itemx M-x texinfo-update-node
+Update a node.
+
+@item C-c C-u C-e
+@itemx M-x texinfo-every-node-update
+Update every node in the buffer.
+@end table
+
+@c subheading Update Menus
+
+@noindent
+Create or update menus.@refill
+
+@noindent
+@xref{Updating Nodes and Menus}.
+
+@table @kbd
+@item C-c C-u C-m
+@itemx M-x texinfo-make-menu
+Make or update a menu.
+
+@item C-c C-u C-a
+@itemx M-x texinfo-all-menus-update
+Make or update all the menus in a buffer.
+With @kbd{C-u} as a prefix argument,
+first update all the nodes.
+@end table
+
+@c subheading Insert Title as Description
+
+@noindent
+Insert a node's chapter or section title in the space for the
+description in a menu entry line; position point so you can edit the
+insert.  (This command works somewhat differently than the other
+insertion commands, which insert only a predefined string.)@refill
+
+@noindent
+@xref{Inserting, Inserting Frequently Used Commands}.
+
+@table @kbd
+@item C-c C-c C-d
+Insert title.
+@end table
+
+@c subheading Format for Info
+
+@noindent
+Provide keybindings both for the Info formatting commands that are
+written in XEmacs Lisp and for @code{makeinfo} that is written in
+C.@refill
+
+@noindent
+@xref{Info Formatting}.
+
+@noindent
+Use the XEmacs lisp @code{texinfo-format@dots{}} commands:
+
+@table @kbd
+@item C-c C-e C-r
+Format the region.
+
+@item C-c C-e C-b
+Format the buffer.
+@end table
+
+@noindent
+Use @code{makeinfo}:
+
+@table @kbd
+@item C-c C-m C-r
+Format the region.
+
+@item C-c C-m C-b
+Format the buffer.
+
+@item C-c C-m C-l
+Recenter the @code{makeinfo} output buffer.
+
+@item C-c C-m C-k
+Kill the @code{makeinfo} formatting job.
+@end table
+
+@c subheading Typeset and Print
+
+@noindent
+Typeset and print Texinfo documents from within XEmacs.
+
+@noindent
+@xref{Printing}.
+
+@table @kbd
+@item C-c C-t C-b
+Run @code{texi2dvi} on the buffer.
+
+@item C-c C-t C-r
+Run @TeX{} on the region.
+
+@item C-c C-t C-i
+Run @code{texindex}.
+
+@item C-c C-t C-p
+Print the DVI file.
+
+@item C-c C-t C-q
+Show the print queue.
+
+@item C-c C-t C-d
+Delete a job from the print queue.
+
+@item C-c C-t C-k
+Kill the current @TeX{} formatting job.
+
+@item C-c C-t C-x
+Quit a currently stopped @TeX{} formatting job.
+
+@item C-c C-t C-l
+Recenter the output buffer.
+@end table
+
+@c subheading Other Updating Commands
+
+@noindent
+The ``other updating commands'' do not have standard keybindings because
+they are used less frequently.@refill
+
+@noindent
+@xref{Other Updating Commands}.
+
+@table @kbd
+@item M-x texinfo-insert-node-lines
+Insert missing @code{@@node} lines using
+section titles as node names.
+
+@item M-x texinfo-multiple-files-update
+Update a multi-file document.
+With a numeric prefix, such as @kbd{C-u 8},
+update  @strong{every} pointer and
+menu in @strong{all} the files and
+then insert a master menu.
+
+@item M-x texinfo-indent-menu-description
+Indent descriptions in menus.
+
+@item M-x texinfo-sequential-node-update
+Insert node pointers in strict sequence.
+@end table
+
+@c no.de New Commands,  , New Texinfo Mode Commands, Obtaining TeX
+@c appendix.sec New Texinfo @@-Commands
+
+The second edition of the Texinfo manual describes more than 50
+commands that were not described in the first edition.  A third or so
+of these commands existed in Texinfo but were not documented in the
+manual; the others are new.  Here is a listing, with brief
+descriptions of them:@refill
+
+@c subheading Indexing
+
+@noindent
+Create your own index, and merge indices.@refill
+
+@noindent
+@xref{Indices}.
+
+@table @kbd
+@item @@defindex @var{index-name}
+Define a new index and its indexing command.
+See also the @code{@@defcodeindex} command.
+
+@c written verbosely to avoid overfull hbox
+@item @@synindex @var{from-index} @var{into-index}
+Merge the @var{from-index} index into the @var{into-index} index.
+See also the @code{@@syncodeindex} command.
+@end table
+
+@c subheading Definitions
+
+@noindent
+Describe functions, variables, macros,
+commands, user options, special forms, and other such artifacts in a
+uniform format.@refill
+
+@noindent
+@xref{Definition Commands}.
+
+@table @kbd
+@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
+Format a description for functions, interactive
+commands, and similar entities.
+
+@item @@defvr, @@defop, @dots{}
+15 other related commands.
+@end table
+
+@c subheading Glyphs
+
+@noindent
+Indicate the results of evaluation, expansion,
+printed output, an error message, equivalence of expressions, and the
+location of point.@refill
+
+@noindent
+@xref{Glyphs}.
+
+@table @kbd
+@item @@equiv@{@}
+@itemx @equiv{}
+Equivalence:
+
+@item @@error@{@}
+@itemx @error{}
+Error message
+
+@item @@expansion@{@}
+@itemx @expansion{}
+Macro expansion
+
+@item @@point@{@}
+@itemx @point{}
+Position of point
+
+@item @@print@{@}
+@itemx @print{}
+Printed output
+
+@item @@result@{@}
+@itemx @result{}
+Result of an expression
+@end table
+
+@c subheading Page Headings
+
+@noindent
+Customize page headings.
+
+@noindent
+@xref{Headings}.
+
+@table @kbd
+@item @@headings @var{on-off-single-double}
+Headings on or off, single, or double-sided.
+
+@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
+Footings for even-numbered (left-hand) pages.
+
+@item @@evenheading, @@everyheading, @@oddheading, @dots{}
+Five other related commands.
+
+@item @@thischapter
+Insert name of chapter and chapter number.
+
+@item @@thischaptername, @@thisfile, @@thistitle, @@thispage
+Related commands.
+@end table
+
+@c subheading Formatting
+
+@noindent
+Format blocks of text.
+
+@noindent
+@xref{Quotations and Examples}, and@*
+@ref{Lists and Tables, , Making Lists and Tables}.
+
+@table @kbd
+@item @@cartouche
+Draw rounded box surrounding text (no effect in Info).
+
+@item @@enumerate @var{optional-arg}
+Enumerate a list with letters or numbers.
+
+@item @@exdent @var{line-of-text}
+Remove indentation.
+
+@item @@flushleft
+Left justify.
+
+@item @@flushright
+Right justify.
+
+@item @@format
+Do not narrow nor change font.
+
+@item @@ftable @var{formatting-command}
+@itemx @@vtable @var{formatting-command}
+Two-column table with indexing.
+
+@item @@lisp
+For an example of Lisp code.
+
+@item @@smallexample
+@itemx @@smalllisp
+Like @@table and @@lisp, but for (originally) @@smallbook.
+@end table
+
+@c subheading Conditionals
+
+@noindent
+Conditionally format text.
+
+@noindent
+@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
+
+@table @kbd
+@item @@set @var{flag} [@var{string}]
+Set a flag.  Optionally, set value
+of @var{flag} to @var{string}.
+
+@item @@clear @var{flag}
+Clear a flag.
+
+@item @@value@{@var{flag}@}
+Replace with value to which @var{flag} is set.
+
+@item @@ifset @var{flag}
+Format, if @var{flag} is set.
+
+@item @@ifclear @var{flag}
+Ignore, if @var{flag} is set.
+@end table
+
+@c subheading @@heading series for Titles
+
+@noindent
+Produce unnumbered headings that do not appear in a table of contents.
+
+@noindent
+@xref{Structuring}.
+
+@table @kbd
+@item @@heading @var{title}
+Unnumbered section-like heading not listed
+in the table of contents of a printed manual.
+
+@item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
+Related commands.
+@end table
+
+@need 1000
+@c subheading Font commands
+
+@need 1000
+@noindent
+@xref{Smallcaps}, and @*
+@ref{Fonts}.
+
+@table @kbd
+@item @@r@{@var{text}@}
+Print in roman font.
+
+@item @@sc@{@var{text}@}
+Print in @sc{small caps} font.
+@end table
+
+@c subheading Miscellaneous
+
+@noindent
+See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
+see @ref{Customized Highlighting},@*
+see @ref{Overfull hboxes},@*
+see @ref{Footnotes},@*
+see @ref{dmn, , Format a Dimension},@*
+see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
+see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@*
+see @ref{minus, , Inserting a Minus Sign},@*
+see @ref{paragraphindent, , Paragraph Indenting},@*
+see @ref{Cross Reference Commands},@*
+see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
+see @ref{Custom Headings, , How to Make Your Own Headings}.
+
+@table @kbd
+@item @@author @var{author}
+Typeset author's name.
+
+@c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
+@c Define a highlighting command for Info.  (Info only.)
+
+@item @@finalout
+Produce cleaner printed output.
+
+@item @@footnotestyle @var{end-or-separate}
+Specify footnote style, either @samp{end} or @samp{separate}.
+@xref{Footnote Styles}.
+
+@item @@dmn@{@var{dimension}@}
+Format a dimension.
+
+@item @@global@@let@var{new-cmd}=@var{existing-cmd}
+Define a highlighting command for @TeX{}. (@TeX{} only.)
+
+@item @@lowersections
+Reduce hierarchical level of sectioning commands.
+
+@item @@math@{@var{mathematical-expression}@}
+Format a mathematical expression.
+
+@item @@minus@{@}
+Generate a minus sign.
+
+@item @@paragraphindent @var{asis-or-number}
+Specify paragraph indentation.
+
+@item @@raisesections
+Raise hierarchical level of sectioning commands.
+
+@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
+Make a reference.  In the printed manual, the
+reference does not start with the word `see'.
+
+@item @@title @var{title}
+Typeset @var{title} in the alternative
+title page format.
+
+@item @@subtitle @var{subtitle}
+Typeset @var{subtitle} in the alternative
+title page format.
+
+@item @@today@{@}
+Insert the current date.
+@end table
+@tex
+% Switch width of first column of tables back to default value
+\global\tableindent=.8in
+@end tex
+@end ignore
+
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+
+@node Command and Variable Index
+@unnumbered Command and Variable Index
+
+This is an alphabetical list of all the @@-commands, assorted XEmacs Lisp
+functions, and several variables.  To make the list easier to use, the
+commands are listed without their preceding @samp{@@}.@refill
+
+@printindex fn
+
+
+@node General Index
+@unnumbered General Index
+
+@printindex cp
+
+
+@bye