texinfo ChangeLog doc/texinfo.txi

[karl]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     karl <karl>     12/09/04 00:27:32

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Insertions): general updates

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1400&r2=1.1401
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.465&r2=1.466

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1400
retrieving revision 1.1401
diff -u -b -r1.1400 -r1.1401
--- ChangeLog   3 Sep 2012 17:51:36 -0000       1.1400
+++ ChangeLog   4 Sep 2012 00:27:30 -0000       1.1401
@@ -1,7 +1,7 @@
 2012-09-03  Patrice Dumas  <address@hidden>
         and Karl Berry  <address@hidden>
 
-       * doc/texinfo.txi (Breaks): general updates.
+       * doc/texinfo.txi (Breaks, Insertions): general updates.
 
 2012-09-02  Karl Berry  <address@hidden>
 

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.465
retrieving revision 1.466
diff -u -b -r1.465 -r1.466
--- doc/texinfo.txi     3 Sep 2012 17:51:37 -0000       1.465
+++ doc/texinfo.txi     4 Sep 2012 00:27:31 -0000       1.466
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.465 2012/09/03 17:51:37 karl Exp $
address@hidden $Id: texinfo.txi,v 1.466 2012/09/04 00:27: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.
 
@@ -10341,7 +10341,7 @@
 @@defindex @var{name}
 @end example
 
-The name of an index should be a two-letter word, such as @samp{au}.
+New index names are usually two-letter words, such as @samp{au}.
 For example:
 
 @example
@@ -10366,10 +10366,9 @@
 @noindent
 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
 
-In general, Texinfo constructs the new indexing command by
-concatenating the name of the index with @samp{index}; thus, defining
-an @samp{xy} index leads to the automatic creation of an
address@hidden@@xyindex} command.
+Texinfo constructs the new indexing command by concatenating the name
+of the index with @samp{index}; thus, defining an @samp{xy} index
+leads to the automatic creation of an @code{@@xyindex} command.
 
 Use the @code{@@printindex} command to print the index, as you do with
 the predefined indices.  For example:
@@ -10715,8 +10714,8 @@
 For example,
 
 @example
-foo vs.@@: (this?)@@: bar
-foo vs. (this?) bar
+foo vs.@@: bar (or?)@@: baz
+foo vs. bar (or?) baz
 @end example
 
 @noindent
@@ -10725,32 +10724,26 @@
 @end ifnottex
 @iftex
 produces the following.  If you look carefully at this printed output,
-you will see a little extraneous space after the @samp{vs.}@: and
+you will see a bit of extraneous space after the @samp{vs.}@: and
 @samp{(or?)}@: in the second line.
 @end iftex
 
 @quotation
 foo vs.@: bar (or?)@: address@hidden
-foo vs. bar (or?) address@hidden
+foo vs. bar (or?) baz
 @end quotation
 
 @noindent
address@hidden@@:} has no effect on the Info and HTML output.  In Docbook and
-XML, the previous punctuation character (.?!:) is output as an entity
-instead of as the normal character: @samp{&period; &quest; &excl;
-&colon;}.  This gives further processors a chance to notice and not
-add the usual extra space.
address@hidden@@:} has no effect on the HTML or Docbook output.
 
 Do not put braces after @code{@@:} (or any non-alphabetic command).
 
 A few Texinfo commands force normal interword spacing, so that you
