texinfo ChangeLog doc/texinfo.txi

[karl]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     karl <karl>     12/09/06 18:13:43

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        general updates throughout

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1404&r2=1.1405
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.468&r2=1.469

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1404
retrieving revision 1.1405
diff -u -b -r1.1404 -r1.1405
--- ChangeLog   5 Sep 2012 15:44:34 -0000       1.1404
+++ ChangeLog   6 Sep 2012 18:13:42 -0000       1.1405
@@ -1,3 +1,8 @@
+2012-09-06  Patrice Dumas  <address@hidden>
+        and Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi: updates throughout.
+
 2012-09-05  Karl Berry  <address@hidden>
 
        * doc/texinfo.tex (\chapheadingzzz, \chapmacro): use

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.468
retrieving revision 1.469
diff -u -b -r1.468 -r1.469
--- doc/texinfo.txi     5 Sep 2012 00:49:41 -0000       1.468
+++ doc/texinfo.txi     6 Sep 2012 18:13:43 -0000       1.469
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.468 2012/09/05 00:49:41 karl Exp $
address@hidden $Id: texinfo.txi,v 1.469 2012/09/06 18:13:43 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.
 
@@ -3655,8 +3655,8 @@
 
 Since an Info file uses menus instead of tables of contents, the Info
 formatting commands ignore the contents commands.  But the contents
-are included in plain text output and in other output formats, such as
-HTML.
+are included in plain text output (generated by @code{makeinfo
+--plaintext}) and in other output formats, such as HTML.
 
 When @code{makeinfo} writes a short table of contents while producing
 HTML output, the links in the short table of contents point to
@@ -4260,32 +4260,27 @@
 more convenient for that format.
 
 @item
-In HTML and Docbook output, @code{@@printindex} produces links
-to the index entries.
+In HTML output, @code{@@printindex} produces links to the index
+entries.
 
 @item
-In XML output, it simply records the index to be printed.
+In XML and Docbook output, it simply records the index to be printed.
 @end itemize
 
-It's not possible to generate an index when writing to standard
-output; @command{makeinfo} generates a warning in this case.
-
 
 @node File End
 @section @code{@@bye} File Ending
 @findex bye
 
 An @code{@@bye} command terminates Texinfo processing.  None of the
-formatters read anything following @code{@@bye}.  The @code{@@bye}
-command should be on a line by itself.
+formatters process anything following @code{@@bye}; any such text is
+completely ignored.  The @code{@@bye} command should be on a line by
+itself.
 
-If you wish, you may follow the @code{@@bye} line with notes. These
-notes will not be formatted and will not appear in either Info or a
-printed manual; it is as if text after @code{@@bye} were within
address@hidden@@ignore} @dots{} @code{@@end ignore}.  Also, you may follow the
address@hidden@@bye} line with a local variables list for Emacs.
address@hidden, , Using Local Variables and the Compile Command},
-for more information.
+Thus, if you wish, you may follow the @code{@@bye} line with arbitrary
+notes.  Also, you may follow the @code{@@bye} line with a local
+variables list for Emacs, most typically a @samp{compile-command}
+(@pxref{Compile-Command,, Using the Local Variables List}).
 
 
 @node Structuring
@@ -6963,14 +6958,6 @@
 @node Useful Highlighting
 @subsection Highlighting Commands are Useful
 
-The highlighting commands can be used to extract useful information
-from the file, such as lists of functions or file names.  It is
-possible, for example, to write a program in Emacs Lisp (or a keyboard
-macro) to insert an index entry after every paragraph that contains
-words or phrases marked by a specified command.  You could do this to
-construct an index of functions if you had not already made the
-entries.
-
 The commands serve a variety of purposes:
 
 @table @code
@@ -7073,10 +7060,9 @@
 start a sentence with a command name written all in lower case, you
 should rearrange the sentence.
 
-In the printed manual, @code{@@code} causes @TeX{} to typeset the
-argument in a typewriter face.  In the Info file, it causes the Info
-formatting commands to use single quotation marks around the text.
-For example,
+In the Info output, @code{@@code} results in single quotation marks
+around the text.  In other formats, @code{@@code} argument is typeset
+in a typewriter (monospace) font.  For example,
 
 @example
 The function returns @@address@hidden@}.
