brain-dead cvs conflict merge

1 files changed, 2176 insertions, 1813 deletions

diff --git a/gnu/usr.bin/texinfo/doc/texinfo.txi b/gnu/usr.bin/texinfo/doc/texinfo.txi
index c34026c9756..5b1efda9b9f 100644
--- a/gnu/usr.bin/texinfo/doc/texinfo.txi
+++ b/gnu/usr.bin/texinfo/doc/texinfo.txi
@@ -1,12 +1,23 @@
 \input texinfo.tex    @c -*-texinfo-*-
-@c $Id: texinfo.txi,v 1.3 2000/02/09 02:18:37 espie Exp $
+@c $Id: texinfo.txi,v 1.4 2002/06/10 13:51:02 espie 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 Emacs's {texinfo,makeinfo}-format region commands.  See the `start of
+@c header' node for more info.
 @c %**start of header
 
-@c All text is ignored before the setfilename.
+@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 texinfo
 
+@c Automake automatically updates version.texi to @set VERSION and
+@c @set UPDATED to appropriate values.
 @include version.texi
-@settitle Texinfo @value{VERSION}
+@settitle GNU Texinfo @value{VERSION}
 
 @c Define a new index for options.
 @defcodeindex op
@@ -18,17 +29,39 @@
 
 @footnotestyle separate
 @paragraphindent 2
-@finalout
+@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 (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
+Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the license is
+included in the section entitled ``GNU Free Documentation License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
 @dircategory Texinfo documentation system
 @direntry
 * Texinfo: (texinfo).           The GNU documentation format.
 * install-info: (texinfo)Invoking install-info. Update info/dir entries.
 * texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
 * texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
-* makeinfo: (texinfo)makeinfo Preferred.        Translate Texinfo source.
+* 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
@@ -42,48 +75,16 @@
 @c set smallbook
 @c @@clear smallbook
 
-@c If you like blank pages.  Can add through texi2dvi -t.
+@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'.)
 
-@ifinfo
-This file documents Texinfo, a documentation system that can produce
-both online information and a printed manual from a single source file.
-
-Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99
-Free Software Foundation, Inc.
-
-This edition is for Texinfo version @value{VERSION}, @value{UPDATED}.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
-@end ifinfo
-
 
 @shorttitlepage Texinfo
 
 @titlepage
-@c use the new format for titles
 @title Texinfo
 @subtitle The GNU Documentation Format
 @subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
@@ -96,56 +97,39 @@ by the Free Software Foundation.
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99
-Free Software Foundation, Inc.
-
-This manual is for Texinfo version @value{VERSION}, @value{UPDATED}.
+@insertcopying
 
 Published by the Free Software Foundation @*
 59 Temple Place Suite 330 @*
 Boston, MA 02111-1307 @*
 USA @*
 ISBN 1-882114-67-1 @c for version 4.0, September 1999.
-@c ISBN 1-882114-65-5 @c for version 3.12, March 1998.
-@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
+@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
 
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
-@sp 2
 Cover art by Etienne Suvasa.
 @end titlepage
 
+
 @summarycontents
 @contents
 
+
 @ifnottex
 @node Top
 @top Texinfo
 
-Texinfo is a documentation system that uses a single source file to
-produce both online information and printed output.
+@insertcopying
 
 The first part of this master menu lists the major nodes in this Info
 document, including the @@-command and concept indices.  The rest of
 the menu lists all the lower level nodes in the document.
 
-This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
 @end ifnottex
 
 @menu
-* Copying::                     Your rights.
+* Copying Conditions::          Your rights.
 * Overview::                    Texinfo in brief.
 * Texinfo Mode::                How to use Texinfo mode.
 * Beginning a File::            What is at the beginning of a Texinfo file?
@@ -173,20 +157,18 @@ This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
 * Creating and Installing Info Files::  
 * Command List::                All the Texinfo @@-commands.
 * Tips::                        Hints on how to write a Texinfo document.
-* Sample Texinfo File::         A sample Texinfo file to look at.
-* Sample Permissions::          Tell readers they have the right to copy
-                                  and distribute.
+* 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.
 * Refilling Paragraphs::        All about paragraph refilling.
 * Command Syntax::              A description of @@-Command syntax.
 * Obtaining TeX::               How to Obtain @TeX{}.
+* Copying This Manual::         The GNU Free Documentation License.
 * Command and Variable Index::  A menu containing commands and variables.
 * Concept Index::               A menu covering many topics.
 
 @detailmenu
-
  --- The Detailed Node Listing ---
 
 Overview of Texinfo
@@ -201,7 +183,7 @@ Overview of Texinfo
 * Minimum::                     What a Texinfo file must have.
 * Six Parts::                   Usually, a Texinfo file has six parts.
 * Short Sample::                A short sample Texinfo file.
-* Acknowledgements and History::  Contributors and genesis.
+* History::                     Acknowledgements, contributors and genesis.
 
 Using Texinfo Mode
 
@@ -226,34 +208,36 @@ Updating Nodes and Menus
 
 Beginning a Texinfo File
 
-* Four Parts::                  Four parts begin a Texinfo file.
-* Sample Beginning::            Here is a sample beginning for a Texinfo file.
-* Header::                      The very beginning of a Texinfo file.
-* Info Summary and Permissions::  Summary and copying permissions for Info.
+* Sample Beginning::            A sample beginning for a Texinfo file.
+* Texinfo File Header::         
+* Document Permissions::        
 * Titlepage & Copyright Page::  Creating the title and copyright pages.
 * The Top Node::                Creating the `Top' node and master menu.
+* Global Document Commands::    
 * Software Copying Permissions::  Ensure that you and others continue to
-                                  have the right to use and share software.
+                                    have the right to use and share software.
 
-The Texinfo File Header
+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.
-* setchapternewpage::           Start chapters on right-hand pages.
-* paragraphindent::             Specify paragraph indentation.
-* exampleindent::               Specify environment indentation.
 * End of Header::               Formatting a region requires this.
 
-The Title and Copyright Pages
+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 & Permissions::     How to write the copyright notice and
+* Copyright::                   How to write the copyright notice and
                                   include copying permissions.
 * end titlepage::               Turn on page headings after the title and
                                   copyright pages.
@@ -262,8 +246,15 @@ The Title and Copyright Pages
 
 The `Top' Node and Master Menu
 
-* Title of Top Node::           Sketch what the file is about.
-* Master Menu Parts::           A master menu has three or more parts.
+* 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.
+* exampleindent::               Specify environment indentation.
 
 Ending a Texinfo File
 
@@ -304,7 +295,6 @@ The @code{@@node} Command
 * 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.
-* Top Node Summary::            Write a brief description for readers.
 
 Menus
 
@@ -346,7 +336,8 @@ Indicating Definitions, Commands, etc.
 * code::                        Indicating program code.
 * kbd::                         Showing keyboard input.
 * key::                         Specifying keys.
-* samp::                        Showing a literal sequence of characters.
+* samp::                        A literal sequence of characters.
+* verb::                        A verbatim sequence of characters.
 * var::                         Indicating metasyntactic variables.
 * env::                         Indicating environment variables.
 * file::                        Indicating file names.
@@ -366,19 +357,19 @@ Emphasizing Text
 
 Quotations and Examples
 
-* Block Enclosing Commands::    Use different constructs for
-                                  different purposes.
-* quotation::                   How to write a quotation.
-* example::                     How to write an example in a fixed-width font.
-* noindent::                    How to prevent paragraph indentation.
-* lisp::                        How to illustrate Lisp code.
+* 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::                       Forms for @code{@@smallbook}.
-* display::                     How to write an example in the current font.
-* format::                      How to write an example that does not narrow
-                                  the margins.
-* exdent::                      How to undo the indentation of a line.
-* flushleft & flushright::      How to push text flushleft or flushright.
-* cartouche::                   How to draw cartouches around examples.
+* 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.
+* cartouche::                   Drawing rounded rectangles around examples.
 
 Lists and Tables
 
@@ -444,7 +435,7 @@ Inserting Space
 * Multiple Spaces::             Inserting multiple spaces.
 * dmn::                         How to format a dimension.
 
-Inserting Ellipsis, Dots, and Bullets
+Inserting Ellipsis and Bullets
 
 * dots::                        How to insert dots @dots{}
 * bullet::                      How to insert a bullet.
@@ -482,7 +473,7 @@ Making and Preventing Breaks
 
 * Break Commands::              Cause and prevent splits.
 * Line Breaks::                 How to force a single line to use two lines.
-* - and hyphenation::           How to tell TeX about hyphenation points.
+* - and hyphenation::           How to tell @TeX{} about hyphenation points.
 * w::                           How to prevent unwanted line breaks.
 * sp::                          How to insert blank lines.
 * page::                        How to force the start of a new page.
@@ -519,8 +510,8 @@ Conditionally Visible Text
 
 @code{@@set}, @code{@@clear}, and @code{@@value}
 
-* ifset ifclear::               Format a region if a flag is set.
 * 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
@@ -549,7 +540,7 @@ Formatting and Printing Hardcopy
 * 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 European A4 paper.
+* 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.
@@ -558,7 +549,7 @@ Formatting and Printing Hardcopy
 Creating and Installing Info Files
 
 * Creating an Info File::       
-* Install an Info File::        
+* Installing an Info File::     
 
 Creating an Info File
 
@@ -578,18 +569,17 @@ Creating an Info File
 Installing an Info File
 
 * Directory File::              The top level menu for all Info files.
-* New Info File::               Listing a new info file.
+* 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.
 
-Sample Permissions
+Sample Texinfo Files
 
-* Inserting Permissions::       How to put permissions in your document.
-* ifinfo Permissions::          Sample @samp{ifinfo} copying permissions.
-* Titlepage Permissions::       Sample Titlepage copying permissions.
+* Short Sample Texinfo File::   
+* GNU Sample Texts::            
 
 Include Files
 
@@ -624,6 +614,11 @@ Finding Badly Referenced Nodes
 * Unsplit::                     How to create an unsplit file.
 * Tagifying::                   How to tagify a file.
 * Splitting::                   How to split a file manually.
+
+Copying This Manual
+
+* GNU Free Documentation License::  License for copying this manual.
+
 @end detailmenu
 @end menu
 
@@ -636,45 +631,45 @@ when it is bad, it is better than nothing.
 @end quotation
 
 
-@node Copying
+@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
-portions of GNU Emacs, plus other separate programs (including
-@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
+@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.@refill
+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
+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.@refill
+you can do these things.
 
-  To make sure that everyone has such rights, we have to forbid you to
+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.@refill
+can get the source code.  And you must tell them their rights.
 
-  Also, for our own protection, we must make certain that everyone finds
+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.@refill
+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.
+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
@@ -707,7 +702,7 @@ that one document.
 * Minimum::                     What a Texinfo file must have.
 * Six Parts::                   Usually, a Texinfo file has six parts.
 * Short Sample::                A short sample Texinfo file.
-* Acknowledgements and History::  Contributors and genesis.
+* History::                     Acknowledgements, contributors and genesis.
 @end menu
 
 
@@ -717,8 +712,8 @@ that one document.
 @cindex Bugs, reporting
 @cindex Suggestions for Texinfo, making
 @cindex Reporting bugs
-We welcome bug reports or suggestions for the Texinfo system, both
-programs and documentation.  Please email them to
+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.
 
@@ -728,26 +723,27 @@ 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, operating system, and compiler versions.
-@item any unusual options you gave to @command{configure}.
+@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, diffutils, Comparing and
 Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
 Log,,, emacs, The GNU Emacs Manual}).
 