-don't have to insert @code{@@:} or @code{@@.} and companions (see next
-section) where you otherwise would.  These are the code-like
-highlighting commands, @code{@@var}, @code{@@abbr}, @code{@@acronym}
-(@pxref{Useful Highlighting}), and @code{@@TeX}.  For example, that
-sentence ended with @samp{@@address@hidden@@@@address@hidden; @code{@@.} was 
not
-needed.  Another example: in @samp{@@address@hidden address@hidden the period 
is
-not considered the end of a sentence, and no extra space is inserted.
+don't have to insert @code{@@:} where you otherwise would.  These are
+the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and
address@hidden@@acronym} (@pxref{Useful Highlighting}).  For example, in
address@hidden@@address@hidden address@hidden the period is not considered the 
end of a
+sentence, and no extra space is inserted.
 
 
 @node Ending a Sentence
@@ -10765,7 +10758,7 @@
 @cindex Spacing, at ends of sentences
 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
 exclamation point, and @code{@@?}@: instead of a question mark at the end
-of a sentence that ends with a capital letter.  Otherwise, @TeX{}
+of a sentence that ends with a capital letter.  Otherwise, the formatter
 will think the letter is an abbreviation and will not insert the correct
 end-of-sentence spacing.  Here is an example:
 
@@ -10775,21 +10768,15 @@
 @end example
 
 @noindent
address@hidden
-produces
address@hidden ifnottex
address@hidden
-produces the following.  If you look carefully at this printed output,
-you will see a little more whitespace after the @samp{W} in the first
-line.
address@hidden iftex
+The output follows.  In printed output and Info, you can see the
+desired extra whitespace after the @samp{W} in the first line.
 
 @quotation
 Give it to M.I.B. and to address@hidden  Also, give it to address@hidden@*
 Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
 @end quotation
 
-In the Info file output, @code{@@.}@: is equivalent to a simple
+In the HTML file output, @code{@@.}@: is equivalent to a simple
 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
 
 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
@@ -10798,8 +10785,14 @@
 
 Do not put braces after any of these commands.
 
-See the end of the previous section for a few commands which
-special-case following spacing.
+A few Texinfo commands are not considered as being an abbreviation,
+even though they may end with a capital letter when expanded, so that
+you don't have to insert @code{@@.} and companions. This is the case
+for code-like highlighting commands, @code{@@var} arguments ending
+with a capital letter, and @code{@@TeX}.  For example, that sentence
+ended with @samp{@@address@hidden@@@@address@hidden; @code{@@.} was not 
needed.  Also
+in @code{... @@address@hidden@}. Text} the period ends the sentence,
+there is no need to insert @code{@@.}.
 
 
 @node Multiple Spaces
@@ -10812,22 +10805,19 @@
 @findex <tab>
 @findex <newline>
 
-Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
-and newline) into a single space.  Info output, on the other hand,
-preserves whitespace as you type it, except for changing a newline into
-a space; this is why it is important to put two spaces at the end of
-sentences in Texinfo documents.
+Ordinarily, multiple whitespace characters (space, tab, and newline)
+are collapsed into a single space.
 
-Occasionally, you may want to actually insert several consecutive
-spaces, either for purposes of example (what your program does with
+Occasionally, you may want to produce several consecutive spaces,
+either for purposes of example (e.g., what your program does with
 multiple spaces as input), or merely for purposes of appearance in
 headings or lists.  Texinfo supports three commands:
address@hidden@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
-which insert a single space into the output.  (Here,
address@hidden@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all
+of which insert a single space into the output.  (Here,
 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
-space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
-character and end-of-line, i.e., when @samp{@@} is the last character on
-a line.)
+space, i.e., @samp{@@ }, @kbd{TAB} represents an actual tab character,
+and @kbd{NL} represent the tab character and end-of-line, i.e., when
address@hidden@@} is the last character on a line.)
 
 For example,
 @example
@@ -10858,9 +10848,10 @@
 @cindex Space, after sentences
 
 In American typography, it is traditional and correct to put extra