@@ -7089,14 +7075,6 @@
 The function returns @code{nil}.
 @end quotation
 
address@hidden
address@hidden
-and this in the Info file:
address@hidden
-The function returns `nil'.
address@hidden example
address@hidden iftex
-
 Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
 
 @itemize @bullet
@@ -7104,18 +7082,18 @@
 For shell command names such as @command{ls} (use @code{@@command}).
 
 @item
+For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
+
address@hidden
 For shell options such as @samp{-c} when such options stand alone (use
 @code{@@option}).
 
 @item
-Also, an entire shell command often looks better if written using
+An entire shell command often looks better if written using
 @code{@@samp} rather than @code{@@code}.  In this case, the rule is to
 choose the more pleasing format.
 
 @item
-For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
-
address@hidden
 For a string of characters shorter than a syntactic token.  For example,
 if you are writing about @samp{goto-ch}, which is just a part of the
 name for the @code{goto-char} Emacs Lisp function, you should use
@@ -7134,17 +7112,18 @@
 
 @end itemize
 
-Since @code{@@command}, @code{@@option}, and @code{@@env} were
-introduced relatively recently, it is acceptable to use @code{@@code} or
address@hidden@@samp} for command names, options, and environment variables.
-The new commands allow you to express the markup more precisely, but
-there is no real harm in using the older commands, and of course the
-long-standing manuals do so.
-
-Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
+By default, @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}}).
+(@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}).  The HTML output
+attempts to respect this for @samp{-}, but ultimately it is up to the
+browser's behavior.  For Info, it seems better never to make such
+breaks.
+
+For Info, the quotes are omitted in the output of the @code{@@code}
+command and related commands (e.g., @code{@@kbd}, @code{@@command}),
+in typewriter-like contexts such as the @code{@@example} environment
+(@pxref{example,,@code{@@example}}) and @code{@@code} itself, etc.
 
 
 @node kbd
@@ -7169,16 +7148,10 @@
 @cindex User input
 @cindex Slanted typewriter font, for @code{@@kbd}
 By default, the @code{@@kbd} command produces a different font
-(slanted typewriter instead of normal typewriter) in the printed
-manual, so users can distinguish the characters that they are supposed
+(slanted typewriter instead of normal typewriter), 
+so users can distinguish the characters that they are supposed
 to type from those that the computer outputs.
 
-In Info output, @code{@@kbd} is usually the same as @code{@@code},
-producing `quotes' around its argument.  However, in typewriter-like
-contexts such as the @code{@@example} environment (@pxref{example})
-and @code{@@code} command itself, the quotes are omitted, since Info
-format cannot use distinguishing fonts.
-
 @findex kbdinputstyle
 Since the usage of @code{@@kbd} varies from manual to manual, you can
 control the font switching with the @code{@@kbdinputstyle} command.
@@ -7329,7 +7302,8 @@
 Also, you may use @code{@@samp} for entire statements in C and for entire
 shell commands---in this case, @code{@@samp} often looks better than
 @code{@@code}.  Basically, @code{@@samp} is a catchall for whatever is
-not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.
+not covered by @code{@@code}, @code{@@kbd}, @code{@@key}, 
address@hidden@@command}, etc.
 
 Only include punctuation marks within braces if they are part of the
 string you are specifying.  Write punctuation marks outside the braces
@@ -7402,23 +7376,23 @@
 @findex var
 
 Use the @code{@@var} command to indicate metasyntactic variables.  A
address@hidden variable} is something that stands for another piece of
-text.  For example, you should use a metasyntactic variable in the
-documentation of a function to describe the arguments that are passed
-to that function.
-
-Do not use @code{@@var} for the names of particular variables in
-programming languages.  These are specific names from a program, so
address@hidden@@code} is correct for them (@pxref{code}).  For example, the
-Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
-variable; it is properly formatted using @code{@@code}.
address@hidden variable} is something that stands for another
+piece of text.  For example, you should use a metasyntactic variable
+in the documentation of a function to describe the arguments that are
+passed to that function.
+
+Do not use @code{@@var} for the names of normal variables in computer
+programs.  These are specific names, so @code{@@code} is correct for
+them (@pxref{code}).  For example, the Emacs Lisp variable
address@hidden is not a metasyntactic variable; it is
+properly formatted using @code{@@code}.
 
 Do not use @code{@@var} for environment variables either; @code{@@env}
 is correct for them (see the next section).
 