-When sending email, please do not encode or split the messages in any
-way if possible; it's much easier to deal with one plain text message,
-however large, than many small ones.
-@uref{ftp://ftp.gnu.org/gnu/sharutils/, GNU shar} is a convenient way of
-packaging multiple and/or binary files for email.
+When sending patches, if possible please do not encode or split them in
+any way; it's much easier to deal with one plain text message, however
+large, than many small ones.  @uref{ftp://ftp.gnu.org/gnu/sharutils/,
+GNU shar} is a convenient way of packaging multiple and/or binary files
+for email.
 
 
 @node Using Texinfo
@@ -762,26 +758,32 @@ features of a book, including chapters, sections, cross references, and
 indices.  From the same Texinfo source file, you can create a
 menu-driven, online Info file with nodes, menus, cross references, and
 indices.  You can also create from that same source file an HTML output
-file suitable for use with a web browser.  @cite{The GNU Emacs Manual}
-is a good example of a Texinfo file, as is this manual.
+file suitable for use with a web browser, or an XML file.  @cite{The GNU
+Emacs Manual} is a good example of a Texinfo file, as is this manual.
 
 To make a printed document, you process a Texinfo source file with the
 @TeX{} typesetting program (but the Texinfo language is very different
-from @TeX{}'s usual language, plain @TeX{}).  This creates a DVI file
-that you can typeset and print as a book or report (@pxref{Hardcopy}).
+and much stricter than @TeX{}'s usual language, plain @TeX{}).  This
+creates a DVI file that you can typeset and print as a book or report
+(@pxref{Hardcopy}).
 
 @pindex makeinfo
 To output an Info file, process your Texinfo source with the
 @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
-You can install the result in your Info tree (@pxref{Install an Info
+You can install the result in your Info tree (@pxref{Installing an Info
 File}).
 
-To output an HTML file, process your Texinfo source with @code{makeinfo}
-using the @samp{--html} option.  You can (for example) install the
-result on your web site.
+To output an HTML file, run @code{makeinfo --html} on your Texinfo
+source.  You can (for example) install the result on your web site.
+
+@cindex Docbook, converting to Texinfo
+@cindex Conversion, from Docbook to Texinfo
+To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
+To output DocBook (a particular form of XML), run @code{makeinfo
+--docbook}.  If you want to convert from Docbook @emph{to} Texinfo,
+please see @uref{http://docbook2X.sourceforge.net/}.
 
 @cindex Output formats, supporting more
-@cindex Docbook output format
 @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
@@ -790,7 +792,7 @@ 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, as it does now for
-Info and HTML.
+Info, plain text, HTML, XML, and DocBook.
 
 @TeX{} works with virtually all printers; Info works with virtually all
 computer terminals; the HTML output works with virtually all web
@@ -821,19 +823,19 @@ because man pages have a very strict conventional format.  Merely
 enhancing @command{makeinfo} to output troff format would be
 insufficient.  Generating a good man page therefore requires a
 completely different source than the typical Texinfo applications of
-generating a good user manual or a good reference manual.  This makes
+writing a good user tutorial 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
-If you wish to support man pages, the program @command{help2man} may 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 Texinfo programs themselves.  It is free software written
-by Brendan O'Dea, available from
-@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}.
+Man pages still have their place, and if you wish to support them, the
+program @command{help2man} may 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 Texinfo programs
+themselves.  It is GNU software written by Brendan O'Dea, available from
+@uref{ftp://ftp.gnu.org/gnu/help2man/}.
 
 
 @node Info Files
@@ -843,17 +845,17 @@ by Brendan O'Dea, available from
 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.)@refill
+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.@refill
+related nodes.
 
 @ifinfo
-@inforef{Top, info, info}, for more information about using Info.@refill
+@inforef{Top, info, info}, for more information about using Info.
 @end ifinfo
 
 Each node of an Info file may have any number of child nodes that
@@ -863,7 +865,7 @@ 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.@refill
+of subsections.
 
 All the children of any one parent are linked together in a
 bidirectional chain of `Next' and `Previous' pointers.  The `Next'
@@ -876,7 +878,7 @@ 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.}@refill
+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
@@ -975,12 +977,13 @@ document.)  @file{texinfo.tex} contains the specifications for printing
 a document.  You can get the latest version of @file{texinfo.tex} from
 @uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
 
-Most often, documents are 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 European A4 size paper
-(@code{@@afourpaper}).  (@xref{smallbook, , Printing ``Small'' Books}.
-Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill
+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
@@ -988,7 +991,7 @@ 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.@refill
+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
@@ -999,15 +1002,13 @@ 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.@refill
+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, Conventions, Printed Books, Overview
-@comment  node-name,  next,  previous,  up
+@node Formatting Commands
 @section @@-commands
 @cindex @@-commands
 @cindex Formatting commands
@@ -1021,8 +1022,7 @@ is the command to indicate the start of a chapter.@refill
 
 @quotation
 @strong{Please note:} All the @@-commands, with the exception of the
-@code{@@TeX@{@}} command, must be written entirely in lower
-case.@refill
+@code{@@TeX@{@}} command, must be written entirely in lower case.
 @end quotation
 
 The Texinfo @@-commands are a strictly limited set of constructs.  The
@@ -1091,8 +1091,8 @@ make it easier to write and read Texinfo files than if all commands
 followed exactly the same syntax.  (For details about @@-command
 syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
 
-@node Conventions, Comments, Formatting Commands, Overview
-@comment  node-name,  next,  previous,  up
+
+@node Conventions
 @section General Syntactic Conventions
 @cindex General syntactic conventions
 @cindex Syntactic conventions
@@ -1104,30 +1104,24 @@ This section describes the general conventions used in all Texinfo documents.
 @item
 All printable @sc{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.
-@samp{@{} and @samp{@}} should be used only 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{@@@}}.@refill
+@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
-@ifinfo
-It is customary in @TeX{} to use doubled single-quote characters to
-begin and end quotations: ` ` and ' ' (but without a space between the
-two single-quote characters).  This convention should be followed in
-Texinfo files.  @TeX{} converts doubled single-quote characters to
-left- and right-hand doubled quotation marks and Info converts doubled
-single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
-@end ifinfo
-@iftex
 It is customary in @TeX{} to use doubled single-quote characters to
-begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}.  This
+begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}.  This
 convention should be followed in Texinfo files.  @TeX{} converts
-doubled single-quote characters to left- and right-hand doubled
-quotation marks, ``like this'', and Info converts doubled single-quote
-characters to @sc{ascii} double-quotes: @w{@t{ `` }} and
-@w{@t{ '' }} to @w{@t{ " }}.@refill
+two single quotes to left- and right-hand doubled
+quotation marks, 
+@c this comes out as "like this" in Info, of course, which is just confusing.
+@iftex
+``like this'', 
 @end iftex
+and Info converts doubled single-quote characters to @sc{ascii}
+double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
 
 @item
 Use three hyphens in a row, @samp{---}, for a dash---like this.  In
@@ -1138,101 +1132,97 @@ for display on the screen.
 @item
 To prevent a paragraph from being indented in the printed manual, put
 the command @code{@@noindent} on a line by itself before the
-paragraph.@refill
+paragraph.
 
 @item
 If you mark off a region of the Texinfo file with the @code{@@iftex}
 and @w{@code{@@end iftex}} commands, that region will appear only in
 the printed copy; in that region, you can use certain commands
-borrowed from plain @TeX{} that you cannot use in Info.  Likewise, if
-you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
-commands, that region will appear only in the Info file; in that
-region, you can use Info commands that you cannot use in @TeX{}.
-Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
-@code{@@ifnothtml @dots{} @@end ifnothtml},
-@code{@@ifnotinfo @dots{} @@end ifnotinfo},
-@code{@@ifnottex @dots{} @@end ifnottex}.
-@xref{Conditionals}.
+borrowed from plain @TeX{} that you cannot use in Info.  Conversely,
+text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
+appear in all output formats @emph{except} @TeX{}.
+
+Each of the other output formats (@code{html}, @code{info},
+@code{plaintext}) have an analogous pair of commands.  @xref{Conditionals}.
 @end itemize
 
 @cindex Tabs; don't use!
 @quotation
-@strong{Caution:} Do not use tabs in a Texinfo file!  @TeX{} uses
-variable-width fonts, which means that it cannot predefine a tab to work
-in all circumstances.  Consequently, @TeX{} treats tabs like single
-spaces, and that is not what they look like.  Furthermore,
-@code{makeinfo} does nothing special with tabs, and thus a tab character
-in your input file may appear differently in the output.
+@strong{Caution:} 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.  Furthermore, @code{makeinfo} does nothing special
+with tabs, and thus a tab character in your input file may appear
+differently in the output, for example, in indented text.
 
 @noindent
 To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
-spaces when you press the @key{TAB} key.@refill
+spaces when you press the @key{TAB} key.
 
 @noindent
 Also, you can run @code{untabify} in Emacs to convert tabs in a region
-to multiple spaces.@refill
+to multiple spaces.
 @end quotation
 
-@node Comments, Minimum, Conventions, Overview
-@comment  node-name,  next,  previous,  up
+
+@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.)@refill
-@cindex Comments
-@findex comment
-@findex c @r{(comment)}
+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.  Often, @code{@@ignore} and @code{@@end ignore} is used
-to enclose a part of the copying permissions that applies to the
-Texinfo source file of a document, but not to the Info or printed
-version of the document.@refill
-@cindex Ignored text
-@cindex Unprocessed text
-@findex ignore
-@c !!! Perhaps include this comment about ignore and ifset:
-@ignore
+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
-will still get error messages if you have invalid Texinfo markup
-within ignored text.
-@end ignore
+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, Six Parts, Comments, Overview
-@comment  node-name,  next,  previous,  up
+
+@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 names of Texinfo files end with one of the
-extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.
-The longer extension is preferred since it describes more clearly to a
-human reader the nature of the file.  The shorter extensions are for
-operating systems that cannot handle long file names.@refill
+By convention, the namea 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:@refill
+file @strong{must} begin with lines like this:
 
 @example
 @group
@@ -1243,29 +1233,44 @@ file @strong{must} begin with lines like this:@refill
 @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:@refill
+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{(@TeX{} command)}
+@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{}.)  The
-@samp{@@setfilename} line provides a name for the Info file and tells
-@TeX{} to open auxiliary files.  The @samp{@@settitle} line specifies a
-title for the page headers (or footers) of the printed manual.@refill
+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.@refill
+the formatters that the file is ended and to stop formatting.
+
+@end itemize
 
-Usually, you will not use quite such a spare format, but will include
+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:@refill
+beginning of a Texinfo file, like this:
 
 @example
 @group
@@ -1281,69 +1286,75 @@ beginning of a Texinfo file, like this:@refill
 In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
 Texinfo mode when you edit the file.
 
-The @code{@@c} lines which surround the @samp{@@setfilename} and
-@samp{@@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},
-for more information.)@refill
+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.  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.@refill
+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, Short Sample, Minimum, Overview
-@comment  node-name,  next,  previous,  up
+
+@node Six Parts
 @section Six Parts of a Texinfo File
 
-Generally, a Texinfo file contains more than the minimal
-beginning and end---it usually contains six parts:@refill
+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 performs other ``housekeeping'' tasks.@refill
-
-@item 2. Summary Description and Copyright
-The @dfn{Summary Description and Copyright} segment describes the document
-and contains the copyright notice and copying permissions for the Info
-file.  The segment must be enclosed between @code{@@ifinfo} and
-@code{@@end ifinfo} commands so that the formatters place it only in the Info
-file.@refill
+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
-and copying permissions 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 @w{manual}.@refill
+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 @dfn{Master Menu} contains a complete menu of all the nodes in the whole
-Info file.  It appears only in the Info file, in the `Top' node.@refill
+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 may be structured like a traditional book or
-encyclopedia or it may be free form.@refill
+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} contains commands for printing indices and generating
-the table of contents, and the @code{@@bye} command on a line of its
-own.@refill
+The @dfn{End} segment contains commands for printing indices and
+generating the table of contents, and 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
+@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.
 
-Here is a complete but very short Texinfo file, in six parts.  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 you write a manual, simply
-insert the names for your own manual in this segment. (@xref{Beginning a
-File}.)@refill
+@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 any comments, is shown in
-@ref{Sample Texinfo File}.
+not.  The complete file, without interspersed comments, is shown in
+@ref{Short Sample Texinfo File}.
 
 @subheading Part 1: Header
 
@@ -1357,8 +1368,7 @@ name of the Info file and the title used in the header.
 \input texinfo   @@c -*-texinfo-*-
 @@c %**start of header
 @@setfilename sample.info
-@@settitle Sample Document
-@@setchapternewpage odd
+@@settitle Sample Manual 1.0
 @@c %**end of header
 @end group
 @end example
@@ -1366,83 +1376,94 @@ name of the Info file and the title used in the header.
 @subheading Part 2: Summary Description and Copyright
 
 @noindent
-The summary description and copyright segment does not
-appear in the printed document.
+A real manual includes more text here, according to the license under
+which it is distributed.  @xref{GNU Sample Texts}.
 
 @example
 @group
-@@ifinfo
-This is a short example of a complete Texinfo file.
+@@copying
+This is a short example of a complete Texinfo file, version 1.0.
 
-Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
-@@end ifinfo
+Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
+@@end copying
 @end group
 @end example
 
-@subheading Part 3: Titlepage and Copyright
+@subheading Part 3: Titlepage, Contents, Copyright
 
 @noindent
-The titlepage segment does not appear in the Info file.
+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
-@@sp 10
-@@comment The title is printed in a large font.
-@@center @@titlefont@{Sample Title@}
+@@title Sample Title
 @end group
 
 @group
 @@c The following two commands start the copyright page.
 @@page
 @@vskip 0pt plus 1filll
-Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
+@@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 a printed manual uses a table of contents rather than
-a menu, the master menu appears only in the Info file.
+The `Top' node contains the master menu for the Info file.  Since a
+printed manual uses a table of contents rather than a menu, the master
+menu appears only in online output.  We also include the copying text
+again for the benefit of online readers.  And since the copying text
+begins with a brief description of the manual, no other text is needed.
 
 @example
 @group
-@@node    Top,       First Chapter, ,         (dir)
-@@comment node-name, next,          previous, up
+@@ifnottex
+@@node Top
+@@end ifnottex
 @end group
 @end example
 
 @example
 @group
+@@insertcopying
+
 @@menu
 * First Chapter::    The first chapter is the
-                     only chapter in this sample.
-* Concept Index::    This index has two entries.
+                       only chapter in this sample.
+* Index::            Complete index.
 @@end menu
 @end group
 @end example
 
-@subheading Part 5:  The Body of the Document
+
+@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.@refill
+chapter containing an enumerated list.
 
 @example
 @group
-@@node    First Chapter, Concept Index, Top,      Top
-@@comment node-name,     next,          previous, up
+@@node First Chapter
 @@chapter First Chapter
-@@cindex Sample index entry
+
+@@cindex chapter, first
 @end group
 
 @group
-This is the contents of the first chapter.
-@@cindex Another sample index entry
+This is the first chapter.
+@@cindex index entry, another
 @end group
 
 @group
@@ -1456,45 +1477,38 @@ This is the first item.
 This is the second item.
 @@end enumerate
 @end group
-
-@group
-The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
-commands transform a Texinfo file such as this into
-an Info file; and @@TeX@{@} typesets it for a printed
-manual.
-@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, (usually) for generating the table of
-contents, and the @code{@@bye} command that marks the end of the
-document.@refill
+unnumbered chapter of its own, and the @code{@@bye} command that marks
+the end of the document.
 
 @example
 @group
-@@node    Concept Index,    ,  First Chapter, Top
-@@unnumbered Concept Index
+@@node Index
+@@unnumbered Index
 @end group
 
 @group
 @@printindex cp
 
-@@contents
 @@bye
 @end group
 @end example
 
-@subheading The Results
+
+@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 contents of the first chapter.
+This is the first chapter.
 
 Here is a numbered list.
 
@@ -1505,27 +1519,23 @@ This is the first item.
 @item
 This is the second item.
 @end enumerate
-
-The @code{makeinfo} and @code{texinfo-format-buffer}
-commands transform a Texinfo file such as this into
-an Info file; and @TeX{} typesets it for a printed
-manual.
 @end quotation
 
 
-@node Acknowledgements and History
-@section Acknowledgements and History
+@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.  @w{Robert J.@:
-Chassell} greatly revised and extended the manual, starting with Edition
+processors, and created Edition 1.0 of this manual.  @w{Robert 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}.  Karl Berry has made the updates since Texinfo 3.8 and
-subsequent releases, starting with Edition 2.22 of the manual.
+@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.
@@ -1533,39 +1543,41 @@ subsequent releases, starting with Edition 2.22 of the manual.
 @cindex Zaretskii, Eli
 @cindex Schwab, Andreas
 @cindex Weinberg, Zack
-Our thanks go out to all who helped improve this work, particularly to
-Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
-reported mistakes and obscurities; our special thanks go to Melissa
-Weisshaus for her frequent and often tedious reviews of nearly similar
-editions.  The indefatigable Eli Zaretskii and Andreas Schwab have
-provided patches beyond counting.  Zack Weinberg did the impossible by
-implementing the macro syntax in @file{texinfo.tex}.  Dozens of others
-have contributed patches and suggestions, they are gratefully
-acknowledged in the @file{ChangeLog} file.  Our mistakes are our own.
+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 @w{David 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 and strived to
-describe document contents rather than formatting.
+@code{@@} character to introduce commands, as Texinfo does.  Much more
+consequentially, it strived 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{}.
+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 on line and
+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
@@ -1575,15 +1587,14 @@ as printed hard copy.
 
 You may edit a Texinfo file with any text editor you choose.  A Texinfo
 file is no different from any other @sc{ascii} file.  However, GNU Emacs
-comes with a special mode, called Texinfo
-mode, that provides  Emacs commands and tools to help ease your work.@refill
+comes with a special mode, called Texinfo mode, that provides Emacs
+commands and tools to help ease your work.
 
 This chapter describes features of GNU Emacs' Texinfo mode but not any
-features of the Texinfo formatting language.  If you are reading this
+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.@refill
+chapters which describe the Texinfo formatting language in detail.
 
 @menu
 * Texinfo Mode Overview::       How Texinfo mode can help you.
@@ -1892,10 +1903,10 @@ about the page commands.@refill
 
 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.@refill
+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
@@ -2077,8 +2088,7 @@ 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, Other Updating Commands, Updating Commands, Updating Nodes and Menus
-@comment  node-name,  next,  previous,  up
+@node Updating Requirements
 @subsection Updating Requirements
 @cindex Updating requirements
 @cindex Requirements for updating commands
@@ -2098,7 +2108,7 @@ node, must be followed by a line with a structuring command such as
 @code{@@unnumberedsubsec}.@refill
 
 Each @code{@@node} line/structuring-command line combination
-must look either like this:@refill
+must look either like this:
 
 @example
 @group
@@ -2117,15 +2127,24 @@ or like this (without the @code{@@comment} line):
 @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.)@refill
+@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.@refill
+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
@@ -2140,8 +2159,8 @@ commands.  (@xref{Creating an Info File}, for more information about
 @code{texinfo-format-@dots{}} commands require that you insert menus in
 the file.
 
-@node Other Updating Commands,  , Updating Requirements, Updating Nodes and Menus
-@comment  node-name,  next,  previous,  up
+
+@node Other Updating Commands
 @subsection Other Updating Commands
 
 In addition to the five major updating commands, Texinfo mode
@@ -2271,7 +2290,7 @@ 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.@refill
+include a line that has @code{@@setfilename} in its header.
 
 @xref{Creating an Info File}, for details about Info formatting.@refill
 
@@ -2520,94 +2539,61 @@ M-x texinfo-sequential-node-update
 @end group
 @end example
 
-@node Beginning a File, Ending a File, Texinfo Mode, Top
-@comment  node-name,  next,  previous,  up
+
+@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 of the file and the title of the
-document.@refill
+Texinfo file, such as the name for the output file(s), the title of the
+document, and the Top node.
+
+This chapter expands on the minimal complete Texinfo source file
+previously given (@pxref{Six Parts}).
 
 @menu
-* Four Parts::                  Four parts begin a Texinfo file.
-* Sample Beginning::            Here is a sample beginning for a Texinfo file.
-* Header::                      The very beginning of a Texinfo file.
-* Info Summary and Permissions::  Summary and copying permissions for Info.
+* 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.
 * 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.
+                                    have the right to use and share software.
 @end menu
 
-@node Four Parts, Sample Beginning, Beginning a File, Beginning a File
-@ifinfo
-@heading Four Parts Begin a File
-@end ifinfo
-
-Generally, the beginning of a Texinfo file has four parts:@refill
-
-@enumerate
-@item
-The header, delimited by special comment lines, that includes the
-commands for naming the Texinfo file and telling @TeX{} what
-definitions file to use when processing the Texinfo file.@refill
-
-@item
-A short statement of what the file is about, with a copyright notice
-and copying permissions.  This is enclosed in @code{@@ifinfo} and
-@code{@@end ifinfo} commands so that the formatters place it only
-in the Info file.@refill
 
-@item
-A title page and copyright page, with a copyright notice and copying
-permissions.  This is enclosed between @code{@@titlepage} and
-@code{@@end titlepage} commands.  The title and copyright page appear
-only in the printed @w{manual}.@refill
-
-@item
-The `Top' node that contains a menu for the whole Info file.  The
-contents of this node appear only in the Info file.@refill
-@end enumerate
+@node Sample Beginning
+@section Sample Texinfo File Beginning
 
-Also, optionally, you may include the copying conditions for a program
-and a warranty disclaimer.  The copying section will be followed by an
-introduction or else by the first chapter of the manual.@refill
+@cindex Example beginning of Texinfo file 
 
-Since the copyright notice and copying permissions for the Texinfo
-document (in contrast to the copying permissions for a program) are in
-parts that appear only in the Info file or only in the printed manual,
-this information must be given twice.@refill
+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.
 
-@node Sample Beginning, Header, Four Parts, Beginning a File
-@comment  node-name,  next,  previous,  up
-@section Sample Texinfo File Beginning
-
-The following sample shows what is needed.@refill
+@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{name-of-info-file}
-@@settitle @var{name-of-manual}
-@@setchapternewpage odd
+@@setfilename @var{infoname}.info
+@@settitle @var{name-of-manual} @var{version}
 @@c %**end of header
 
-@@ifinfo
-This file documents @dots{}
+@@copying
+This manual is for @var{program}, version @var{version}.
 
-Copyright @var{year} @var{copyright-owner}
+Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
 
 @group
+@@quotation
 Permission is granted to @dots{}
-@@end ifinfo
-@end group
-
-@group
-@@c  This title page illustrates only one of the
-@@c  two methods of forming a title page.
+@@end quotation
+@@end copying
 @end group
 
 @group
@@ -2623,74 +2609,70 @@ Permission is granted to @dots{}
 @@c  start the copyright page.
 @@page
 @@vskip 0pt plus 1filll
-Copyright @@copyright@{@} @var{year} @var{copyright-owner}
+@@insertcopying
 @end group
 
 Published by @dots{}
-
-Permission is granted to @dots{}
 @@end titlepage
 
-@@node Top, Overview, , (dir)
+@@c So the toc is printed in the right place.
+@@contents
 
-@@ifinfo
-This document describes @dots{}
+@@ifnottex
+@@node Top
+@@top @var{title}
 
-This document applies to version @dots{}
-of the program named @dots{}
-@@end ifinfo
+@@insertcopying
+@@end ifnottex
 
 @group
 @@menu
-* Copying::          Your rights and freedoms.
 * First Chapter::    Getting started @dots{}
-* Second Chapter::              @dots{}
-  @dots{}
+* Second Chapter::          @dots{}
   @dots{}
+* Copying::          Your rights and freedoms.
 @@end menu
 @end group
 
 @group
-@@node    First Chapter, Second Chapter, top,      top
-@@comment node-name,     next,           previous, up
+@@node First Chapter
 @@chapter First Chapter
-@@cindex Index entry for First Chapter
+
+@@cindex first chapter
+@@cindex chapter, first
+@dots{}
 @end group
 @end example
 
-@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File
-@comment  node-name,  next,  previous,  up
-@section The Texinfo File Header
+
+@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.  If you want to run @TeX{} on just a part
-of the Texinfo File, you must write the @code{@@settitle}
-and @code{@@setfilename} lines between start-of-header and end-of-header
-lines.@refill
+@TeX{} with necessary information.  These are the @code{\input texinfo}
+line, the @code{@@settitle} line, and the @code{@@setfilename} line.
 
-Thus, the beginning of a Texinfo file looks like this:
+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.
 
-@example
-@group
-\input texinfo   @@c -*-texinfo-*-
-@@setfilename sample.info
-@@settitle Sample Document
-@end group
-@end example
+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.
 
-@noindent
-or else like this:
+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 Document
+@@settitle Sample Manual 1.0
 @@c %**end of header
 @end group
 @end example
@@ -2700,9 +2682,6 @@ or else like this:
 * Start of Header::             Formatting a region requires this.
 * setfilename::                 Tell Info the name of the Info file.
 * settitle::                    Create a title for the printed work.
-* setchapternewpage::           Start chapters on right-hand pages.
-* paragraphindent::             Specify paragraph indentation.
-* exampleindent::               Specify environment indentation.
 * End of Header::               Formatting a region requires this.
 @end menu
 
@@ -2714,7 +2693,7 @@ or else like this:
 @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:@refill
+with a line that looks like this:
 
 @example
 \input texinfo   @@c -*-texinfo-*-
@@ -2727,45 +2706,50 @@ This line serves two functions:
 @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 is usually located
-in the @file{/usr/lib/tex/macros} directory.  @TeX{} uses the backslash,
-@samp{\}, to mark the beginning of a command, just 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.@refill
+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 GNU Emacs, the @samp{-*-texinfo-*-} mode
-specification tells Emacs to use Texinfo mode.@refill
+specification tells Emacs to use Texinfo mode.
 @end enumerate
 
-@node Start of Header, setfilename, First Line, Header
-@comment  node-name,  next,  previous,  up
+
+@node Start of Header
 @subsection Start of Header
 @cindex Start of header line
 
-Write a 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 command lines, such
-as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
-end-of-header line (@pxref{End of Header}).@refill
-
-With these lines, you can format part of a Texinfo file for Info or
-typeset part for printing.@refill
-
-A start-of-header line looks like this:@refill
+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.@refill
+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} Emacs variables.  @xref{Texinfo Mode Printing}.
+
 
 @node setfilename
-@subsection @code{@@setfilename}
-@cindex Info file requires @code{@@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:
@@ -2780,34 +2764,40 @@ else on the line; anything on the line after the command is considered
 part of the file name, including what would otherwise be a
 comment.
 
-The @code{@@setfilename} line specifies the name of the output file to
-be generated.  This name should be different from the name of the
-Texinfo file.  There are two conventions for choosing the name: you can
-either remove the extension (such as @samp{.texi}) from the input file
-name, or replace it with the @samp{.info} extension.  When producing
-HTML output, @code{makeinfo} will replace any extension with
-@samp{html}, or add @samp{.html} if the given name has no extension.
-
-Some operating systems cannot handle long file names.  You can run into
-a problem even when the file name you specify is itself short enough.
-This occurs because the Info formatters split a long Info file into
-short indirect subfiles, and name them by appending @samp{-1},
-@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
-file name.  (@xref{Tag and Split Files, , Tag Files and Split Files}.)
-The subfile name @file{texinfo.info-10}, for example, is too long for
-some systems; 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 grave limits on file
-names, it will sometimes 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.
-
 @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
@@ -2816,297 +2806,217 @@ also reads @file{texinfo.cnf} if that file is present on your system
 (@pxref{Preparing for TeX,, Preparing for @TeX{}}).
 
 
-@node settitle, setchapternewpage, setfilename, Header
-@comment  node-name,  next,  previous,  up
-@subsection @code{@@settitle}
+@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:@refill
+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 a comment.@refill
+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 in @TeX{}.
+
+@cindex <title> HTML tag
+In the HTML file produced by @command{makeinfo}, @var{title} also serves
+as the document @samp{<title>} and the default document description in
+the @samp{<head>} part; see @ref{documentdescription}, for how to change
+that.
+
+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.)  Page footers are not
-printed.@refill
+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. @refill
-
-The @code{@@settitle} command should precede everything that generates
-actual output in @TeX{}.@refill
-
-Although the title in the @code{@@settitle} command is usually the
-same as the title on the title page, it does not affect the title as
-it appears on the title page.  Thus, the two do not need not match
-exactly;  and the title in the @code{@@settitle} command can be a
-shortened or expanded version of the title as it appears on the title
-page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
+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.)@refill
-
-You may, if you wish, create your own, customized headings and
-footings.  @xref{Headings, , Page Headings}, for a detailed discussion
-of this process.@refill
+information.)
 
+You may, if you wish, create your own, customized headings and footings.
+@xref{Headings}, for a detailed discussion of this.
 
-@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.@refill
-
-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).@refill
 
-Write the @code{@@setchapternewpage} command at the beginning of a
-line followed by its argument.@refill
+@node End of Header
+@subsection End of Header
+@cindex End of header line
 
-For example, you would write the following to cause each chapter to
-start on a fresh odd-numbered page:@refill
+Follow the header lines with an @w{end-of-header} line, which is a
+Texinfo comment that looks like this:
 
 @example
-@@setchapternewpage odd
+@@c %**end of header
 @end example
 
-You can specify one of three alternatives with the
-@code{@@setchapternewpage} command:@refill
-
-@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. (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 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 alternative is the default.@refill
-
-@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.@refill
-@end table
-
-Texinfo does not have an @code{@@setchapternewpage even} command.@refill
-
-You can countermand or modify the effect on headers of an
-@code{@@setchapternewpage} command with an @code{@@headings} command.
-@xref{headings on off, , The @code{@@headings} Command}.@refill
+@xref{Start of Header}.
 
-At the beginning of a manual or book, pages are not numbered---for
-example, the title and copyright pages of a book are not numbered.
-By convention, table of contents pages are numbered with roman
-numerals and not in sequence with the rest of the document.@refill
 
-Since an Info file does not have pages, the @code{@@setchapternewpage}
-command has no effect on it.@refill
+@node Document Permissions
+@section Document Permissions
+@cindex Document Permissions
+@cindex Copying Permissions
 
-We recommend not including any @code{@@setchapternewpage} command in
-your manual sources at all, since the desired output is not intrinsic to
-the document.  Instead, 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.
+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 paragraphindent
-@subsection Paragraph Indenting
-@cindex Indenting paragraphs
-@cindex Paragraph indentation
-@findex paragraphindent
+@node copying
+@subsection @code{@@copying}: Declare copying permissions
+@findex copying
 
-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:
+The @code{@@copying} command should be given very early in the document;
+right after the header material (@pxref{Texinfo File Header}) is the
+recommended location.  It conventionally consists of a sentence or two
+about what the program is, the legal copyright line, and the copying
+permissions.  Here is a skeletal example:
 
 @example
-@@paragraphindent @var{indent}
-@end example
-
-The indentation is according to the value of @var{indent}:
+@@copying
+This manual is for @var{program} (version @var{version}),
+which @dots{}
 
-@table @asis
-@item @code{asis}
-Do not change the existing indentation (not implemented in @TeX{}).
+Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
 
-@item 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 @samp{asis}.
-@code{@@paragraphindent} is ignored for HTML output.
-
-Write the @code{@@paragraphindent} command before or shortly after the
-end-of-header line at the beginning of a Texinfo file.  (If you write
-the command between the start-of-header and end-of-header lines, the
-region formatting commands indent paragraphs as specified.)
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
+@end example
 
-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.
-@xref{Refilling Paragraphs}, for further information.
+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.
 
-@node exampleindent
-@subsection @code{@@exampleindent}: Environment Indenting
-@cindex Indenting environments
-@cindex Environment indentation
-@cindex Example indentation
-@findex exampleindent
+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.
 
-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:
+@findex copyright
+In output formats that support it (print and HTML), the
+@code{@@copyright@{@}} command generates a @samp{c} inside a circle.  In
+Info and plain text, it generates @samp{(C)}.  The copyright notice
+itself has the following legally defined sequence:
 
 @example
-@@exampleindent @var{indent}
+Copyright @copyright{} @var{years} @var{copyright-owner}.
 @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 0
-Omit all indentation.
+@cindex Copyright word, always in English
+The word `Copyright' must always be written in English, even if the
+manual is otherwise in another language.  This is due to international
+law.
 
-@item @var{n}
-Indent environments by @var{n} space characters in Info output, by
-@var{n} ems in @TeX{}.
+@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, separated by
+commas.
 
-@end table
+@cindex Copyright owner 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 default value of @var{indent} is 5.  @code{@@exampleindent} is
-ignored for HTML output.
+@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
+additional information.
 
-Write the @code{@@exampleindent} command before or shortly after the
-end-of-header line at the beginning of a Texinfo file.  (If you write
-the command between the start-of-header and end-of-header lines, the
-region formatting commands indent examples as specified.)
 
+@node insertcopying
+@subsection @code{@@insertcopying}: Include permissions text
+@findex insertcopying
+@cindex Copying text, including
+@cindex Permissions text, including
+@cindex Including permissions text
 
-@node End of Header
-@subsection End of Header
-@cindex End of header line
-
-Follow the header lines with an @w{end-of-header} line.
-An end-of-header line looks like this:@refill
+The @code{@@insertcopying} command is simply written on a line by
+itself, like this:
 
 @example
-@@c %**end of header
+@@insertcopying
 @end example
 
-If you include the @code{@@setchapternewpage} command between the
-start-of-header and end-of-header lines, @TeX{} will typeset a region as
-that command specifies.  Similarly, if you include an @code{@@smallbook}
-command between the start-of-header and end-of-header lines, @TeX{} will
-typeset a region in the ``small'' book format.@refill
-
-@ifinfo
-The reason for the odd string of characters (@samp{%**}) is so that the
-@code{texinfo-tex-region} command does not accidentally find
-something that it should not when it is looking for the header.@refill
-
-The start-of-header line and the end-of-header line are Texinfo mode
-variables that you can change.@refill
-@end ifinfo
-
-@iftex
-@xref{Start of Header}.
-@end iftex
+It inserts the text previously defined by @code{@@copying}.  Legally, it
+must be used on the copyright page in the printed manual
+(@pxref{Copyright}).
 
+Although it's not a legal requirement, we also strongly recommend using
+@code{@@insertcopying} in the Top node of your manual (@pxref{The Top
+Node}).  Here's why:
 
-@node Info Summary and Permissions
-@section Summary and Copying Permissions for Info
+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 *}).  Therefore, an explicit @code{@@insertcopying}
+in the Top node makes it apparent to readers that the manual is free.
 
