[6612] update documentation for punctutation following a cross-referencefg

[Gavin D. Smith]

Revision: 6612
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6612
Author:   gavin
Date:     2015-09-10 15:45:25 +0000 (Thu, 10 Sep 2015)
Log Message:
-----------
update documentation for punctutation following a cross-referencefg

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/doc/texinfo.texi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-09-10 14:54:11 UTC (rev 6611)
+++ trunk/ChangeLog     2015-09-10 15:45:25 UTC (rev 6612)
@@ -4,7 +4,14 @@
        Add caveat about @setfilename removal.
        * doc/texinfo-tex-test.texi: Add examples for cross-references, 
        and part pages.
+       * doc/texinfo.texi (One Argument, Two Arguments, Three Arguments)
+       (Four and Five Arguments, @ref, @pxref, Cross Reference Parts)
+       Update to reflect automatic comma insertion.
+       (References, One Argument): Consolidate discussion of output of 
+       cross-references in References node.
 
+       (Three Arguments): Remove a couple of sentences.
+
 2015-09-10  Gavin Smith  <address@hidden>
 
        * util/texi2dvi (usage): Add reference to "info texi2dvi".

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-09-10 14:54:11 UTC (rev 6611)
+++ trunk/doc/texinfo.texi      2015-09-10 15:45:25 UTC (rev 6612)
@@ -4690,28 +4690,22 @@
 references to help readers find other information that they may not
 have read.
 
-In a printed manual, a cross reference results in a page reference,
-unless it is to another manual altogether, in which case the cross
-reference names that manual.
+In a printed manual, a cross-reference results in a page reference,
+unless it is to another manual altogether, in which case the
+cross-reference names that manual.  In Info, a cross-reference results
+in an entry that you can follow using the Info @samp{f} command.
+(@xref{Help-Xref,, Following cross-references, info, Info}.)  In HTML, a
+cross-reference results in an hyperlink.
 
-In Info, a cross reference results in an entry that you can follow
-using the Info @samp{f} command.  (@xref{Help-Xref,, Following
-cross-references, info, Info}.)
+The various cross-reference commands use nodes (or anchors,
address@hidden@code{@@anchor}}) to define cross-reference locations.
address@hidden needs nodes to define cross-reference locations.  When @TeX{}
+generates a DVI file, it records each node's page number and uses the 
+page numbers in making references.  Thus, even if you are writing a 
+manual that will only be printed, and not used online, you must 
+nonetheless write @code{@@node} lines in order to name the places to 
+which you make cross-references.
 
-In HTML, a cross reference results in an hyperlink.
-
-The various cross reference commands use nodes (or anchors,
address@hidden@code{@@anchor}}) to define cross reference locations.  This is
-evident in Info and HTML, in which a cross reference takes you to the
-specified location.
-
address@hidden also needs nodes to define cross reference locations, but the
-action is less obvious.  When @TeX{} generates a DVI file, it records
-each node's page number and uses the page numbers in making
-references.  Thus, even if you are writing a manual that will only be
-printed, and not used online, you must nonetheless write @code{@@node}
-lines in order to name the places to which you make cross references.
-
 @need 800
 @node Cross Reference Commands
 @section Different Cross Reference Commands
@@ -4856,13 +4850,6 @@
 ignored.  To include a comma in one of the arguments, use
 @code{@@address@hidden@}} (@pxref{Inserting a Comma}).
 
-A period or comma should follow the closing brace of an @code{@@xref}.
-It is required to terminate the cross-reference.  This period or comma
-will appear in the output.  This period or comma is not generated
-automatically, so you must write it yourself; otherwise, Info will
-not recognize the end of the reference.  (The @code{@@pxref} command
-works differently; @address@hidden@@pxref}}.)
-
 Cross references with one, two, three, four, and five arguments are
 described separately following the description of @code{@@xref}.
 
@@ -4897,10 +4884,7 @@
 @cindex One-argument form of cross references
 
 The simplest form of @code{@@xref} takes one argument, the name of
