texinfo update (Wed Dec 29 10:22:01 EST 2004)

[Karl Berry]

Index: doc/texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.127
retrieving revision 1.128
diff -c -r1.127 -r1.128
*** doc/texinfo.txi     28 Dec 2004 19:29:10 -0000      1.127
--- doc/texinfo.txi     29 Dec 2004 15:06:41 -0000      1.128
***************
*** 1,5 ****
  \input texinfo.tex    @c -*-texinfo-*-
! @c $Id: texinfo.txi,v 1.127 2004/12/28 19:29:10 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.
  
--- 1,5 ----
  \input texinfo.tex    @c -*-texinfo-*-
! @c $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 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.
  
***************
*** 6265,6284 ****
  
  @cindex Hurricanes
  @example
! For more information, @@address@hidden@}, and @@address@hidden@}.
  @end example
  
! @noindent produces in Info (the capitalization is unfortunate):
  
  @example
! For more information, *note This::, and *Note That::.
  @end example
  
! @noindent and in printed output:
  
  @quotation
! For more information, see Section 1.1 [This], page 1,
! and Section 1.2 [That], page 2.
  @end quotation
  
  The @code{@@ref} command sometimes tempts writers to express
--- 6265,6283 ----
  
  @cindex Hurricanes
  @example
! For more information, see @@address@hidden@}.
  @end example
  
! @noindent produces (in Info):
  
  @example
! For more information, see *Note Hurricanes::.
  @end example
  
! @noindent and (in printed output):
  
  @quotation
! For more information, see Section 8.2 [Hurricanes], page 123.
  @end quotation
  
  The @code{@@ref} command sometimes tempts writers to express
***************
*** 6303,6317 ****
  Sea surges are described in *Note Hurricanes::.
  @end example
  
! You should write a period or comma immediately after an @code{@@ref}
! command with two or more arguments.  If there is no such following
! punctuation, @command{makeinfo} will generate a (grammatically
! incorrect) period in the Info output; otherwise, the cross-reference
! would fail completely, due to the current syntax of Info format.
! 
! In general, it is best to use @code{@@ref} only when you need some
! word other than ``see'' to precede the reference.  When ``see'' (or
! ``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.
  
  
  @node pxref
--- 6302,6314 ----
  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.
! 
! 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.
  
  
  @node pxref
***************
*** 6321,6340 ****
  @findex pxref
  
  The parenthetical reference command, @code{@@pxref}, is nearly the
! same as @code{@@xref}, but it is best used at the end of a sentence or
! before a closing parenthesis.  The command differs from @code{@@xref}
  in two ways:
  
  @enumerate
  @item
  @TeX{} typesets the reference for the printed manual with a lower case
! `see' rather than an upper case `See'.
  
  @item
  The Info formatting commands automatically end the reference with a
! closing colon or period, if necessary.
  @end enumerate
  
  @code{@@pxref} is designed so that the output looks right and works
  right between parentheses both in printed output and in an Info file.
  In a printed manual, a closing comma or period should not follow a
--- 6318,6345 ----
  @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}
  in two ways:
  
  @enumerate
  @item
  @TeX{} typesets the reference for the printed manual with a lower case
! `see' rather than an upper case `See'address@hidden
  
  @item
  The Info formatting commands automatically end the reference with a
! closing colon or address@hidden
  @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
***************
*** 6342,6351 ****
  an Info file, suitable closing punctuation must follow the cross
  reference so Info can recognize its end.  @code{@@pxref} spares you
  the need to use complicated methods to put a terminator into one form
! of the output and not the other.
  
  @noindent
! With one argument, a parenthetical cross reference looks like this:
  
  @cindex Flooding
  @example
--- 6347,6357 ----
  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 address@hidden
  
  @noindent
! With one argument, a parenthetical cross reference looks like
! this:@refill
  
  @cindex Flooding
  @example
***************
*** 6369,6375 ****
  @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
  @end quotation
  
! With two arguments, a parenthetical cross reference has this template:
  
  @example
  @dots{} (@@address@hidden@var{node-name}, @address@hidden) @dots{}
--- 6375,6382 ----
  @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
  
  @example
  @dots{} (@@address@hidden@var{node-name}, @address@hidden) @dots{}
***************
*** 6390,6424 ****
  @dots{} (see Section @var{nnn} address@hidden, page @var{ppp}) @dots{}
  @end quotation
  
! @code{@@pxref} can be used with up to five arguments, just like
! @code{@@xref} (@pxref{xref, , @code{@@xref}}).
! 
! In past versions of Texinfo, it was not allowed to write punctuation
! after a @code{@@pxref}, so it could be used @emph{only} before a right
! parenthesis.  This is no longer the case, so now it can be used (for
! example) at the end of a sentence, where a lowercase ``see'' works
! best.  For instance:
  
! @example
! @dots{} For more information, @@address@hidden@}.
! @end example
! 
! @noindent
! which outputs (in Info):
! 
! @example
! @dots{} For more information, *Note More::.
! @end example
! 
! @noindent
! This works fine.  @code{@@pxref} should only be followed by a comma,
! period, or right parenthesis; in other cases, @command{makeinfo} has
! to insert a period to make the cross-reference work correctly in Info,
! and that period looks wrong.
  
! As a matter of general style, @code{@@pxref} is best used at the ends
! of sentences.  Although it technically works in the middle of a
! sentence, that location breaks up the flow of reading.
  
  
  @node inforef
--- 6397,6415 ----
  @dots{} (see Section @var{nnn} address@hidden, page @var{ppp}) @dots{}
  @end quotation
  
! @code{@@pxref} can be used with up to five arguments just like
! @code{@@xref} (@pxref{xref, , @code{@@xref}})address@hidden
  
! @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
! address@hidden
! @end quotation
  
! 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.
  
  
  @node inforef
***************
*** 18460,18466 ****
  Concurrent Versions System}) or RCS (see rcsintro(1)) version control
  systems, which expand it into a string such as:
  @example
! $Id: texinfo.txi,v 1.127 2004/12/28 19:29:10 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}
--- 18451,18457 ----
  Concurrent Versions System}) or RCS (see rcsintro(1)) 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 $
  @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}
***************
*** 18526,18532 ****
  
  @verbatim
  \input texinfo   @c -*-texinfo-*-
! @comment $Id: texinfo.txi,v 1.127 2004/12/28 19:29:10 karl Exp $
  @comment %**start of header
  @setfilename sample.info
  @include version.texi
--- 18517,18523 ----
  
  @verbatim
  \input texinfo   @c -*-texinfo-*-
! @comment $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $
  @comment %**start of header
  @setfilename sample.info
  @include version.texi
P doc/texinfo.txi