-The title page and the copyright page appear only in the printed copy of
-the manual; therefore, the same information must be inserted in a
-section that appears only in the Info file.  This section usually
-contains a brief description of the contents of the Info file, a
-copyright notice, and copying permissions.@refill
+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).  And
+therefore again, the @code{@@insertcopying} in the Top node is valuable
+because it makes the copying permissions visible and thus promotes
+freedom.
 
-The copyright notice should read:@refill
-
-@example
-Copyright @var{year} @var{copyright-owner}
-@end example
-
-@noindent
-and be put on a line by itself.@refill
-
-Standard text for the copyright permissions is contained in an appendix
-to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying
-Permissions}, for the complete text.@refill
-
-The permissions text appears in an Info file @emph{before} the first
-node.  This mean that a reader does @emph{not} see this text when
-reading the file using Info, except when using the advanced Info command
-@kbd{g *}.
+The permissions text defined by @code{@@copying} also appears
+automatically at the beginning of the XML output file.
 
 
 @node Titlepage & Copyright Page
-@section The Title and Copyright Pages
+@section Title and Copyright Pages
 
-A manual's name and author are usually printed on a title page.
-Sometimes copyright information is printed on the title page as well;
-more often, copyright information is printed on the back of the title
-page.
+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
+The title and copyright pages appear in the printed manual, but not in
+the Info file.  Because of this, it is possible to use several slightly
 obscure @TeX{} typesetting commands that cannot be used in an Info file.
-In addition, this part of the beginning of a Texinfo file contains the text
-of the copying permissions that will appear in the printed manual.@refill
+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 Titlepage, for plain text
+@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{@@ifinfo}
-and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain
-text output.  It will not show up in the Info readers.
-
-@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the
-standard text for the copyright permissions.@refill
+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.
@@ -3114,7 +3024,7 @@ standard text for the copyright permissions.@refill
                                   and @code{@@sp} commands.
 * title subtitle author::       The @code{@@title}, @code{@@subtitle},
                                   and @code{@@author} commands.
-* Copyright & Permissions::     How to write the copyright notice and
+* Copyright::                   How to write the copyright notice and
                                   include copying permissions.
 * end titlepage::               Turn on page headings after the title and
                                   copyright pages.
@@ -3123,15 +3033,14 @@ standard text for the copyright permissions.@refill
 @end menu
 
 
-@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
-@comment  node-name,  next,  previous,  up
+@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.@refill
+@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
@@ -3153,13 +3062,13 @@ 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 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.
+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{makeinfo top, , @code{@@top}}.)
+@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
@@ -3181,8 +3090,9 @@ the sections below.
 @cindex Title page, bastard
 For extremely simple applications, and for the bastard title page in
 traditional book front matter, Texinfo also provides a command
-@code{@@shorttitlepage} which takes a single argument as the title.  The
-argument is typeset on a page by itself and followed by a blank page.
+@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
@@ -3193,7 +3103,7 @@ argument is typeset on a page by itself and followed by a blank page.
 
 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.)@refill
+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
@@ -3207,7 +3117,7 @@ For example:
 @end example
 
 Use the @code{@@center} command at the beginning of a line to center
-the remaining text on that line.  Thus,@refill
+the remaining text on that line.  Thus,
 
 @example
 @@center @@titlefont@{Texinfo@}
@@ -3215,9 +3125,9 @@ the remaining text on that line.  Thus,@refill
 
 @noindent
 centers the title, which in this example is ``Texinfo'' printed
-in the title font.@refill
+in the title font.
 
-Use the @code{@@sp} command to insert vertical space.  For example:@refill
+Use the @code{@@sp} command to insert vertical space.  For example:
 
 @example
 @@sp 2
@@ -3226,9 +3136,9 @@ Use the @code{@@sp} command to insert vertical space.  For example:@refill
 @noindent
 This inserts two blank lines on the printed page.  (@xref{sp, ,
 @code{@@sp}}, for more information about the @code{@@sp}
-command.)@refill
+command.)
 
-A template for this method looks like this:@refill
+A template for this method looks like this:
 
 @example
 @group
@@ -3244,7 +3154,7 @@ A template for this method looks like this:@refill
 @end group
 @end example
 
-The spacing of the example fits an 8.5 by 11 inch manual.@refill
+The spacing of the example fits an 8.5 by 11 inch manual.
 
 
 @node title subtitle author
@@ -3261,7 +3171,7 @@ 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.@refill
+or author.
 
 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.
@@ -3272,18 +3182,18 @@ 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.@refill
+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.)@refill
+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:@refill
+an @code{@@author} command:
 
 @example
 @@author by Jane Smith and John Doe
@@ -3291,7 +3201,7 @@ an @code{@@author} command:@refill
 
 @noindent
 or you can write the names one above each other by using two (or more)
-@code{@@author} commands:@refill
+@code{@@author} commands:
 
 @example
 @group
@@ -3301,10 +3211,10 @@ or you can write the names one above each other by using two (or more)
 @end example
 
 @noindent
-(Only the bottom name is underlined with a black rule.)@refill
+(Only the bottom name is underlined with a black rule.)
 
 @need 950
-A template for this method looks like this:@refill
+A template for this method looks like this:
 
 @example
 @group
@@ -3329,40 +3239,34 @@ may be useful if you have a very long title.  Here is a real-life example:
 @@titlefont@{GNU Software@}
 @@sp 1
 @@title for MS-Windows and MS-DOS
-@@subtitle Edition @@value@{edition@} for Release @@value@{cd-edition@}
+@@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,,@code{@@value} Example}.)
+(The use of @code{@@value} here is explained in @ref{value Example}.
 
 
-@node Copyright & Permissions
-@subsection Copyright Page and Permissions
+@node Copyright
+@subsection Copyright Page
 @cindex Copyright page
 @cindex Printed permissions
 @cindex Permissions, printed
 
-By international treaty, the copyright notice for a book should be
-either on the title page or on the back of the title page.  The
-copyright notice should include the year followed by the name of the
-organization or person who owns the copyright.@refill
-
-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.@refill
+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
-@findex filll
-@cindex Vertical whitespace (@samp{vskip})
+@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, you can write a somewhat mysterious line after the
-@code{@@page} command that reads like this:@refill
+bottom of the page, use the following incantantion after @code{@@page}:
 
 @example
 @@vskip 0pt plus 1filll
@@ -3370,31 +3274,36 @@ bottom of the page, you can write a somewhat mysterious line after the
 
 @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 the correct usage in
-@TeX{}.@refill
+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.
 
-@findex copyright
-In a printed manual, the @code{@@copyright@{@}} command generates a
-@samp{c} inside a circle.  (In Info, it generates @samp{(C)}.)  The
-copyright notice itself has the following legally defined sequence:@refill
+To insert the copyright text itself, write @code{@@insertcopying}
+next (@pxref{Document Permissions}):
 
 @example
-Copyright @copyright{} @var{year} @var{copyright-owner}
+@@insertcopying
 @end example
 
-It is customary to put information on how to get a manual after the
-copyright notice, followed by the copying permissions for the manual.
+Follow the copying text by the publisher, ISBN numbers, cover art
+credits, and other such information.
 
-Permissions must be given here as well as in the summary segment within
-@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the
-header since this text appears only in the printed manual and the
-@samp{ifinfo} text appears only in the Info file.
+Here is an example putting all this together:
 
-@xref{Sample Permissions}, for the standard text.@refill
+@example
+@@titlepage
+@dots{}
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+
+Published by @dots{}
+
+Cover art by @dots{}
+@@end titlepage
+@end example
 
 
 @node end titlepage
@@ -3404,23 +3313,22 @@ header since this text appears only in the printed manual and the
 @cindex Titlepage end starts headings
 @cindex End titlepage starts headings
 
-An @code{@@end titlepage} command on a line by itself not only marks
-the end of the title and copyright pages, but also causes @TeX{} to start
-generating page headings and page numbers.
+The @code{@@end titlepage} command must be written on a line by itself.
+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).
-(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
-You can specify these formats in different ways:@refill
+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, , @code{@@setchapternewpage}}.)@refill
+(@xref{setchapternewpage}.)
 
 @item
 Alternatively, you can use the @code{@@headings} command to prevent page