-another node in the same Texinfo file.  The Info formatters produce
-output that the Info readers can use to jump to the reference; @TeX{}
-produces output that specifies the page and section number for you;
-the HTML output is a normal hyperlink.
+another node in the same Texinfo file.
 
 @need 700
 @noindent
@@ -4926,51 +4910,20 @@
 
 @noindent
 in a printed manual.
-(Note that in the preceding example the closing brace to
address@hidden@@xref}'s argument is followed by a period.)
 
-You can write a clause after the cross reference, like this:
 
address@hidden
-@@address@hidden address@hidden, for more info.
address@hidden example
-
address@hidden
-which produces
-
address@hidden
-*Note Tropical Storms::, for more info.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 3.1 [Tropical Storms], page 24, for more info.
address@hidden quotation
-
-
address@hidden
-in a printed manual.  Note that in the preceding example the closing
-brace to @code{@@xref} is followed by a comma, then the additional
-text.  It's a common mistake to follow an @code{@@xref} command with a
-space, but this is never correct.
-
-
 @node Two Arguments
 @subsection @code{@@xref} with Two Arguments
 @cindex Two-argument form of cross references
 
-With two arguments, the second is used as the name of the cross
-reference, while the first is still the name of the node to which the
-cross reference points.
+With two arguments, the second is used as a label for the online output.
 
 @need 750
 @noindent
 The template is like this:
 
 @example
-@@address@hidden@var{node-name}, @address@hidden
+@@address@hidden@var{node-name}, @address@hidden
 @end example
 
 @need 700
@@ -4996,35 +4949,8 @@
 @end quotation
 
 @noindent
-in a printed manual.
-(Note that in the preceding example the closing brace is followed by a
-period; and that the node name is printed, not the cross reference name.)
+in a printed manual, where the node name is printed.
 
-You can write a clause after the cross reference, like this:
-
address@hidden
-@@address@hidden Effects, address@hidden, for more info.
address@hidden example
-
address@hidden
-which produces
-
address@hidden
-*Note Lightning: Electrical Effects, for more info.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 5.2 [Electrical Effects], page 57, for more info.
address@hidden quotation
-
address@hidden
-in a printed manual.  (Note that in the preceding example the closing
-brace is followed by a comma, and then by the clause, which is
-followed by a period.)
-
 The second argument to cross references must observe some of the
 restrictions for node names (@pxref{Node Line Requirements}).  The
 most common issue is that colons cannot be used, since that interferes
@@ -5037,15 +4963,8 @@
 
 A third argument replaces the node name in the @TeX{} output.  The third
 argument should be the name of the section in the printed output, or
-else state the topic discussed by that section.  Often, you will want to
-use initial uppercase letters so it will be easier to read when the
-reference is printed.  Use a third argument when the node name is
-unsuitable because of syntax or meaning.
+else state the topic discussed by that section.
 
-Remember to write a comma or period after the closing brace of an
address@hidden@@xref} to terminate the cross reference.  In the following
-examples, a clause follows a terminating comma.
-
 @need 750
 @noindent
 The template is like this:
@@ -5146,9 +5065,6 @@
 Info file, different from the file in which the reference appears, and
 a fifth argument specifies its title as a printed manual.
 
-Remember that a comma or period must follow the closing brace of an
address@hidden@@xref} command to terminate the cross reference.
-
 @need 800
 @noindent
 The full template is:
@@ -5394,17 +5310,7 @@
 Sea surges are described in *note Hurricanes::.
 @end example
 
-You should write a period or comma immediately after a @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 @code{@@pxref}
 @section @code{@@pxref}
 
@@ -5416,28 +5322,9 @@
 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:
+in that @TeX{} typesets the reference for the printed manual with a
+lowercase `see' rather than an uppercase `See'.
 
address@hidden
address@hidden
address@hidden typesets the reference for the printed manual with a lowercase
-`see' rather than an uppercase `See'.
-
address@hidden
-The Info formatting commands automatically end the reference with a
-closing colon or period, if necessary.
address@hidden enumerate
-
address@hidden@@pxref} is designed so that the output looks right and works
-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:
 
@@ -5509,12 +5396,6 @@
 @dots{} For more information, *note More::.
 @end example
 
address@hidden
-In general, @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 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.