-space at the end of a sentence.  This is the default in Texinfo.  In
-French typography (and many others), this extra space is wrong; all
-spaces are uniform.
+space at the end of a sentence.  This is the default in Texinfo
+(implemented in Info and printed output; for HTML, we don't try to
+override the browser).  In French typography (and 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
@@ -10876,7 +10867,7 @@
 This is text. Two sentences. Three sentences. Non-French spacing.
 @end example
 
address@hidden produces (there will be no difference in Info):
address@hidden produces:
 
 @frenchspacing on
 This is text. Two sentences. Three sentences. French spacing.
@@ -10884,34 +10875,8 @@
 @frenchspacing off
 This is text. Two sentences. Three sentences. Non-French spacing.
 
address@hidden@@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:
-
address@hidden
-Some sentence.
-Next sentence.
address@hidden example
-
address@hidden produces in Info output, with @code{@@frenchspacing off}
-(the default), two spaces between the sentences:
-
address@hidden
-Some sentence.  Next sentence.
address@hidden example
-
address@hidden With @code{@@frenchspacing on}, @command{makeinfo} outputs
-only a single space:
-
address@hidden
-Some sentence. Next sentence.
address@hidden example
address@hidden@@frenchspacing} also affects the output after @code{@@.},
address@hidden@@!}, and @code{@@?} (@pxref{Ending a Sentence}).
 
 @code{@@frenchspacing} has no effect on the HTML or Docbook output;
 for XML, it outputs a transliteration of itself (@pxref{Output
@@ -10925,12 +10890,11 @@
 @cindex Format a dimension
 @findex dmn
 
-At times, you may want to write @address@hidden or
address@hidden@dmn{in}} with little or no space between the number and the
-abbreviation for the dimension.  You can use the @code{@@dmn} command
-to do this.  On seeing the command, @TeX{} inserts just enough space
-for proper typesetting; the Info formatting commands insert no space
-at all, since the Info file does not require it.
+You can use the @code{@@dmn} command to format a dimension with a
+little extra space in the printed output.  That is, on seeing
address@hidden@@dmn}, @TeX{} inserts just enough space for proper typesetting;
+in other output formats, the formatting commands insert no space at
+all.
 
 To use the @code{@@dmn} command, write the number and then follow it
 immediately, with no intervening space, by @code{@@dmn}, and then by
@@ -10947,13 +10911,14 @@
 A4 paper is address@hidden wide.
 @end quotation
 