@@ -3432,16 +3340,16 @@ after the @code{@@end titlepage} command.  @xref{headings on off, , The
 @item
 Or, you may specify your own page heading and footing format.
 @xref{Headings, , Page Headings}, for detailed
-information about page headings and footings.@refill
+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.@refill
+single-sided printing.
 
-@node headings on off,  , end titlepage, Titlepage & Copyright Page
-@comment  node-name,  next,  previous,  up
+
+@node headings on off
 @subsection The @code{@@headings} Command
 @findex headings
 
@@ -3506,98 +3414,86 @@ You can also specify your own style of page heading and footing.
 
 @node The Top Node
 @section The `Top' Node and Master Menu
-@cindex @samp{@r{Top}} node
-@cindex Master menu
+@cindex Top node
 @cindex Node, `Top'
 
-The `Top' node is the node from which you enter an Info file.@refill
-
-A `Top' node should contain a brief description of the Info file and an
-extensive, master menu for the whole Info file.
-This helps the reader understand what the Info file is
-about.  Also, you should write the version number of the program to
-which the Info file applies; or, at least, the edition number.@refill
-
-The contents of the `Top' node should appear only in the Info file; none
-of it should appear in printed output, so enclose it between
-@code{@@ifinfo} and @code{@@end ifinfo} commands.  (@TeX{} does not
+The `Top' node is the node in which a reader enters an Info manual.  As
+such, it should begin with the @code{@@insertcopying} command
+(@pxref{Document Permissions}) to provide a brief description of the
+manual (including the version number) and copying permissions, 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 also conventional 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{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
-@xref{Conditionals, , Conditionally Visible Text}.)@refill
+@code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
+so.  @xref{Conditionals, , Conditionally Visible Text}.)
 
 @menu
-* Title of Top Node::           Sketch what the file is about.
-* Master Menu Parts::           A master menu has three or more parts.
+* Top Node Example::            
+* Master Menu Parts::           
 @end menu
 
 
-@node Title of Top Node
-@subsection `Top' Node Title
+@node Top Node Example
+@subsection Top Node Example
 
-Sometimes, you will want to place 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}, for more information).@refill
+@cindex Top node example
 
-For example, the beginning of the Top node of this manual contains an
-@code{@@top} sectioning command, a short description, and edition and
-version information.  It looks like this:@refill
+Here is an example of a Top node.
 
 @example
 @group
-@dots{}
-@@end titlepage
-
 @@ifnottex
-@@node Top, Copying, , (dir)
-@@top Texinfo
+@@node Top
+@@top Sample Title
 
-Texinfo is a documentation system@dots{}
+@@insertcopying
 @end group
 
-@group
-This is edition@dots{}
-@dots{}
-@@end ifnottex
-@end group
+Additional general information.
 
 @group
 @@menu
-* Copying::                 Texinfo is freely
-                              redistributable.
-* Overview::                What is Texinfo?
+* First Chapter::
+* Second Chapter::
 @dots{}
+* Index::
 @end group
 @@end menu
 @end example
 
-In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
-level directory of the whole Info system, which is called @samp{(dir)}.
-The `Next' node refers to the first node that follows the main or master
-menu, which is usually the copying permissions, introduction, or first
-chapter.@refill
 
-@node Master Menu Parts,  , Title of Top Node, The Top Node
+@node Master Menu Parts
 @subsection Parts of a Master Menu
-@cindex Master menu parts
+@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.@refill
+commands and does not appear in the printed document.
 
-Generally, a master menu is divided into parts.@refill
+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.@refill
+for the chapters, chapter-like sections, and the appendices.
 
 @item
-The second part contains nodes for the indices.@refill
+The second part contains nodes for the indices.
 
 @item
 The third and subsequent parts contain a listing of the other, lower
@@ -3613,25 +3509,21 @@ first one, and @code{@@end detailmenu} after the last; otherwise,
 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.)@refill
+information.)
 
 For example, the master menu for this manual looks like the following
-(but has many more entries):@refill
+(but has many more entries):
 
 @example
 @group
 @@menu
-* Copying::             Texinfo is freely
-                          redistributable.
-* Overview::            What is Texinfo?
-* Texinfo Mode::        Special features in GNU Emacs.
-@dots{}
+* Copying Conditions::  Your rights.
+* Overview::            Texinfo in brief.
 @dots{}
 @end group
 @group
 * Command and Variable Index::
-                        An entry for each @@-command.
-* Concept Index::       An entry for each concept.
+* Concept Index::       
 @end group
 
 @group
@@ -3640,27 +3532,230 @@ For example, the master menu for this manual looks like the following
 
 Overview of Texinfo
 
-* Info Files::          What is an Info file?
-* Printed Manuals::     Characteristics of
-                          a printed manual.
-@dots{}
+* Reporting Bugs:: @dots{}
 @dots{}
 @end group
 
 @group
-Using Texinfo Mode
+Beginning a Texinfo File
 
-* Info on a Region::    Formatting part of a file
-                          for Info.
-@dots{}
+* Sample Beginning:: @dots{}
 @dots{}
 @@end detailmenu
 @@end menu
 @end group
 @end example
 
-@node Software Copying Permissions,  , The Top Node, Beginning a File
-@comment  node-name,  next,  previous,  up
+
+@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.
+* 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 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.
+@xref{Refilling Paragraphs}, for further information.
+
+
+@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
+
+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.  @code{@@exampleindent} is
+ignored for HTML output.
+
+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
@@ -3668,15 +3763,14 @@ Using Texinfo Mode
 @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, this section usually follows the
-`Top' node.  The General Public License is very important to Project
+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.@refill
+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.@refill
+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
@@ -3684,12 +3778,9 @@ is very helpful.  Ideally, it should state clearly and concisely what
 the file is about and who would be interested in reading it.  In
 general, an introduction would follow the licensing and distribution
 information, although sometimes people put it earlier in the document.
-Usually, an introduction is put in an @code{@@unnumbered} section.
-(@xref{unnumbered & appendix, , The @code{@@unnumbered} and
-@code{@@appendix} Commands}.)@refill
 
-@node Ending a File, Structuring, Beginning a File, Top
-@comment  node-name,  next,  previous,  up
+
+@node Ending a File
 @chapter Ending a Texinfo File
 @cindex Ending a Texinfo file
 @cindex Texinfo file ending
@@ -3697,21 +3788,22 @@ Usually, an introduction is put in an @code{@@unnumbered} section.
 @findex bye
 
 The end of a Texinfo file should include commands to create indices and
-(usually) to generate detailed and summary tables of contents.  And it
-must include the @code{@@bye} command that marks the last line processed
-by @TeX{}.@refill
+(perhaps) to generate both the full and summary tables of contents.
+Finally, it must include the @code{@@bye} command that marks the last
+line to be processed.
 
 @need 700
 For example:
 
 @example
-@@node    Concept Index,     , Variables Index, Top
-@@c        node-name,    next, previous,        up
-@@unnumbered Concept Index
+@@node Index
+@@unnumbered Index
 
 @@printindex cp
 
+@@shortcontents
 @@contents
+
 @@bye
 @end example
 
@@ -3722,79 +3814,72 @@ For example:
 * File End::                    How to mark the end of a file.
 @end menu
 
-@node Printing Indices & Menus, Contents, Ending a File, Ending a File
-@comment  node-name,  next,  previous,  up
-@section Index Menus and Printing an Index
+
+@node Printing Indices & Menus
+@section Printing Indices and Menus
 @findex printindex
 @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.@refill
-
-Texinfo offers six different types of predefined index: the concept
-index, the function index, the variables index, the keystroke index, the
-program index, and the data type index (@pxref{Predefined Indices}).  Each
-index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
-@samp{ky}, @samp{pg}, and @samp{tp}.  You may merge indices, or put them
-into separate sections (@pxref{Combining Indices}); or you may define
-your own indices (@pxref{New Indices, , Defining New Indices}).@refill
-
-The @code{@@printindex} command takes a two-letter index name, reads
-the corresponding sorted index file and formats it appropriately into
-an index.@refill
-
-@ignore
-The two-letter index names are:
+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, each with a
+two-letter abbreviation, as illustrated in the following table.
+However, you may merge indices (@pxref{Combining Indices}) or define
+your own indices (@pxref{New Indices}).
+
+Here are the predefined indices, their abbreviations, and the
+corresponding index entry commands:
 
 @table @samp
 @item cp
-concept index
+concept index (@code{@@cindex})
 @item fn
-function index
+function index (@code{@@findex})
 @item vr
-variable index
+variable index (@code{@@index})
 @item ky
-key index
+key index (@code{@@kindex})
 @item pg
-program index
+program index (@code{@@pindex})
 @item tp
-data type index
+data type index (@code{@@tindex})
 @end table
-@end ignore
-The @code{@@printindex} command does not generate a chapter heading
-for the index.  Consequently, you should precede the
-@code{@@printindex} command with a suitable section or chapter command
-(usually @code{@@unnumbered}) to supply the chapter heading and put
-the index into the table of contents.  Precede the @code{@@unnumbered}
-command with an @code{@@node} line.@refill
 
-@need 1200
+The @code{@@printindex} command takes a two-letter index abbreviation,
+reads the corresponding sorted index file and formats it appropriately
+into an index.
+
+The @code{@@printindex} command does not generate a chapter heading for
+the index.  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
+@code{@@unnumbered} command with an @code{@@node} line.
+
 For example:
 
 @smallexample
 @group
-@@node Variable Index, Concept Index, Function Index, Top
-@@comment    node-name,         next,       previous, up
+@@node Variable Index
 @@unnumbered Variable Index
 
 @@printindex vr
 @end group
 
 @group
-@@node     Concept Index,     , Variable Index, Top
-@@comment      node-name, next,       previous, up
+@@node Concept Index
 @@unnumbered Concept Index
 
 @@printindex cp
@@ -3802,10 +3887,10 @@ For example:
 @end smallexample
 
 @noindent
-Readers often prefer that the concept index come last in a book,
-since that makes it easiest to find.  Having just one index helps
-readers also, since then they have only one place to look
-(@pxref{synindex}).
+
+We recommend placing the concept index last, since that makes it easiest
+to find.  We also recommend having a single index whenever possible,
+since then readers have only one place to look (@pxref{Combining Indices}).
 
 
 @node Contents
@@ -3826,18 +3911,17 @@ the @code{@@contents} and/or @code{@@summarycontents} command(s).
 @item @@contents
 Generate a table of contents in a printed manual, including all
 chapters, sections, subsections, etc., as well as appendices and
-unnumbered chapters.  (Headings generated by the @code{@@heading}
-series of commands do not appear in the table of contents.)
+unnumbered chapters.  Headings generated by the @code{@@heading}
+series of commands do not appear in the table of contents.
 
 @item @@shortcontents
 @itemx @@summarycontents
-(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
-two commands are exactly the same.)@refill
+(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
 
 Generate a short or summary table of contents that lists only the
-chapters (and appendices and unnumbered chapters).  Omit sections, subsections
-and subsubsections.  Only a long manual needs a short table
-of contents in addition to the full table of contents.@refill
+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
 
@@ -3848,7 +3932,15 @@ 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}).
+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.
 
 The contents commands can be placed either at the very end of the file,
 after any indices (see the previous section) and just before the
@@ -3858,8 +3950,7 @@ the former is that then the contents output is always up to date,
 because it reflects the processing just done.  The advantage to the
 latter is that the contents are printed in the proper place, thus you do
 not need to rearrange the DVI file with @command{dviselect} or shuffle
-paper.  However, contents commands at the beginning of the document are
-ignored when outputting to standard output.
+paper.
 
 @findex setcontentsaftertitlepage
 @findex setshortcontentsaftertitlepage
@@ -3869,7 +3960,7 @@ As an author, you can put the contents commands wherever you prefer.
 But if you are a user simply printing a manual, you may wish to print
 the contents after the title page even if the author put the contents
 commands at the end of the document (as is the case in most existing
-Texinfo documents).  You can do this by specifying
+Texinfo documents, at this writing).  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
@@ -3879,11 +3970,11 @@ short contents and the main contents.  In either case, any subsequent
 
 You need to include the @code{@@set@dots{}contentsaftertitlepage}
 commands early in the document (just after @code{@@setfilename}, for
-example).  Or, if you're using @command{texi2dvi} (@pxref{Format with
-texi2dvi}), you can use its @option{--texinfo} option to specify this
-without altering the source file at all.  For example:
+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=@@setshortcontentsaftertitlepage foo.texi
+texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
 @end example
 
 
@@ -3892,15 +3983,16 @@ texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi
 @findex bye
 
 An @code{@@bye} command terminates @TeX{} or Info formatting.  None of
-the formatting commands see any of the file following @code{@@bye}.
-The @code{@@bye} command should be on a line by itself.@refill
-
-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.  @xref{Compile-Command, , Using Local
-Variables and the Compile Command}, for more information.@refill
+the formatting commands reading 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 Emacs.
+@xref{Compile-Command, , Using Local Variables and the Compile Command},
+for more information.
 
 
 @node Structuring
@@ -4033,25 +4125,25 @@ 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:@refill
+Here are the four groups of chapter structuring commands:
 
-@multitable @columnfractions .19 .30 .29 .22
+@tex
+{\globaldefs = 1 \smallfonts}
+@end tex
 
-@item              @tab              @tab                @tab No new page
-@item Numbered     @tab Unnumbered   @tab Lettered and numbered
-                                                         @tab 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}
+@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 Omitted from@*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
@@ -4622,7 +4714,6 @@ see @ref{Cross References}.)@refill
 * 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.
-* Top Node Summary::            Write a brief description for readers.
 @end menu
 
 
@@ -4736,6 +4827,7 @@ capitalized; others are not.@refill
 @subsection @code{@@node} Line Requirements
 
 @cindex Node line requirements
+@cindex Restrictions on node names
 Here are several requirements for @code{@@node} lines:
 
 @itemize @bullet
@@ -4761,10 +4853,11 @@ node containing the pointer.
 @cindex @@-commands in nodename
 @cindex Node name, should not contain @@-commands
 @item
-@w{@@-commands} used in node names generally confuse Info, so you should
-avoid them.  For a few rare cases when this is useful, Texinfo has
-limited support for using @w{@@-commands} in node names; see
-@ref{Pointer Validation}.
+@w{@@-commands} used in node names generally confuse Info, so you
+should avoid them.  This includes punctuation characters that are
+escaped with a @samp{@@}, such as @code{@@} and @code{@{}.  For a few
+rare cases when this is useful, Texinfo has limited support for using
+@w{@@-commands} in node names; see @ref{Pointer Validation}.
 
 @need 750
 Thus, the beginning of the section called @code{@@chapter} looks like
@@ -4780,6 +4873,12 @@ this:@refill
 @end smallexample
 
 @item
+@cindex Parentheses in nodename
+You cannot use parentheses in node names, because a node name such as
+@samp{(foo)bar} is interpreted by the Info readers as a node
+@samp{bar} in an Info file @file{foo}.
+
+@item
 @cindex Apostrophe in nodename
 @cindex Colon in nodename
 @cindex Comma in nodename
@@ -4787,7 +4886,7 @@ this:@refill
 @cindex Characters, invalid in node name
 @cindex Invalid characters in node names
 Unfortunately, you cannot use periods, commas, colons or apostrophes
-within a node name; these confuse @TeX{} or the Info formatters.@refill
+within a node name; these confuse @TeX{} or the Info formatters.
 
 @need 700
 For example, the following is a section title:
@@ -4803,69 +4902,82 @@ The corresponding node name is:
 unnumberedsec appendixsec heading
 @end smallexample
 
-@cindex Case in nodename
+@cindex Case in node name
 @item
 Case is significant.
 @end itemize
 
 
-@node First Node, makeinfo top command, Node Line Requirements, node
-@comment  node-name,  next,  previous,  up
+@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 contains the main
-or master menu for the document, and a short summary of the document
-(@pxref{Top Node Summary}).
+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.  If
-the file is to be installed directly in the Info directory file, 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.  For
-example, the @code{@@node Top} line of this manual looks like this:
+menu that leads to this file.  Specify the file name in parentheses.
 
-@example
-@@node Top, Copying, , (dir)
-@end example
-
-@noindent
-(You can use the Texinfo updating commands or the @code{makeinfo}
-utility to insert these pointers automatically.)
+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 Previous node of Top node
-Do not define the `Previous' node of the Top node to be @samp{(dir)}, as
-it causes confusing behavior for users: if you are in the Top node and
-hits @key{DEL} to go backwards, you wind up in the middle of the
-some other entry in the @file{dir} file, which has nothing to do with
-what you were reading.
+On the other hand, do not define the `Previous' node of the Top node to
+be @samp{(dir)}, as it causes confusing behavior for users: if you are
+in the Top node and hits @key{DEL} to go backwards, you wind up in the
+middle of the some other entry in the @file{dir} file, which has nothing
+to do with what you were reading.
+
+@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{Install an Info File}, for more information about installing
+@xref{Installing an Info File}, for more information about installing
 an Info file in the @file{info} directory.
 
+For concreteness, here is an example with explicit pointers (which you
+can maintain automatically with the texinfo mode commands):
 
-@node makeinfo top command, Top Node Summary, First Node, node
-@comment  node-name,  next,  previous,  up
+Or you can leave the pointers off entirely and let the tools implicitly
+define them.  This is recommended.  Thus:
+
+@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}, has been created for use
-with the @code{@@node Top} line.  The @code{@@top} sectioning command tells
+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.@refill
+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.@refill
+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}.
@@ -4874,37 +4986,15 @@ 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.@refill
-
-
-@node Top Node Summary,  , makeinfo top command, node
-@subsection The `Top' Node Summary
-@cindex @samp{@r{Top}} node summary
-
-You can help readers by writing a summary in the `Top' node, after the
-@code{@@top} line, before the main or master menu.  The summary should
-briefly describe the document.  In Info, this summary will appear just
-before the master menu.  In a printed manual, this summary will appear
-on a page of its own.@refill
-
-If you do not want the summary to appear on a page of its own in a
-printed manual, you can enclose the whole of the `Top' node, including
-the @code{@@node Top} line and the @code{@@top} sectioning command line
-or other sectioning command line between @code{@@ifinfo} and @code{@@end
-ifinfo}.  This prevents any of the text from appearing in the printed
-output. (@pxref{Conditionals, , Conditionally Visible Text}).  You can
-repeat the brief description from the `Top' node within @code{@@iftex}
-@dots{} @code{@@end iftex} at the beginning of the first chapter, for
-those who read the printed manual.  This saves paper and may look
-neater.@refill
-
-You should write the version number of the program to which the manual
-applies in the summary.  This helps the reader keep track of which
-manual is for which version of the program.  If the manual changes more
-frequently than the program or is independent of it, you should also
-include an edition number for the manual.  (The title page should also
-contain this information: see @ref{titlepage, ,
-@code{@@titlepage}}.)@refill
+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}
@@ -4933,6 +5023,12 @@ This node pointer insertion 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 contain sectioning
+commands at all.  For example, if you never intend the document to be
+printed.  In those cases, you will need to explicitly specify the pointers.
+
 
 @node anchor
 @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
@@ -5025,10 +5121,10 @@ avoid this, you can write a menu near the beginning of its node and
 follow the menu by an @code{@@node} line, and then an @code{@@heading}
 line located within @code{@@ifinfo} and @code{@@end ifinfo}.  This way,
 the menu, @code{@@node} line, and title appear only in the Info file,
-not the printed document.@refill
+not the printed document.
 
 For example, the preceding two paragraphs follow an Info-only menu,
-@code{@@node} line, and heading, and look like this:@refill
+@code{@@node} line, and heading, and look like this:
 
 @example
 @group
@@ -5049,9 +5145,8 @@ For example, the preceding two paragraphs follow an Info-only menu,
 @end group
 @end example
 
-The Texinfo file for this document contains more than a dozen
-examples of this procedure.  One is at the beginning of this chapter;
-another is at the beginning of @ref{Cross References}. @refill
+The Texinfo file for this document contains a number of
+examples of this procedure; one is at the beginning of this chapter.
 
 
 @node Writing a Menu, Menu Parts, Menu Location, Menus
@@ -5278,7 +5373,7 @@ 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{Install an Info File}.)@refill
+nodes of each Info document.  (@xref{Installing an Info File}.)
 
 @need 700
 For example:
@@ -6275,48 +6370,47 @@ The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
 
 An example of the two-argument form:
 @example
-The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} holds
-programs and texts.
+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.
+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.
+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.
+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@{http://example.org/man.cgi/1/ls,,ls(1)@} program @dots{}
+The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{}
 @end example
 
 @noindent produces:
 @display
-The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program @dots{}
+The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
 @end display
 
 @noindent but with HTML:
 @example
-The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program @dots{}
+The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
 @end example
 
 To merely indicate a url without creating a link people can follow, use
 @code{@@url} (@pxref{url, @code{@@url}}).
 
-
 Some people prefer to display url's in the unambiguous format:
 
 @display
@@ -6324,7 +6418,7 @@ Some people prefer to display url's in the unambiguous format:
 @end display
 
 @noindent
-@cindex <URL: convention, not used
+@cindex <URL convention, not used
 You can use this form in the input file if you wish.  We feel it's not
 necessary to clutter up the output with the extra @samp{<URL:} and
 @samp{>}, since any software that tries to detect url's in text already
@@ -6351,8 +6445,8 @@ program.  Also, you can emphasize text, in several different ways.
 * Emphasis::                    How to emphasize text.
 @end menu
 
+
 @node Indicating, Emphasis, Marking Text, Marking Text
-@comment  node-name,  next,  previous,  up
 @section Indicating Definitions, Commands, etc.
 @cindex Highlighting text
 @cindex Indicating commands, definitions, etc.
@@ -6380,7 +6474,8 @@ not something else that should not be changed.@refill
 * code::                        Indicating program code.
 * kbd::                         Showing keyboard input.
 * key::                         Specifying keys.
-* samp::                        Showing a literal sequence of characters.
+* samp::                        A literal sequence of characters.
+* verb::                        A verbatim sequence of characters.
 * var::                         Indicating metasyntactic variables.
 * env::                         Indicating environment variables.
 * file::                        Indicating file names.
@@ -6712,8 +6807,7 @@ example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
 @c the beginning of the sentence.  The @code{@@key@{META@}} key is often in
 @c the lower left of the keyboard.''@refill
 
-@node samp, var, key, Indicating
-@comment  node-name,  next,  previous,  up
+@node samp
 @subsection @code{@@samp}@{@var{text}@}
 @findex samp
 
@@ -6767,6 +6861,38 @@ In English, the vowels are @samp{a}, @samp{e},
 @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 La@TeX{}'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), whose argument is normal Texinfo text, where the characters
+@code{@@@{@}} are special; with @code{@@verb}, nothing is special except
+the delimiter character you choose.
+
+
 @node var
 @subsection @code{@@var}@{@var{metasyntactic-variable}@}
 @findex var
@@ -6859,11 +6985,11 @@ section).
 For example:
 
 @example
-The @@env@{PATH@} environment variable sets the search path for commands.
+The @@env@{PATH@} environment variable @dots{}
 @end example
 @noindent produces
 @quotation
-The @env{PATH} environment variable sets the search path for commands.
+The @env{PATH} environment variable @dots{}
 @end quotation
 
 
@@ -7093,17 +7219,17 @@ the text to display if any.  In HTML output, @code{@@email} produces a
 For example:
 
 @example
-Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}.
-Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
+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}.
-Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
+Send bug reports to @email{bug-texinfo@@gnu.org},
+suggestions to the @email{bug-texinfo@@gnu.org, same place}.
 @end display
 
 
-@node Emphasis,  , Indicating, Marking Text
+@node Emphasis
 @comment node-name,  next,  previous,  up
 @section Emphasizing Text
 @cindex Emphasizing text
@@ -7267,7 +7393,8 @@ produces
 
 If possible, you should avoid using the other three font commands.  If
 you need to use one, it probably indicates a gap in the Texinfo
-language.@refill
+language.
+
 
 @node Quotations and Examples
 @chapter Quotations and Examples
@@ -7282,25 +7409,26 @@ 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.@refill
+line.
 @findex end
 
 @menu
-* Block Enclosing Commands::    Use different constructs for
-                                  different purposes.
-* quotation::                   How to write a quotation.
-* example::                     How to write an example in a fixed-width font.
-* noindent::                    How to prevent paragraph indentation.
-* lisp::                        How to illustrate Lisp code.
+* 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::                       Forms for @code{@@smallbook}.
-* display::                     How to write an example in the current font.
-* format::                      How to write an example that does not narrow
-                                  the margins.
-* exdent::                      How to undo the indentation of a line.
-* flushleft & flushright::      How to push text flushleft or flushright.
-* cartouche::                   How to draw cartouches around examples.
+* 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.
+* cartouche::                   Drawing rounded rectangles around examples.
 @end menu
 
+
 @node Block Enclosing Commands
 @section Block Enclosing Commands
 
@@ -7310,16 +7438,22 @@ following sections:
 @table @code
 @item @@quotation
 Indicate text that is quoted. The text is filled, indented, and
-printed in a roman font by default.@refill
+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.@refill
+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 for the @code{@@smallbook} format than for the
-default 8.5 by 11 inch format.
+text in a smaller font.
 
 @item @@lisp
 Like @code{@@example}, but specifically for illustrating Lisp code. The
@@ -7351,7 +7485,7 @@ 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.@refill
+paragraph.
 
 You can use the @code{@@cartouche} command within one of the above
 constructs to highlight the example or quotation by drawing a box with
@@ -7408,13 +7542,13 @@ This is a foo.
 
 
 @node example
-@section @code{@@example}
+@section @code{@@example}: Example Text
 @cindex Examples, formatting them
 @cindex Formatting examples
 @findex example
 
 The @code{@@example} command is used to indicate an example that is
-not part of the running text, such as computer input or output.@refill
+not part of the running text, such as computer input or output.
 
 @example
 @group
@@ -7463,11 +7597,11 @@ Note that blank lines inside the beginning
 the output.@refill
 
 @quotation
-@strong{Caution:} Do not use tabs in the lines of an example (or anywhere
-else in Texinfo, for that matter)!  @TeX{} treats tabs as single
-spaces, and that is not what they look like.  This is a problem with
-@TeX{}.  (If necessary, in Emacs, you can use @kbd{M-x untabify} to
-convert tabs in a region to multiple spaces.)@refill
+@strong{Caution:} Do not use tabs in the lines of an example or anywhere
+else in Texinfo (except in verbatim environments)!  The @TeX{}
+implementation of Texinfo treats tabs as single spaces, and that is not
+what they look like.  (If necessary, in Emacs, you can use @kbd{M-x
+untabify} to convert tabs in a region to multiple spaces.)@refill
 @end quotation
 
 Examples are often, logically speaking, ``in the middle'' of a
@@ -7483,66 +7617,84 @@ embedded within sentences, not set off from preceding and following
 text.  @xref{code, , @code{@@code}}.)
 
 
-@node noindent
-@section @code{@@noindent}
-@findex noindent
+@node verbatim
+@section @code{@@verbatim}: Literal Text
+@findex verbatim
+@cindex Verbatim environment
 
-An example or other inclusion can break a paragraph into segments.
-Ordinarily, the formatters indent text that follows an example as a new
-paragraph.  However, you can prevent this by writing @code{@@noindent}
-at the beginning of a line by itself preceding the continuation
-text.@refill
+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 output in a Texinfo manual.  Here is an example;
+the output you see is just the same as the input, with a line
+@code{@@verbatim} before and a line @code{@@end verbatim} after.
+
+@verbatim
+This is an example of text written in a @verbatim
+block.  No character substitutions are made.  All commands
+are ignored, until `<at>end verbatim'.
+
+In the printed manual, the text is typeset in a
+fixed-width font, and not indented or filled.  All
+spaces and blank lines are significant, including tabs.
+@end verbatim
+
+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.
 
