texinfo update (Tue Dec 28 14:52:01 EST 2004)

[Karl Berry]

Index: doc/texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.126
retrieving revision 1.127
diff -c -r1.126 -r1.127
*** doc/texinfo.txi     14 Dec 2004 17:21:53 -0000      1.126
--- doc/texinfo.txi     28 Dec 2004 19:29:10 -0000      1.127
***************
*** 1,5 ****
  \input texinfo.tex    @c -*-texinfo-*-
! @c $Id: texinfo.txi,v 1.126 2004/12/14 17:21:53 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.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.
  
***************
*** 899,909 ****
  @cindex Beebe, Nelson
  @pindex pdftex
  (Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.)  This
! format, based on PostScript, was developed by Adobe Systems for
! document interchange.  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}.
  
  @item XML
--- 899,911 ----
  @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}.
  
  @item XML
***************
*** 6263,6281 ****
  
  @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
--- 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
***************
*** 6300,6312 ****
  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
--- 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
***************
*** 6316,6343 ****
  @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
--- 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
***************
*** 6345,6355 ****
  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
--- 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
***************
*** 6373,6380 ****
  @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{}
--- 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{}
***************
*** 6395,6413 ****
  @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
--- 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
***************
*** 6726,6732 ****
  @xref{acronym,,@code{@@acronym}}.
  
  @item @@address@hidden@address@hidden
! Indicate an example (nonfunctional) uniform resource locator.
  @xref{indicateurl,,@code{@@indicateurl}}.  (Use @code{@@url}
  (@pxref{uref,,@code{@@url}}) for live url's.)
  
--- 6737,6743 ----
  @xref{acronym,,@code{@@acronym}}.
  
  @item @@address@hidden@address@hidden
! Indicate an example (that is, nonfunctional) uniform resource locator.
  @xref{indicateurl,,@code{@@indicateurl}}.  (Use @code{@@url}
  (@pxref{uref,,@code{@@url}}) for live url's.)
  
***************
*** 13363,13370 ****
  Euro symbol.
  
  A full description of the encodings is beyond our scope here;
! @uref{http://czyborra.com/charsets/iso8859.html} is one of many useful
! references.
  @end table
  
  Specifying an encoding @var{enc} has the following effects:
--- 13374,13380 ----
  Euro symbol.
  
  A full description of the encodings is beyond our scope here;
! one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
  @end table
  
  Specifying an encoding @var{enc} has the following effects:
***************
*** 14790,14800 ****
  
  @dfn{PDF} stands for `Portable Document Format'. It was invented by
  Adobe Systems some years ago for document interchange, based on their
! PostScript language.  A @uref{http://www.foolabs.com/xpdf/, PDF
! reader} for the X window system is freely available, as is the
! @uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, definition
! of the file format}.  At present, there are no @samp{@@ifpdf} or
! @samp{@@pdf} commands as with the other output formats.
  
  PDF files require special software to be displayed, unlike the plain
  ASCII formats (Info, HTML) that Texinfo supports.  They also tend to
--- 14800,14825 ----
  
  @dfn{PDF} stands for `Portable Document Format'. It was invented by
  Adobe Systems some years ago for document interchange, based on their
! PostScript language.  Related links:
! 
! @itemize
! @item
! GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF
! reader}.  (It can also preview PostScript documents.)
! 
! @item
! A freely available standalone @uref{http://www.foolabs.com/xpdf/,
! PDF reader} for the X window system.
! 
! @item
! @uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}.
! 
! @end itemize
! 
! At present, Texinfo does not provide
! @samp{@@ifpdf} or @samp{@@pdf} commands as for the other output
! formats, since PDF documents contain many internal links that would be
! hard or impossible to get right at the Texinfo source level.
  
  PDF files require special software to be displayed, unlike the plain
  ASCII formats (Info, HTML) that Texinfo supports.  They also tend to
***************
*** 18435,18441 ****
  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.126 2004/12/14 17:21:53 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}
--- 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}
***************
*** 18501,18507 ****
  
  @verbatim
  \input texinfo   @c -*-texinfo-*-
! @comment $Id: texinfo.txi,v 1.126 2004/12/14 17:21:53 karl Exp $
  @comment %**start of header
  @setfilename sample.info
  @include version.texi
--- 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
P doc/texinfo.txi