-Not everyone uses this style.  Some people prefer @address@hidden in.@@:}}
-or @address@hidden inches}} to @samp{8.27@@address@hidden@}} in the Texinfo 
file.
-In these cases, however, the formatters may insert a line break between
-the number and the dimension, so use @code{@@w} (@pxref{w}).  Also, if
-you write a period after an abbreviation within a sentence, you should
-write @samp{@@:} after the period to prevent @TeX{} from inserting extra
-whitespace, as shown here.  @xref{Not Ending a Sentence}.
+Not everyone uses this style.  Some people prefer address@hidden'@: or
address@hidden'.  In these cases, however, you need to use
address@hidden@@tie} (@pxref{tie,,@code{@@tie}}) or @code{@@w}
+(@pxref{w,,@code{@@w}}) so that no line break can occur between the
+number and the dimension.  Also, if you write a period after an
+abbreviation within a sentence (as with the `in.'@: above), you should
+write @samp{@@:} after the period to prevent @TeX{} from inserting
+extra whitespace, as shown here.  @xref{Not Ending a Sentence}.
 
 
 @node Inserting Accents
@@ -11389,24 +11354,22 @@
 @cindex Euro symbol
 
 Use the @code{@@address@hidden@}} command to generate address@hidden'.  Where
-possible, this is the symbol for the Euro currency, invented as part
-of the European economic unification.  In plain Info, it is the word
address@hidden }.  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.
+possible, this is the symbol for the Euro currency.  Otherwise, the
+word @samp{Euro} is used.
 
 Texinfo cannot magically synthesize support for the Euro symbol where
-the underlying system (fonts, software, whatever) does not support
-it.  Therefore, in many cases it is preferable to use the word
-``Euro''.  (In banking circles, the abbreviation for the Euro is EUR.)
+the underlying system (fonts, software, whatever) does not support it.
+Therefore, in many cases it is preferable to use the word ``Euro''.
+(In banking contexts, the abbreviation for the Euro is EUR.)
 
 @cindex ISO 8859-15, and Euro
 @cindex Latin 9, and Euro
 In order to get the Euro symbol in encoded Info output, for example,
-it is necessary to specify @code{@@documentencoding ISO-8859-15}.
+it is necessary to specify @code{@@documentencoding ISO-8859-15} or
address@hidden@@documentencoding UTF-8}
 (@xref{documentencoding,,@code{@@documentencoding}}.)  The Euro symbol
 is in ISO 8859-15 (aka address@hidden), and is @emph{not} in the more
-widely-used and supported ISO 8859-1 (address@hidden).
+widely-used ISO 8859-1 (address@hidden).
 
 @pindex feymr10
 @cindex Euro font
@@ -11425,8 +11388,8 @@
 @cindex Pounds symbol
 
 Use the @code{@@address@hidden@}} command to generate address@hidden'.  Where
-possible, this is the symbol for the currency pounds sterling.  In
-Info, it is a @samp{#}.
+possible, this is the symbol for the pounds sterling British currency.
+Otherwise, it is @samp{#}.
 
 
 @node textdegree
@@ -11435,8 +11398,8 @@
 @cindex Degree symbol
 
 Use the @code{@@address@hidden@}} command to generate address@hidden'.
-Where possible, this is the normal symbol for degrees.  In plain text
-and Info output, it is an @samp{o}.
+Where possible, this is the normal symbol for degrees.  Otherwise, 
+it is an @samp{o}.
 
 
 @node minus
@@ -11479,8 +11442,8 @@
 
 Use the @code{@@address@hidden@}} and @code{@@address@hidden@}} commands to 
generate
 greater-than-or-equal and less-than-equal-signs, address@hidden' and
address@hidden'.  In plain text and Info output, these are the ASCII
-sequences @samp{>=} and @samp{<=}.
address@hidden'.  When those symbols are not available, the ASCII sequences
address@hidden>=} and @samp{<=} are output.
 
 
 @node math
@@ -11594,9 +11557,9 @@
 
 @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{@@address@hidden@}}.
+The @code{@@click} command produces a right arrow by default; this
+glyph is also available independently via the command
address@hidden@@address@hidden@}}.
 
 @findex clickstyle
 You can change the glyph produced by @code{@@click} with the command
@@ -11629,14 +11592,13 @@
 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
 @code{@@end lisp}.  In such examples, you can indicate the results of
 evaluation or an expansion using @address@hidden or
address@hidden@expansion{}}.  Likewise, there are commands to insert glyphs
-to indicate
-printed output, error messages, equivalence of expressions, and the
-location of point.
-
-The glyph-insertion commands do not need to be used within an example, but
-most often they are.  Every  glyph-insertion command is followed by a pair of
-left- and right-hand braces.
address@hidden@expansion{}}.  Likewise, there are commands to insert glyphs to
+indicate printed output, error messages, equivalence of expressions,
+and the location of point in an editor.
+
+The glyph-insertion commands do not need to be used within an example,
+but most often they are.  All glyph-insertion commands are followed by
+empty braces.
 
 @menu
 * Glyphs Summary::
@@ -11652,7 +11614,7 @@
 @node Glyphs Summary
 @subsection Glyphs Summary
 
-Here are the different glyph commands:
+Here is a summary of the glyph commands:
 
 @table @asis
 @item @result{}
@@ -11686,14 +11648,9 @@
 Use the @code{@@address@hidden@}} command to indicate the result of
 evaluating an expression.
 
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden in
-the printed output and as @samp{=>} in other formats.
address@hidden iftex
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden in
-Info and HTML and as a true double stemmed arrow in the printed output.
address@hidden ifnottex
+The @code{@@address@hidden@}} command is displayed as @address@hidden,
+either a double stemmed arrow or (when that is not available) the
+ASCII sequence @samp{=>}.
 
 Thus, the following,
 
@@ -11716,15 +11673,9 @@
 You can indicate the result of the expansion with the
 @code{@@address@hidden@}} command.
 
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden
-in the printed output and as @samp{==>} in other formats.
address@hidden iftex
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden
-in Info and HTML, and as a long arrow with a flat base in the printed
-output.
address@hidden ifnottex
+The @code{@@address@hidden@}} command is displayed as
address@hidden@expansion{}}, either a long arrow with a flat base or (when
+that is not available) the ASCII sequence @samp{==>}.
 
 @need 700
 For example, the following
@@ -11771,15 +11722,9 @@
 Sometimes an expression will print output during its execution.  You
 can indicate the printed output with the @code{@@address@hidden@}} command.
 
address@hidden
-The @code{@@address@hidden@}} command is displayed as @samp{-|} in Info and
-HTML and as @address@hidden in the printed output.
address@hidden iftex
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
-and HTML and (similarly) as a horizontal dash butting against a
-vertical bar in the printed output.
address@hidden ifnottex
+The @code{@@address@hidden@}} command is displayed as @address@hidden, either
+a horizontal dash butting against a vertical bar or (when that is not
+available) the ASCII sequence @samp{-|}.
 
 In the following example, the printed text is indicated with
 @address@hidden, and the value of the expression follows on the
@@ -11817,14 +11762,10 @@
 A piece of code may cause an error when you evaluate it.  You can
 designate the error message with the @code{@@address@hidden@}} command.
 
address@hidden
-The @code{@@address@hidden@}} command is displayed as @samp{error-->} in Info
-and HTML and as @address@hidden in the printed output.
address@hidden iftex
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
-and HTML and as the word `error' in a box in the printed output.
address@hidden ifnottex
+The @code{@@address@hidden@}} command is displayed as @address@hidden, either
+the word `error' in a box in the printed output, the word error
+followed by an arrow in other formats or (when no arrow is available)
address@hidden>}.
 
 @need 700
 Thus,
@@ -11860,18 +11801,12 @@
 @cindex Equivalence, indicating
 @findex equiv
 
-Sometimes two expressions produce identical results.  You can indicate the
-exact equivalence of two forms with the @code{@@address@hidden@}} command.
-
address@hidden
-The @code{@@address@hidden@}} command is displayed as @samp{==} in Info and
-HTML and as @address@hidden in the printed output.
address@hidden iftex
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
-and HTML and as a standard mathematical equivalence sign (three
-parallel horizontal lines) in the printed output.
address@hidden ifnottex
+Sometimes two expressions produce identical results.  You can indicate
+the exact equivalence of two forms with the @code{@@address@hidden@}}
+command.  The @code{@@address@hidden@}} command is displayed as
address@hidden@equiv{}}, either a standard mathematical equivalence sign
+(three parallel horizontal lines) or (when that is not available) as
+the ASCII sequence @samp{==}.
 
 Thus,
 
@@ -11903,20 +11838,14 @@
 buffer in question between two lines of dashes containing the buffer
 name.
 
-You can use the @samp{@@address@hidden@}} command to show the location of point
-in the text in the buffer.  (The symbol for point, of course, is not
-part of the text in the buffer; it indicates the place @emph{between}
-two characters where point is located.)
-
address@hidden
-The @code{@@address@hidden@}} command is displayed as @samp{-!-} in Info and
-HTML and as @address@hidden in the printed output.
address@hidden iftex
address@hidden
-The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
-and HTML and as a small five pointed star in the printed
-output.
address@hidden ifnottex
+You can use the @samp{@@address@hidden@}} command to show the location of
+point in the text in the buffer.  (The symbol for point, of course, is
+not part of the text in the buffer; it indicates the place
address@hidden two characters where point is located.)
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden, either
+a pointed star or (when that is not available) the ASCII sequence
address@hidden
 
 The following example shows the contents of buffer @file{foo} before
 and after evaluating a Lisp command to insert the word @code{changed}.
@@ -21943,7 +21872,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.465 2012/09/03 17:51:37 karl Exp $
+$Id: texinfo.txi,v 1.466 2012/09/04 00:27: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}