-@need 1500
 For example:
+@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
 
 @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
+@exdent @@verbatim
+@exdent @{
+@exdent <tab>@@command with strange characters: @@'e 
+@exdent expand<tab>me
+@exdent @}
+@exdent @@end verbatim
 @end example
 
 @noindent
 produces
 
-@display
-@example
-This is an example
-@end example
-@tex
-% Remove extra vskip; this is a kludge to counter the effect of display
-\vskip-3.5\baselineskip
-@end tex
+@verbatim
+{
+	@command with strange characters: @'e 
+expand	me
+}
+@end verbatim
 
-@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
+Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
+produce no output, tyically 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.
 
-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.@refill
 
-In the Texinfo source file for this manual, each line that says
-`produces' is preceded by a line containing @code{@@noindent}.@refill
+@node verbatiminclude
+@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
+@cindex Verbatim, include file
+@cindex Including a file verbatim
+@findex verbatiminclude
 
-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}).@refill
+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.
 
 
 @node lisp
-@section @code{@@lisp}
+@section @code{@@lisp}: Marking a Lisp Example
 @findex lisp
 @cindex Lisp example
 
@@ -7567,9 +7719,9 @@ itself.@refill
 
 @node small
 @section @code{@@small@dots{}} Block Commands
-@cindex Small book example
-@cindex Example for a small book
-@cindex Lisp example for a small book
+@cindex Small examples
+@cindex Examples in smaller fonts
+@cindex Lisp examples in smaller fonts
 @findex smalldisplay
 @findex smallexample
 @findex smallformat
@@ -7578,19 +7730,13 @@ itself.@refill
 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}.  All of these commands are designed for use with the
-@code{@@smallbook} command (which causes @TeX{} to format a printed book for
-a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size).
+@code{@@smalllisp}.
 
 In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
-font for the smaller @code{@@smallbook} format than for the 8.5 by 11
-inch format.  Consequently, many examples containing long lines fit in a
-narrower, @code{@@smallbook} page without needing to be shortened.  Both
-commands typeset in the normal font size when you format for the 8.5 by
-11 inch size.  Indeed, in this situation, the @code{@@small@dots{}}
-commands are equivalent to their non-small versions.
-
-In Info, the @code{@@small@dots{}} commands are also equivalent to their
+font than the non-small example commands.  Consequently, many examples
+containing long lines fit on a page without needing to be shortened.
+
+In Info, the @code{@@small@dots{}} commands are equivalent to their
 non-small companion commands.
 
 Mark the end of an @code{@@small@dots{}} block with a corresponding
@@ -7621,24 +7767,22 @@ programs; and that you know you can do these things.}
 @iftex
 @smallexample
 This is an example of text written between @code{@@smallexample} and
-@code{@@end smallexample}.  In Info and in an 8.5 by 11 inch manual,
-this text appears in its normal size; but in a 7 by 9.25 inch manual,
-this text appears in a smaller font.
+@code{@@end smallexample}.  In Info this text appears in its normal size;
+but in printed manuals, this text appears in a smaller font.
 @end smallexample
 @end iftex
 @end ifset
 @ifinfo
 @smallexample
 This is an example of text written between @code{@@smallexample} and
-@code{@@end smallexample}.  In Info and in an 8.5 by 11 inch manual,
-this text appears in its normal size; but in a 7 by 9.25 inch manual,
-this text appears in a smaller font.
+@code{@@end smallexample}.  In Info this text appears in its normal size;
+but in a 7 by 9.25 inch manual, this text appears in a smaller font.
 @end smallexample
 @end ifinfo
 
-The @code{@@small@dots{}} commands make it easier to prepare smaller
-format manuals without forcing you to edit examples by hand to fit them
-onto narrower pages.@refill
+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 better if you use only one
 of (for example) @code{@@example} or in @code{@@smallexample}
@@ -7646,7 +7790,7 @@ consistently within a chapter.  Only occasionally should you mix the two
 formats.
 
 @xref{smallbook, , Printing ``Small'' Books}, for more information
-about the @code{@@smallbook} command.@refill
+about the @code{@@smallbook} command.
 
 
 @node display
@@ -7736,10 +7880,13 @@ 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, cartouche, exdent, Quotations and Examples
+
+@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,
@@ -7795,16 +7942,76 @@ right justifies every line but leaves the
 left end ragged.
 @end flushright
 
-@node cartouche,  , flushleft & flushright, Quotations and Examples
-@section Drawing Cartouches Around Examples
+
+@node noindent
+@section @code{@@noindent}: Omitting Indentation
+@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.  However, you can prevent this by writing @code{@@noindent}
+at the beginning of a line by itself preceding the continuation
+text.@refill
+
+@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
+@tex
+% Remove extra vskip; this is a kludge to counter the effect of display
+\vskip-3.5\baselineskip
+@end tex
+
+@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.@refill
+
+In the Texinfo source file for this manual, each line that says
+`produces' is preceded by a line containing @code{@@noindent}.@refill
+
+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}).@refill
+
+
+@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.  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.@refill
+for emphasis.
 
 @code{@@cartouche} affects only the printed manual; it has no effect in
 other output files.
@@ -7841,7 +8048,7 @@ In a printed manual, the example looks like this:@refill
 @end iftex
 
 
-@node Lists and Tables, Indices, Quotations and Examples, Top
+@node Lists and Tables
 @chapter Lists and Tables
 @cindex Making lists and tables
 @cindex Lists and tables, making
@@ -8672,7 +8879,7 @@ the braces of @code{@@code}.@refill
                                   default font of the merged-to index.
 @end menu
 
-@node syncodeindex, synindex, Combining Indices, Combining Indices
+@node syncodeindex
 @subsection @code{@@syncodeindex}
 @findex syncodeindex
 
@@ -8820,7 +9027,8 @@ rather than the @code{@@cindex} command.@refill
 
 You should define new indices within or right after the end-of-header
 line of a Texinfo file, before any @code{@@synindex} or
-@code{@@syncodeindex} commands (@pxref{Header}).@refill
+@code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
+
 
 @node Insertions
 @chapter Special Insertions
@@ -8889,7 +9097,7 @@ necessary.
 
 @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
 @subsection Inserting @samp{@@} with @@@@
-@findex @@ @r{(single @samp{@@})}
+@findex @@ @r{(literal @samp{@@})}
 
 @code{@@@@} stands for a single @samp{@@} in either printed or Info
 output.
@@ -8899,8 +9107,8 @@ Do not put braces after an @code{@@@@} command.
 
 @node Inserting Braces
 @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
-@findex @{ @r{(single @samp{@{})}
-@findex @} @r{(single @samp{@}})}
+@findex @{ @r{(literal @samp{@{})}
+@findex @} @r{(literal @samp{@}})}
 
 @code{@@@{} stands for a single @samp{@{} in either printed or Info
 output.
@@ -8944,7 +9152,7 @@ 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 : @r{(suppress widening)}
+@findex <colon> @r{(suppress widening)}
 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
@@ -9070,6 +9278,8 @@ Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
 
 Do not follow any of these commands with braces.
 
+To produce a non-breakable space, see @ref{w, non-breakable space}.
+
 
 @node dmn
 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
@@ -9123,35 +9333,35 @@ braces around their argument (which is taken to be the next character).
 This is so as to make the source as convenient to type and read as
 possible, since accented characters are very common in some languages.
 
-@findex "
+@findex " @r{(umlaut accent)}
 @cindex Umlaut accent
-@findex '
+@findex ' @r{(umlaut accent)}
 @cindex Acute accent
-@findex =
+@findex = @r{(macron accent)}
 @cindex Macron accent
-@findex ^
+@findex ^ @r{(circumflex accent)}
 @cindex Circumflex accent
-@findex `
+@findex ` @r{(grave accent)}
 @cindex Grave accent
-@findex ~
+@findex ~ @r{(tilde accent)}
 @cindex Tilde accent
-@findex ,
+@findex , @r{(cedilla accent)}
 @cindex Cedilla accent
 @findex dotaccent
 @cindex Dot accent
-@findex H
+@findex H @r{(Hungarian umlaut accent)}
 @cindex Hungarian umlaut accent
 @findex ringaccent
 @cindex Ring accent
 @findex tieaccent
 @cindex Tie-after accent
-@findex u
+@findex u @r{(breve accent)}
 @cindex Breve accent
 @findex ubaraccent
 @cindex Underbar accent
 @findex udotaccent
 @cindex Underdot accent
-@findex v
+@findex v @r{(check accent)}
 @cindex Check accent
 @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
 @item Command               @tab Output         @tab What
@@ -9208,7 +9418,7 @@ commonly used in languages other than English.
 @cindex Es-zet
 @cindex Sharp S
 @cindex German S
-@multitable {x@@questiondown@{@} } {oe,OE} {es-zet or sharp S}
+@multitable {x@@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
@@ -9335,6 +9545,8 @@ available.
 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
 @findex minus
 
+@cindex em-dash
+@cindex hyphen
 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
@@ -9361,10 +9573,11 @@ an itemized list, you do not need to type the braces
 (@pxref{itemize, , @code{@@itemize}}.)
 
 
-@node math, Glyphs, minus, Insertions
+@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:
@@ -9374,20 +9587,16 @@ command.  Write the mathematical expression between braces, like this:
 @end example
 
 @iftex
-@need 1000
-@noindent
-This produces the following in @TeX{}:
+@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 Info:
+@noindent and the following in Info:
 @end iftex
 @ifinfo
-@noindent
-This produces the following in Info:
+@noindent This produces the following in Info:
 @end ifinfo
 
 @example
@@ -9396,15 +9605,46 @@ This produces the following in Info:
 
 Thus, the @code{@@math} command has no effect on the Info output.
 
-For complex mathematical expressions, you can also use @TeX{} directly
-(@pxref{Raw Formatter Commands}).  When you use @TeX{} directly,
-remember to write the mathematical expression between one or two
-@samp{$} (dollar-signs) as appropriate.
+@code{@@math} implies @code{@@tex}.  This not only makes it possible to
+write superscripts and subscripts (as in the above example), but also
+allows you to use any of the plain @TeX{} math control sequences.  It's
+conventional to use @samp{\} instead of @samp{@@} for these commands.
+As in:
+@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'll 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 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
@@ -9429,12 +9669,11 @@ left- and right-hand braces.@refill
 * Point Glyph::                 How to indicate the location of point.
 @end menu
 
-@node Glyphs Summary, result, Glyphs, Glyphs
-@ifinfo
-@subheading Glyphs Summary
+
+@node Glyphs Summary
+@subsection Glyphs Summary
 
 Here are the different glyph commands:@refill
-@end ifinfo
 
 @table @asis
 @item @result{}
@@ -9457,7 +9696,6 @@ message.@refill
 @code{@@point@{@}} shows the location of point.@refill
 @end table
 
-
 @menu
 * result::
 * expansion::
@@ -9467,7 +9705,8 @@ message.@refill
 * Point Glyph::
 @end menu
 
-@node result, expansion, Glyphs Summary, Glyphs
+
+@node result
 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
 @cindex Result of an expression
 @cindex Indicating evaluation
@@ -9757,13 +9996,14 @@ 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.}@refill
+University of Chicago Press.}
 
 @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
 
@@ -9783,16 +10023,21 @@ 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:@refill
+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.@refill
+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
@@ -9950,7 +10195,7 @@ You can insert an image given in an external file with the
 @code{@@image} command:
 
 @example
-@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@}
+@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@}
 @end example
 
 @cindex Formats for images