-The effect of @code{@@var} in the Info file is to change the case of the
-argument to all upper case.  In the printed manual and HTML output, the
-argument is printed in slanted type.
+The effect of @code{@@var} in the Info file is to change the case of
+the argument to all upper case.  In the printed manual and HTML
+output, the argument is output in slanted type.
 
 @need 700
 For example,
@@ -7471,9 +7445,13 @@
 @end example
 
 @noindent
-However, that is not the style that Texinfo uses.  (You can, of
-course, modify the sources to @file{texinfo.tex} and the Info formatting 
commands
-to output the @code{<@dots{}>} format if you wish.)
+However, that is not the style that Texinfo uses.
+
address@hidden FIXME add a customization variable?  Add an example on how to do 
that
address@hidden for HTML?
address@hidden (You can, of course, modify the sources to @file{texinfo.tex}
address@hidden and the Info formatting commands
address@hidden to output the @code{<@dots{}>} format if you wish.)
 
 
 @node env
@@ -7624,8 +7602,8 @@
 @cindex @code{<abbr>} and @code{<abbrev>} tags
 In @TeX{} and in the Info output, the first argument is printed as-is;
 if the second argument is present, it is printed in parentheses after
-the abbreviation.  In HTML and XML, the @code{<abbr>} tag is
-used; in Docbook, the @code{<abbrev>} tag is used.  For instance:
+the abbreviation.  In HTML the @code{<abbr>} tag is used; in Docbook,
+the @code{<abbrev>} tag is used.  For instance:
 
 @example
 @@address@hidden J., Computer address@hidden
@@ -7665,8 +7643,7 @@
 In @TeX{}, the acronym is printed in slightly smaller font.  In the
 Info output, the argument is printed as-is.  In either format, if the
 second argument is present, it is printed in parentheses after the
-acronym.  In HTML, Docbook, and XML, the @code{<acronym>} tag is
-used.
+acronym.  In HTML and Docbook the @code{<acronym>} tag is used.
 
 For instance (since GNU is a recursive acronym, we use
 @code{@@acronym} recursively):
@@ -7772,14 +7749,14 @@
 @section Emphasizing Text
 @cindex Emphasizing text
 
-Usually, Texinfo changes the font to mark words in the text according to
-what category the words belong to; an example is the @code{@@code} command.
-Most often, this is the best way to mark words.
-However, sometimes you will want to emphasize text without indicating a
+Usually, Texinfo changes the font to mark words in the text according
+to the category the words belong to; an example is the @code{@@code}
+command.  Most often, this is the best way to mark words.  However,
+sometimes you will want to emphasize text without indicating a
 category.  Texinfo has two commands to do this.  Also, Texinfo has
-several commands that specify the font in which @TeX{} will typeset
-text.  These commands have no effect on Info and only one of them,
-the @code{@@r} command, has any regular use.
+several commands that specify the font in which text will be output.
+These commands have no effect in Info and only one of them, the
address@hidden@@r} command, has any regular use.
 
 @menu
 * emph & strong::               How to emphasize text in Texinfo.
@@ -7797,45 +7774,36 @@
 The @code{@@emph} and @code{@@strong} commands are for emphasis;
 @code{@@strong} is stronger.  In printed output, @code{@@emph} produces
 @emph{italics} and @code{@@strong} produces @strong{bold}.
+In the Info output, @code{@@emph} surrounds the text with underscores
+(@samp{_}), and @code{@@strong} puts asterisks around the text.
 
 For example,
 
 @example
 @group
-@@address@hidden:@} @@address@hidden * address@hidden
-removes @@address@hidden@} files in the directory.
+@@address@hidden:@} @@address@hidden address@hidden
+removes @@address@hidden@} normal files.
 @end group
 @end example
 
 @noindent
-produces the following in printed output and HTML:
+produces the following:
 
 @quotation
 @strong{Caution}: @samp{rm * .[^.]*}
