summaryrefslogtreecommitdiff
path: root/Build/source/utils/texinfo/doc/texinfo.txi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/texinfo/doc/texinfo.txi')
-rw-r--r--Build/source/utils/texinfo/doc/texinfo.txi2242
1 files changed, 1466 insertions, 776 deletions
diff --git a/Build/source/utils/texinfo/doc/texinfo.txi b/Build/source/utils/texinfo/doc/texinfo.txi
index 15ef1dd0cab..e3478242da6 100644
--- a/Build/source/utils/texinfo/doc/texinfo.txi
+++ b/Build/source/utils/texinfo/doc/texinfo.txi
@@ -1,5 +1,5 @@
\input texinfo.tex @c -*-texinfo-*-
-@c $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $
+@c $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $
@c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi
@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
@@ -37,20 +37,22 @@ 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, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
+Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below. A copy of the license is
-included in the section entitled ``GNU Free Documentation License.''
+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.''
+(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
+this GNU Manual. Buying copies from GNU Press supports the FSF in
+developing GNU and promoting software freedom.''
@end quotation
@end copying
@@ -60,6 +62,7 @@ Software Foundation raise funds for GNU development.''
* install-info: (texinfo)Invoking install-info. Update info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
+* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
@end direntry
@@ -101,8 +104,8 @@ Software Foundation raise funds for GNU development.''
@sp 1
Published by the Free Software Foundation @*
-59 Temple Place Suite 330 @*
-Boston, MA 02111-1307 @*
+51 Franklin St, Fifth Floor @*
+Boston, MA 02110-1301 @*
USA @*
ISBN 1-882114-67-1 @c for version 4.0, September 1999.
@c ISBN 1-882114-65-5 is for version 3.12, March 1998.
@@ -122,7 +125,9 @@ Cover art by Etienne Suvasa.
@node Top
@top Texinfo
-@insertcopying
+This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
+a documentation system that can produce both online information and a
+printed manual from a single source.
The first part of this master menu lists the major nodes in this Info
document, including the @@-command and concept indices. The rest of
@@ -163,9 +168,9 @@ the menu lists all the lower level nodes in the document.
* Include Files:: How to incorporate other Texinfo files.
* Headings:: How to write page headings and footings.
* Catching Mistakes:: How to find formatting mistakes.
-* Copying This Manual:: The GNU Free Documentation License.
+* GNU Free Documentation License::Copying this manual.
* Command and Variable Index:: A menu containing commands and variables.
-* Concept Index:: A menu covering many topics.
+* General Index:: A menu covering many topics.
@detailmenu
--- The Detailed Node Listing ---
@@ -434,16 +439,21 @@ Combining Indices
Special Insertions
* Atsign Braces Comma:: Inserting @@ and @{@} and ,.
+* Inserting Quote Characters:: Inserting left and right quotes, in code.
* Inserting Space:: How to insert the right amount of space
within a sentence.
* Inserting Accents:: How to insert accents and special characters.
+* Inserting Quotation Marks:: How to insert quotation marks.
* Dots Bullets:: How to insert dots and bullets.
* TeX and copyright:: How to insert the @TeX{} logo
and the copyright symbol.
* euro:: How to insert the Euro currency symbol.
* pounds:: How to insert the pounds currency symbol.
+* textdegree:: How to insert the degrees symbol.
* minus:: How to insert a minus sign.
+* geq leq:: How to insert greater/less-than-or-equal signs.
* math:: How to format a mathematical expression.
+* Click Sequences:: Inserting GUI usage sequences.
* Glyphs:: How to indicate results of evaluation,
expansion of macros, errors, etc.
@@ -458,6 +468,7 @@ Inserting Space
* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
* Ending a Sentence:: Sometimes it does.
* Multiple Spaces:: Inserting multiple spaces.
+* frenchspacing:: Specifying end-of-sentence spacing.
* dmn:: How to format a dimension.
Inserting Ellipsis and Bullets
@@ -495,6 +506,7 @@ Forcing and Preventing Breaks
* Break Commands:: Summary of break-related commands.
* Line Breaks:: Forcing line breaks.
* - and hyphenation:: Helping @TeX{} with hyphenation points.
+* allowcodebreaks:: Controlling line breaks within @@code text.
* w:: Preventing unwanted line breaks in text.
* tie:: Inserting an unbreakable but varying space.
* sp:: Inserting blank lines.
@@ -628,9 +640,7 @@ Sample Texinfo Files
* Verbatim Copying License::
* All-permissive Copying License::
-Copying This Manual
-
-* GNU Free Documentation License:: License for copying this manual.
+GNU Free Documentation License
Include Files
@@ -666,10 +676,6 @@ Finding Badly Referenced Nodes
* 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
@@ -789,13 +795,7 @@ better to include too much than to leave out something important.
Patches are most welcome; if possible, please make them with
@samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging
Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,,
-emacs, The GNU Emacs Manual}).
-
-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.
+emacs, The GNU Emacs Manual}), and follow the existing coding style.
@node Using Texinfo
@@ -819,7 +819,7 @@ computer terminals; the HTML output works with virtually all web
browsers. Thus Texinfo can be used by almost any computer user.
@cindex Source file format
-A Texinfo source file is a plain @sc{ascii} file containing text
+A Texinfo source file is a plain ASCII file containing text
interspersed with @dfn{@@-commands} (words preceded by an @samp{@@})
that tell the typesetting and formatting programs what to do. You can
edit a Texinfo file with any text editor, but it is especially
@@ -899,14 +899,15 @@ For more information on @TeX{} in general, please see the book
@cindex Beebe, Nelson
@pindex pdftex
(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This
-was developed by Adobe Systems for portable document interchange,
-based on their previous PostScript language. It can represent the exact
-appearance of a document, including fonts, and supporting arbitrary
-scaling. It is intended to be platform-independent and easily
-viewable, among other design goals; for a discussion, see
-@uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebeI.pdf}. Texinfo
-uses the @command{pdftex} program, a variant of @TeX{}, to output PDF;
-see @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
+format was developed by Adobe Systems for portable document
+interchange, based on their previous PostScript language. It can
+represent the exact appearance of a document, including fonts and
+graphics, and supporting arbitrary scaling. It is intended to be
+platform-independent and easily viewable, among other design goals;
+@uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has
+some background. Texinfo uses the @command{pdftex} program, a variant
+of @TeX{}, to output PDF; see
+@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
@item XML
@cindex XML output
@@ -914,7 +915,7 @@ see @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
@pindex texinfo.dtd
(Generated via @command{makeinfo --xml}.) XML is a generic syntax
specification usable for any sort of content (see, for example,
-@uref{http://www.w3.org/XML/}). The @command{makeinfo} xml output,
+@uref{http://www.w3.org/XML/}). The @command{makeinfo} XML output,
unlike all the formats above, interprets very little of the Texinfo
source. Rather, it merely translates the Texinfo markup commands into
XML syntax, for processing by further XML tools. The particular
@@ -1058,7 +1059,7 @@ info:emacs#Dissociated%20Press
info://localhost/usr/info/emacs#Dissociated%20Press
@end example
-The @command{info} program itself does not follow URI's of any kind.
+The @command{info} program itself does not follow URIs of any kind.
@node Printed Books
@@ -1098,7 +1099,7 @@ file @file{texinfo.tex} that contains information (definitions or
to @TeX{} commands, which @TeX{} can then process to create the typeset
document.) @file{texinfo.tex} contains the specifications for printing
a document. You can get the latest version of @file{texinfo.tex} from
-@uref{ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex}.
+the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
In the United States, documents are most often printed on 8.5 inch by 11
inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But
@@ -1180,7 +1181,7 @@ the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
@item
Write a command such as @code{@@dots@{@}} wherever you wish but usually
-within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
+within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill
@item
Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
@@ -1225,7 +1226,7 @@ This section describes the general conventions used in all Texinfo documents.
@itemize @bullet
@item
@cindex Source files, characters used
-All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
+All printable ASCII characters except @samp{@@}, @samp{@{} and
@samp{@}} can appear in a Texinfo file and stand for themselves.
@samp{@@} is the escape character which introduces commands, while
@samp{@{} and @samp{@}} are used to surround arguments to certain
@@ -1245,30 +1246,9 @@ in other cases as well; you can use the @code{@@noindent} to inhibit
paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}).
@item
-@cindex Quotation characters (`'), in source
-Use doubled single-quote characters to begin and end quotations:
-@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to
-left- and right-hand doubled quotation marks,
-@c this comes out as "like this" in Info, which is just confusing.
-@iftex
-``like this'',
-@end iftex
-and Info converts doubled single-quote characters to @sc{ascii}
-double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
-
-You may occasionally need to produce two consecutive single quotes;
-for example, in documenting a computer language such as Maxima where
-@t{'@w{}'} is a valid command. You can do this with the input
-@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into
-the double-quote characters.
-
-@cindex Unicode quotation characters
-@cindex Grave accent, vs.@: left quote
-The left quote character (@t{`}, ASCII code 96) used in Texinfo is a
-grave accent in ANSI and ISO character set standards. We use it as a
-quote character because that is how @TeX{} is set up, by default. We
-hope to eventually support the various quotation characters in
-Unicode.
+Texinfo supports the usual quotation marks used in English, and
+quotation marks used in other languages, please see @ref{Inserting
+Quotation Marks}.
@item
@cindex Multiple dashes in source
@@ -1288,25 +1268,24 @@ contexts, such as @code{@@code} and @code{@@example}.
@item
@cindex Tabs; don't use!
-@strong{Caution:} Last and most important, do not use tab characters
-in a Texinfo file (except in verbatim modes)! @TeX{} uses
-variable-width fonts, which means that it is impractical at best to
-define a tab to work in all circumstances. Consequently, @TeX{}
-treats tabs like single spaces, and that is not what they look like in
-the source. Furthermore, @code{makeinfo} does nothing special with
-tabs, and thus a tab character in your input file will usually appear
-differently in the output.
-
-@noindent
-To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
-spaces when you press the @key{TAB} key.
+@strong{Caution:} Last, do not use tab characters in a Texinfo file
+(except in verbatim modes)! @TeX{} uses variable-width fonts, which
+means that it is impractical at best to define a tab to work in all
+circumstances. Consequently, @TeX{} treats tabs like single spaces,
+and that is not what they look like in the source. Furthermore,
+@code{makeinfo} does nothing special with tabs, and thus a tab
+character in your input file will usually appear differently in the
+output.
@noindent
-Also, you can run @code{untabify} in Emacs to convert tabs in a region
-to multiple spaces, or use the @code{unexpand} command from the shell.
+To avoid this problem, Texinfo mode in GNU Emacs inserts
+multiple spaces when you press the @key{TAB} key. Also, you can run
+@code{untabify} in Emacs to convert tabs in a region to multiple
+spaces, or use the @code{unexpand} command from the shell.
@end itemize
+
@node Comments
@section Comments
@@ -1355,7 +1334,7 @@ error messages if you have invalid Texinfo commands within ignored text.
@cindex Required in Texinfo file
@cindex Texinfo file minimum
-By convention, the namea of a Texinfo file ends with (in order of
+By convention, the name of a Texinfo file ends with (in order of
preference) one of the extensions @file{.texinfo}, @file{.texi},
@file{.txi}, or @file{.tex}. The longer extensions are preferred since
they describe more clearly to a human reader the nature of the file.
@@ -1472,9 +1451,8 @@ The @dfn{Body} of the document is typically structured like a
traditional book or encyclopedia, but it may be free form.
@item 6. End
-The @dfn{End} segment contains commands for printing indices and
-generating the table of contents, and the @code{@@bye} command on a line
-of its own.
+The @dfn{End} segment may contain commands for printing indices, and
+closes with the @code{@@bye} command on a line of its own.
@end table
@@ -1526,7 +1504,7 @@ which it is distributed. @xref{GNU Sample Texts}.
@@copying
This is a short example of a complete Texinfo file, version 1.0.
-Copyright @@copyright@{@} 2004 Free Software Foundation, Inc.
+Copyright @@copyright@{@} 2005 Free Software Foundation, Inc.
@@end copying
@end group
@end example
@@ -1563,18 +1541,18 @@ writing it out again; it is output on the back of the title page. The
@noindent
The `Top' node contains the master menu for the Info file. Since the
printed manual uses a table of contents rather than a menu, it
-excludes the `Top' node. We also include the copying text again for
-the benefit of online readers. Since the copying text begins with
-a brief description of the manual, no other text is needed in this
-case. The @samp{@@top} command itself helps @command{makeinfo}
-determine the relationships between nodes.
+excludes the `Top' node. We repeat the short description from the
+beginning of the @samp{@@copying} text, but there's no need to repeat
+the copyright information, so we don't use @samp{@@insertcopying} here.
+The @samp{@@top} command itself helps @command{makeinfo} determine the
+relationships between nodes.
@example
@@ifnottex
@@node Top
@@top Short Sample
-@@insertcopying
+This is a short sample Texinfo file.
@@end ifnottex
@group
@@ -1670,13 +1648,13 @@ This is the second item.
@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
-1.1. Brian Fox was responsible for the standalone Texinfo distribution
-until version 3.8, and wrote the standalone @command{makeinfo} and
-@command{info} programs. Karl Berry has continued maintenance since
-Texinfo 3.8 (manual edition 2.22).
+Richard M. Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual. Robert@tie{}J.
+Chassell greatly revised and extended the manual, starting with
+Edition 1.1. Brian Fox was responsible for the standalone Texinfo
+distribution until version 3.8, and wrote the standalone
+@command{makeinfo} and @command{info} programs. Karl Berry has
+continued maintenance since Texinfo 3.8 (manual edition 2.22).
@cindex Pinard, Fran@,{c}ois
@cindex Zuhn, David D.
@@ -1686,7 +1664,7 @@ Texinfo 3.8 (manual edition 2.22).
@cindex Weinberg, Zack
Our thanks go out to all who helped improve this work, particularly the
indefatigable Eli Zaretskii and Andreas Schwab, who have provided
-patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
+patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn,
tirelessly recorded and reported mistakes and obscurities. Zack
Weinberg did the impossible by implementing the macro syntax in
@file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her
@@ -1701,7 +1679,7 @@ the @file{ChangeLog} file. Our mistakes are our own.
A bit of history: in the 1970's at CMU, Brian Reid developed a program
and format named Scribe to mark up documents for printing. It used the
@code{@@} character to introduce commands, as Texinfo does. Much more
-consequentially, it strived to describe document contents rather than
+consequentially, it strove to describe document contents rather than
formatting, an idea wholeheartedly adopted by Texinfo.
@cindex Bolio
@@ -1727,7 +1705,7 @@ as printed hard copy.
@cindex Emacs
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
+file is no different from any other ASCII file. However, GNU Emacs
comes with a special mode, called Texinfo mode, that provides Emacs
commands and tools to help ease your work.
@@ -1805,7 +1783,7 @@ equivalents, such as appendices. With this value for the page
delimiter, you can jump from chapter title to chapter title with the
@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
(@code{backward-page}) commands and narrow to a chapter with the
-@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
+@kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
The GNU Emacs Manual}, for details about the page commands.)@refill
You may name a Texinfo file however you wish, but the convention is to
@@ -1918,12 +1896,12 @@ cursor at the beginning of the next line.@refill
@findex texinfo-insert-braces
Insert @code{@{@}} and put the cursor between the braces.@refill
-@item C-c C-c @}
-@itemx C-c C-c ]
+@item C-c @}
+@itemx C-c ]
@itemx M-x up-list
@findex up-list
Move from between a pair of braces forward past the closing brace.
-Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
+Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which
is, however, more mnemonic; hence the two keybindings. (Also, you can
move out from between braces by typing @kbd{C-f}.)@refill
@end table
@@ -2027,7 +2005,7 @@ Texinfo mode sets the value of the page delimiter variable to match
the chapter-level @@-commands. This enables you to use the @kbd{C-x
]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
commands to move forward and backward by chapter, and to use the
-@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
+@kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter.
@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
about the page commands.@refill
@@ -2211,7 +2189,7 @@ This updates all the nodes and menus.@refill
The @code{texinfo-column-for-description} variable specifies the
column to which menu descriptions are indented. By default, the value
-is 32 although it is often useful to reduce it to as low as 24. You
+is 32 although it can be useful to reduce it to as low as 24. You
can set the variable via customization (@pxref{Changing an Option,,,
emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable}
command (@pxref{Examining, , Examining and Setting Variables, emacs,
@@ -2511,9 +2489,9 @@ C-c C-c i @r{Insert} @samp{@@item}.
C-c C-c n @r{Insert} @samp{@@node}.
C-c C-c s @r{Insert} @samp{@@samp}.
C-c C-c v @r{Insert} @samp{@@var}.
-C-c C-c @{ @r{Insert braces.}
-C-c C-c ]
-C-c C-c @} @r{Move out of enclosing braces.}
+C-c @{ @r{Insert braces.}
+C-c ]
+C-c @} @r{Move out of enclosing braces.}
@group
C-c C-c C-d @r{Insert a node's section title}
@@ -2760,7 +2738,7 @@ Published by @dots{}
@@node Top
@@top @var{title}
-@@insertcopying
+This manual is for @var{program}, version @var{version}.
@@end ifnottex
@group
@@ -3094,10 +3072,11 @@ The copyright owner (or owners) is whoever holds legal copyright on the
work. In the case of works assigned to the FSF, the owner is `Free
Software Foundation, Inc.'.
-The copyright `line' may actually be split across multiple
-lines, both in the source document and in the output. This often
-happens for documents with a long history, having many different years
-of publication.
+The copyright `line' may actually be split across multiple lines, both
+in the source document and in the output. This often happens for
+documents with a long history, having many different years of
+publication. If you do use several lines, do not indent any of them
+(or anything else in the @code{@@copying} block) in the source file.
@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
additional information.
@@ -3121,24 +3100,17 @@ This inserts the text previously defined by @code{@@copying}. To meet
legal requirements, it must be used on the copyright page in the printed
manual (@pxref{Copyright}).
-We also strongly recommend using @code{@@insertcopying} in the Top node
-of your manual (@pxref{The Top Node}), although it is not required
-legally. Here's why:
-
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.
+command @kbd{g *}), but this does not matter for legal purposes,
+because the text is present.
Similarly, the @code{@@copying} text is automatically included at the
beginning of each HTML output file, as an HTML comment. Again, this
-text is not visible (unless the reader views the HTML source). And
-therefore again, the @code{@@insertcopying} in the Top node is valuable
-because it makes the copying permissions visible and thus promotes
-freedom.
+text is not visible (unless the reader views the HTML source).
The permissions text defined by @code{@@copying} also appears
automatically at the beginning of the XML output file.
@@ -3422,7 +3394,7 @@ commands.
@findex filll @r{@TeX{} dimension}
Use the @code{@@page} command to cause a page break. To push the
copyright notice and the other text on the copyright page towards the
-bottom of the page, use the following incantantion after @code{@@page}:
+bottom of the page, use the following incantation after @code{@@page}:
@example
@@vskip 0pt plus 1filll
@@ -3515,25 +3487,21 @@ The @code{@@headings} command is rarely used. It specifies what kind of
page headings and footings to print on each page. Usually, this is
controlled by the @code{@@setchapternewpage} command. You need the
@code{@@headings} command only if the @code{@@setchapternewpage} command
-does not do what you want, or if you want to turn off pre-defined page
+does not do what you want, or if you want to turn off predefined page
headings prior to defining your own. Write an @code{@@headings} command
-immediately after the @code{@@end titlepage} command.@refill
+immediately after the @code{@@end titlepage} command.
-You can use @code{@@headings} as follows:@refill
+You can use @code{@@headings} as follows:
@table @code
@item @@headings off
-Turn off printing of page headings.@refill
+Turn off printing of page headings.
@item @@headings single
Turn on page headings appropriate for single-sided printing.
-@refill
@item @@headings double
-@itemx @@headings on
-Turn on page headings appropriate for double-sided printing. The two
-commands, @code{@@headings on} and @code{@@headings double}, are
-synonymous.@refill
+Turn on page headings appropriate for double-sided printing.
@item @@headings singleafter
@itemx @@headings doubleafter
@@ -3554,7 +3522,7 @@ double} after the @code{@@end titlepage} command.
You can stop @TeX{} from generating any page headings at all by
writing @code{@@headings off} on a line of its own immediately after the
-line containing the @code{@@end titlepage} command, like this:@refill
+line containing the @code{@@end titlepage} command, like this:
@example
@@end titlepage
@@ -3563,11 +3531,10 @@ line containing the @code{@@end titlepage} command, like this:@refill
@noindent
The @code{@@headings off} command overrides the @code{@@end titlepage}
-command, which would otherwise cause @TeX{} to print page
-headings.@refill
+command, which would otherwise cause @TeX{} to print page headings.
You can also specify your own style of page heading and footing.
-@xref{Headings, , Page Headings}, for more information.@refill
+@xref{Headings, , Page Headings}, for more information.
@node Contents
@@ -3619,7 +3586,7 @@ included in plain text output (generated by @code{makeinfo
output.
When @code{makeinfo} writes a short table of contents while producing
-html output, the links in the short table of contents point to
+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.
@@ -3658,25 +3625,24 @@ texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
@cindex Top node
@cindex Node, `Top'
-The `Top' node is the node in which a reader enters an Info manual. As
-such, it should begin with 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.
+The `Top' node is the node in which a reader enters an Info manual.
+As such, it should begin with a brief description of the manual
+(including the version number), and end with a master menu for the
+whole manual. Of course you should include any other general
+information you feel a reader would find helpful.
@findex top
-It is 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}).
+It is conventional and desirable to write an @code{@@top} sectioning
+command line containing the title of the document immediately after
+the @code{@@node Top} line (@pxref{makeinfo top command, , The
+@code{@@top} Sectioning Command}).
The contents of the `Top' node should appear only in the online output;
none of it should appear in printed output, so enclose it between
@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
print either an @code{@@node} line or a menu; they appear only in Info;
strictly speaking, you are not required to enclose these parts between
-@code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
+@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
so. @xref{Conditionals, , Conditionally Visible Text}.)
@menu
@@ -3699,6 +3665,7 @@ Here is an example of a Top node.
@@top Sample Title
@@insertcopying
+@@end ifnottex
@end group
Additional general information.
@@ -3737,6 +3704,8 @@ for the chapters, chapter-like sections, and the appendices.
The second part contains nodes for the indices.
@item
+@findex detailmenu
+@cindex Detailed menu
The third and subsequent parts contain a listing of the other, lower
level nodes, often ordered by chapter. This way, rather than go
through an intermediary menu, an inquirer can go directly to a
@@ -3764,7 +3733,7 @@ For example, the master menu for this manual looks like the following
@end group
@group
* Command and Variable Index::
-* Concept Index::
+* General Index::
@end group
@group
@@ -4422,17 +4391,11 @@ This kind of stylistic choice is not usually offered by Texinfo.
Use the @code{@@unnumbered} command to create a chapter that appears
in a printed manual without chapter numbers of any kind. Use the
@code{@@appendix} command to create an appendix in a printed manual
-that is labelled by letter instead of by number.@refill
-
-For Info file output, the @code{@@unnumbered} and @code{@@appendix}
-commands are equivalent to @code{@@chapter}: the title is printed on a
-line by itself with a line of asterisks underneath. (@xref{chapter, ,
-@code{@@chapter}}.)@refill
+that is labelled by letter (`A', `B', @dots{}) instead of by number.
-To create an appendix or an unnumbered chapter, write an
-@code{@@appendix} or @code{@@unnumbered} command at the beginning of a
-line and follow it on the same line by the title, as you would if you
-were creating a chapter.@refill
+Write an @code{@@appendix} or @code{@@unnumbered} command at the
+beginning of a line and follow it on the same line by the title, as
+you would if you were creating a chapter.
@node majorheading & chapheading
@@ -4459,17 +4422,19 @@ of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
@node section
-@comment node-name, next, previous, up
@section @code{@@section}
@findex section
-In a printed manual, an @code{@@section} command identifies a
-numbered section within a chapter. The section title appears in the
-table of contents. In Info, an @code{@@section} command provides a
-title for a segment of text, underlined with @samp{=}.@refill
+A @code{@@section} command identifies a section within a chapter unit,
+whether created with @code{@@chapter}, @code{@@unnumbered}, or
+@code{@@appendix}, following the numbering scheme of the chapter-level
+command. Thus, within a @code{@@chapter} chapter numbered `1', the
+section is numbered like `1.2'; within an @code{@@appendix}
+``chapter'' labeled `A', the section is numbered like `A.2'; within an
+@code{@@unnumbered} chapter, the section gets no number.
-This section is headed with an @code{@@section} command and looks like
-this in the Texinfo file:@refill
+For example, this section is headed with an @code{@@section} command
+and looks like this in the Texinfo file:
@example
@@section @@code@{@@@@section@}
@@ -4477,7 +4442,7 @@ this in the Texinfo file:@refill
To create a section, write the @code{@@section} command at the
beginning of a line and follow it on the same line by the section
-title.@refill
+title. The output is underlined with @samp{=} in Info.
Thus,
@@ -4486,21 +4451,17 @@ Thus,
@end example
@noindent
-produces
+might produce the following in Info:
@example
@group
-This is a section
-=================
+5.7 This is a section
+=====================
@end group
@end example
-@noindent
-in Info.
-
@node unnumberedsec appendixsec heading
-@comment node-name, next, previous, up
@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
@findex unnumberedsec
@findex appendixsec
@@ -4508,8 +4469,8 @@ in Info.
The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
commands are, respectively, the unnumbered, appendix-like, and
-heading-like equivalents of the @code{@@section} command.
-(@xref{section, , @code{@@section}}.)@refill
+heading-like equivalents of the @code{@@section} command, as described
+in the previous section.
@table @code
@item @@unnumberedsec
@@ -4531,15 +4492,19 @@ You may use the @code{@@heading} command anywhere you wish for a
section-style heading that will not appear in the table of contents.@refill
@end table
+@code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used
+in ordinary circumstances, because @code{@@section} may also be used
+within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
+the previous section.
+
@node subsection
-@comment node-name, next, previous, up
@section The @code{@@subsection} Command
@findex subsection
Subsections are to sections as sections are to chapters.
(@xref{section, , @code{@@section}}.) In Info, subsection titles are
-underlined with @samp{-}. For example,@refill
+underlined with @samp{-}. For example,
@example
@@subsection This is a subsection
@@ -4550,16 +4515,16 @@ produces
@example
@group
-This is a subsection
---------------------
+1.2.3 This is a subsection
+--------------------------
@end group
@end example
In a printed manual, subsections are listed in the table of contents
and are numbered three levels deep.@refill
+
@node unnumberedsubsec appendixsubsec subheading
-@comment node-name, next, previous, up
@section The @code{@@subsection}-like Commands
@cindex Subsection-like commands
@findex unnumberedsubsec
@@ -4569,7 +4534,7 @@ and are numbered three levels deep.@refill
The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
@code{@@subheading} commands are, respectively, the unnumbered,
appendix-like, and heading-like equivalents of the @code{@@subsection}
-command. (@xref{subsection, , @code{@@subsection}}.)@refill
+command. (@xref{subsection, , @code{@@subsection}}.)
In Info, the @code{@@subsection}-like commands generate a title
underlined with hyphens. In a printed manual, an @code{@@subheading}
@@ -4579,7 +4544,13 @@ an @code{@@unnumberedsubsec} command produces an unnumbered heading like
that of a subsection and an @code{@@appendixsubsec} command produces a
subsection-like heading labelled with a letter and numbers; both of
these commands produce headings that appear in the table of
-contents.@refill
+contents.
+
+@code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
+be used in ordinary circumstances, because @code{@@subsection} may
+also be used within sections of @code{@@unnumbered} and
+@code{@@appendix} chapters (@pxref{section,,@code{section}}).
+
@node subsubsection
@section The `subsub' Commands
@@ -4618,6 +4589,13 @@ Info, subsubheadings look exactly like ordinary subsubsection
headings.@refill
@end table
+@code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec} do not
+need to be used in ordinary circumstances, because
+@code{@@subsubsection} may also be used within subsections of
+@code{@@unnumbered} and @code{@@appendix} chapters
+(@pxref{section,,@code{section}}).
+
+
In Info, `subsub' titles are underlined with periods.
For example,@refill
@@ -4630,8 +4608,8 @@ produces
@example
@group
-This is a subsubsection
-.......................
+1.2.3.4 This is a subsubsection
+...............................
@end group
@end example
@@ -4879,31 +4857,35 @@ contain any number of nodes. Indeed, a chapter usually contains
several nodes, one for each section, subsection, and
subsubsection.
-To create a node, write an @code{@@node} command at the beginning of a
-line, and follow it with up to four arguments, separated by commas, on
-the rest of the same line. The first argument is required; it is the
-name of this node. The subsequent arguments are the names of the
-`Next', `Previous', and `Up' pointers, in that order, and may be omitted
-if your Texinfo document is hierarchically organized (@pxref{makeinfo
+To specify a node, write an @code{@@node} command at the beginning of
+a line, and follow it with up to four arguments, separated by commas,
+on the rest of the same line. The first argument is required; it is
+the name of this node (for details of node names, @pxref{Node Line
+Requirements}). The subsequent arguments are the names of the `Next',
+`Previous', and `Up' pointers, in that order, and may be omitted if
+your Texinfo document is hierarchically organized (@pxref{makeinfo
Pointer Creation}).
-You may insert spaces before each name if you wish; the spaces are
-ignored. You must write the name of the node and (if present) the names
-of the `Next', `Previous', and `Up' pointers all on the same line.
-Otherwise, the formatters fail. (@inforef{Top, info, info}, for more
-information about nodes in Info.)
+@opindex accesskey@r{, in HTML output}
+Whether the node pointers are specified implicitly or explicitly, the
+HTML output from @command{makeinfo} for each node includes links to
+the `Next', `Previous', and `Up' nodes. The HTML also uses the
+@code{accesskey} attribute with the values @samp{n}, @samp{p}, and
+@samp{u} respectively. This allows people using web browsers to
+follow the nagivation using (typically) @kbd{M-@var{letter}}, e.g.,
+@kbd{M-n} for the `Next' node, from anywhere within the node.
+
+You may insert spaces before each name on the @code{@@node} line if
+you wish; the spaces are ignored. You must write the name of the node
+and (if present) the names of the `Next', `Previous', and `Up'
+pointers all on the same line. Otherwise, the formatters fail.
+(@inforef{Top, info, info}, for more information about nodes in Info.)
Usually, you write one of the chapter-structuring command lines
immediately after an @code{@@node} line---for example, an
@code{@@section} or @code{@@subsection} line. (@xref{Structuring
Command Types}.)
-@quotation Note
-The GNU Emacs Texinfo mode updating commands work
-only with Texinfo files in which @code{@@node} lines are followed by chapter
-structuring lines. @xref{Updating Requirements}.
-@end quotation
-
@TeX{} uses @code{@@node} lines to identify the names to use for cross
references. For this reason, you must write @code{@@node} lines in a
Texinfo file that you intend to format for printing, even if you do not
@@ -4925,15 +4907,16 @@ see @ref{Cross References}.)
@subsection Choosing Node and Pointer Names
@cindex Node names, choosing
-The name of a node identifies the node. The pointers enable
-you to reach other nodes and consist simply of the names of those nodes.
+The name of a node identifies the node (for details of node names,
+@pxref{Node Line Requirements}). The pointers enable you to reach
+other nodes and consist simply of the names of those nodes.
-Normally, a node's `Up' pointer contains the name of the node whose menu
-mentions that node. The node's `Next' pointer contains the name of the
-node that follows that node in that menu and its `Previous' pointer
-contains the name of the node that precedes it in that menu. When a
-node's `Previous' node is the same as its `Up' node, both node pointers
-name the same node.
+Normally, a node's `Up' pointer contains the name of the node whose
+menu mentions that node. The node's `Next' pointer contains the name
+of the node that follows the present node in that menu and its
+`Previous' pointer contains the name of the node that precedes it in
+that menu. When a node's `Previous' node is the same as its `Up'
+node, both node pointers name the same node.
Usually, the first node of a Texinfo file is the `Top' node, and its
`Up' and `Previous' pointers point to the @file{dir} file, which
@@ -4948,7 +4931,7 @@ Even when you explicitly specify all pointers, that does not mean you
can write the nodes in the Texinfo source file in an arbitrary order!
Because @TeX{} processes the file sequentially, irrespective of node
pointers, you must write the nodes in the order you wish them to appear
-in the printed output.
+in the output.
@node Writing a Node
@@ -4959,7 +4942,7 @@ in the printed output.
The easiest way to write an @code{@@node} line is to write @code{@@node}
at the beginning of a line and then the name of the node, like
-this:@refill
+this:
@example
@@node @var{node-name}
@@ -4969,7 +4952,7 @@ If you are using GNU Emacs, you can use the update node commands
provided by Texinfo mode to insert the names of the pointers; or you
can leave the pointers out of the Texinfo file and let @code{makeinfo}
insert node pointers into the Info file it creates. (@xref{Texinfo
-Mode}, and @ref{makeinfo Pointer Creation}.)@refill
+Mode}, and @ref{makeinfo Pointer Creation}.)
Alternatively, you can insert the `Next', `Previous', and `Up'
pointers yourself. If you do this, you may find it helpful to use the
@@ -4977,15 +4960,21 @@ Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
@samp{@@node} and a comment line listing the names of the pointers in
their proper order. The comment line helps you keep track of which
arguments are for which pointers. This comment line is especially useful
-if you are not familiar with Texinfo.@refill
+if you are not familiar with Texinfo.
The template for a fully-written-out node line with `Next', `Previous',
-and `Up' pointers looks like this:@refill
+and `Up' pointers looks like this:
@example
@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
@end example
+The @var{node-name} argument must be present, but the others are
+optional. If you wish to specify some but not others, just insert
+commas as needed, as in: @samp{@@node mynode,,,uppernode}. However,
+we recommend leaving off all the pointers and letting @code{makeinfo}
+determine them, as described above.
+
If you wish, you can ignore @code{@@node} lines altogether in your first
draft and then use the @code{texinfo-insert-node-lines} command to
create @code{@@node} lines for you. However, we do not recommend this
@@ -5138,12 +5127,8 @@ 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
-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.
+@cindex Prev node of Top node
+The `Prev' node of the Top node should also be your @samp{(dir)} file.
@item
@cindex Next node of Top node
@@ -5155,11 +5140,8 @@ document.
@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):
-
-Or you can leave the pointers off entirely and let the tools implicitly
-define them. This is recommended. Thus:
+It is usually best to leave the pointers off entirely and let the
+tools implicitly define them, with this simple result:
@example
@@node Top
@@ -5205,8 +5187,9 @@ Thus, in practice, a Top node starts like this:
@cindex Pointer creation with @code{makeinfo}
@cindex Automatic pointer creation with @code{makeinfo}
-The @code{makeinfo} program has a feature for automatically determining
-node pointers for a hierarchically organized document.
+The @code{makeinfo} program has a feature for automatically
+determining node pointers for a hierarchically organized document. We
+highly recommend using it.
When you take advantage of this feature, you do not need to write the
`Next', `Previous', and `Up' pointers after the name of a node.
@@ -5222,7 +5205,14 @@ Finally, you must write the name of each node (except for the `Top'
node) in a menu that is one or more hierarchical levels above the
node's hierarchical level.
-This implicit node pointer insertion feature in @code{makeinfo}
+@cindex Detail menu
+@findex detailmenu
+If you use a detailed menu in your master menu (@pxref{Master Menu
+Parts}), mark it with the @code{@@detailmenu @@dots@{@} @@end
+detailmenu} environment, or @command{makeinfo} will get confused,
+typically about the last and/or first node in the document.
+
+This implicit node pointer creation feature in @code{makeinfo}
relieves you from the need to update menus and pointers manually or
with Texinfo mode commands. (@xref{Updating Nodes and Menus}.)
@@ -5233,8 +5223,7 @@ sectioning commands at all (for example, if you never intend the
document to be printed). The special procedure for handling the short
text before a menu (@pxref{Menus}) also disables this
feature, for that group of nodes. In those cases, you will need to
-explicitly specify the pointers.
-
+explicitly specify all pointers.
@node anchor
@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
@@ -5273,13 +5262,16 @@ It is best to put @code{@@anchor} commands just before the position you
wish to refer to; that way, the reader's eye is led on to the correct
text when they jump to the anchor. You can put the @code{@@anchor}
command on a line by itself if that helps readability of the source.
-Spaces are always ignored after @code{@@anchor}.
+Whitespace (including newlines) is ignored after @code{@@anchor}.
Anchor names and node names may not conflict. Anchors and nodes are
given similar treatment in some ways; for example, the @code{goto-node}
command in standalone Info takes either an anchor name or a node name as
an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
+Also like node names, anchor names cannot include some characters
+(@pxref{Node Line Requirements}).
+
@node Menus
@chapter Menus
@@ -5291,11 +5283,12 @@ you use menus to go to such nodes. Menus have no effect in printed
manuals and do not appear in them.
A node with a menu should not contain much text. If you find yourself
-writing a lot of before a menu, we generally recommend moving most of
-the text into a new subnode---all but a paragraph or two. Otherwise,
-a reader with a terminal that displays only a few lines may miss the
-menu and its associated text. As a practical matter, it is best to
-locate a menu within 20 or so lines of the beginning of the node.
+writing a lot of text before a menu, we generally recommend moving
+most of the text into a new subnode---all but a paragraph or two.
+Otherwise, a reader with a terminal that displays only a few lines may
+miss the menu and its associated text. As a practical matter, it is
+best to locate a menu within 20 or so lines of the beginning of the
+node.
@menu
* Menu Location:: Menus go at the ends of short nodes.
@@ -5338,10 +5331,10 @@ In the past, we recommended using a @samp{@@heading} command within an
@code{@@ifinfo} conditional instead of the normal sectioning commands
after a very short node with a menu. This had the advantage of making
the printed output look better, because there was no very short text
-between two headings on the page. But aside from not working with
-@command{makeinfo}'s implicit pointer creation, it also makes the XML
-output incorrect, since it does not reflect the true document
-structure. So, unfortunately we can no longer recommend this.
+between two headings on the page. But this also does not work with
+@command{makeinfo}'s implicit pointer creation, and it also makes the
+XML output incorrect, since it does not reflect the true document
+structure. So, regrettably, we can no longer recommend this.
@node Writing a Menu
@@ -5377,6 +5370,13 @@ menu comment line; the two lines starting with @w{@samp{* }} are menu
entries. Space characters in a menu are preserved as-is; this allows
you to format the menu as you wish.
+@opindex accesskey@r{, in HTML output}
+In the HTML output from @command{makeinfo}, the @code{accesskey}
+attribute is used with the values @samp{1}@dots{}@samp{9} for the
+first nine entries. This allows people using web browsers to follow
+the first menu entries using (typically) @kbd{M-@var{digit}}, e.g.,
+@kbd{M-1} for the first entry.
+
@node Menu Parts
@section The Parts of a Menu
@@ -5753,9 +5753,12 @@ node provides the page reference only for references within the same
document.@refill
@item
-The cross reference name for the Info reference, if it is to be different
-from the node name. If you include this argument, it becomes
-the first part of the cross reference. It is usually omitted.@refill
+The cross reference name for the Info reference, if it is to be
+different from the node name or the topic description. If you
+include this argument, it becomes the first part of the cross reference.
+It is usually omitted; then the topic description (third argument) is
+used if it was specified; if that was omitted as well, the node name
+is used.
@item
A topic description or section name. Often, this is the title of the
@@ -6265,19 +6268,20 @@ This makes it useful as the last part of a sentence.
@cindex Hurricanes
@example
-For more information, see @@ref@{Hurricanes@}.
+For more information, @@pxref@{This@}, and @@ref@{That@}.
@end example
-@noindent produces (in Info):
+@noindent produces in Info:
@example
-For more information, see *Note Hurricanes::.
+For more information, *note This::, and *note That::.
@end example
-@noindent and (in printed output):
+@noindent and in printed output:
@quotation
-For more information, see Section 8.2 [Hurricanes], page 123.
+For more information, see Section 1.1 [This], page 1,
+and Section 1.2 [That], page 2.
@end quotation
The @code{@@ref} command sometimes tempts writers to express
@@ -6296,19 +6300,21 @@ Sea surges are described in @@ref@{Hurricanes@}.
Sea surges are described in Section 6.7 [Hurricanes], page 72.
@end quotation
-@noindent but is awkward to read in Info:
+@noindent but is awkward to read in Info, ``note'' being a verb:
@example
-Sea surges are described in *Note Hurricanes::.
+Sea surges are described in *note Hurricanes::.
@end example
-As a general rule, you should write a period or comma immediately
-after an @code{@@ref} command with two or more arguments.
+You should write a period or comma immediately after an @code{@@ref}
+command with two or more arguments. If there is no such following
+punctuation, @command{makeinfo} will generate a (grammatically
+incorrect) period in the Info output; otherwise, the cross-reference
+would fail completely, due to the current syntax of Info format.
-If there is no such following punctuation, @command{makeinfo} will
-generate a (grammatically incorrect) period in the Info output;
-otherwise, the cross-reference would fail completely, due to the
-current syntax of Info format.
+In general, it is best to use @code{@@ref} only when you need some
+word other than ``see'' to precede the reference. When ``see'' (or
+``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.
@node pxref
@@ -6318,40 +6324,32 @@ current syntax of Info format.
@findex pxref
The parenthetical reference command, @code{@@pxref}, is nearly the
-same as @code{@@xref}, but you use it @emph{only} inside parentheses
-and you do @emph{not} type a comma or period (or anything else) after
-the command's closing brace. The command differs from @code{@@xref}
+same as @code{@@xref}, but it is best used at the end of a sentence or
+before a closing parenthesis. The command differs from @code{@@xref}
in two ways:
@enumerate
@item
@TeX{} typesets the reference for the printed manual with a lower case
-`see' rather than an upper case `See'.@refill
+`see' rather than an upper case `See'.
@item
The Info formatting commands automatically end the reference with a
-closing colon or period.@refill
+closing colon or period, if necessary.
@end enumerate
-Because one type of formatting automatically inserts closing
-punctuation and the other does not, you should use @code{@@pxref}
-@emph{only} inside parentheses as part of another sentence. Also, you
-yourself should not insert punctuation after the reference (or any
-other text), as you do with @code{@@xref}. In the Info
-output, such text would follow a period, which is grammatically wrong.
-
@code{@@pxref} is designed so that the output looks right and works
-right between parentheses both in printed output and in an Info file.
-In a printed manual, a closing comma or period should not follow a
-cross reference within parentheses; such punctuation is wrong. But in
-an Info file, suitable closing punctuation must follow the cross
-reference so Info can recognize its end. @code{@@pxref} spares you
-the need to use complicated methods to put a terminator into one form
-of the output and not the other.@refill
+right at the end of a sentence or parenthetical phrase, both in
+printed output and in an Info file. In a printed manual, a closing
+comma or period should not follow a cross reference within
+parentheses; such punctuation is wrong. But in an Info file, suitable
+closing punctuation must follow the cross reference so Info can
+recognize its end. @code{@@pxref} spares you the need to use
+complicated methods to put a terminator into one form of the output
+and not the other.
@noindent
-With one argument, a parenthetical cross reference looks like
-this:@refill
+With one argument, a parenthetical cross reference looks like this:
@cindex Flooding
@example
@@ -6364,7 +6362,7 @@ which produces
@example
@group
-@dots{} storms cause flooding (*Note Hurricanes::) @dots{}
+@dots{} storms cause flooding (*note Hurricanes::) @dots{}
@end group
@end example
@@ -6375,8 +6373,7 @@ and
@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
@end quotation
-With two arguments, a parenthetical cross reference has this
-template:@refill
+With two arguments, a parenthetical cross reference has this template:
@example
@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
@@ -6386,30 +6383,45 @@ template:@refill
which produces
@example
-@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
+@dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{}
@end example
@noindent
and
-@need 1500
@quotation
@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
@end quotation
-@code{@@pxref} can be used with up to five arguments just like
-@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
+@code{@@pxref} can be used with up to five arguments, just like
+@code{@@xref} (@pxref{xref, , @code{@@xref}}).
-@quotation Caution
-Use @code{@@pxref} only as a parenthetical
-reference. Do not try to use @code{@@pxref} as a clause in a sentence.
-It will look bad in either the Info file, the printed output, or
-both.@refill
-@end quotation
+In past versions of Texinfo, it was not allowed to write punctuation
+after a @code{@@pxref}, so it could be used @emph{only} before a right
+parenthesis. This is no longer the case, so now it can be used (for
+example) at the end of a sentence, where a lowercase ``see'' works
+best. For instance:
+
+@example
+@dots{} For more information, @@pxref@{More@}.
+@end example
+
+@noindent
+which outputs (in Info):
+
+@example
+@dots{} For more information, *note More::.
+@end example
+
+@noindent
+This works fine. @code{@@pxref} should only be followed by a comma,
+period, or right parenthesis; in other cases, @command{makeinfo} has
+to insert a period to make the cross-reference work correctly in Info,
+and that period looks wrong.
-Parenthetical cross references look best at the ends of sentences.
-Although they technically work in the middle of a sentence, that
-location breaks up the flow of reading.
+As a matter of general style, @code{@@pxref} is best used at the ends
+of sentences. Although it technically works in the middle of a
+sentence, that location breaks up the flow of reading.
@node inforef
@@ -6505,7 +6517,7 @@ produces a link you can follow.
had the meaning of @code{@@indicateurl}
(@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it
was misused the vast majority of the time. So we've changed the
-definitions.
+meaning.
The second argument, if specified, is the text to display (the default
is the url itself); in Info and DVI output, but not in HTML output, the
@@ -6563,17 +6575,17 @@ holds programs and texts.
An example of the three-argument form:
@example
-The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{}
+The @@uref@{/man.cgi/1/ls,,ls@} program @dots{}
@end example
@noindent produces:
@display
-The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
+The @uref{/man.cgi/1/ls,,ls} program @dots{}
@end display
@noindent but with HTML:
@example
-The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
+The <a href="/man.cgi/1/ls">ls</a> program @dots{}
@end example
To merely indicate a url without creating a link people can follow, use
@@ -6698,7 +6710,7 @@ Indicate a metasyntactic variable.
@item @@env@{@var{environment-variable}@}
Indicate an environment variable.
-@xref{env,,@code{@@kenv}}.
+@xref{env,,@code{@@env}}.
@item @@file@{@var{file-name}@}
Indicate the name of a file.
@@ -6738,7 +6750,7 @@ Indicate an electronic mail address.
@ignore
@item @@ctrl@{@var{ctrl-char}@}
-Use for an @sc{ascii} control character.@refill
+Use for an ASCII control character.
@end ignore
@end table
@@ -6778,8 +6790,6 @@ should rearrange the sentence.
In the printed manual, @code{@@code} causes @TeX{} to typeset the
argument in a typewriter face. In the Info file, it causes the Info
formatting commands to use single quotation marks around the text.
-
-@need 700
For example,
@example
@@ -6787,7 +6797,7 @@ The function returns @@code@{nil@}.
@end example
@noindent
-produces this in the printed manual:
+produces this:
@quotation
The function returns @code{nil}.
@@ -6801,7 +6811,7 @@ The function returns `nil'.
@end example
@end iftex
-Here are some cases for which it is preferable not to use @code{@@code}:
+Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
@itemize @bullet
@item
@@ -6845,6 +6855,11 @@ The new commands allow you to express the markup more precisely, but
there is no real harm in using the older commands, and of course the
long-standing manuals do so.
+Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
+@samp{_} characters within @code{@@code} and related commands. This
+can be controlled with @code{@@allowcodebreaks}
+(@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}).
+
@node kbd
@subsection @code{@@kbd}@{@var{keyboard-characters}@}
@@ -6933,7 +6948,6 @@ input, write @kbd{@@key@{SPC@}} for it.)@refill
@node key
-@comment node-name, next, previous, up
@subsection @code{@@key}@{@var{key-name}@}
@findex key
@@ -6948,11 +6962,12 @@ You can use the @code{@@key} command within the argument of an
@code{@@kbd} command when the sequence of characters to be typed
includes one or more keys that are described by name.@refill
-@need 700
-For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
+For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you
+would type:
@example
@@kbd@{C-x @@key@{ESC@}@}
+@@kbd@{M-@@key@{TAB@}@}
@end example
Here is a list of the recommended names for keys:
@@ -6969,14 +6984,14 @@ Space
Return
@item LFD
Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
-it might be better to call this character @kbd{C-j}.
+it might be better to call this character @kbd{C-j})
@item TAB
Tab
@item BS
Backspace
@item ESC
Escape
-@item DEL
+@item DELETE
Delete
@item SHIFT
Shift
@@ -6996,12 +7011,9 @@ to the modifier key in isolation, use the @code{@@key} command. For
example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
@samp{@@key@{META@}} to produce @key{META}.
-@c I don't think this is a good explanation.
-@c I think it will puzzle readers more than it clarifies matters. -- rms.
-@c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
-@c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
-@c the beginning of the sentence. The @code{@@key@{META@}} key is often in
-@c the lower left of the keyboard.''@refill
+As a convention in GNU manuals, @code{@@key} should not be used in
+index entries.
+
@node samp
@subsection @code{@@samp}@{@var{text}@}
@@ -7319,7 +7331,7 @@ command since a reader can easily follow such a reference in Info.
@c subsection @code{@@ctrl}@{@var{ctrl-char}@}
@findex ctrl
-The @code{@@ctrl} command is seldom used. It describes an @sc{ascii}
+The @code{@@ctrl} command is seldom used. It describes an ASCII
control character by inserting the actual character into the Info
file.
@@ -7335,7 +7347,7 @@ to make it easier for a reader to understand.@refill
@code{@@ctrl} is an idea from the beginnings of Texinfo which may not
really fit in to the scheme of things. But there may be times when
you want to use the command. The pattern is
-@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character
+@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character
whose control-equivalent is wanted. For example, to specify
@samp{control-f}, you would enter@refill
@@ -7382,7 +7394,7 @@ not at the end of a sentence, and has no second argument, remember to
use the @code{@@.} command (@pxref{Not Ending a
Sentence}) to get the correct spacing. However, you do not have to
use @code{@@.} within the abbreviation itself; Texinfo automatically
-assumes periods within the abbreivation do not end a sentence.
+assumes periods within the abbreviation do not end a sentence.
@cindex <abbr> tag
In @TeX{} and in the Info output, the first argument is printed as-is;
@@ -7475,8 +7487,7 @@ acronyms.
@item
It's not essential to use these commands for all abbreviations. Text
-is perfectly readable without them, and for common abbreviations like
-`etc.@:', we consider them to be overkill.
+is perfectly readable without them.
@end itemize
@@ -7531,7 +7542,6 @@ suggestions to the @email{bug-texinfo@@gnu.org, same place}.
@node Emphasis
-@comment node-name, next, previous, up
@section Emphasizing Text
@cindex Emphasizing text
@@ -7649,7 +7659,34 @@ We recommend using regular mixed case wherever possible.
@subsection Fonts for Printing, Not Info
@cindex Fonts for printing, not Info
-Texinfo provides a number of font commands that specify font changes
+@findex fonttextsize
+@cindex Font size, reducing
+@cindex Reducing font size
+@cindex Smaller fonts
+Texinfo provides one command to change the size of the main body font
+in the @TeX{} output for a document: @code{@@fonttextsize}. It has no
+effect at all in other output. It takes a single argument on the
+remainder of the line, which must be either @samp{10} or @samp{11}.
+For example:
+
+@example
+@@fonttextsize 10
+@end example
+
+@cindex Printing cost, reducing
+The effect is to reduce the body font to a 10@dmn{pt} size (the
+default is 11@dmn{pt}). Fonts for other elements, such as sections
+and chapters, are reduced accordingly. This should only be used in
+conjunction with @code{@@smallbook} (@pxref{smallbook,,Printing
+``Small'' Books}) or similar, since 10@dmn{pt} fonts on standard paper
+(8.5x11 or A4) are too small. One reason to use this command is to
+save pages, and hence printing cost, for physical books.
+
+Texinfo does not at present have commands to switch the font family
+to use, or more general size-changing commands.
+
+@cindex Styles, font
+Texinfo also provides a number of font commands that specify font changes
in the printed manual and (where possible) in the HTML output, but
have no effect in the Info file. All the commands apply to an
argument that follows, surrounded by braces.
@@ -7681,7 +7718,7 @@ selects a @sansserif{sans serif} font;
@findex slanted @r{(slanted font)}
@cindex Slanted font
@cindex Oblique font
-rselects a @slanted{slanted} font;
+selects a @slanted{slanted} font;
@item @@t
@findex t @r{(typewriter font)}
@@ -7693,8 +7730,8 @@ selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
@end table
(The commands with longer names were invented much later than the
-others, when it did not seem desirable to use very short names for
-such an infrequently needed feature.)
+others, at which time it did not seem desirable to use very short
+names for such an infrequently needed feature.)
@cindex <lineannotation> Docbook tag
Only the @code{@@r} command has much use: in example-like
@@ -7721,8 +7758,8 @@ produces
@end lisp
In general, you should avoid using the other font commands. Some of
-them are only useful when documenting functionality with specific font
-effects, such as in \TeX\ and related packages.
+them are only useful when documenting functionality of specific font
+effects, such as in @TeX{} and related packages.
@node Quotations and Examples
@@ -7966,20 +8003,13 @@ normal roman font, you can use the @code{@@r} command (@pxref{Fonts}).
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.
+as regular Texinfo commands). This is especially useful for including automatically
+generated files in a Texinfo manual.
-@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
+In general, the output will be just the same as the input. No
+character substitutions are made, e.g., all spaces and blank lines are
+significant, including tabs. In the printed manual, the text is
+typeset in a fixed-width font, and not indented or filled.
Write a @code{@@verbatim} command at the beginning of a line by itself.
This line will disappear from the output. Mark the end of the verbatim
@@ -8000,7 +8030,7 @@ For example:
@end example
@noindent
-produces
+This produces:
@verbatim
{
@@ -8015,7 +8045,22 @@ produce no output, typically you should put a blank line before the
verbatim}. Blank lines between the beginning @code{@@verbatim} and
the ending @code{@@end verbatim} will appear in the output.
-It is not reliable to use @code{@@verbatim} inside other Texinfo constructs.
+@cindex Verbatim, small
+@cindex Small verbatim
+You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in
+an @code{@@smallformat} environment, as shown here:
+
+@c more cheating ...
+@smallexample
+@exdent @t{@@smallformat}
+@exdent @t{@@verbatim}
+@exdent @t{... still verbatim, but in a smaller font ...}
+@exdent @t{@@end verbatim}
+@exdent @t{@@end smallformat}
+@end smallexample
+
+Finally, a word of warning: it is not reliable to use
+@code{@@verbatim} inside other Texinfo constructs.
@node verbatiminclude
@@ -8040,16 +8085,19 @@ the @code{@@verbatiminclude} within @code{@@example}
The name of the file is taken literally, with a single exception:
@code{@@value@{@var{var}@}} references are expanded. This makes it
-possible to reliably include files in other directories in a
-distribution, for instance:
+possible to include files in other directories within a distribution,
+for instance:
@example
-@@include @@value@{top_srcdir@}/NEWS
+@@verbatiminclude @@value@{top_srcdir@}/NEWS
@end example
@noindent (You still have to get @code{top_srcdir} defined in the
first place.)
+For a method on printing the file contents in a smaller font size, see
+the end of the previous section on @code{@@verbatim}.
+
@node lisp
@section @code{@@lisp}: Marking a Lisp Example
@@ -8195,7 +8243,7 @@ This line follows an @@@@example command.
@@exdent This line is exdented.
This line follows the exdented line.
The @@@@end example comes on the next line.
-@@end group
+@@end example
@end group
@end example
@@ -8989,7 +9037,9 @@ input lines in your source file as necessary.
@cindex <thead> HTML tag
You can also use @code{@@headitem} instead of @code{@@item} to produce
a @dfn{heading row}. The @TeX{} output for such a row is in bold, and
-the HTML, XML, and Docbook output uses the @code{<thead>} tag.
+the HTML, XML, and Docbook output uses the @code{<thead>} tag. In
+Info, the heading row is followed by a separator line made of dashes
+(@samp{-} characters).
Here is a complete example of a multi-column table (the text is from
@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
@@ -9079,7 +9129,7 @@ an @code{@@group} (@pxref{group,,@code{@@group}}).
@node float
-@subsection @code{@@float} [@var{type}][,@var{label}]: Floating material
+@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material
@findex float
@cindex Float environment
@@ -9116,7 +9166,7 @@ cross-referencing will simply use a bare number.
@item label
Specifies a cross-reference label for this float. If given, this
float is automatically given a number, and will appear in any
-@code{@@listofloats} output (@pxref{listoffloats}). Cross-references
+@code{@@listoffloats} output (@pxref{listoffloats}). Cross-references
to @var{label} are allowed.
@cindex Floats, making unnumbered
@@ -9196,7 +9246,7 @@ environments such as @code{@@example}, or other complex constructs.
@node listoffloats
-@subsection @code{@@listoffloats}: Tables of contents for floats
+@subsection @code{@@listoffloats}: Tables of Contents for Floats
@findex listoffloats
@cindex List of floats
@cindex Floats, list of
@@ -9259,7 +9309,7 @@ since they are most often part of a displayed figure or example.
@node Image Syntax
@subsection Image Syntax
-Here is the basic synopsis of the @code{@@image} command:
+Here is the synopsis of the @code{@@image} command:
@example
@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@}
@@ -9272,11 +9322,18 @@ extension, because the different processors support different formats:
@itemize @bullet
@item
+@pindex eps image format
@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
format).
@item
@pindex pdftex@r{, and images}
-PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
+@pindex png image format
+@pindex jpeg image format
+@pindex pdf image inclusions
+pdf@TeX{} reads @file{@var{filename}.png}, @file{@var{filename}.jpg},
+@file{@var{filename}.jpeg}, or @file{@var{filename}.pdf} (in that
+order). It also tries uppercase versions of the extensions. The PDF
+format cannot support EPS images, so they must be converted first.
@item
@code{makeinfo} includes @file{@var{filename}.txt} verbatim for
Info output (more or less as if it was an @code{@@example}).
@@ -9297,31 +9354,34 @@ will cause @code{makeinfo} to look for @file{foo.xpm} before any others.
The @var{width} and @var{height} arguments are described in the next
section.
-For @TeX{} output, if an image is the first thing in a paragraph, for
-example if you want two images side-by-side, you must precede it with
-@code{@@noindent} (@pxref{noindent,,@code{@@noindent}}). Otherwise it
-will be displayed on a line by itself. If you want it centered,
-use @code{@@center} (@pxref{titlefont center sp,,@code{@@titlefont
-@@center @@sp}}).
+For @TeX{} output, if an image is the only thing in a paragraph it
+will ordinarily be displayed on a line by itself, respecting the
+current environment indentation, but without the normal paragraph
+indentation. If you want it centered, use @code{@@center}
+(@pxref{titlefont center sp,,@code{@@titlefont @@center @@sp}}).
@cindex Alt attribute for images
@cindex Images, alternate text for
-When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
+@findex - (in image alt string)
+For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for
inline images to the optional @var{alttext} (fourth) argument to
@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses
-the full file name of the image being displayed. If you want an empty
-@code{alt} string, use @code{@@-}. The @var{alttext} is taken as
-Texinfo text, so special characters such as @samp{"} and @samp{<} and
-@samp{&} are escaped in the HTML and XML output.
+the full file name of the image being displayed. The @var{alttext} is
+taken as Texinfo text, so special characters such as @samp{"} and
+@samp{<} and @samp{&} are escaped in the HTML and XML output; also,
+you can get an empty @code{alt} string with @code{@@-} (a command
+that produces no output; @pxref{- and hyphenation}).
+
+For Info output, the @code{alt} string is also processed as Texinfo
+text and output. In this case, @samp{\} is escaped as @samp{\\} and
+@samp{"} as @samp{\"}; no other escapes are done.
-@cindex GIF images, unsupported due to patents
@cindex PNG image format
-@cindex JPG image format
+@cindex JPEG image format
If you do not supply the optional @var{extension} (fifth) argument,
@code{makeinfo} first tries @file{@var{filename}.png}; if that does
not exist, it tries @file{@var{filename}.jpg}. If that does not exist
-either, it complains. (We cannot support GIF format directly due to
-software patents.)
+either, it complains.
In Info output, @code{makeinfo} writes a reference to the binary image
file (trying @var{filename} suffixed with @file{@var{extension}},
@@ -9332,6 +9392,7 @@ Emacs Info browser, running under X) can do so, whereas Info readers
which can only use text (such as the standalone Info reader) can
display the textual version.
+@cindex @samp{^@@^H} for images in Info
The implementation of this is to put the following construct into the
Info output:
@@ -9966,7 +10027,8 @@ These are:
@item Accents.
@item Dots and bullets.
@item The @TeX{} logo and the copyright symbol.
-@item The pounds currency symbol.
+@item The euro and pounds currency symbols.
+@item The degrees symbol.
@item The minus sign.
@item Mathematical expressions.
@item Glyphs for evaluation, macros, errors, etc.
@@ -9977,16 +10039,21 @@ These are:
@menu
* Atsign Braces Comma:: Inserting @@ and @{@} and ,.
+* Inserting Quote Characters:: Inserting left and right quotes, in code.
* Inserting Space:: How to insert the right amount of space
within a sentence.
* Inserting Accents:: How to insert accents and special characters.
+* Inserting Quotation Marks:: How to insert quotation marks.
* Dots Bullets:: How to insert dots and bullets.
* TeX and copyright:: How to insert the @TeX{} logo
and the copyright symbol.
* euro:: How to insert the Euro currency symbol.
* pounds:: How to insert the pounds currency symbol.
+* textdegree:: How to insert the degrees symbol.
* minus:: How to insert a minus sign.
+* geq leq:: How to insert greater/less-than-or-equal signs.
* math:: How to format a mathematical expression.
+* Click Sequences:: Inserting GUI usage sequences.
* Glyphs:: How to indicate results of evaluation,
expansion of macros, errors, etc.
@end menu
@@ -10036,7 +10103,7 @@ output.
output.
Do not put braces after either an @code{@@@{} or an @code{@@@}}
-command.ppp
+command.
@node Inserting a Comma
@@ -10053,9 +10120,9 @@ context: some commands, such as @code{@@acronym} (@pxref{acronym}) and
macros (@pxref{Defining Macros}), can take more than one argument. In
these cases, the comma character is used to separate arguments.
-Since a comma chacter would confuse Texinfo's parsing for these
-commands, you must use the command @samp{@comma{}} instead if you want
-to have an actual comma in the output. Here are some examples:
+Since a comma character would confuse Texinfo's parsing for these
+commands, you must use the command @samp{@@comma@{@}} instead if you want
+to pass an actual comma. Here are some examples:
@example
@@acronym@{ABC, A Bizarre @@comma@{@}@}
@@ -10063,10 +10130,60 @@ to have an actual comma in the output. Here are some examples:
@@mymac@{One argument@@comma@{@} containing a comma@}
@end example
-Although @comma{} can be used anywhere, there is no need for it
+Although @comma{} can be used nearly anywhere, there is no need for it
anywhere except in this unusual case.
+@node Inserting Quote Characters
+@section Inserting Quote Characters
+
+@cindex Inserting quote characters
+@cindex Quote characters, inserting
+
+As explained in the early section on general Texinfo input conventions
+(@pxref{Conventions}), Texinfo source files use the ASCII character
+@code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'}
+(39 decimal) to produce a right quote ('). Doubling these input
+characters (@code{``} and @code{''}) produces double quotes (`` and
+''). These are the conventions used by @TeX{}.
+
+This works all right for text. However, in examples of computer code,
+readers are especially likely to cut and paste the text
+verbatim---and, unfortunately, some document viewers will mangle these
+characters. (The free PDF reader @command{xpdf} works fine, but other
+PDF readers, both free and nonfree, have problems.)
+
+If this is a concern for your document, Texinfo provides two special
+settings via @code{@@set}:
+
+@table @code
+@item @@set txicodequoteundirected
+causes the output for the @code{'} character to be the undirected
+single quote, like this:
+@set txicodequoteundirected
+@code{'}.
+@clear txicodequoteundirected
+
+@item @@set txicodequotebacktick
+Cause the output for the @code{`} character to be the standalone grave
+accent, like this:
+@set txicodequotebacktick
+@code{`}.
+@clear txicodequotebacktick
+
+@end table
+
+@code{xyza`'bc}
+
+If you want these settings for only part of the document,
+@code{@@clear} will restore the normal behavior, as in
+@code{@@clear@tie{}txicodequoteundirected}.
+
+These settings affect @code{@@code}, @code{@@example}, and
+@code{@@verbatim}; they do not affect @code{@@samp}. (@xref{Useful
+Highlighting}.)
+
+
@node Inserting Space
@section Inserting Space
@@ -10079,6 +10196,7 @@ kinds within and after sentences.
* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
* Ending a Sentence:: Sometimes it does.
* Multiple Spaces:: Inserting multiple spaces.
+* frenchspacing:: Specifying end-of-sentence spacing.
* dmn:: How to format a dimension.
@end menu
@@ -10108,8 +10226,8 @@ which are not at the ends of sentences.
For example,
@example
-The s.o.p.@@: has three parts @dots{}
-The s.o.p. has three parts @dots{}
+foo vs.@@: bar
+foo vs. bar
@end example
@noindent
@@ -10118,19 +10236,16 @@ produces
@end ifnottex
@iftex
produces the following. If you look carefully at this printed output,
-you will see a little extraneous space after @samp{s.o.p.} in the second
+you will see a little extraneous space after @samp{vs.}@: in the second
line.
@end iftex
@quotation
-The s.o.p.@: has three parts @dots{}@*
-The s.o.p. has three parts @dots{}
+foo vs.@: bar @*
+foo vs. bar
@end quotation
@noindent
-(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
-Procedure''.)
-
@code{@@:} has no effect on the Info and HTML output. In Docbook and
XML, the previous punctuation character (.?!:) is output as an entity
instead of as the normal character: @samp{&period; &quest; &excl;
@@ -10233,6 +10348,74 @@ Do not follow any of these commands with braces.
To produce a non-breakable space, see @ref{tie, @code{@@tie}}.
+@node frenchspacing
+@subsection @code{@@frenchspacing} @var{val}: Control sentence spacing
+@findex frenchspacing
+@cindex French spacing
+@cindex Sentences, spacing after
+@cindex Space, after sentences
+
+In American typography, it is traditional and correct to put extra
+space at the end of a sentence, after a semi-colon, and so on. This
+is the default in Texinfo. In French typography (and many others),
+this extra space is wrong; all spaces are uniform.
+
+Therefore Texinfo provides the @code{@@frenchspacing} command to
+control the spacing after punctuation. It reads the rest of the line
+as its argument, which must be the single word @samp{on} or @samp{off}
+(always these words, regardless of the language) of the document.
+Here is an example:
+
+@example
+@@frenchspacing on
+This is text. Two sentences. Three sentences. French spacing.
+
+@@frenchspacing off
+This is text. Two sentences. Three sentences. Non-French spacing.
+@end example
+
+@noindent produces (there will be no difference in Info):
+
+@frenchspacing on
+This is text. Two sentences. Three sentences. French spacing.
+
+@frenchspacing off
+This is text. Two sentences. Three sentences. Non-French spacing.
+
+@code{@@frenchspacing} mainly affects the printed output, including
+the output after @code{@@.}, @code{@@!}, and @code{@@?} (@pxref{Ending
+a Sentence}).
+
+In Info, usually space characters in the input are written unaltered
+to the output, and @code{@@frenchspacing} does not change this. It
+does change the one case where @command{makeinfo} outputs a space on
+its own: when a sentence ends at a newline in the source. Here's an
+example:
+
+@example
+Some sentence.
+Next sentence.
+@end example
+
+@noindent produces in Info output, with @code{@@frenchspacing off}
+(the default), two spaces between the sentences:
+
+@example
+Some sentence. Next sentence.
+@end example
+
+@noindent With @code{@@frenchspacing on}, @command{makeinfo} outputs
+only a single space:
+
+@example
+Some sentence. Next sentence.
+@end example
+
+@code{@@frenchspacing} has no effect on the HTML or Docbook output;
+for XML, it outputs a transliteration of itself (@pxref{Output
+Formats}).
+
+
@node dmn
@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
@cindex Thin space between number, dimension
@@ -10285,9 +10468,11 @@ 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 documentencoding
To get the true accented characters output in Info, and not just the
-ASCII transliterations, you can use the @option{--enable-encoding}
-option to @command{makeinfo} (@pxref{makeinfo options}).
+ASCII transliterations, it is necessary to specify
+@code{@@documentencoding} with an encoding which supports the required
+characters (@pxref{documentencoding,,@code{@@documentencoding}}).
@findex " @r{(umlaut accent)}
@cindex Umlaut accent
@@ -10321,8 +10506,8 @@ option to @command{makeinfo} (@pxref{makeinfo options}).
@cindex Hacek accent
@cindex Check accent
@cindex Caron accent
-@multitable {@@questiondown@{@}} {Output} {hacek/check/caron accent}
-@item Command @tab Output @tab What
+@multitable {@t{@@questiondown@{@}}} {Output} {hacek/check/caron accent}
+@headitem Command @tab Output @tab What
@item @t{@@"o} @tab @"o @tab umlaut accent
@item @t{@@'o} @tab @'o @tab acute accent
@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
@@ -10384,7 +10569,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 {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S}
@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
@item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle
@@ -10399,6 +10584,150 @@ commonly used in languages other than English.
@end multitable
+@node Inserting Quotation Marks
+@section Inserting Quotation Marks
+@cindex Inserting quotation marks
+@cindex Quotation marks, inserting
+
+@cindex Quotation characters (`'), in source
+Use doubled single-quote characters to begin and end quotations:
+@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to
+left- and right-hand doubled quotation marks,
+@c this comes out as "like this" in Info, which is just confusing.
+@iftex
+``like this'',
+@end iftex
+and Info converts doubled single-quote characters to ASCII
+double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
+
+You may occasionally need to produce two consecutive single quotes;
+for example, in documenting a computer language such as Maxima where
+@t{'@w{}'} is a valid command. You can do this with the input
+@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into
+the double-quote characters.
+
+@cindex Unicode quotation characters
+@cindex Grave accent, vs. left quote
+The left quote character (@t{`}, ASCII code 96) used in Texinfo is a
+grave accent in ANSI and ISO character set standards. We use it as a
+quote character because that is how @TeX{} is set up, by default.
+
+Texinfo supports several other quotation marks used in languages other
+than English. Below is a table with the commands Texinfo provides for
+inserting quotation marks.
+
+@findex documentencoding
+@cindex UTF-8
+@cindex ISO 8859-15
+@cindex Latin 9
+@cindex ISO 8859-1
+@cindex Latin 1
+In order to get the symbols for the quotation marks in encoded Info
+output, it is necessary to specify @code{@@documentencoding UTF-8}.
+(@xref{documentencoding,,@code{@@documentencoding}}.) Double
+guillemets are also present in ISO 8859-1 (aka Latin@tie{}1) and ISO
+8859-15 (aka Latin@tie{}9).
+
+@cindex European Computer Modern fonts
+@cindex EC fonts
+The standard @TeX{} fonts support the usual quotation marks used in
+English (the ones produced with single and doubled ASCII
+single-quotes). For the other quotation marks, @TeX{} uses European
+Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
+These fonts are freely available, of course; you can download them
+from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other
+places.
+
+@cindex CM-Super fonts
+The free EC fonts are bitmap fonts created with Metafont. Especially
+for on-line viewing, Type@tie{}1 (vector) versions of the fonts are
+preferable; these are available in the CM-Super font package
+(@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}).
+
+Both distributions include installation instructions.
+
+@cindex Single quotation marks
+@cindex Double quotation marks
+@cindex Left quotation marks
+@cindex Right quotation marks
+@findex quotedblleft
+@cindex ``
+@findex quoteleft
+@cindex `
+@findex quotedblright
+@cindex ''
+@findex quoteright
+@cindex '
+@cindex Double low-9 quotation mark
+@cindex Single low-9 quotation mark
+@findex quotedblbase
+@cindex @quotedblbase{} (double low-9 quotation mark)
+@findex quotesinglbase
+@cindex @quotesinglbase{} (single low-9 quotation mark)
+@cindex Angle quotation marks
+@cindex Guillemets
+@cindex Guillemots
+@cindex French quotation marks
+@cindex Quotation marks, French
+@cindex German quotation marks
+@cindex Quotation marks, German
+@cindex Double guillemets
+@cindex Single guillemets
+@cindex Double angle quotation marks
+@cindex Single angle quotation marks
+@cindex Left-pointing angle quotation marks
+@cindex Right-pointing angle quotation marks
+@cindex Double left-pointing angle quotation mark
+@cindex Double right-pointing angle quotation mark
+@cindex Single left-pointing angle quotation mark
+@cindex Single right-pointing angle quotation mark
+@findex guillemetleft
+@findex guillemotleft
+@cindex @guillemetleft{}
+@findex guillemetright
+@findex guillemotright
+@cindex @guillemetright{}
+@findex guilsinglleft
+@cindex @guilsinglleft{}
+@findex guilsinglright
+@cindex @guilsinglright{}
+@multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation mark (U+00BB)}
+@headitem Command @tab Glyph @tab Unicode name (point)
+@item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C)
+@item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D)
+@item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018)
+@item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019)
+@item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E)
+@item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A)
+@item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB)
+@item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB)
+@item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039)
+@item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A)
+@end multitable
+
+For the double angle quotation marks, Adobe and @LaTeX{} glyph names
+are also supported: @code{@@guillemotleft} and
+@code{@@guillemotright}. These names are actually incorrect; a
+``guillemot'' is a bird species (a type of auk).
+
+Traditions for quotation mark usage vary to a great extent between
+languages (@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}).
+Texinfo does not provide commands for typesetting quotation marks
+according to the numerous traditions. Therefore, you have to choose
+the commands appropriate for the language of your manual. Sometimes
+aliases (@pxref{alias,,@code{@@alias}}) can simplify the usage and
+make the source code more readable. For example, in German,
+@code{@@quotedblbase} is used for the left double quote, and the right
+double quote is actually @code{@@quotedblleft}, which is
+counter-intuitive. Thus, in this case the following aliases would be
+convenient:
+
+@example
+@@alias lgqq = quotedblbase
+@@alias rgqq = quotedblleft
+@end example
+
+
@node Dots Bullets
@section Inserting Ellipsis and Bullets
@cindex Dots, inserting
@@ -10445,7 +10774,7 @@ end-of-sentence ellipsis, which has different spacing afterwards,
Here is an ellipsis: @dots{}
Here are three periods in a row: ...
-In printed output, the three periods in a row are closer together than
+In printed output, the three periods in a row are much closer together than
the dots in the ellipsis.
@end iftex
@@ -10484,6 +10813,9 @@ between the name of the command and the braces.
@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{})
@findex TeX
@findex LaTeX
+@cindex Logos, @TeX{}
+@cindex @TeX{} logo
+@cindex @LaTeX{} logo
Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
manual, this is a special logo that is different from three ordinary
@@ -10503,6 +10835,7 @@ that they use both uppercase and lowercase letters.
@node copyright symbol
@subsection @code{@@copyright@{@}} (@copyright{})
@findex copyright
+@cindex Copyright symbol
Use the @code{@@copyright@{@}} command to generate the copyright
symbol, `@copyright{}'. Where possible, this is a @samp{c}
@@ -10512,6 +10845,7 @@ inside a circle; in Info, this is @samp{(C)}.
@node registered symbol
@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{})
@findex registeredsymbol
+@cindex Registered symbol
Use the @code{@@registeredsymbol@{@}} command to generate the
registered symbol, `@registeredsymbol{}'. Where possible, this is an
@@ -10519,15 +10853,16 @@ registered symbol, `@registeredsymbol{}'. Where possible, this is an
@node euro
-@section @code{@@euro}@{@} (@euro{}): Euro currency symbol
+@section @code{@@euro}@{@} (@euro{}): Euro Currency Symbol
@findex euro
+@cindex Euro symbol
Use the @code{@@euro@{@}} command to generate `@euro{}'. Where
possible, this is the symbol for the Euro currency, invented as part
-of the European economic unification relatively recently. In plain
-Info, it is the word @samp{Euro }. (The space is included in the text
-transliteration since typically there would be no space after the
-symbol, so it would be inappropriate to have a space in the source document.)
+of the European economic unification. In plain Info, it is the word
+@samp{Euro }. A trailing space is included in the text
+transliteration since typically no space is desired after the symbol,
+so it would be inappropriate to have a space in the source document.
Texinfo cannot magically synthesize support for the Euro symbol where
the underlying system (fonts, software, whatever) does not support
@@ -10542,19 +10877,41 @@ it is necessary to specify @code{@@documentencoding ISO-8859-15}.
is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more
widely-used and supported ISO 8859-1 (Latin@tie{}1).
+@pindex feymr10
+@cindex Euro font
+The Euro symbol does not exist in the standard @TeX{} fonts (which
+were designed before the Euro was legislated into existence).
+Therefore, @TeX{} uses an additional font, named @code{feymr10} (along
+with other variables). It is freely available, of course; you can
+download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym},
+among other places. The distribution includes installation
+instructions.
+
@node pounds
@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
@findex pounds
+@cindex Pounds symbol
Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where
possible, this is the symbol for the currency pounds sterling. In
Info, it is a @samp{#}.
+@node textdegree
+@section @code{@@textdegree}@{@} (@textdegree{}): Degrees Symbol
+@findex textdegree
+@cindex Degree symbol
+
+Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'.
+Where possible, this is the normal symbol for degrees. In plain text
+and Info output, it is an @samp{o}.
+
+
@node minus
@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
@findex minus
+@cindex Minus sign
@cindex Em dash, compared to minus sign
@cindex Hyphen, compared to minus
@@ -10584,6 +10941,17 @@ an itemized list, you do not need to type the braces
(@pxref{itemize, , @code{@@itemize}}).
+@node geq leq
+@section @code{@@geq@{@}} (@geq{}) and @code{@@leq@{@}} (@leq{}): Inserting relations
+@findex geq
+@findex leq
+
+Use the @code{@@geq@{@}} and @code{@@geq@{@}} commands to generate
+greater-than-or-equal and less-than-equal-signs, `@geq{}' and
+`@leq{}'. In plain text and Info output, these are the ASCII
+sequences @samp{>=} and @samp{<=}.
+
+
@node math
@section @code{@@math}: Inserting Mathematical Expressions
@findex math
@@ -10614,15 +10982,31 @@ command. Write the mathematical expression between braces, like this:
(a + b)(a + b) = a^2 + 2ab + b^2
@end example
-Thus, the @code{@@math} command has no effect on the Info and HTML
-output; @command{makeinfo} just reproduces the input, it does not try
-to interpret the mathematics in any way.
+The @code{@@math} command has no special effect on the Info and HTML
+output. @command{makeinfo} expands any @code{@@}-commands as usual,
+but it does not try to produce good mathematical formatting in any
+way.
+
+However, as far as the @TeX{} output is concerned, plain @TeX{}
+mathematical commands are allowed in @code{@@math}, starting with
+@samp{\}, and the plain @TeX{} math characters like @samp{^} and
+@samp{_} are also recognized. In essence, @code{@@math} drops you
+into plain @TeX{} math mode.
+
+This allows you to conveniently write superscripts and subscripts (as
+in the above example), and also to use all the plain @TeX{} math
+control sequences for symbols, functions, and so on, and thus get
+proper formatting in the @TeX{} output, at least.
+
+It's best to use @samp{\} instead of @samp{@@} for any such
+mathematical commands; otherwise, @command{makeinfo} will complain.
+On the other hand, input with matching (but unescaped) braces, such as
+@samp{k_@{75@}}, is allowed inside @code{@@math}, although
+@command{makeinfo} would complain about the bare braces in regular
+input.
+
+Here's an example:
-@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
@@ -10643,17 +11027,67 @@ As in:
@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
+but you'd get the literal @samp{\\} in Info). @code{@@\} is not
defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
literal @samp{\}.
-
@cindex Displayed equations
@cindex Equations, displayed
For displayed equations, you must at present use @TeX{} directly
(@pxref{Raw Formatter Commands}).
+@node Click Sequences
+@section Click Sequences
+@cindex Click sequences
+@cindex Sequence of clicks
+@cindex GUI click sequence
+
+@findex clicksequence
+When documenting graphical interfaces, it is necessary to describe
+sequences such as `Click on @samp{File}, then choose @samp{Open}, then
+@dots{}'. Texinfo offers commands @code{@@clicksequence} and
+@code{click} to represent this, typically used like this:
+
+@example
+@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
+@end example
+
+@noindent
+which produces:
+
+@display
+@dots{} @clicksequence{File @click{} Open} @dots{}
+@end display
+
+@findex click
+@findex arrow
+The @code{@@click} command produces a simple right arrow (@samp{->} in
+Info) by default; this glyph is also available independently via the
+command @code{@@arrow@{@}}.
+
+@findex clickstyle
+You can change the glyph produced by @code{@@click} with the command
+@code{@@clickstyle}, which takes a command name as its single argument
+on the rest of the line, much like @code{@@itemize} and friends
+(@pxref{itemize,,@code{@@itemize}}). The command should produce a
+glyph, and the usual empty braces @samp{@{@}} are omitted. Here's an
+example:
+
+@example
+@@clickstyle @@result
+@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
+@end example
+
+@noindent
+now produces:
+
+@display
+@clickstyle @result
+@dots{} @clicksequence{File @click{} Open} @dots{}
+@end display
+
+
@node Glyphs
@section Glyphs for Examples
@cindex Glyphs
@@ -10666,7 +11100,7 @@ evaluation or an expansion using @samp{@result{}} or
@samp{@expansion{}}. Likewise, there are commands to insert glyphs
to indicate
printed output, error messages, equivalence of expressions, and the
-location of point.@refill
+location of point.
The glyph-insertion commands do not need to be used within an example, but
most often they are. Every glyph-insertion command is followed by a pair of
@@ -10762,7 +11196,7 @@ You can indicate the result of the expansion with the
@iftex
The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
-in the printed output. and as @samp{==>} in other formats.
+in the printed output and as @samp{==>} in other formats.
@end iftex
@ifnottex
The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
@@ -11029,6 +11463,7 @@ commands.
* Break Commands:: Summary of break-related commands.
* Line Breaks:: Forcing line breaks.
* - and hyphenation:: Helping @TeX{} with hyphenation points.
+* allowcodebreaks:: Controlling line breaks within @@code text.
* w:: Preventing unwanted line breaks in text.
* tie:: Inserting an unbreakable but varying space.
* sp:: Inserting blank lines.
@@ -11161,10 +11596,51 @@ put a @samp{-} at each hyphenation point. For example:
@@hyphenation@{man-u-script man-u-scripts@}
@end example
@noindent @TeX{} only uses the specified hyphenation points when the
-words match exactly, so give all necessary variants.
+words match exactly, so give all necessary variants, such as plurals.
@end table
-Info output is not hyphenated, so these commands have no effect there.
+Info, HTML, and other non-@TeX{} output is not hyphenated, so none of
+these commands have any effect there.
+
+
+@node allowcodebreaks
+@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code}
+
+@findex allowcodebreaks
+@cindex Breaks, within @code{@@code}
+@cindex -, breakpoint within @code{@@code}
+@cindex Hyphen, breakpoint within @code{@@code}
+@cindex Dash, breakpoint within @code{@@code}
+@cindex _, breakpoint within @code{@@code}
+@cindex Underscore, breakpoint within @code{@@code}
+
+Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
+@samp{_} characters within @code{@@code} and related commands
+(@pxref{code,,@code{@@code}}), more or less as if they were ``empty''
+hyphenation points.
+
+This is necessary as many manuals, especially for Lisp-family
+languages, must document very long identifiers. On the other hand,
+other manuals don't have this problems, and you may not wish to allow
+a line break at the underscore in, for example, @code{SIZE_MAX}, or
+even worse, after any of the four underscores in @code{__typeof__}.
+
+So Texinfo provides this command:
+
+@example
+@@allowcodebreaks false
+@end example
+
+@noindent to prevent @TeX{} from breaking at @samp{-} or @samp{_} within
+@code{@@code}. You can go back to allowing such breaks with
+@code{@@allowcodebreaks true}. Write these commands on lines by
+themselves.
+
+These commands can be given anywhere in the document. For example,
+you may have just one problematic paragraph where you need to turn off
+the breaks, but want them in general, or vice versa.
+
+This command has no effect in Info, HTML, and other non-@TeX{} output.
@node w
@@ -11192,7 +11668,7 @@ the width of a normal interword space:
The space from @code{@@w@{@w{ }@}}, as well as being non-breakable,
also will not stretch or shrink. Sometimes that is what you want, for
-instance if you're doing indenting manual. However, usually you want
+instance if you're doing manual indenting. However, usually you want
a normal interword space that does stretch and shrink (in the printed
output); see the @code{@@tie} command in the next section.
@@ -11490,7 +11966,7 @@ produces
@quotation
@deffn Command forward-word count
-This function moves point forward @var{count} words
+This command moves point forward @var{count} words
(or backward if @var{count} is negative). @dots{}
@end deffn
@end quotation
@@ -11511,7 +11987,9 @@ enclose it in braces. For example:
Otherwise, the second word will be mistaken for the name of the
entity. As a general rule, when any of the arguments in the heading
line @emph{except} the last one are more than one word, you need to
-enclose them in braces.
+enclose them in braces. This may also be necessary if the text
+contains commands, for example, @samp{@{declaraci@@'on@}} if you are
+writing in Spanish.
Some of the definition commands are more general than others. The
@code{@@deffn} command, for example, is the general definition command
@@ -12782,7 +13260,7 @@ sections for more details:
@table @code
@item @@set @var{flag} [@var{value}]
-Set the variable @var{flag}, to the optional @var{value} if specifed.
+Set the variable @var{flag}, to the optional @var{value} if specified.
@item @@clear @var{flag}
Undefine the variable @var{flag}, whether or not it was previously defined.
@@ -12807,7 +13285,9 @@ is ignored. If @var{flag} is clear, text through the following
@node set value
@subsection @code{@@set} and @code{@@value}
+@findex set
@findex value
+@findex clear
You use the @code{@@set} command to specify a value for a flag, which
is later expanded by the @code{@@value} command.
@@ -13118,222 +13598,75 @@ supports, see @ref{Inserting Accents}.
@node documentlanguage
-@section @code{@@documentlanguage @var{cc}}: Set the Document Language
+@section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language
@findex documentlanguage
@cindex Language, declaring
+@cindex Locale, declaring
@cindex Document language, declaring
The @code{@@documentlanguage} command declares the current document
-language. Write it on a line by itself, with a two-letter ISO-639
-language code following (list is included below). If you have a
-multilingual document, the intent is to be able to use this command
-multiple times, to declare each language change. If the command is not
-used at all, the default is @code{en} for English.
+locale. Write it on a line by itself, near the beginning of the
+file, but after @code{@@setfilename}
+(@pxref{setfilename,,@code{@@setfilename}}).
+
+Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following
+the command name, optionally followed by a two-letter ISO@tie{}3166
+two-letter country code (@var{cc}). If you have a multilingual
+document, the intent is to be able to use this command multiple times,
+to declare each language change. If the command is not used at all,
+the default is @code{en_US} for US English.
+
+As with GNU Gettext (@pxref{Top,,,gettext, Gettext}), if the country
+code is omitted, the main dialect is assumed where possible. For
+example, @code{de} is equivalent to @code{de_DE} (German as spoken in
+Germany).
+
+@cindex Document strings, translation of
+For Info and other online output, this command changes the translation
+of various @dfn{document strings} such as ``see'' in cross-references
+(@pxref{Cross References}), ``Function' in defuns (@pxref{Definition
+Commands}), and so on. Some strings, such as ``Node:'', ``Next:'',
+``Menu:'', etc., are keywords in Info output, so are not translated
+there; they are translated in other output formats.
@cindex @file{txi-@var{cc}.tex}
-At present, this command is ignored in Info and HTML output. For
-@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
-exists). Such a file appropriately redefines the various English words
-used in @TeX{} output, such as `Chapter', `See', and so on.
+For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to
+be read (if it exists). If @code{@@setdocumentlanguage} argument
+contains the optional @samp{_@var{cc}} suffix, this is tried first.
+For example, with @code{@@setdocumentlanguage de_DE}, @TeX{} first
+looks for @file{txi-de_DE.tex}, then @file{txi-de.tex}.
+
+Such a @file{txi-*} file is intended to redefine the various English
+words used in @TeX{} output, such as `Chapter', `See', and so on. We
+are aware that individual words like these cannot always be translated
+in isolation, and that a very different strategy would be required for
+ideographic (among other) scripts. Help in improving Texinfo's
+language support is welcome.
@cindex Hyphenation patterns, language-dependent
-It would be good if this command also changed @TeX{}'s ideas of the
-current hyphenation patterns (via the @TeX{} primitive
-@code{\language}), but this is unfortunately not currently implemented.
+It would also be desirable for this command to also change @TeX{}'s
+ideas of the current hyphenation patterns (via the @TeX{} primitive
+@code{\language}), but this is unfortunately not currently
+implemented.
-@cindex ISO 639 codes
-@cindex Language codes
-Hereare the valid language codes, from ISO-639.
+In September 2006, the W3C Internationalization Activity released a
+new recommendation for specifying tags identifying language:
+@example
+@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}
+@end example
+When Gettext supports this new scheme, Texinfo will too.
-@multitable @columnfractions .07 .26 .07 .26 .07 .26
-@item
-@code{aa} @tab Afar @tab
-@code{ab} @tab Abkhazian @tab
-@code{af} @tab Afrikaans
-@item
-@code{am} @tab Amharic @tab
-@code{ar} @tab Arabic @tab
-@code{as} @tab Assamese
-@item
-@code{ay} @tab Aymara @tab
-@code{az} @tab Azerbaijani @tab
-@code{ba} @tab Bashkir
-@item
-@code{be} @tab Byelorussian @tab
-@code{bg} @tab Bulgarian @tab
-@code{bh} @tab Bihari
-@item
-@code{bi} @tab Bislama @tab
-@code{bn} @tab Bengali; Bangla @tab
-@code{bo} @tab Tibetan
-@item
-@code{br} @tab Breton @tab
-@code{ca} @tab Catalan @tab
-@code{co} @tab Corsican
-@item
-@code{cs} @tab Czech @tab
-@code{cy} @tab Welsh @tab
-@code{da} @tab Danish
-@item
-@code{de} @tab German @tab
-@code{dz} @tab Bhutani @tab
-@code{el} @tab Greek
-@item
-@code{en} @tab English @tab
-@code{eo} @tab Esperanto @tab
-@code{es} @tab Spanish
-@item
-@code{et} @tab Estonian @tab
-@code{eu} @tab Basque @tab
-@code{fa} @tab Persian
-@item
-@code{fi} @tab Finnish @tab
-@code{fj} @tab Fiji @tab
-@code{fo} @tab Faroese
-@item
-@code{fr} @tab French @tab
-@code{fy} @tab Frisian @tab
-@code{ga} @tab Irish
-@item
-@code{gd} @tab Scots Gaelic @tab
-@code{gl} @tab Galician @tab
-@code{gn} @tab Guarani
-@item
-@code{gu} @tab Gujarati @tab
-@code{ha} @tab Hausa @tab
-@code{he} @tab Hebrew
-@item
-@code{hi} @tab Hindi @tab
-@code{hr} @tab Croatian @tab
-@code{hu} @tab Hungarian
-@item
-@code{hy} @tab Armenian @tab
-@code{ia} @tab Interlingua @tab
-@code{id} @tab Indonesian
-@item
-@code{ie} @tab Interlingue @tab
-@code{ik} @tab Inupiak @tab
-@code{is} @tab Icelandic
-@item
-@code{it} @tab Italian @tab
-@code{iu} @tab Inuktitut @tab
-@code{ja} @tab Japanese
-@item
-@code{jw} @tab Javanese @tab
-@code{ka} @tab Georgian @tab
-@code{kk} @tab Kazakh
-@item
-@code{kl} @tab Greenlandic @tab
-@code{km} @tab Cambodian @tab
-@code{kn} @tab Kannada
-@item
-@code{ks} @tab Kashmiri @tab
-@code{ko} @tab Korean @tab
-@code{ku} @tab Kurdish
-@item
-@code{ky} @tab Kirghiz @tab
-@code{la} @tab Latin @tab
-@code{ln} @tab Lingala
-@item
-@code{lt} @tab Lithuanian @tab
-@code{lo} @tab Laothian @tab
-@code{lv} @tab Latvian, Lettish
-@item
-@code{mg} @tab Malagasy @tab
-@code{mi} @tab Maori @tab
-@code{mk} @tab Macedonian
-@item
-@code{ml} @tab Malayalam @tab
-@code{mn} @tab Mongolian @tab
-@code{mo} @tab Moldavian
-@item
-@code{mr} @tab Marathi @tab
-@code{ms} @tab Malay @tab
-@code{mt} @tab Maltese
-@item
-@code{my} @tab Burmese @tab
-@code{na} @tab Nauru @tab
-@code{ne} @tab Nepali
-@item
-@code{nl} @tab Dutch @tab
-@code{no} @tab Norwegian @tab
-@code{oc} @tab Occitan
-@item
-@code{om} @tab (Afan) Oromo @tab
-@code{or} @tab Oriya @tab
-@code{pa} @tab Punjabi
-@item
-@code{pl} @tab Polish @tab
-@code{ps} @tab Pashto, Pushto @tab
-@code{pt} @tab Portuguese
-@item
-@code{qu} @tab Quechua @tab
-@code{rm} @tab Rhaeto-Romance @tab
-@code{rn} @tab Kirundi
-@item
-@code{ro} @tab Romanian @tab
-@code{ru} @tab Russian @tab
-@code{rw} @tab Kinyarwanda
-@item
-@code{sa} @tab Sanskrit @tab
-@code{sd} @tab Sindhi @tab
-@code{sg} @tab Sangro
-@item
-@code{sh} @tab Serbo-Croatian @tab
-@code{si} @tab Sinhalese @tab
-@code{sk} @tab Slovak
-@item
-@code{sl} @tab Slovenian @tab
-@code{sm} @tab Samoan @tab
-@code{sn} @tab Shona
-@item
-@code{so} @tab Somali @tab
-@code{sq} @tab Albanian @tab
-@code{sr} @tab Serbian
-@item
-@code{ss} @tab Siswati @tab
-@code{st} @tab Sesotho @tab
-@code{su} @tab Sundanese
-@item
-@code{sv} @tab Swedish @tab
-@code{sw} @tab Swahili @tab
-@code{ta} @tab Tamil
-@item
-@code{te} @tab Telugu @tab
-@code{tg} @tab Tajik @tab
-@code{th} @tab Thai
-@item
-@code{ti} @tab Tigrinya @tab
-@code{tk} @tab Turkmen @tab
-@code{tl} @tab Tagalog
-@item
-@code{tn} @tab Setswana @tab
-@code{to} @tab Tonga @tab
-@code{tr} @tab Turkish
-@item
-@code{ts} @tab Tsonga @tab
-@code{tt} @tab Tatar @tab
-@code{tw} @tab Twi
-@item
-@code{ug} @tab Uighur @tab
-@code{uk} @tab Ukrainian @tab
-@code{ur} @tab Urdu
-@item
-@code{uz} @tab Uzbek @tab
-@code{vi} @tab Vietnamese @tab
-@code{vo} @tab Volapuk
-@item
-@code{wo} @tab Wolof @tab
-@code{xh} @tab Xhosa @tab
-@code{yi} @tab Yiddish
-@item
-@code{yo} @tab Yoruba @tab
-@code{za} @tab Zhuang @tab
-@code{zh} @tab Chinese
-@item
-@code{zu} @tab Zulu
-@end multitable
+@cindex ISO 639-2 language codes
+@cindex ISO 3166 country codes
+@cindex Language codes
+@cindex Country codes
+Since the lists of language codes and country codes are quite dynamic,
+we don't attempt to list them here. The valid language codes are on
+the official home page for ISO@tie{}639,
+@url{http://www.loc.gov/standards/iso639-2/}. The country codes and
+the official web site for ISO@tie{}3166 can be found via
+@url{http://en.wikipedia.org/wiki/ISO_3166}.
@node documentencoding
@@ -13347,7 +13680,8 @@ Hereare the valid language codes, from ISO-639.
The @code{@@documentencoding} command declares the input document
encoding. Write it on a line by itself, with a valid encoding
-specification following.
+specification following, near the beginning of the file but after
+@code{@@setfilename} (@pxref{setfilename,,@code{@@setfilename}}).
At present, Texinfo supports only these encodings:
@@ -13355,6 +13689,11 @@ At present, Texinfo supports only these encodings:
@item US-ASCII
This has no particular effect, but it's included for completeness.
+@itemx UTF-8
+The vast global character encoding, expressed in 8-bit bytes.
+The Texinfo processors have no deep knowledge of Unicode; for the most
+part, they just pass along the input they are given to the output.
+
@itemx ISO-8859-1
@itemx ISO-8859-15
@item ISO-8859-2
@@ -13362,10 +13701,17 @@ These specify the standard encodings for Western European (the first
two) and Eastern European languages (the third), respectively. ISO
8859-15 replaces some little-used characters from 8859-1 (e.g.,
precomposed fractions) with more commonly needed ones, such as the
-Euro symbol.
+Euro symbol (@euro{}).
A full description of the encodings is beyond our scope here;
one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
+
+@item koi8-r
+This is the commonly used encoding for the Russian language.
+
+@item koi8-u
+This is the commonly used encoding for the Ukrainian language.
+
@end table
Specifying an encoding @var{enc} has the following effects:
@@ -13373,7 +13719,7 @@ Specifying an encoding @var{enc} has the following effects:
@opindex --enable-encoding
@cindex Local Variables: section, for encoding
@cindex Info output, and encoding
-In Info output, if the option @option{--enable-encoding} is given
+In Info output, unless the option @option{--disable-encoding} is given
to @command{makeinfo}, a so-called `Local Variables' section
(@pxref{File Variables,,,emacs,The GNU Emacs Manual}) is output
including @var{enc}. This allows Info readers to set the encoding
@@ -13385,6 +13731,11 @@ coding: @var{enc}
End:
@end example
+Also, in Info and plain text output (barring
+@option{--disable-encoding}), accent constructs and special
+characters, such as @code{@@'e}, are output as the actual 8-bit
+character in the given encoding.
+
@cindex HTML output, and encodings
@cindex @code{http-equiv}, and charset specification
@cindex @code{<meta>} HTML tag, and charset specification
@@ -13398,7 +13749,19 @@ used to display the page, if supported by the system.
charset=@var{enc}">
@end example
-In all other cases, it is recognized but ignored.
+In split HTML output, if @option{--transliterate-file-names} is
+given (@pxref{HTML Xref 8-bit Character Expansion}), the names of HTML
+files are formed by transliteration of the corresponding node names,
+using the specified encoding.
+
+In XML and Docbook output, the given document encoding is written in
+the output file as usual with those formats.
+
+In @TeX{} output, the characters which are supported in the standard
+Computer Modern fonts are output accordingly. (For example, this
+means using constructed accents rather than precomposed glyphs.)
+Using a missing character generates a warning message, as does
+specifying an unimplemented encoding.
@node Defining New Texinfo Commands
@@ -13578,16 +13941,78 @@ No arguments here.
@end display
@cindex Comma, in macro arguments
+Passing strings containing commas as macro arguments requires special
+care, since they should be properly @dfn{quoted} to prevent
+@command{makeinfo} from confusing them with argument separators. To
+manually quote a comma, prepend it with a backslash character, like
+this: @code{\,}. Alternatively, use the @code{@@comma} command
+(@pxref{Inserting a Comma}). However, to facilitate use of macros,
+@command{makeinfo} implements a set of rules called @dfn{automatic
+quoting}:
+
+@enumerate 1
+@item If a macro takes only one argument, all commas in its invocation
+are quoted by default. For example:
+
+@example
+@group
+@@macro FIXME@{text@}
+@@strong@{FIXME: \text\@}
+@@end macro
+
+@@FIXME@{A nice feature, though it can be dangerous.@}
+@end group
+@end example
+
+@noindent
+will produce the following output
+
+@example
+@strong{FIXME: A nice feature, though it can be dangerous.}
+@end example
+
+And indeed, it can. Namely, @command{makeinfo}
+does not control number of arguments passed to one-argument
+macros, so be careful when you invoke them.
+
+@item If a macro invocation includes another command (including a
+recursive invocation of itself), any commas in the nested command
+invocation(s) are quoted by default. For example, in
+
+@example
+@@say@{@@strong@{Yes, I do@}, person one@}
+@end example
+
+the comma after @samp{Yes} is implicitly quoted. Here's another
+example, with a recursive macro:
+
+@example
+@group
+@@rmacro cat@{a,b@}
+\a\\b\
+@@end rmacro
+
+@@cat@{@@cat@{foo, bar@}, baz@}
+@end group
+@end example
+
+@noindent
+will produce the string @samp{foobarbaz}.
+
+@item Otherwise, a comma should be explicitly quoted, as above, to be
+treated as a part of an argument.
+@end enumerate
+
@cindex Braces, in macro arguments
-To insert a comma, brace, or backslash in an argument, prepend a
-backslash, as in
+Other characters that need to be quoted in macro arguments are
+curly braces and backslash. For example
@example
@@@var{macname} @{\\\@{\@}\,@}
@end example
@noindent
-which will pass the (almost certainly error-producing) argument
+will pass the (almost certainly error-producing) argument
@samp{\@{@},} to @var{macname}. However, commas in parameters, even
if escaped by a backslash, might cause trouble in @TeX{}.
@@ -13827,7 +14252,7 @@ follow the command name with two commas in a row; otherwise, the Info
formatting commands will naturally misinterpret the end delimiter string
you intended as the start delimiter string.
-If you do a @code{@@definfoenclose} on the name of a pre-defined macro
+If you do a @code{@@definfoenclose} on the name of a predefined macro
(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
enclosure definition will override the built-in definition.
@@ -14092,31 +14517,72 @@ MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
texi2dvi foo.texi} instead of relying on the operating system to invoke
the shell on the @samp{texi2dvi} script.
-Perhaps the most useful option to @code{texi2dvi} is
-@samp{--command=@var{cmd}}. This inserts @var{cmd} on a line by itself
-after the @code{@@setfilename} in a temporary copy of the input file
-before running @TeX{}. With this, you can specify different printing
+@opindex --command @r{(@command{texi2dvi})}
+One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}.
+This inserts @var{cmd} on a line by itself after the
+@code{@@setfilename} in a temporary copy of the input file before
+running @TeX{}. With this, you can specify different printing
formats, such as @code{@@smallbook} (@pxref{smallbook}),
@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
(@pxref{pagesizes}), without actually changing the document source.
(You can also do this on a site-wide basis with @file{texinfo.cnf};
@pxref{Preparing for TeX,,Preparing for @TeX{}}).
+@opindex --pdf @r{(@command{texi2dvi})}
With the @option{--pdf} option, @command{texi2dvi} produces PDF output
instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
instead of @command{tex}. Alternatively, the command
-@command{texi2pdf} is an abbreviation for running @samp{texi2dvi --pdf}.
+@command{texi2pdf} is an abbreviation for running @samp{texi2dvi
+--pdf}. The command @command{pdftexi2dvi} is also supported as a
+convenience to AUC-@TeX{} users, since the latter merely prepends
+@samp{pdf} to DVI producing tools to have PDF producing tools.
@cindex @LaTeX{}, processing with @command{texi2dvi}
@command{texi2dvi} can also be used to process @LaTeX{} files; simply
run @samp{texi2dvi filename.ext}.
+@opindex --language @r{(@command{texi2dvi})}
+Normally @command{texi2dvi} is able to guess the input file language
+by its contents and file name suffix. If, however, it fails to do so
+you can specify the input language using
+@option{--language=@var{lang}} command line option, where @var{lang}
+is either @samp{latex} or @samp{texinfo}.
+
@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if
they are available; these extended versions of @TeX{} are not
required, and the DVI (or PDF) output is identical, but they simplify
the @TeX{} programming in some cases, and provide additional tracing
information when debugging @file{texinfo.tex}.
+@opindex --translate-file @r{(@command{texi2dvi})}
+Several options are provided for handling documents, written in
+character sets other than ASCII. The
+@option{--translate-file=@var{file}} option instructs
+@command{texi2dv} to translate input into internal @TeX{} character
+set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX
+files, TCX files: Character translations, web2c, Web2c: A @TeX{}
+implementation}).
+
+@opindex --recode @r{(@command{texi2dvi})}
+The options @option{--recode} and @option{--recode-from=@var{enc}}
+allow conversion of an input document before running @TeX{}. The
+@option{--recode} option recodes the document from encoding specified
+by @samp{@@documentencoding} command
+(@pxref{documentencoding,,@code{documentencoding}}) to plain 7-bit
+@samp{texinfo} encoding.
+
+@opindex --recode-from @r{(@command{texi2dvi})}
+The option @option{--recode-from=@var{enc}} recodes the document from
+@var{enc} encoding to the encoding specified by
+@samp{@@documentencoding}. This is useful, for example, if the
+document is written in @samp{UTF-8} encoding and an equivalent 8-bit
+encoding is supported by @command{makeinfo}.
+
+Both @option{--recode} and @option{--recode-from=@var{enc}} use
+@command{recode} utility to perform the conversion. If
+@command{recode} fails to process the file, @command{texi2dvi} prints
+a warning and continues using unmodified input file.
+
For a list of other options, run @samp{texi2dvi --help}.
@@ -14440,9 +14906,18 @@ 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.
+@cindex European Computer Modern fonts, installing
+@cindex EC fonts, installing
+@cindex CM-Super fonts, installing
+To be able to use quotation marks other than those used in English
+you'll need to install European Computer Modern fonts and optionally
+CM-Super fonts, unless they are already installed (@pxref{Inserting
+Quotation Marks}).
+
+@pindex feymr10@r{, installing}
+@cindex Euro font, installing
+If you intend to use the @code{@@euro} command, you should install the
+Euro font, if it is not already installed. @xref{euro}.
@pindex texinfo.cnf @r{installation}
@cindex Customizing of @TeX{} for Texinfo
@@ -14524,6 +14999,7 @@ redumping.) You can do this by running this command, assuming
initex texinfo @@dump
@end example
+@noindent
(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
wherever your @code{.fmt} files are found; typically, this will be in the
subdirectory @file{web2c} of your @TeX{} installation.
@@ -14782,12 +15258,12 @@ magnifications. Be prepared to experiment.
@pindex pdftex
The simplest way to generate PDF output from Texinfo source is to run
-the convenience script @command{texi2pdf}; this simply executes the
-@command{texi2dvi} script with the @option{--pdf} option
-(@pxref{Format with texi2dvi}). If for some reason you want to
-process by hand, simply run the @command{pdftex} program instead of
-plain @command{tex}. That is, run @samp{pdftex foo.texi} instead of
-@samp{tex foo.texi}.
+the convenience script @command{texi2pdf} (or @command{pdftexi2dvi});
+this simply executes the @command{texi2dvi} script with the
+@option{--pdf} option (@pxref{Format with texi2dvi}). If for some
+reason you want to process the document by hand, simply run the
+@command{pdftex} program instead of plain @command{tex}. That is, run
+@samp{pdftex foo.texi} instead of @samp{tex foo.texi}.
@dfn{PDF} stands for `Portable Document Format'. It was invented by
Adobe Systems some years ago for document interchange, based on their
@@ -14844,8 +15320,8 @@ Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
@display
@group
Free Software Foundation, Inc.
-59 Temple Place Suite 330
-Boston, MA @ @ 02111-1307
+51 Franklin St, Fifth Floor
+Boston, MA @ @ 02110-1301
USA
Telephone: @w{+1-617-542-5942}
Fax: (including Japan) @w{+1-617-542-2652}
@@ -14993,15 +15469,34 @@ style sheets specifications, in the @samp{<style>} block of the HTML
output. @xref{HTML CSS}. If @var{file} is @samp{-}, read standard
input.
+@item --css-ref=@var{url}
+@opindex --css-ref
+In HTML mode, add a @samp{<link>} tag to the HTML output which
+references a cascading style sheet at @var{url}. This allows using
+standalone style sheets.
+
+@item --disable-encoding
+@itemx --enable-encoding
+@opindex --disable-encoding
+@opindex --enable-encoding
+By default, or with @option{--enable-encoding}, output accented and
+special characters in Info or plain text output based on
+@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit
+ASCII transliterations are output.
+@xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting
+Accents}.
+
@item --docbook
@opindex --docbook
Generate Docbook output rather than Info.
-@item --enable-encoding
-@opindex --enable-encoding
-Output accented and special characters in Info or plain text output
-based on @samp{@@documentencoding}.
-@xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting Accents}.
+@item --document-language=@var{lang}
+@opindex --document-language
+@vindex LANG
+Use @var{lang} to translate Texinfo keywords which end up in the
+output document. The default is the locale specified by the
+@code{@@documentlanguage} command if there is one
+(@pxref{documentlanguage}).
@item --error-limit=@var{limit}
@itemx -e @var{limit}
@@ -15212,19 +15707,15 @@ Delete any existing indentation.
Indent each paragraph by @var{num} spaces.
@end table
-@item --reference-limit=@var{limit}
-@itemx -r @var{limit}
-@opindex --reference-limit=@var{limit}
-@opindex -r @var{limit}
-Set the value of the number of references to a node that
-@code{makeinfo} will make without reporting a warning. If a node has more
-than this number of references in it, @code{makeinfo} will make the
-references but also report a warning. The default is 1000.
-
@item --split-size=@var{num}
@opindex --split-size=@var{num}
Keep Info files to at most @var{num} characters; default is 300,000.
+@item --transliterate-file-names
+@opindex --transliterate-file-names
+Enable transliteration of 8-bit characters in node names for the
+purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}.
+
@item -U @var{var}
Cause @var{var} to be undefined. This is equivalent to
@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
@@ -15893,6 +16384,16 @@ the beginning of the Texinfo input, before the first @code{@@node}
command. If you use them later on in the input, @code{install-info}
will not notice them.
+@code{install-info} will automatically reformat the description of the
+menu entries it is adding. As a matter of convention, the description
+of the main entry (above, @samp{The GNU documentation format}) should
+start at column 32, starting at zero (as in
+@code{what-cursor-position} in Emacs). This will make it align with
+most others. Description for individual utilities best start in
+column 48, where possible. For more information about formatting see
+the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
+@ref{Invoking install-info}.
+
If you use @code{@@dircategory} more than once in the Texinfo source,
each usage specifies the `current' category; any subsequent
@code{@@direntry} commands will add to that category.
@@ -15932,7 +16433,8 @@ traditional @command{man} system.
@code{install-info} inserts menu entries from an Info file into the
top-level @file{dir} file in the Info system (see the previous sections
-for an explanation of how the @file{dir} file works). It's most often
+for an explanation of how the @file{dir} file works). @code{install-info}
+also removes menu entries from the @file{dir} file. It's most often
run as part of software installation, or when constructing a @file{dir} file
for all manuals on a system. Synopsis:
@@ -15961,23 +16463,56 @@ open @file{@var{dir-file}.gz}.
Options:
@table @code
+@item --add-once
+Specifies that the entry or entries will only be put into a single section.
+
+@item --align=@var{column}
+@opindex --align=@var{column}
+Specifies the column that the second and subsequent lines of menu entry's
+description will be formatted to begin at. The default for this option is
+@samp{35}. It is used in conjunction with the @samp{--max-width} option.
+@var{column} starts counting at 1.
+
+@item --append-new-sections
+Instead of alphabetizing new sections, place them at the end of the DIR file.
+
+@item --calign=@var{column}
+@opindex --calign=@var{column}
+Specifies the column that the first line of menu entry's description will
+be formatted to begin at. The default for this option is @samp{33}. It is
+used in conjunction with the @samp{--max-width} option.
+When the name of the menu entry exceeds this column, entry's description
+will start on the following line.
+@var{column} starts counting at 1.
+
+@item --debug
+@opindex --debug
+Report what is being done.
+
@item --delete
@opindex --delete
Delete the entries in @var{info-file} from @var{dir-file}. The file
name in the entry in @var{dir-file} must be @var{info-file} (except for
an optional @samp{.info} in either one). Don't insert any new entries.
+Any empty sections that result from the removal are also removed.
+
+@item --description=@var{text}
+@opindex --description=@var{text}
+Specify the explanatory portion of the menu entry. If you don't specify
+a description (either via @samp{--entry}, @samp{--item} or this option),
+the description is taken from the Info file itself.
@item --dir-file=@var{name}
-@itemx -d @var{name}
@opindex --dir-file=@var{name}
-@opindex -d @var{name}
Specify file name of the Info directory file. This is equivalent to
using the @var{dir-file} argument.
+@item --dry-run
+@opindex --dry-run
+Same as @samp{--test}.
+
@item --entry=@var{text}
-@itemx -e @var{text}
@opindex --entry=@var{text}
-@opindex -e @var{text}
Insert @var{text} as an Info directory entry; @var{text} should have the
form of an Info menu item line plus zero or more extra lines starting
with whitespace. If you specify more than one entry, they are all
@@ -15985,54 +16520,119 @@ added. If you don't specify any entries, they are determined from
information in the Info file itself.
@item --help
-@itemx -h
@opindex --help
-@opindex -h
-Display a usage message listing basic usage and all available options,
+Display a usage message with basic usage and all available options,
then exit successfully.
@item --info-file=@var{file}
-@itemx -i @var{file}
@opindex --info-file=@var{file}
-@opindex -i @var{file}
-Specify Info file to install in the directory.
-Equivalent to using the @var{info-file} argument.
+Specify Info file to install in the directory. This is
+equivalent to using the @var{info-file} argument.
@item --info-dir=@var{dir}
-@itemx -D @var{dir}
@opindex --info-dir=@var{dir}
-@opindex -D @var{dir}
Specify the directory where the directory file @file{dir} resides.
Equivalent to @samp{--dir-file=@var{dir}/dir}.
+@item --infodir=@var{dir}
+@opindex --infodir=@var{dir}
+Same as @samp{--info-dir}.
+
@item --item=@var{text}
@opindex --item=@var{text}
Same as @samp{--entry=@var{text}}. An Info directory entry is actually
a menu item.
+@item --keep-old
+@opindex --keep-old
+Do not replace pre-existing menu entries. When @samp{--remove} is specified,
+this option means that empty sections are not removed.
+
+@item --max-width=@var{column}
+@opindex --max-width=@var{column}
+Specifies the column that the menu entry's description will be word-wrapped
+at. @var{column} starts counting at 1.
+
+@item --maxwidth=@var{column}
+@opindex --maxwidth=@var{column}
+Same as @samp{--max-width}.
+
+@item --menuentry=@var{text}
+@opindex --menuentry=@var{text}
+Same as @samp{--name}.
+
+@item --name=@var{text}
+@opindex --name=@var{text}
+Specify the name portion of the menu entry. If the @var{text} does not start
+with an asterisk @samp{*}, it is presumed to be the text after the @samp{*}
+and before the parentheses that specify the Info file. Otherwise @var{text}
+is taken verbatim, and is meant to include the text up to and including the
+first dot @samp{.}. If you don't specify the name (either via @samp{--entry},
+@samp{--item} or this option), it is taken from the Info file itself. If
+the Info does not contain the name, the basename of the Info file is used.
+
+@item --no-indent
+@opindex --no-indent
+Suppress formatting of new entries into the @file{dir} file.
+
@item --quiet
@opindex --quiet
-Suppress warnings.
+@itemx --silent
+@opindex --silent
+Suppress warnings, etc., for silent operation.
@item --remove
-@itemx -r
@opindex --remove
-@opindex -r
Same as @samp{--delete}.
+@item --remove-exactly
+@opindex --remove-exactly
+Also like @samp{--delete}, but only entries if the Info file name
+matches exactly; @code{.info} and/or @code{.gz} suffixes are
+@emph{not} ignored.
+
@item --section=@var{sec}
-@itemx -s @var{sec}
@opindex --section=@var{sec}
-@opindex -s @var{sec}
Put this file's entries in section @var{sec} of the directory. If you
specify more than one section, all the entries are added in each of the
sections. If you don't specify any sections, they are determined from
-information in the Info file itself.
+information in the Info file itself. If the Info file doesn't specify
+a section, the menu entries are put into the Miscellaneous section.
+
+@item --section @var{regex} @var{sec}
+@opindex --section @var{regex} @var{sec}
+Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
+
+@code{install-info} tries to detect when this alternate syntax is used,
+but does not always guess correctly! Here is the heuristic that
+@code{install-info} uses:
+@enumerate
+@item
+If the second argument to @code{--section} starts with a hyphen, the original syntax is presumed.
+@item
+If the second argument to @code{--section} is a file that can be opened, the original syntax is presumed
+@item
+Otherwise the alternate syntax is used.
+@end enumerate
+
+When heuristic fails because your section title starts with a hyphen, or it
+happens to be a filename that can be opened, the syntax should be changed
+to @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
+
+
+@item --regex=@var{regex}
+@opindex --regex=@var{regex}
+Put this file's entries into any section that matches @var{regex}. If
+more than one section matches, all of the entries are added in each of the
+sections. Specify @var{regex} using basic regular expression syntax, more
+or less as used with @command{grep}, for example.
+
+@item --test
+@opindex --test
+Suppress updating of the directory file.
@item --version
-@itemx -V
@opindex --version
-@opindex -V
@cindex Version number, for install-info
Display version information and exit successfully.
@@ -16165,11 +16765,18 @@ and to use the `inherited' font (generally a regular roman typeface)
for both @code{@@smalldisplay} and @code{@@display}. By default, the
HTML @samp{<pre>} command uses a monospaced font.
-You can influence the CSS in the HTML output with the
-@option{--css-include=@var{file}} option to @command{makeinfo}. This
-includes the contents @var{file} in the HTML output, as you might
-expect. However, the details are somewhat tricky, as described in the
-following, to provide maximum flexibility.
+You can influence the CSS in the HTML output with two
+@command{makeinfo} options: @option{--css-include=@var{file}} and
+@option{--css-ref=@var{url}}.
+
+The option @option{--css-ref=@var{url}} adds to each output HTML file
+a @samp{<link>} tag referencing a CSS at the given @var{url}. This
+allows using external style sheets.
+
+The option @option{--css-include=@var{file}} includes the contents
+@var{file} in the HTML output, as you might expect. However, the
+details are somewhat tricky, as described in the following, to provide
+maximum flexibility.
@cindex @@import specifications, in CSS files
The CSS file may begin with so-called @samp{@@import} directives,
@@ -16290,9 +16897,10 @@ HTML links, the @samp{http://localhost/} could be omitted entirely.
The @var{dir} and @var{file} parts are more complicated, and depend on
the relative split/mono nature of both the manual being processed and
the manual that the cross-reference refers to. The underlying idea is
-that there is one directory for Texinfo manuals in HTML, and each
-manual is either available as a monolithic file @file{manual.html}, or a
-split subdirectory @file{manual/*.html}. Here are the cases:
+that there is one directory for Texinfo manuals in HTML, and a given
+@var{manual} is either available as a monolithic file
+@file{@var{manual}.html}, or a split subdirectory
+@file{@var{manual}/*.html}. Here are the cases:
@itemize @bullet
@item
@@ -16501,9 +17109,9 @@ according to the other rules.
@item @code{@@minus} @tab U+2212
@item @code{@@ordf} @tab U+00AA
@item @code{@@ordm} @tab U+00BA
-@item @code{@@point} @tab U+2217
+@item @code{@@point} @tab U+2605
@item @code{@@pounds} @tab U+00A3
-@item @code{@@print} @tab @samp{-|}
+@item @code{@@print} @tab U+22A3
@item @code{@@questiondown} @tab U+00BF
@item @code{@@registeredsymbol} @tab U+00AE
@item @code{@@result} @tab U+21D2
@@ -16531,6 +17139,7 @@ Any other command is an error, and the result is unspecified.
@cindex HTML cross-reference 8-bit character expansion
@cindex 8-bit characters, in HTML cross-references
@cindex Expansion of 8-bit characters in HTML cross-references
+@cindex Transliteration of 8-bit characters in HTML cross-references
Usually, characters other than plain 7-bit ASCII are transformed into
the corresponding Unicode code point(s) in Normalization Form C, which
@@ -16561,6 +17170,19 @@ point is 0x10ffff, this is sufficient. (We felt it was better to
define this extra escape than to always use six hex digits, since the
first two would nearly always be zeros.)
+This method works fine if the node name consists mostly of ASCII
+characters and contains only few 8-bit ones. If the document is
+written in a language whose script is not based on the Latin alphabet
+(such as, e.g. Ukrainian), it will create file names consisting
+entirely of @samp{_@var{xxxx}} notations, which is inconvenient.
+
+To handle such cases, @command{makeinfo} offers
+@option{--transliterate-file-names} command line option. This option
+enables @dfn{transliteration} of node names into ASCII characters for
+the purposes of file name creation and referencing. The
+transliteration is based on phonetic principle, which makes the
+produced file names easily readable.
+
For the definition of Unicode Normalization Form C, see Unicode report
UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many related
documents and implementations are available elsewhere on the web.
@@ -16697,11 +17319,9 @@ end-of-sentence capital letter). @xref{Ending a Sentence}.
Produces no output, but allows a line break. @xref{Line Breaks}.
@item @@:
-Indicate to @TeX{} that an immediately preceding period, question
-mark, exclamation mark, or colon does not end a sentence. Prevent
-@TeX{} from inserting extra whitespace as it does at the end of a
-sentence. The command has no effect on the Info file output.
-@xref{Not Ending a Sentence}.
+Tell @TeX{} to refrain from inserting extra whitespace after an
+immediately preceding period, question mark, exclamation mark, or
+colon, as @TeX{} normally would. @xref{Not Ending a Sentence}.
@item @@=
Generate a macron (bar) accent over the next character, as in @=o.
@@ -16797,10 +17417,14 @@ title appears in the table of contents of a printed manual. In Info,
the title is underlined with periods. @xref{subsubsection,, The
`subsub' Commands}.@refill
+@item @@arrow@{@}
+Produce a normal right arrow glyph: @samp{@arrow{}}. Used by default
+for @code{@@click}. @xref{Click Sequences}.
+
@item @@asis
Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
print the table's first column without highlighting (``as is'').
-@xref{Two-column Tables, , Making a Two-column Table}.@refill
+@xref{Two-column Tables}.
@item @@author @var{author}
Typeset @var{author} flushleft and underline it. @xref{title
@@ -16864,6 +17488,18 @@ Defining the Entries of an Index}.@refill
Highlight the name of a book or other reference that lacks a
companion Info file. @xref{cite, , @code{@@cite}}.@refill
+@item @@click@{@}
+Represent a single ``click'' in a GUI. Used within
+@code{@@clicksequence}. @xref{Click Sequences}.
+
+@item @@clicksequence@{@var{action} @@click@{@} @var{action}@}
+Represent a sequence of clicks in a GUI. @xref{Click Sequences}.
+
+@item @@clickstyle @@@var{cmd}
+Execute @@@var{cmd} for each @code{@@click}; the default is
+@code{@@arrow}. The usual following empty braces on @@@var{cmd} are
+omitted. @xref{Click Sequences}.
+
@item @@clear @var{flag}
Unset @var{flag}, preventing the Texinfo formatting commands from
formatting text between subsequent pairs of @code{@@ifset @var{flag}}
@@ -16900,8 +17536,8 @@ Generate the copyright symbol @copyright{}. @xref{copyright symbol,,
@ignore
@item @@ctrl@{@var{ctrl-char}@}
-Describe an @sc{ascii} control character. Insert actual control character
-into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
+Describe an ASCII control character. Insert actual control character
+into Info file. @xref{ctrl, , @code{@@ctrl}}.
@end ignore
@item @@defcodeindex @var{index-name}
@@ -17214,6 +17850,9 @@ index of functions. Pair with @code{@@end ftable}. The same as
@code{@@table}, except for indexing. @xref{ftable vtable, ,
@code{@@ftable} and @code{@@vtable}}.@refill
+@item @@geq@{@}
+Generate a greater-than-or-equal sign, `@geq{}'. @xref{geq leq}.
+
@item @@group
Hold text together that must appear on one printed page. Pair with
@code{@@end group}. Not relevant to Info. @xref{group, ,
@@ -17267,7 +17906,7 @@ resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
@itemx @@ifnotxml
Begin a stretch of text that will be ignored in one output format but
not the others. The text appears in the formats not specified:
-@code{@@ifnothtml} text is omitted from html output, etc. The exception
+@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 the corresponding @code{@@end
ifnot@var{format}}. @xref{Conditionals}.
@@ -17360,6 +17999,9 @@ respectively: @L{}, @l{}.
@item @@LaTeX@{@}
Insert the logo @LaTeX{}. @xref{tex, , @TeX{} and @LaTeX{}}.
+@item @@leq@{@}
+Generate a less-than-or-equal sign, `@leq{}'. @xref{geq leq}.
+
@item @@lisp
Begin an example of Lisp code. Indent text, do not fill, and select
fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
@@ -17393,7 +18035,7 @@ Mark the beginning of a menu of nodes in Info. No effect in a printed
manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
@item @@minus@{@}
-Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill
+Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.
@item @@multitable @var{column-width-spec}
Begin a multi-column table. Pair with @code{@@end multitable}.
@@ -17402,15 +18044,15 @@ Begin a multi-column table. Pair with @code{@@end multitable}.
@item @@need @var{n}
Start a new page in a printed manual if fewer than @var{n} mils
(thousandths of an inch) remain on the current page. @xref{need, ,
-@code{@@need}}.@refill
+@code{@@need}}.
@item @@node @var{name}, @var{next}, @var{previous}, @var{up}
Define the beginning of a new node in Info, and serve as a locator for
-references for @TeX{}. @xref{node, , @code{@@node}}.@refill
+references for @TeX{}. @xref{node, , @code{@@node}}.
@item @@noindent
Prevent text from being indented as if it were a new paragraph.
-@xref{noindent, , @code{@@noindent}}.@refill
+@xref{noindent, , @code{@@noindent}}.
@item @@novalidate
Suppress validation of node references, omit creation of auxiliary files
@@ -17692,14 +18334,16 @@ Formatter Commands}.
@item @@thischapter
@itemx @@thischaptername
+@itemx @@thischapternum
@itemx @@thisfile
@itemx @@thispage
@itemx @@thistitle
-Only allowed in a heading or footing. Stands for the number and name of
-the current chapter (in the format `Chapter 1: Title'), the chapter name
+Only allowed in a heading or footing. Stands for, respectively, the
+number and name of the current chapter (in the format `Chapter 1:
+Title'), the current chapter name only, the current chapter number
only, the filename, the current page number, and the title of the
document, respectively. @xref{Custom Headings, , How to Make Your Own
-Headings}.@refill
+Headings}.
@item @@tie@{@}
Generate a normal interword space at which a line break is not allowed.
@@ -17858,14 +18502,12 @@ has four types of @@-command:@refill
@table @asis
@item 1. Non-alphabetic commands.
-These commands consist of an @@ followed by a punctuation mark or other
-character that is not part of the alphabet. Non-alphabetic commands are
-almost always part of the text within a paragraph, and never take any
-argument. The two characters (@@ and the other one) are complete in
-themselves; none is followed by braces. The non-alphabetic commands
-are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
-@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
-@code{@@@}}.@refill
+These commands consist of an @@ followed by a punctuation mark or
+other character that is not part of the alphabet. Non-alphabetic
+commands are almost always part of the text within a paragraph. The
+non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}},
+@code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and
+many more.
@item 2. Alphabetic commands that do not require arguments.
These commands start with @@ followed by a word followed by left- and
@@ -18362,7 +19004,7 @@ it for a printed manual.
@@copying
This is a short example of a complete Texinfo file.
-Copyright (C) 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 2005 Free Software Foundation, Inc.
@@end copying
@@titlepage
@@ -18448,10 +19090,11 @@ Here are some notes on the example:
@cindex Documentation identification
@cindex Identification of documentation
The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs,
-Concurrent Versions System}) or RCS (see rcsintro(1)) version control
-systems, which expand it into a string such as:
+Concurrent Versions System}) or RCS
+(@url{http://www.gnu.org/software/rcs}) version control systems, which
+expand it into a string such as:
@example
-$Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $
+$Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $
@end example
(This is useful in all sources that use version control, not just manuals.)
You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -18503,8 +19146,16 @@ 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 change the text here accordingly.
+If the FSF is not the copyright holder, then use the appropriate name.
+
+@item
+If your manual is not published on paper by the FSF, then omit the
+last sentence in the Back-Cover Text that talks about copies from GNU
+Press.
+
+@item
+If your manual has Invariant Sections (again, see the license itself
+for details), then change the text here accordingly.
@item
For documents that express your personal views, feelings or experiences,
@@ -18517,7 +19168,7 @@ Here is the sample document:
@verbatim
\input texinfo @c -*-texinfo-*-
-@comment $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $
+@comment $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $
@comment %**start of header
@setfilename sample.info
@include version.texi
@@ -18525,24 +19176,23 @@ Here is the sample document:
@syncodeindex pg cp
@comment %**end of header
@copying
-This manual is for GNU Sample
-(version @value{VERSION}, @value{UPDATED}),
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
which is an example in the Texinfo documentation.
-Copyright @copyright{} 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual. Buying copies from the FSF
+supports it in developing GNU and promoting software freedom.''
@end quotation
@end copying
@@ -18566,7 +19216,7 @@ Software Foundation raise funds for GNU development.''
@node Top
@top GNU Sample
-@insertcopying
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
@end ifnottex
@menu
@@ -18587,12 +19237,8 @@ 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
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include fdl.texi
@@ -18628,7 +19274,7 @@ see the previous sections.
@copying
This document is a sample for allowing verbatim copying only.
-Copyright @copyright{} 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 2005 Free Software Foundation, Inc.
@quotation
Permission is granted to make and distribute verbatim copies
@@ -18659,7 +19305,7 @@ the license text itself. For a complete sample document, see the
previous sections.
@example
-Copyright @copyright{} 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 2005 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
@@ -19139,12 +19785,12 @@ Write custom heading specifications in the Texinfo file immediately
after the @code{@@end titlepage} command.
You must cancel the predefined heading commands with the
@code{@@headings off} command before defining your own
-specifications.@refill
+specifications.
@need 1000
Here is how to tell @TeX{} to place the chapter name at the left, the
page number in the center, and the date at the right of every header
-for both even- and odd-numbered pages:@refill
+for both even- and odd-numbered pages:
@example
@group
@@ -19157,37 +19803,35 @@ for both even- and odd-numbered pages:@refill
You need to divide the left part from the central part and the central
part from the right part by inserting @samp{@@|} between parts.
Otherwise, the specification command will not be able to tell where
-the text for one part ends and the next part begins.@refill
+the text for one part ends and the next part begins.
Each part can contain text or @@-commands. The text
is printed as if the part were within an ordinary paragraph in the
body of the page. The @@-commands replace
themselves with the page number, date, chapter name, or
-whatever.@refill
+whatever.
@need 950
-Here are the six heading and footing commands:@refill
+Here are the six heading and footing commands:
-@findex everyheading
-@findex everyfooting
@table @code
@item @@everyheading @var{left} @@| @var{center} @@| @var{right}
@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
-
+@findex everyheading
+@findex everyfooting
The `every' commands specify the format for both even- and odd-numbered
pages. These commands are for documents that are printed on one side
of each sheet of paper, or for documents in which you want symmetrical
-headers or footers.@refill
+headers or footers.
-@findex evenheading
-@findex evenfooting
-@findex oddheading
-@findex oddfooting
@item @@evenheading @var{left} @@| @var{center} @@| @var{right}
@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
-
+@findex evenheading
+@findex evenfooting
+@findex oddheading
+@findex oddfooting
The `even' and `odd' commands specify the format for even-numbered
pages and odd-numbered pages. These commands are for books and
manuals that are printed on both sides of each sheet of paper.
@@ -19198,53 +19842,66 @@ provide the names of chapters
and sections and the page number. You can use the
@samp{@@this@dots{}} commands in the left, center, or right portions
of headers and footers, or anywhere else in a Texinfo file so long as
-they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
+they are between @code{@@iftex} and @code{@@end iftex} commands.
@need 1000
-Here are the @samp{@@this@dots{}} commands:@refill
+Here are the @samp{@@this@dots{}} commands:
@table @code
-@findex thispage
@item @@thispage
-Expands to the current page number.@refill
-@c !!! Karl Berry says that `thissection' can fail on page breaks.
-@ignore
+@findex thispage
+Expands to the current page number.
+
+@item @@thissectionname
+@findex thissectionname
+Expands to the name of the current section.
+
+@item @@thissectionnum
+@findex thissectionnum
+Expands to the number of the current section.
+
@item @@thissection
-Expands to the name of the current section.@refill
-@end ignore
+@findex thissection
+Expands to the number and name of the current section, in the format
+`Section 1: Title'.
-@findex thischaptername
@item @@thischaptername
-Expands to the name of the current chapter.@refill
+@findex thischaptername
+Expands to the name of the current chapter.
+
+@item @@thischapternum
+@findex thischapternum
+Expands to the number of the current chapter, or letter of the current
+appendix.
-@findex thischapter
@item @@thischapter
+@findex thischapter
Expands to the number and name of the current
-chapter, in the format `Chapter 1: Title'.@refill
+chapter, in the format `Chapter 1: Title'.
-@findex thistitle
@item @@thistitle
+@findex thistitle
Expands to the name of the document, as specified by the
-@code{@@settitle} command.@refill
+@code{@@settitle} command.
-@findex thisfile
@item @@thisfile
+@findex thisfile
For @code{@@include} files only: expands to the name of the current
@code{@@include} file. If the current Texinfo source file is not an
@code{@@include} file, this command has no effect. This command does
@emph{not} provide the name of the current Texinfo source file unless
it is an @code{@@include} file. (@xref{Include Files}, for more
-information about @code{@@include} files.)@refill
+information about @code{@@include} files.)
@end table
@noindent
You can also use the @code{@@today@{@}} command, which expands to the
-current date, in `1 Jan 1900' format.@refill
+current date, in `1 Jan 1900' format.
@findex today
Other @@-commands and text are printed in a header or footer just as
if they were in the body of a page. It is useful to incorporate text,
-particularly when you are writing drafts:@refill
+particularly when you are writing drafts:
@example
@group
@@ -19255,7 +19912,44 @@ particularly when you are writing drafts:@refill
@end example
Beware of overlong titles: they may overlap another part of the
-header or footer and blot it out.@refill
+header or footer and blot it out.
+
+If you have very short chapters and/or sections, several of them can
+appear on a single page. You can specify which chapters and sections
+you want @code{@@thischapter}, @code{@@thissection} and other such
+macros to refer to on such pages as follows:
+
+@table @code
+@item @@everyheadingmarks @var{ref}
+@itemx @@everyfootingmarks @var{ref}
+@findex everyheadingmarks
+@findex everyfootingmarks
+The @var{ref} argument can be either @code{top} (the @code{@@this...}
+commands will refer to the chapter/section at the top of a page) or
+@code{bottom} (the commands will reflect the situation at the bottom
+of a page). These @samp{@@every...} commands specify what to do on
+both even- and odd-numbered pages.
+
+@item @@evenheadingmarks @var{ref}
+@itemx @@oddheadingmarks @var{ref}
+@itemx @@evenfootingmarks @var{ref}
+@itemx @@oddfootingmarks @var{ref}
+@findex evenheadingmarks
+@findex oddheadingmarks
+@findex evenfootingmarks
+@findex oddfootingmarks
+These @samp{@@even...} and @samp{@@odd...} commands specify what to do
+on only even- or odd-numbered pages, respectively. The @var{ref}
+argument is the same as with the @samp{@@every...} commands.
+@end table
+
+Write these commands immediately after the @code{@@...contents}
+commands, or after the @code{@@end titlepage} command if you don't
+have a table of contents or if it is printed at the end of your
+manual.
+
+By default the @code{@@this...} commands reflect the situation at the
+bottom of a page both in headings and in footings.
@node Catching Mistakes
@@ -20484,12 +21178,8 @@ 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
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include fdl.texi
@@ -20504,8 +21194,8 @@ commands are listed without their preceding @samp{@@}.@refill
@printindex fn
-@node Concept Index
-@unnumbered Concept Index
+@node General Index
+@unnumbered General Index
@printindex cp