@@ -9968,13 +10213,26 @@ PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
 @code{makeinfo} uses @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 to @code{@@image} for the extension if
+you supply it.  For example:
+
+@pindex XPM image format
+@example
+@@image@{foo,,,,xpm@}
+@end example
+
+@noindent
+will cause @samp{makeinfo --html} to try @file{foo.xpm}.
+
 @cindex GIF, unsupported due to patents
 @cindex PNG image format
-@cindex JPEG image format
-@code{makeinfo} producing HTML output tries @file{@var{filename}.png};
-if that does not exist, it tries @file{@var{filename}.jpg}.  If that
-does not exist either, it complains.  (We cannot support GIF format due
-to patents.)
+@cindex JPG image format
+If you do not supply the optional fifth argument, @samp{makeinfo
+---html} 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.  (We cannot support GIF format directly due to software
+patents.)
 @end itemize
 
 @cindex Width of images
@@ -10035,38 +10293,48 @@ 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 available from
-@uref{ftp://tug.org/tex/epsf.tex}.
+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.
 
+@cindex alt attribute for images
+@cindex alternate text for images
+When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
+inline images to the optional fourth argument to @code{@@image}, if
+supplied.  If not supplied, @code{makeinfo} uses the full file name of
+the image being displayed.
+
 
 @node Breaks
 @chapter Making and Preventing 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.@refill
+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.@refill
+commands.
 
 @menu
 * Break Commands::              Cause and prevent splits.
 * Line Breaks::                 How to force a single line to use two lines.
-* - and hyphenation::           How to tell TeX about hyphenation points.
+* - and hyphenation::           How to tell @TeX{} about hyphenation points.
 * w::                           How to prevent unwanted line breaks.
 * sp::                          How to insert blank lines.
 * page::                        How to force the start of a new page.
@@ -10074,6 +10342,7 @@ commands.@refill
 * need::                        Another way to prevent unwanted page breaks.
 @end menu
 
+
 @node Break Commands, Line Breaks, Breaks, Breaks
 @ifinfo
 @heading Break Commands
@@ -10120,8 +10389,7 @@ Hold text together that must appear on one printed page.@refill
 Start a new printed page if not enough space on this one.@refill
 @end table
 
-@node Line Breaks, - and hyphenation, Break Commands, Breaks
-@comment  node-name,  next,  previous,  up
+@node Line Breaks
 @section @code{@@*}: Generate Line Breaks
 @findex * @r{(force line break)}
 @cindex Line breaks
@@ -10176,10 +10444,11 @@ refilled after the line break occurs, negating the effect of the line
 break.@refill
 @end quotation
 
-@node - and hyphenation, w, Line Breaks, Breaks
+
+@node - and hyphenation
 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
 
-@findex -
+@findex - @r{(discretionary hyphen)}
 @findex hyphenation
 @cindex Hyphenation, helping @TeX{} do
 @cindex Fine-tuning, and hyphenation
@@ -10193,10 +10462,10 @@ 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 in a word
-containing @code{@@-}.
+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
@@ -10305,8 +10574,8 @@ and is followed by another line.
 The @code{@@br} command is seldom used.
 @end ignore
 
-@node page, group, sp, Breaks
-@comment  node-name,  next,  previous,  up
+
+@node page
 @section @code{@@page}: Start a New Page
 @cindex Page breaks
 @findex page
@@ -10314,7 +10583,8 @@ The @code{@@br} command is seldom used.
 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.@refill
+section of a Texinfo file to start the copyright page.
+
 
 @node group, need, page, Breaks
 @comment  node-name,  next,  previous,  up
@@ -10555,6 +10825,10 @@ definition.@refill
 
 The other specialized commands work like @code{@@defun}.@refill
 
+@cindex Macros in definition commands
+Note that, due to implementation difficulties, macros are not expanded
+in @code{@@deffn} and all the other definition commands.
+
 @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
 @section Optional and Repeated Arguments
 @cindex Optional and repeated arguments
@@ -11548,22 +11822,27 @@ Substituting text for all formats, and testing if a flag is set or clear.
 @node Conditional Commands
 @section Conditional Commands
 
+Texinfo has a pair of commands 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.  The segment of text appears only
-in the Info file.  The @code{@@ifinfo} command should appear on a line
-by itself; end the Info-only text with a line containing @code{@@end
-ifinfo} by itself.  At the beginning of a Texinfo file, the Info
-permissions are contained within a region marked by @code{@@ifinfo} and
-@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.)
+in the Info file and (for historical compatibility) the plain text
+output.  The @code{@@ifinfo} command should appear on a line by itself;
+end the Info-only text with a line containing @code{@@end ifinfo} by
+itself.
 
 @findex iftex
 @findex ifhtml
-The @code{@@iftex} and @code{@@end iftex} commands are similar to the
-@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
-specify text that will appear in the printed manual but not in the Info
-file.  Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
-specify text to appear only in HTML output.@refill
+@findex ifplaintext
+The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
+@code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
+will appear in the printed manual but not in the Info file.  Likewise
+for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
+appear only in HTML output.  And for @code{@@ifplaintext} and
+@code{@@end ifplaintext}, which specify text to appear only in plain
+text output.
 
 For example,
 
@@ -11572,11 +11851,14 @@ For example,
 This text will appear only in the printed manual.
 @@end iftex
 @@ifinfo
-However, this text will appear only in Info.
+However, this text will appear only in Info (or 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
 @end example
 
 @noindent
@@ -11585,11 +11867,14 @@ The preceding example produces the following line:
 This text will appear only in the printed manual.
 @end iftex
 @ifinfo
-However, this text will appear only in Info.
+However, this text will appear only in Info (or 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
 
 @noindent
 Notice that you only see one of the input lines, depending on which
@@ -11600,6 +11885,7 @@ version of the manual you are reading.
 @section Conditional Not Commands
 @findex ifnothtml
 @findex ifnotinfo
+@findex ifnotplaintext
 @findex ifnottex
 
 You can specify text to be included in any output format @emph{other}
@@ -11607,21 +11893,34 @@ than some given one with the @code{@@ifnot@dots{}} commands:
 @example
 @@ifnothtml @dots{} @@end ifnothtml
 @@ifnotinfo @dots{} @@end ifnotinfo
+@@ifnotplaintext @dots{} @@end ifnotplaintext
 @@ifnottex @dots{} @@end ifnottex
 @end example
 @noindent
 (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
-actually appear on lines by themselves.)
+appear on lines by themselves in your actual source file.)
+
+If the output file is @emph{not} being made for the given format, the
+region is included.  Otherwise, it is ignored.
 
-If the output file is not being made for the given format, the region is
-included.  Otherwise, it is ignored.
+With 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, set clear value, Conditional Not Commands, Conditionals
+@node Raw Formatter Commands
 @section Raw Formatter Commands
 @cindex @TeX{} commands, using ordinary
 @cindex HTML commands, using ordinary
@@ -11697,147 +11996,45 @@ 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.@refill
 
-In addition, you can use the @code{@@set @var{flag}} command to set the
-value of @var{flag} to a string of characters; and use
-@code{@@value@{@var{flag}@}} to insert that string.  You can use
-@code{@@set}, for example, to set a date and use @code{@@value} to
-insert the date in several places in the Texinfo file.@refill
-
-@menu
-* ifset ifclear::               Format a region if a flag is set.
-* set value::                   Expand a flag variable to a string.
-* value Example::               An easy way to update edition information.
-@end menu
-
-
-@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.
-
-Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a
-@var{flag}; a @dfn{flag} name can be any single word, containing
-letters, numerals, hyphens, or underscores.
-
-The format for the command looks like this:@refill
-@findex set
-
-@example
-@@set @var{flag}
-@end example
-
-Write the conditionally formatted text between @code{@@ifset @var{flag}}
-and @code{@@end ifset} commands, like this:@refill
-
-@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:@refill
-
-@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.@refill
-
-@findex clear
-Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear},
-a flag.  Clearing a flag is the opposite of setting a flag.  The
-command looks like this:@refill
-
-@example
-@@clear @var{flag}
-@end example
-
-@noindent
-Write the command on a line of its own.
-
-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.@refill
-
-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:@refill
-
-@example
-@@ifclear @var{flag}
-@end example
-
-@need 700
-In brief, the commands are:@refill
+Brief descriptions:
 
 @table @code
-@item @@set @var{flag}
-Tell the Texinfo formatting commands that @var{flag} is set.@refill
+@item @@set @var{flag} [@var{value}]
+Set the variable @var{flag}, to the optional @var{value} if specifed.
 
 @item @@clear @var{flag}
-Tell the Texinfo formatting commands that @var{flag} is cleared.@refill
+Undefine the variable @var{flag}, whether or not it was previously defined.
 
 @item @@ifset @var{flag}
-If @var{flag} is set, tell the Texinfo formatting commands to format
-the text up to the following @code{@@end ifset} command.@refill
-
-If @var{flag} is cleared, tell the Texinfo formatting commands to
-ignore text up to the following @code{@@end ifset} command.@refill
+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, tell the Texinfo formatting commands to ignore
-the text up to the following @code{@@end ifclear} command.@refill
-
-If @var{flag} is cleared, tell the Texinfo formatting commands to
-format the text up to the following @code{@@end ifclear}
-command.@refill
+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 value
 
-You can use the @code{@@set} command to specify a value for a flag,
-which is expanded by the @code{@@value} command.  A flag is an
-identifier; for best results, 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 just a string of
-characters, the remainder of the input line.
+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} is an identifier.  In general, 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:
 
@@ -11850,12 +12047,12 @@ 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
+@code{foo} is set as shown above, the Texinfo formatters convert this:
 
 @example
 @group
 @@value@{foo@}
-@exdent @r{to}
+@exdent @r{to this:}
 This is a string.
 @end group
 @end example
@@ -11870,12 +12067,10 @@ If you write the @code{@@set} command like this:
 @end example
 
 @noindent
-without specifying a string, the value of @code{foo} is an empty string.
+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 is invalid and the string is
-replaced with an error message that says @samp{@{No value for
-"@var{flag}"@}}.
+subsequent @code{@@value@{flag@}} command will report an error.
 
 For example, if you set @code{foo} as follows:@refill
 
@@ -11912,12 +12107,87 @@ It is a @{No value for "how-much"@} wet day.
 @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 limit the number of places you
-need to change when you record an update to a manual.  Here is how it is
-done in @cite{The GNU Make Manual}:
+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 an example of this same principle can work with
+Automake distributions, and full texts.
+
+Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
+Manual}):
 
 @enumerate
 @item
@@ -11933,29 +12203,37 @@ Set the flags:
 @end example
 
 @item
-Write text for the first @code{@@ifinfo} section, for people reading the
-Texinfo file:
+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:
-@c List only the month and the year since that looks less fussy on a
-@c printed cover than a date that lists the day as well.
 
 @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
 
@@ -11968,15 +12246,18 @@ Write text for the Top node, for people reading the Info file:
 
 @example
 @group
-This is Edition @@value@{EDITION@}
-of the @@cite@{GNU Make Manual@},
-last updated @@value@{UPDATED@}
-for @@code@{make@} Version @@value@{VERSION@}.
+@@ifnottex
+@@node Top
+@@top Make
+
+@@insertcopying
+@dots{}
+@@end ifnottex
 @end group
 @end example
 
-After you format the manual, the text in the first @code{@@ifinfo}
-section looks like this:
+After you format the manual, the @code{@@value} constructs have been
+expanded, so the output contains text like this:
 
 @example
 @group
@@ -11986,8 +12267,8 @@ of `The GNU Make Manual', for `make', Version 3.63 Beta.
 @end example
 @end enumerate
 
-When you update the manual, change only the values of the flags; you do
-not need to edit the three sections.
+When you update the manual, you change only the values of the flags; you
+do not need to edit the three sections.
 
 
 @node Internationalization
@@ -12033,14 +12314,9 @@ current hyphenation patterns (via the @TeX{} primitive
 
 @cindex ISO 639 codes
 @cindex Language codes
-@cindex African languages
-Here is the list of valid language codes.  This list comes from
-@uref{http://www.iro.umontreal.ca/contrib/po/iso-639, the free
-translation project}.  In the future we may wish to allow the 3-letter
-POV codes described at @uref{http://www.sil.org/ethnologue/#contents}.
-This will be necessary to support African languages.
-
-@multitable @columnfractions .06 .27 .06 .27 .06 .27
+Hereare the valid language codes, from ISO-639.
+
+@multitable @columnfractions .07 .26 .07 .26 .07 .26
 @item
 @code{aa} @tab Afar @tab
 @code{ab} @tab Abkhazian @tab
@@ -12245,11 +12521,12 @@ specification following, such as @samp{ISO-8859-1}.
 @cindex http-equiv, and charset
 @cindex meta HTML tag, and charset
 At present, this is used only in HTML output from @code{makeinfo}.  If a
-document encoding @var{enc} is specified, it is used in the
-@samp{<meta>} tag is included in the @samp{<head>} of the output:
+document encoding @var{enc} is specified, it is used in a
+@samp{<meta>} tag included in the @samp{<head>} of the output:
 
 @example
-<meta http-equiv="Content-Type" content="text/html; charset=@var{enc}">
+<meta http-equiv="Content-Type" content="text/html;
+      charset=@var{enc}">
 @end example
 
 
@@ -12297,7 +12574,6 @@ customized output in the Info file.
 @section Defining Macros
 @cindex Defining macros
 @cindex Macro definitions
-@cindex Definitions, a.k.a.@: macros
 
 @findex macro
 You use the Texinfo @code{@@macro} command to define a macro, like this:
@@ -12351,7 +12627,7 @@ 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
+@@rmacro rmac @{arg@}
 a\arg\b
 @@end rmacro
 @dots{}
@@ -12423,6 +12699,8 @@ No arguments here.
 No arguments here.
 @end display
 
+@cindex Comma, in macro arguments
+@cindex Braces, in macro arguments
 To insert a comma, brace, or backslash in an argument, prepend a
 backslash, as in
 
@@ -12432,7 +12710,8 @@ backslash, as in
 
 @noindent
 which will pass the (almost certainly error-producing) argument
-@samp{\@{@},} to @var{macname}.
+@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
@@ -12481,25 +12760,30 @@ implementations, Texinfo macros have the following limitations.
 @itemize @bullet
 @item
 All macros are expanded inside at least one @TeX{} group.  This means
-that @set and other such commands will have no effect inside a macro.
+that @code{@@set} and other such commands will have no effect inside a
+macro.
 
 @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.
 
 @item
+Commas in macro arguments, even if escaped by a backslash, don't
+always work.
+
+@item
 The @TeX{} implementation cannot construct macros that define macros in
 the natural way.  To do this, you must use conditionals and raw @TeX{}.
 For example:
 
 @example
-@@ifinfo
+@@ifnottex
 @@macro ctor @{name, arg@}
 @@macro \name\
 something involving \arg\ somehow
 @@end macro
 @@end macro
-@@end ifinfo
+@@end ifnottex
 @@tex
 \gdef\ctor#1@{\ctorx#1,@}
 \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
@@ -12511,6 +12795,10 @@ It is best to avoid comments inside macro definitions.
 
 @end itemize
 
+If some macro feature causes 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; see @ref{Format
+with texi2dvi}.
 
 @node alias
 @section @samp{@@alias @var{new}=@var{existing}}
@@ -12553,7 +12841,7 @@ Aliases must not be recursive, directly or indirectly.
 @findex definfoenclose
 
 A @code{@@definfoenclose} command may be used to define a highlighting
-command for Info, but not for TeX.  A command defined using
+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.
@@ -12595,7 +12883,7 @@ 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 
+Also, for @TeX{} formatting, you could write 
 
 @example
 @@iftex
@@ -12604,14 +12892,13 @@ Also, for TeX formatting, you could write
 @end example
 
 @noindent
-to define @code{@@phoo} as a command that causes TeX to typeset the
+to define @code{@@phoo} as a command that causes @TeX{} to typeset the
 argument to @code{@@phoo} in italics.
 
-Note that 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}.
+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
@@ -12665,7 +12952,7 @@ print queue, and delete a job from the print queue.
 * 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 European A4 paper.
+* 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.
@@ -12680,10 +12967,11 @@ 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 @code{makeinfo}, @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}).
+The standalone @code{makeinfo} program and Emacs 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
@@ -12844,7 +13132,7 @@ Perhaps the most useful option to @code{texi2dvi} is
 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{@@pageparams}