-removes @emph{all} files in the directory.
+removes @emph{all} normal files.
 @end quotation
 
address@hidden
-and the following in Info:
-
address@hidden
-*Caution:* `rm * .[^.]*' removes _all_
-files in the directory.
address@hidden example
-
 The @code{@@strong} command is seldom used except to mark what is, in
 effect, a typographical element, such as the word `Caution' in the
 preceding example.
 
-In the Info output, @code{@@emph} surrounds the text with underscores
-(@samp{_}), and @code{@@strong} puts asterisks around the text.
-
 @quotation Caution
-Do not use @code{@@strong} with the word @samp{Note}; Info will
-mistake the combination for a cross reference.  (It's usually
-redundant, anyway.)  Use a phrase such as @strong{Please notice} or
address@hidden instead, or the optional argument to
address@hidden@@address@hidden is allowable there.
+Do not use @code{@@strong} with the word @samp{Note} followed by a
+space; Info will mistake the combination for a cross reference.  Use a
+phrase such as @strong{Please notice} or @strong{Caution} instead, or
+the optional argument to @code{@@address@hidden is allowable
+there.
 @end quotation
 
 
@@ -7877,15 +7845,12 @@
 uppercased and the output marked with the @code{<small>} tag to reduce
 the font size.
 
-Since it's redundant to mark all-uppercase text with @code{@@sc},
address@hidden warns about such usage.
-
 We recommend using regular mixed case wherever possible.
 
 
 @node Fonts
address@hidden Fonts for Printing, Not Info
address@hidden Fonts for printing, not Info
address@hidden Fonts for Printing
address@hidden Fonts for printing
 
 @findex fonttextsize
 @cindex Font size, reducing
@@ -7893,9 +7858,9 @@
 @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:
+effect 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
@@ -7905,7 +7870,7 @@
 The effect is to reduce the body font to a address@hidden size (the
 default is address@hidden).  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
+conjunction with @code{@@smallbook} (@pxref{smallbook,, Printing
 ``Small'' Books}) or similar, since address@hidden 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.
@@ -7913,11 +7878,10 @@
 Texinfo does not at present have commands to switch the font family
 to use, or more general size-changing commands.
 
address@hidden 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.
+Texinfo also provides a number of font commands that specify font
+changes in the printed manual and (where possible) in the HTML output.
+They have no effect in Info.  All the commands apply to a following
+argument surrounded by braces.
 
 @table @code
 @item @@b
@@ -7959,7 +7923,7 @@
 
 (The commands with longer names were invented much later than the
 others, at which time it did not seem desirable to use very short
-names for such an infrequently needed feature.)
+names for such infrequently needed features.)
 
 @cindex <lineannotation> Docbook tag
 Only the @code{@@r} command has much use: in example-like
@@ -13854,9 +13818,8 @@
 
 The behavior of newlines in raw regions is unspecified.
 
-In all cases, the exception to the raw processing is that @code{@@} is
-still an escape character, so the @code{@@end} command can be
-recognized.
+In all cases, in raw processing, @code{@@} retains the same meaning as
+in the remainder of the document.
 
 
 @node Inline Conditional Commands
@@ -14281,7 +14244,7 @@
 
 @item
 @samp{@@definfoenclose} allows you to define new commands with
-customized output in the Info file.
+customized output for all address@hidden output formats.
 
 @end itemize
 
@@ -14646,6 +14609,9 @@
 @code{@@example} environments, may behave unpredictably in @TeX{}.
 
 @item
+White space is ignored at the beginnings of lines.
+
address@hidden
 It is (usually) best to avoid comments inside macro definitions, but
 see the next item.
 
@@ -14733,9 +14699,6 @@
 
 @end itemize
 
-One more limitation is common to both implementations: white space is
-ignored at the beginnings of lines.
-
 
 @node alias
 @section @samp{@@alias @address@hidden
@@ -14803,12 +14766,12 @@
 @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} of
 @samp{@@tex} in your document.
 