+@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{}}).
@@ -12852,16 +13140,15 @@ formats, such as @code{@@smallbook} (@pxref{smallbook}),
 For a list of other options, run @samp{texi2dvi --help}.
 
 
-@node Print with lpr, Within Emacs, Format with texi2dvi, Hardcopy
+@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, but @samp{lpr -d} is common.  The command may require the
-DVI file name without any extension or with a @samp{.dvi}
-extension.  (If it is @samp{lpr}, you must include the @samp{.dvi}.)
+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
+For example, the following commands will (perhaps) suffice to sort the
 indices, format, and print the @cite{Bison Manual}:
 
 @example
@@ -12875,15 +13162,15 @@ lpr -d bison.dvi
 
 @noindent
 (Remember that the shell commands may be different at your site; but
-these are commonly used versions.)@refill
+these are commonly used versions.)
 
-@need 1000
-Using the @code{texi2dvi} shell script, you simply need type:@refill
+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
 
@@ -13062,8 +13349,7 @@ emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
 Emacs Manual}), or with your @file{.emacs} initialization file
 (@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
 
-@cindex Customize Emacs package
-@findex Development/Docs/Texinfo Customize group
+@cindex Customize Emacs package (@t{Development/Docs/Texinfo})
 Beginning with version 20, GNU Emacs offers a user-friendly interface,
 called @dfn{Customize}, for changing values of user-definable variables.
 @xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
@@ -13072,7 +13358,7 @@ be found in the @samp{Development/Docs/Texinfo} group, once you invoke
 the @kbd{M-x customize} command.
 
 
-@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy
+@node Compile-Command
 @section Using the Local Variables List
 @cindex Local variables
 @cindex Compile command for formatting
@@ -13155,26 +13441,28 @@ For more information, see:
 @cindex @b{.cshrc} initialization file
 @cindex Initialization file for @TeX{} input
 
-@TeX{} needs to know where to find the @file{texinfo.tex} file that you
-have told it to input with the @samp{\input texinfo} command at the
-beginning of the first line.  The @file{texinfo.tex} file tells @TeX{}
-how to handle @@-commands; it is included in all standard GNU
-distributions.
+@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.
 
 @pindex texinfo.tex@r{, installing}
-Usually, the @file{texinfo.tex} file is put under the default directory
-that contains @TeX{} macros
-(@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when
-GNU Emacs or other GNU software is installed.  In this case, @TeX{} will
-find the file and you do not need to do anything special.
-Alternatively, you can put @file{texinfo.tex} in the current directory
-when you run @TeX{}, and @TeX{} will find it there.
+
+Usually, the installer has put the @file{texinfo.tex} file in the
+default directory that contains @TeX{} macros when GNU Texinfo, Emacs 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} in the same place as
-@file{texinfo.tex}, if it is not already installed from another
-distribution.  This file is needed to support the @code{@@image} command
-(@pxref{Images}).
+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}).
+
+@pindex pdfcolor.tex@r{, installing}
+Likewise for @file{pdfcolor.tex}, if it is not already installed and you
+use pdftex.
 
 @pindex texinfo.cnf @r{installation}
 @cindex Customizing of @TeX{} for Texinfo
@@ -13254,10 +13542,9 @@ redumping.)  You can do this by running this command, assuming
 initex texinfo @@dump
 @end example
 
-(@code{@@dump} is a @TeX{} primitive.)  You'll then need to 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, for example, @file{/usr/local/share/tex/web2c}.
+(@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
@@ -13305,10 +13592,10 @@ like this:
 @end example
 
 @noindent
-(You can adjust the fraction as needed.)  This huge value for
+(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
-value is @samp{.15\hsize}.  @code{\hsize} is the @TeX{} dimension
+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
@@ -13369,15 +13656,16 @@ require changing the source file.
 @node A4 Paper
 @section Printing on A4 Paper
 @cindex A4 paper, printing on
-@cindex Paper size, European A4
+@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 with the @code{@@afourpaper} 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:
+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
@@ -13391,15 +13679,15 @@ manual:
 @end example
 
 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
-@TeX{}}, for other ways to format with @code{@@afourpaper} that do not
+@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
@@ -13471,7 +13759,7 @@ 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{(@TeX{} command)}
+@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
@@ -13515,21 +13803,21 @@ You can generate a PDF output file from Texinfo source by using the
 @command{tex}.  Just run @samp{pdftex foo.texi} instead of @samp{tex
 foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
 
-PDF stands for Portable Document Format, and was invented by Adobe
-Systems.  The
-@uref{http://www.adobe.com/prodindex/acrobat/adobepdf.html, file format
-definition} is freely available, as is a
-@uref{http://www.foolabs.com/xpdf/, free viewer} for the X window
-system.  Since PDF is a binary format, there is no @samp{@@ifpdf} or
-@samp{@@pdf} command by analogy with the other output formats.
+@dfn{PDF} stands for `Portable Document Format'. It was invented by
+Adobe Systems some years ago for document interchange, based on their
+PostScript language.  A @uref{http://www.foolabs.com/xpdf/, PDF reader}
+for the X window system is freely available, as is the
+@uref{http://partners.adobe.com/asn/developer/technotes/, definition of
+the file format}.  Since PDF is a binary format, there are no
+@samp{@@ifpdf} or @samp{@@pdf} commands as with the other output
+formats.
 
 Despite the `portable' in the name, PDF files are nowhere near as
-portable in practice as the plain ASCII formats (Info, HTML) Texinfo
-also supports (portability relative to DVI is arguable).  They also tend
-to be much larger and do not support the bitmap fonts used by @TeX{} (by
+portable in practice as the plain ASCII formats (Info, HTML) that
+Texinfo supports (DVI portability is arguable).  They also tend to be
+much larger and do not support the bitmap fonts used by @TeX{} (by
 default) very well.  Nevertheless, a PDF file does preserve an actual
-printed document on a screen as faithfully as possible, unlike HTML,
-say, so have their place.
+printed document on a screen as faithfully as possible, so it has its place.
 
 PDF support in Texinfo is fairly rudimentary.
 
@@ -13537,15 +13825,15 @@ PDF support in Texinfo is fairly rudimentary.
 @node Creating and Installing Info Files
 @chapter Creating and Installing Info Files
 
-This chapter describes how to create and install info files.  @xref{Info
+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::       
-* Install an Info File::        
+* Installing an Info File::     
 @end menu
 
+
 @node Creating an Info File
 @section Creating an Info File
 @cindex Creating an Info file
@@ -13558,7 +13846,7 @@ file, HTML file, or plain text.  @code{texinfo-format-region} and
 Texinfo to Info.
 
 For information on installing the Info file in the Info system,
-@pxref{Install an Info File}.
+@pxref{Installing an Info File}.
 
 @menu
 * makeinfo advantages::         @code{makeinfo} provides better error checking.
@@ -13622,7 +13910,6 @@ makeinfo --version
 
 
 @node makeinfo options
-@comment  node-name,  next,  previous,  up
 @subsection Options for @code{makeinfo}
 @cindex @code{makeinfo} options
 @cindex Options for @code{makeinfo}
@@ -13668,6 +13955,10 @@ can probably never be implemented in @TeX{}.  It also makes
 @samp{--no-validate} is used.  @xref{Pointer Validation}, for more
 details.
 
+@item --docbook
+@opindex --docbook
+Generate DocBook output rather than Info.  
+
 @item --error-limit=@var{limit}
 @itemx -e @var{limit}
 @opindex --error-limit=@var{limit}
@@ -13714,7 +14005,11 @@ created.  With this option, they are preserved.
 Print a usage message listing all available options, then exit successfully.
 
 @item --html
-Generate HTML output rather than Info.  @xref{makeinfo html}.
+@opindex --html
+Generate HTML output rather than Info.  @xref{makeinfo html}.  By
+default, the HTML output is split into one output file per 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}
@@ -13740,16 +14035,21 @@ that does not support @code{@@macro}.
 @cindex ASCII text output
 @cindex Generating plain text files
 @cindex @file{INSTALL} file, generating
-For Info output, do not include menus or node lines in the output and
-write to standard output (unless @option{--output} is specified).  This
-results in an @sc{ascii} file that you cannot read in Info since it does
-not contain the requisite nodes or menus.  It is primarily useful to
-extract certain pieces of a manual into separate files to be included in
-a distribution, such as @file{INSTALL} files.  
+@cindex Node separators, omitting
+@cindex Menus, omitting
+For Info output, do not include menus or node separator lines in the
+output.  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, if @samp{--no-split} is also specified, do not include a
-navigation links at the top of each node.  @xref{makeinfo html}.
+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{makeinfo html}.
+
+In both cases, write to standard output by default (can still be
+overridden by @option{-o}).
 
 @item --no-split
 @opindex --no-split
@@ -13796,8 +14096,8 @@ 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 of the output file for the top node
-(@pxref{makeinfo html}).
+HTML output, @var{file} is the name for the directory into which all
+HTML nodes are written (@pxref{makeinfo html}).
 
 @item -P @var{dir}
 @opindex -P @var{dir}
@@ -13850,6 +14150,10 @@ warnings.
 @opindex -V
 Print the version number, then exit successfully.
 
+@item --xml
+@opindex --xml
+Generate XML output rather than Info.  
+
 @end table
 
 
@@ -14205,14 +14509,26 @@ Info-validate}.@refill
 @subsection Generating HTML
 @cindex HTML
 
-As an alternative to the normal Info format output you can use the
+Besides generating output in the Info format, you can use the
 @samp{--html} option to generate output in HTML format, for installation
-on a web site (for example).  In this release, HTML output from
-@code{makeinfo} is monolithic, splitting the output by chapter or node
-is not supported.  We hope to implement this feature soon.
-
-The HTML output file is named according to @code{@@setfilename}, but
-with any @samp{.info} extension replaced with @samp{.html}.
+on a web site (for example).  By default, the HTML output is split at
+node level.
+
+When splitting, the HTML output files are written into a subdirectory.
+The subdirectory is named according to the name from
+@code{@@setfilename} with any extension removed; for example, HTML
+output for @code{@@setfilename emacs.info} would be written into a
+subdirectory named @samp{emacs}.  If that directory cannot be created
+for any reason, then @samp{.html} is appended to the directory name, as
+in @samp{emacs.html} (this is necessary because sometimes the info file
+is named without an extension, e.g., @samp{texinfo}).  If the
+@samp{@var{name}.html} directory can't be created either,
+@code{makeinfo} gives up.  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} or @code{--outfile}.  Cross-document node
+references are not supported in monolithic HTML.
 
 Texinfo input marked up with the @code{@@ifhtml} command will produce
 output only with the @samp{--html} option supplied.  Input marked up
@@ -14221,29 +14537,27 @@ the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
 which have special significance in HTML).
 
 The @samp{--footnote-style} option is currently ignored for HTML output;
-footnotes are hyperlinked at the end of the output file.
+footnotes are linked to the end of the output file.
 
-The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866).  The
+The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866).  The
 exception is that HTML 3.2 tables are generated from the
 @code{@@multitable} command, but tagged to degrade as well as possible
-in browsers without table support.  Please report output from an
-error-free run of @code{makeinfo} which violates the HTML 3.2 DTD as a
-bug.
+in browsers without table support.  The HTML 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.
 
 Navigation bars are inserted at the start of nodes, similarly to Info
 output.  The @samp{--no-headers} option will suppress 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 @w{HTML 1.0} feature.  You still won't normally get
-the multi-file regexp and index search facilities provided by Info
-readers.  Otherwise, hyperlinks are generated from Texinfo commands
-where appropriate.  @samp{@@xref} commands to other documents are
-generated assuming the other document is available in HTML form too, and
-@samp{.html} is appended to the @samp{@@xref} Info file name.  This
-presumably will often not work.
+which implement this @w{HTML 1.0} feature.  @samp{@@xref} commands to
+other documents are generated assuming the other document is available
+in split HTML form, and installed in the same HTML documentation tree,
+at @file{../<info-document>/}.
 
 
-@node Install an Info File
+@node Installing an Info File
 @section Installing an Info File
 @cindex Installing an Info file
 @cindex Info file installation
@@ -14255,7 +14569,7 @@ into Emacs.  (@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.
+* 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
@@ -14285,7 +14599,7 @@ this:@refill
                        text editor.
 * Texinfo: (texinfo).  With one source file, make
                        either a printed manual using
-                       TeX or an Info file.
+                       @@TeX@{@} or an Info file.
 @dots{}
 @end group
 @end example
@@ -14316,9 +14630,9 @@ 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 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
 
@@ -14391,23 +14705,23 @@ standard @file{dir} file:@refill
 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{.emacs}
-file:@refill
+Alternatively, you could write the following in your @file{.emacs} file:
 
 @vindex Info-directory-list
 @example
 @group
 (require 'info)
 (setq Info-directory-list
-      (cons (expand-file-name "/home/bob/info") Info-directory-list))
+  (cons (expand-file-name "/home/bob/info")
+        Info-directory-list))
 @end group
 @end example
 
-This tells Emacs to merge the @file{dir} file from the
-@file{/home/bob/info} directory with the system @file{dir} file.  Info
-will list the @file{/home/bob/info/info-test} file as a menu entry in
-the @file{/home/bob/info/dir} file.  Emacs does the merging only
-when @kbd{M-x info} is first run, so if you want to set
+This tells Emacs 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.  Emacs does the merging only when
+@kbd{M-x info} is first run, so if you want to set
 @code{Info-directory-list} in an Emacs session where you've already run
 @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
 to recompose the @file{dir} file.
@@ -14461,7 +14775,7 @@ 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 @samp{:} @r{last in @env{INFOPATH}}
+@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
@@ -14485,7 +14799,7 @@ copying an existing @file{dir} file and replace all the text after the
 special CTRL-_ characters that Info needs will be present.
 
 
-@node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File
+@node Installing Dir Entries
 @subsection Installing Info Directory Files
 
 When you install an Info file onto your system, you can use the program
@@ -14495,8 +14809,8 @@ 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 should
-use the commands @code{@@dircategory} and
+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
@@ -14536,12 +14850,21 @@ 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.  
 
-Here are some recommended @code{@@dircategory} categories: `GNU
-packages', `GNU programming tools', `GNU programming documentation',
-`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual
-utilities'.  The idea is to include the `invoking' node for every
-program installed by a package under `Individual utilities', and an
-entry for the manual as a whole in the appropriate other category.
+Here are some recommended @code{@@dircategory} categories:
+
+@display
+GNU packages
+GNU programming tools
+GNU programming documentation
+GNU Emacs Lisp
+GNU libraries
+TeX
+Individual utilities
+@end display
+
+The idea is to include the `Invoking' node for every program installed
+by a package under `Individual utilities', and an entry for the manual
+as a whole in the appropriate other category.
 
 
 @node Invoking install-info
@@ -14686,7 +15009,7 @@ character, as in @"o and @'o.  @xref{Inserting Accents}.
 
 @item @@*
 Force a line break. Do not end a paragraph that uses @code{@@*} with
-an @code{@@refill} command.  @xref{Line Breaks}.@refill
+an @code{@@refill} command.  @xref{Line Breaks}.
 
 @item @@,@{@var{c}@}
 Generate a cedilla accent under @var{c}, as in @,{c}.  @xref{Inserting
@@ -14718,10 +15041,14 @@ an end-of-sentence capital letter).  @xref{Ending a Sentence}.
 Stands for an at sign, @samp{@@}.
 @xref{Braces Atsigns, , Inserting @@ and braces}.
 
+@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.
+character, as in @^o and @`e.
 @xref{Inserting Accents}.
 
 @item @@@{
@@ -14750,6 +15077,9 @@ capital letters, such as `NASA'.  @xref{acronym,, @code{acronym}}.
 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
@@ -15052,8 +15382,13 @@ 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 @@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 as @var{enc}.
+Declare the input encoding to be @var{enc}.
 @xref{documentencoding,, @code{@@documentencoding}}.
 
 @item @@documentlanguage @var{CC}
@@ -15106,7 +15441,7 @@ 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.  Only allowed inside @code{@@iftex}.  @xref{Custom Headings, ,
+pages.  @xref{Custom Headings, ,
 How to Make Your Own Headings}.@refill
 
 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
@@ -15205,8 +15540,7 @@ Explicitly define hyphenation points.  @xref{- and hyphenation,,
 @code{@@-} and @code{@@hyphenation}}.
 
 @item @@i@{@var{text}@}
-Print @var{text} in @i{italic} font.  No effect in Info.
-@xref{Fonts}.@refill
+Print @var{text} in @i{italic} font.  No effect in Info.  @xref{Fonts}.
 
 @item @@ifclear @var{flag}
 If @var{flag} is cleared, the Texinfo formatting commands format text
@@ -15217,17 +15551,26 @@ ifclear} command.
 @item @@ifhtml
 @itemx @@ifinfo
 Begin a stretch of text that will be ignored by @TeX{} when it typesets
-the printed manual.  The text appears only in the HTML resp.@: Info
-file.  Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
-@xref{Conditionals}.
+the printed manual.  @code{@@ifhtml} text appears only in the HTML
+output.  @code{@@ifinfo} output appears in both Info and (for historical
+compatibility) plain text output .  Pair with @code{@@end ifhtml}
+resp.@: @code{@@end ifinfo}.  @xref{Conditionals}.
 
 @item @@ifnothtml
 @itemx @@ifnotinfo
+@itemx @@ifnotplaintext
 @itemx @@ifnottex
 Begin a stretch of text that will be ignored in one output format but
-not the others.  The text appears only in the format not specified.
-Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
-@code{@@end ifnotinfo}.  @xref{Conditionals}.
+not the others.  The text appears in the formats not specified:
+@code{@@ifnothtml} text is omitted from html output, etc.  The exception
+is @code{@@ifnotinfo} text, which is omitted from plain text output as
+well as Info output.  Pair with @code{@@end ifnothtml} resp.@:
+@code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
+@code{@@end ifnottex}.  @xref{Conditionals}.
+
+@item @@ifplaintext
+Begin a stretch of text that appears only in the plain text output.
+Pair with @code{@@end ifplaintext}.  @xref{Conditionals}.
 
 @item @@ifset @var{flag}
 If @var{flag} is set, the Texinfo formatting commands format text
@@ -15245,9 +15588,10 @@ Begin a stretch of text that will not appear in either the Info file
 or the printed output.  Pair with @code{@@end ignore}.
 @xref{Comments, , Comments and Ignored Text}.@refill
 
-@item @@image@{@var{filename}, [@var{width}], [@var{height}]@}
+@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}.  @xref{Images}.
+@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}
 Incorporate the contents of the file @var{filename} into the Info file
@@ -15264,7 +15608,7 @@ 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{Header, , The Texinfo File Header}.@refill
+@xref{Texinfo File Header}.
 
 @item @@item
 Indicate the beginning of a marked paragraph for @code{@@itemize} and
@@ -15370,7 +15714,7 @@ Generate the uppercase and lowercase O-with-slash letters, respectively:
 @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.  Only allowed inside @code{@@iftex}.  @xref{Custom Headings, ,
+pages.  @xref{Custom Headings, ,
 How to Make Your Own Headings}.@refill
 
 @item @@OE@{@}
@@ -15503,7 +15847,8 @@ command even if the @code{@@shortcontents} command is not there.
 @xref{Contents}.
 
 @item @@settitle @var{title}
-Provide a title for page headers in a printed manual.
+Provide a title for page headers in a printed manual, and the default
+document description for HTML @samp{<head>}.
 @xref{settitle, , @code{@@settitle}}.@refill
 
 @item @@shortcontents
@@ -15521,28 +15866,23 @@ 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} (indent text, no
-filling), but do not select the fixed-width font.  In @code{@@smallbook}
-format, print text in a smaller font than with @code{@@display}.  Pair
-with @code{@@end smalldisplay}.  @xref{small}.
+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
 Indent text to indicate an example.  Do not fill, select fixed-width
-font.  In @code{@@smallbook} format, print text in a smaller font than
-with @code{@@example}.  Pair with @code{@@end smallexample}.
+font, narrow the margins.  In printed manuals, 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 and do not select the fixed-width font.
-In @code{@@smallbook} format, print text in a smaller font than
-with @code{@@format}.  Pair with @code{@@end smallformat}.
-@xref{small}.
+the margins.  Pair with @code{@@end smallformat}.  @xref{small}.
 
 @item @@smalllisp
-Begin an example of Lisp code.  Indent text, do not fill, select
-fixed-width font.  In @code{@@smallbook} format, print text in a
-smaller font.  Pair with @code{@@end smalllisp}.  @xref{small}.
+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
@@ -15670,12 +16010,12 @@ Headings, , How to Make Your Own Headings}.@refill
 
 @item @@top @var{title}
 In a Texinfo file to be formatted with @code{makeinfo}, identify the
-topmost @code{@@node} line in the file, which must be written on the line
+topmost @code{@@node} in the file, which must be written on the line
 immediately preceding the @code{@@top} command.  Used for
 @code{makeinfo}'s node pointer insertion feature.  The title is
 underlined with asterisks.  Both the @code{@@node} line and the @code{@@top}
-line normally should be enclosed by @code{@@ifinfo} and @code{@@end
-ifinfo}.  In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+line normally should be enclosed by @code{@@ifnottex} and @code{@@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}}.
 
@@ -15735,6 +16075,19 @@ Highlight a metasyntactic variable, which is something that stands for
 another piece of text.  @xref{var, , Indicating Metasyntactic
 Variables}.@refill
 
+@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
@@ -15744,8 +16097,7 @@ 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 & Permissions, ,
-The Copyright Page and Printed Permissions}.@refill
+only in contexts ignored for Info.  @xref{Copyright}.
 
 @item @@vtable @var{formatting-command}
 Begin a two-column table, using @code{@@item} for each entry.
@@ -15916,49 +16268,15 @@ a complete expression.  Do not write ``You can set:''; instead, write
 
 @subsubheading Editions, Dates and Versions
 
-Write the edition and version numbers and date in three places in every
-manual:
-
-@enumerate
-@item
-In the first @code{@@ifinfo} section, for people reading the Texinfo file.
-
-@item
-In the @code{@@titlepage} section, for people reading the printed manual.
+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).
 
-@item
-In the `Top' node, for people reading the Info file.
-@end enumerate
-
-@noindent
-Also, it helps to write a note before the first @code{@@ifinfo}
-section to explain what you are doing.
-
-@need 800
-@noindent
-For example:
-
-@example
-@group
-@@c ===> NOTE! <==
-@@c Specify the edition and version numbers and date
-@@c in *three* places:
-@@c   1. First ifinfo section  2. title page  3. top node
-@@c To find the locations, search for !!set
-@end group
-
-@group
-@@ifinfo
-@@c !!set edition, date, version
-This is Edition 4.03, January 1992,
-of the @@cite@{GDB Manual@} for GDB Version 4.3.
-@dots{}
-@end group
-@end example
+It is easiest to do this using @code{@@set} and @code{@@value}.
+@xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
 
-@noindent
----or use @code{@@set} and @code{@@value}
-(@pxref{value Example, , @code{@@value} Example}).
 
 @subsubheading Definition Commands
 
@@ -16125,12 +16443,12 @@ file, but only when the command is used inside parentheses.
 You can invoke programs such as Emacs, 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, readers find it hard to search for the
-section.@refill
+sections are all different, they are difficult for users to find.
+
+So, there is a convention to name such sections with a phrase beginning
+with the word `Invoking', as in `Invoking Emacs'; this way, users can
+find the section easily.
 
-Name such sections with a phrase beginning with the word
-@w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way
-users can find the section easily.
 
 @subsubheading ANSI C Syntax
 
@@ -16208,57 +16526,77 @@ Write notes for yourself at the very end of a Texinfo file after the
 @end itemize
 
 
-@node Sample Texinfo File
-@appendix A Sample Texinfo File
+@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 sample
+includes the full texts to be used in GNU manuals.
+
+@menu
+* Short Sample Texinfo File::   
+* GNU Sample Texts::            
+@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, , A Short Sample Texinfo File}.
+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 Document
+@@settitle Sample Manual 1.0
 @@c %**end of header
 
-@@setchapternewpage odd
-
-@@ifinfo
+@@copying
 This is a short example of a complete Texinfo file.
 
-Copyright 1990 Free Software Foundation, Inc.
-@@end ifinfo
+Copyright (C) 2002 Free Software Foundation, Inc.
+@@end copying
 
 @@titlepage
-@@sp 10
-@@comment The title is printed in a large font.
-@@center @@titlefont@{Sample Title@}
-
-@@c The following two commands start the copyright page.
+@@title Sample Title
 @@page
 @@vskip 0pt plus 1filll
-Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
+@@insertcopying
 @@end titlepage
 
-@@node    Top,       First Chapter,         , (dir)
-@@comment node-name, next,          previous, up
+@@c Output the table of the contents at the beginning.
+@@contents
+
+@@ifnottex
+@@node Top
+
+@@insertcopying
+@@end ifnottex
 
 @@menu
 * First Chapter::    The first chapter is the
-                     only chapter in this sample.
-* Concept Index::    This index has two entries.
+                       only chapter in this sample.
+* Index::            Complete index.
 @@end menu
 
-@@node    First Chapter, Concept Index, Top,      Top
-@@comment node-name,     next,          previous, up
+
+@@node First Chapter
 @@chapter First Chapter
-@@cindex Sample index entry
 
-This is the contents of the first chapter.
-@@cindex Another sample index entry
+@@cindex chapter, first
+
+This is the first chapter.
+@@cindex index entry, another
 
 Here is a numbered list.
 
@@ -16270,162 +16608,183 @@ This is the first item.
 This is the second item.
 @@end enumerate
 
-The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
-commands transform a Texinfo file such as this into
-an Info file; and @@TeX@{@} typesets it for a printed
-manual.
 
-@@node    Concept Index,    ,  First Chapter, Top
-@@comment node-name,    next,  previous,      up
-@@unnumbered Concept Index
+@@node Index
+@@unnumbered Index
 
 @@printindex cp
 
-@@contents
 @@bye
 @end example
 
 
-@node Sample Permissions
-@appendix Sample Permissions
-@cindex Permissions
-@cindex Sample permissions
-@cindex Copying permissions
-
-Texinfo files should contain sections that tell the readers that they
-have the right to copy and distribute the Texinfo file, the Info file,
-and the printed manual.@refill
+@node GNU Sample Texts
+@section GNU Sample Texts
 
-Also, if you are writing a manual about software, you should explain
-that the software is free and either include the GNU General Public
-License (GPL) or provide a reference to it.  @xref{Distrib, ,
-Distribution, emacs, The GNU Emacs Manual}, for an example of the text
-that could be used in the software ``Distribution'', ``General Public
-License'', and ``NO WARRANTY'' sections of a document.  @xref{Copying,
-, Texinfo Copying Conditions}, for an example of a brief explanation
-of how the copying conditions provide you with rights. @refill
+@cindex GNU sample texts
+@cindex Sample texts, GNU
+@cindex Full texts, GNU
 
-@menu
-* Inserting Permissions::       How to put permissions in your document.
-* ifinfo Permissions::          Sample @samp{ifinfo} copying permissions.
-* Titlepage Permissions::       Sample Titlepage copying permissions.
-@end menu
+Here is a sample Texinfo document with the full texts that should be
+used in GNU manuals.
 
-@node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions
-@ifinfo
-@section Inserting Permissions
-@end ifinfo
+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.
 
-In a Texinfo file, the first @code{@@ifinfo} section usually begins
-with a line that says what the file documents.  This is what a person
-reading the unprocessed Texinfo file or using the advanced Info
-command @kbd{g *} sees first.  @inforef{Expert, Advanced Info
-commands, info}, for more information. (A reader using the regular
-Info commands usually starts reading at the first node and skips
-this first section, which is not in a node.)@refill
-
-In the @code{@@ifinfo} section, the summary sentence is followed by a
-copyright notice and then by the copying permission notice.  One of
-the copying permission paragraphs is enclosed in @code{@@ignore} and
-@code{@@end ignore} commands.  This paragraph states that the Texinfo
-file can be processed through @TeX{} and printed, provided the printed
-manual carries the proper copying permission notice.  This paragraph
-is not made part of the Info file since it is not relevant to the Info
-file; but it is a mandatory part of the Texinfo file since it permits
-people to process the Texinfo file in @TeX{} and print the
-results.@refill
-
-In the printed manual, the Free Software Foundation copying permission
-notice follows the copyright notice and publishing information and is
-located within the region delineated by the @code{@@titlepage} and
-@code{@@end titlepage} commands.  The copying permission notice is exactly
-the same as the notice in the @code{@@ifinfo} section except that the
-paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
-not part of the notice.@refill
-
-To make it simple to insert a permission notice into each section of
-the Texinfo file, sample permission notices for each section are
-reproduced in full below.@refill
-
-You may need to specify the correct name of a section mentioned in the
-permission notice.  For example, in @cite{The GDB Manual}, the name of
-the section referring to the General Public License is called the ``GDB
-General Public License'', but in the sample shown below, that section is
-referred to generically as the ``GNU General Public License''.  If the
-Texinfo file does not carry a copy of the General Public License, leave
-out the reference to it, but be sure to include the rest of the
-sentence.
-
-@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions
-@comment  node-name,  next,  previous,  up
-@section @samp{ifinfo} Copying Permissions
-@cindex @samp{ifinfo} permissions
+@xref{Short Sample}, for a minimal example of a Texinfo file.
+@xref{Beginning a File}, for a full explanation of that minimal
+example.
 
-In the @code{@@ifinfo} section of a Texinfo file, the standard Free
-Software Foundation permission notice reads as follows:@refill
+Here are some notes on the example:
 
+@itemize @bullet
+@item
+@cindex $Id: texinfo.txi,v 1.4 2002/06/10 13:51:02 espie Exp $ comment
+@cindex CVS $Id: texinfo.txi,v 1.4 2002/06/10 13:51:02 espie Exp $, in Texinfo
+@cindex RCS $Id: texinfo.txi,v 1.4 2002/06/10 13:51:02 espie Exp $, in Texinfo
+The @samp{$Id: texinfo.txi,v 1.4 2002/06/10 13:51:02 espie Exp $} comment is for CVS (@pxref{Top,, Overview, cvs,
+Concurrent Versions System}) or RCS (see rcsintro(1)) version control
+systems, which expand it into a string such as:
 @example
-This file documents @dots{}
+$Id: texinfo.txi,v 1.4 2002/06/10 13:51:02 espie Exp $
+@end example
+(This is useful in all sources that use version control, not just manuals.)
 
-Copyright 1999 Free Software Foundation, Inc.
+@item
+@pindex automake@r{, and version info}
+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, you can mimic
+these or equivalent settings.
 
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
+@item
+The @code{@@syncodeindex} command reflects the recommendation to use only
+one index if at all possible, to make it easier for readers.
 
-@@ignore
-Permission is granted to process this file through TeX
-and print the results, provided the printed document
-carries a copying permission notice identical to this
-one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
+@item
+The @code{@@dircategory} is for constructing the Info directory.
+@xref{Installing Dir Entries}, which includes a variety of recommended
+category names.
 
-@@end ignore
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided also that the sections
-entitled ``Copying'' and ``GNU General Public License''
-are included exactly as in the original, and provided
-that the entire resulting derived work is distributed
-under the terms of a permission notice identical to this
-one.
+@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}.
 
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
-@end example
+@item
+It is best to include the entire GNU Free Documentation License in a GNU
+manual, unless the manual is only a few pages long.  Of course this
+sample is even shorter than that, but it includes the FDL anyway in
+order to show one conventional way of doing so.  The @file{fdl.texi}
+file is available on the GNU machines (and in the Texinfo and other GNU
+distributions).
 
-@node Titlepage Permissions,  , ifinfo Permissions, Sample Permissions
-@comment  node-name,  next,  previous,  up
-@section Titlepage Copying Permissions
-@cindex Titlepage permissions
+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 your manual has invariant sections (again, see the license itself for
+details), then don't forget to include them.
+@end itemize
 
-In the @code{@@titlepage} section of a Texinfo file, the standard Free
-Software Foundation copying permission notice follows the copyright
-notice and publishing information.  The standard phrasing is as
-follows:@refill
+Here is the sample document:
 
+@c We do the first part of this with @example instead of @verbatim
+@c because the literal @setfilename and @include confuse Automake.  Argh.
 @example
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
+\input texinfo    @@c -*-texinfo-*-
+@@comment $Id: texinfo.txi,v 1.4 2002/06/10 13:51:02 espie 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.
 
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided also that the sections
-entitled ``Copying'' and ``GNU General Public License''
-are included exactly as in the original, and provided
-that the entire resulting derived work is distributed
-under the terms of a permission notice identical to this
-one.
+Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
 
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
+@@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@@end quotation
+@@end copying
+
+@@dircategory Texinfo documentation system
+@@direntry
+* sample: (sample)Invoking sample.    
+@@end direntry
+
+@@titlepage
+@@title GNU Sample
+@@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@}
+@@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@})
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@contents
+
+@@ifnottex
+@@node Top
+@@top GNU Sample
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* Invoking sample::
+* Copying This Manual::
+* Index::
+@@end menu
+
+
+@@node Invoking sample
+@@chapter Invoking sample
+
+@@pindex sample
+@@cindex invoking @@command@{sample@}
+
+This is a sample manual.  There is no sample program to
+invoke, but if there was, you could see its basic usage
+and command line options here.
+
+
+@@node Copying This Manual
+@@appendix Copying This Manual
+
+@@menu
+* GNU Free Documentation License::  License for copying this manual.
+@@end menu
+
+@@include fdl.texi
+
+
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@bye
 @end example
 
 
@@ -16437,10 +16796,10 @@ 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.@refill
+the indices of the output file.
 
 Include files let you keep a single large document as a collection of
-conveniently small parts.@refill
+conveniently small parts.
 
 @menu
 * Using Include Files::         How to use the @code{@@include} command.
@@ -16570,7 +16929,8 @@ 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 File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files
+
+@node Include File Requirements
 @section Include File Requirements
 @cindex Include file requirements
 @cindex Requirements for include files
@@ -16627,7 +16987,7 @@ would insert a main or master menu:@refill
 @group
 @@page
 @@vskip 0pt plus 1filll
-Copyright @@copyright@{@} 1999 Free Software Foundation, Inc.
+Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
 @@end titlepage
 @end group
 
@@ -16652,8 +17012,7 @@ Copyright @@copyright@{@} 1999 Free Software Foundation, Inc.
 @end group
 @end example
 
-An included file, such as @file{foo.texinfo}, might look like
-this:@refill
+An included file, such as @file{foo.texinfo}, might look like this:
 
 @example
 @group
@@ -16680,8 +17039,8 @@ Manual} is named @file{elisp.texi}.  This outer file contains a master
 menu with 417 entries and a list of 41 @code{@@include}
 files.@refill
 
-@node Include Files Evolution,  , Sample Include File, Include Files
-@comment  node-name,  next,  previous,  up
+
+@node Include Files Evolution
 @section Evolution of Include Files
 
 When Info was first created, it was customary to create many small
@@ -16907,10 +17266,8 @@ for odd-numbered (right-hand) pages.
 @end itemize
 
 Write custom heading specifications in the Texinfo file immediately
-after the @code{@@end titlepage} command.  Enclose your specifications
-between @code{@@iftex} and @code{@@end iftex} commands since the
-@code{texinfo-format-buffer} command may not recognize them.  Also,
-you must cancel the predefined heading commands with the
+after the @code{@@end titlepage} command.
+You must cancel the predefined heading commands with the
 @code{@@headings off} command before defining your own
 specifications.@refill
 
@@ -16921,10 +17278,8 @@ for both even- and odd-numbered pages:@refill
 
 @example
 @group
-@@iftex
 @@headings off
 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
-@@end iftex
 @end group
 @end example
 
@@ -17024,11 +17379,9 @@ particularly when you are writing drafts:@refill
 
 @example
 @group
-@@iftex
 @@headings off
 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
-@@end iftex
 @end group
 @end example
 
@@ -17046,10 +17399,10 @@ header or footer and blot it out.@refill
 @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.@refill
+Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
 
 Emacs has two tools for catching the @@-command mistakes and two for
 catching structuring mistakes.@refill
@@ -18372,6 +18725,16 @@ Insert the current date.
 @end ignore
 
 
+@node Copying This Manual
+@appendix Copying This Manual
+
+@menu
+* GNU Free Documentation License::  License for copying this manual.
+@end menu
+
+@include fdl.texi
+
+
 @node Command and Variable Index
 @unnumbered Command and Variable Index