-Write an @code{@@definfoenclose} command on a line and follow it with
-three arguments separated by commas.  The first argument to
+Write an @code{@@definfoenclose} command at the beginning of a line
+followed by three comma-separated arguments.  The first argument to
 @code{@@definfoenclose} is the @@-command name (without the
address@hidden@@}); the second argument is the Info start delimiter string;
-and the third argument is the Info end delimiter string.  The latter
-two arguments enclose the highlighted text in the Info file.
address@hidden@@}); the second argument is the start delimiter string; and the
+third argument is the end delimiter string.  The latter two arguments
+enclose the highlighted text in the output.
 
 A delimiter string may contain spaces.  Neither the start nor end
 delimiter is required.  If you do not want a start delimiter but do
@@ -15312,12 +15275,13 @@
 simplest way to create printable output.  These commands are installed
 as part of the Texinfo package.
 
-More specifically, three major shell commands for making a printed
-manual from a Texinfo file: one for converting the Texinfo file into a
-file that will be printed, a second for sorting indices, and a third
-for printing the formatted document.  When you use the shell commands,
-you can either work directly in the operating system shell or work
-within a shell inside GNU Emacs (or some other computing environment).
+More specifically, three major shell commands are used to print
+formatted output from a Texinfo manual: one converts the Texinfo
+source into something printable, a second sorts indices, and a third
+actually prints the formatted document.  When you use the shell
+commands, you can either work directly in the operating system shell
+or work within a shell inside GNU Emacs (or some other computing
+environment).
 
 If you are using GNU Emacs, you can use commands provided by Texinfo
 mode instead of shell commands.  In addition to the three commands to
@@ -15352,15 +15316,11 @@
 
 The typesetting program called @TeX{} is used for formatting a Texinfo
 file.  @TeX{} is a very powerful typesetting program and, when used
-correctly, does an exceptionally good job.  (@xref{Obtaining @TeX{}},
-for information on how to obtain @TeX{}.  It is not included in the
-Texinfo package, being a vast suite of software itself.)
-
-The standalone @code{makeinfo} program and Emacs functions
address@hidden and @code{texinfo-format-buffer} commands
-read the very same @@-commands in the Texinfo file as does @TeX{}, but
-process them differently to make Info, HTML, and other output formats
-(@pxref{Generic Translator texi2any}).
+correctly, does an exceptionally good job.
+
address@hidden @TeX{}}, for information on how to obtain @TeX{}.  It
+is not included in the Texinfo package, being a vast suite of software
+itself.
 
 
 @node Format with tex/texindex
@@ -16219,14 +16179,14 @@
 
 @node Cropmarks and Magnification
 @section Cropmarks and Magnification
+
 @findex cropmarks
 @cindex Cropmarks for printing
 @cindex Printing cropmarks
 You can (attempt to) direct @TeX{} to print cropmarks at the corners
 of pages with the @code{@@cropmarks} command.  Write the
address@hidden@@cropmarks} command on a line by itself between @code{@@iftex}
-and @code{@@end iftex} lines near the beginning of the Texinfo file,
-before the title page, like this:
address@hidden@@cropmarks} command on a line by itself near the beginning of
+the Texinfo file, before the title page, like this:
 
 @example
 @@cropmarks
@@ -17263,6 +17223,10 @@
 For HTML, the text appearing in @code{<body>}.  By default, set
 automatically taking into account the document language.
 
address@hidden CASE_INSENSITIVE_FILENAMES
+For address@hidden  Construct file names as if the filesystem was case
+insensitive (@pxref{HTML Splitting}).
+
 @item CHAPTER_HEADER_LEVEL
 For address@hidden  Header formatting level used for chapter level sectioning
 commands.
@@ -18782,7 +18746,9 @@
 If @command{makeinfo} is run on a system which does not distinguish
 case in file names, nodes which are the same except for case (e.g.,
 @samp{index} and @samp{Index}) will also be folded into the same
-output file with anchors.  You can also pretend zzzz.
+output file with anchors.  You can also pretend to be on a case
+insensitive filesystem by setting the customization variable
address@hidden
 
 It is also possible to split at chapters or sections with
 @option{--split} (@pxref{Invoking texi2any}).  In that case, the file
@@ -21850,7 +21816,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.468 2012/09/05 00:49:41 karl Exp $
+$Id: texinfo.txi,v 1.469 2012/09/06 18:13:43 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}