texinfo ChangeLog doc/texinfo.txi

[karl]

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

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Nodes): use @ in node names

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1500&r2=1.1501
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.511&r2=1.512

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1500
retrieving revision 1.1501
diff -u -b -r1.1500 -r1.1501
--- ChangeLog   6 Jan 2013 12:34:55 -0000       1.1500
+++ ChangeLog   6 Jan 2013 19:09:11 -0000       1.1501
@@ -1,3 +1,11 @@
+2013-01-06  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Nodes): node names with @
+       throughout chapter.
+
+       * doc/texinfo.txi (acronyn, Smallcaps): more about the problems of
+       using them, and not recommending them.
+
 2013-01-06  Patrice Dumas  <address@hidden>
 
        * configure.ac: prove is required for tp tests.

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.511
retrieving revision 1.512
diff -u -b -r1.511 -r1.512
--- doc/texinfo.txi     5 Jan 2013 17:02:09 -0000       1.511
+++ doc/texinfo.txi     6 Jan 2013 19:09:12 -0000       1.512
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.511 2013/01/05 17:02:09 karl Exp $
address@hidden $Id: texinfo.txi,v 1.512 2013/01/06 19:09:12 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.
 
@@ -287,9 +287,9 @@
 
 Nodes
 
-* node::                        Creating nodes, in detail.
-* makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
-* anchor::                      Defining arbitrary cross reference targets.
+* @code{@@node}::                        Creating nodes, in detail.
+* @code{@@makeinfo} Pointer Creation::   Letting makeinfo determine node 
pointers.
+* @code{@@anchor}::                      Defining arbitrary cross reference 
targets.
 * Node Menu Illustration::      A diagram, and sample nodes and menus.
 
 The @code{@@node} Command
@@ -298,7 +298,7 @@
 * Writing a Node::              How to write an @code{@@node} line.
 * Node Line Requirements::      Keep names unique, without @@-commands.
 * First Node::                  How to write a `Top' node.
-* top command::                 How to use the @code{@@top} command.
+* @code{@@top} command::                How to use the @code{@@top} command.
 
 Menus
 
@@ -4337,8 +4337,7 @@
 like the one above.  They also provide information for generating the
 table of contents (@pxref{Contents,, Generating a Table of Contents}),
 and for implicitly determining node pointers, as is recommended
-(@pxref{makeinfo Pointer Creation,, Creating Pointers with
address@hidden).
+(@address@hidden Pointer Creation}).
 
 The chapter structuring commands do not create a node structure, so
 normally you put an @code{@@node} command immediately before each
@@ -4915,17 +4914,19 @@
 @xref{HTML Xref Link Preservation}.
 
 @menu
-* node::                        Creating nodes, in detail.
-* makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
-* anchor::                      Defining arbitrary cross reference targets.
+* @code{@@node}::                    Creating nodes, in detail.
+* @code{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
+* @code{@@anchor}::                  Defining arbitrary cross reference 
targets.
 * Node Menu Illustration::      A diagram, and sample nodes and menus.
 @end menu
 
 
address@hidden node
address@hidden @code{@@node}
 @section The @code{@@node} Command
address@hidden Node, defined
+
address@hidden@c node
 @findex node
address@hidden Node, defined
 
 A @dfn{node} is a stretch of text that begins at an @code{@@node}
 command and continues until the next @code{@@node} command.  The
@@ -4943,7 +4944,7 @@
 Requirements}).  The subsequent arguments are optional---they are the
 names of the `Next', `Previous', and `Up' pointers, in that order.  We
 strongly recommend omitting them if your Texinfo document is
-hierarchically organized, as virtually all are (@pxref{makeinfo
+hierarchically organized, as virtually all are (@address@hidden
 Pointer Creation}).  You may insert spaces before or after each name
 on the @code{@@node} line if you wish; such spaces are ignored.
 
@@ -4967,8 +4968,8 @@
 printing, even if you do not intend to format it for Info; and you
 must include a chapter-structuring command after a node for it to be a
 valid cross reference target (to @TeX{}).  You can use @code{@@anchor}
-(@pxref{anchor,,@code{@@anchor}}) to make cross references to an
-arbitrary position in a document.
+(@address@hidden@@anchor}}) to make cross references to an arbitrary
+position in a document.
 
 Cross references, such as the one at the end of this sentence, are
 made with @code{@@xref} and related commands; see @ref{Cross
@@ -4979,7 +4980,7 @@
 * Writing a Node::              How to write an @code{@@node} line.
 * Node Line Requirements::      Keep names unique.
 * First Node::                  How to write a `Top' node.
-* top command::                 How to use the @code{@@top} command.
+* @code{@@top} command::                How to use the @code{@@top} command.
 @end menu
 
 
@@ -5015,7 +5016,7 @@
 The pointers from a given node enable you to reach other nodes and
 consist simply of the names of those nodes.  The pointers are usually
 not specified explicitly, as @command{makeinfo} can determine them
-(@pxref{makeinfo Pointer Creation}).
+(@address@hidden Pointer Creation}).
 
 Normally, a node's `Up' pointer contains the name of the node whose
 menu mentions that node.  The node's `Next' pointer contains the name
@@ -5047,7 +5048,8 @@
 provided by Texinfo mode to insert the names of the pointers; or
 (recommended), you can leave the pointers out of the Texinfo file and
 let @code{makeinfo} insert node pointers into the Info file it
-creates.  (@xref{Texinfo Mode}, and @ref{makeinfo Pointer Creation}.)
+creates.  (@xref{Texinfo Mode}, and @address@hidden Pointer
+Creation}.)
 
 Alternatively, you can insert the `Next', `Previous', and `Up'
 pointers yourself.  If you do this, you may find it helpful to use the
@@ -5117,7 +5119,7 @@
 @item
 The next/previous/up pointers on @code{@@node} lines must be the names
 of nodes.  (It's recommended to leave out these explicit node pointer
-names, which automatically avoids any problem here; @pxref{makeinfo
+names, which automatically avoids any problem here; @address@hidden
 Pointer Creation}.)
 
 @item
@@ -5255,12 +5257,13 @@
 @end example
 
 
address@hidden top command
address@hidden @code{@@top} command
 @subsection The @code{@@top} Sectioning Command
address@hidden top
 
address@hidden address@hidden name of an older node with this info
address@hidden top address@hidden another name
address@hidden address@hidden old name
address@hidden address@hidden another old name
address@hidden top address@hidden yet another name
address@hidden top
 
 The @code{@@top} command is a special sectioning command that you
 should only use after an @samp{@@node Top} line at the beginning of a
@@ -5290,8 +5293,9 @@
 (@pxref{Raise/lower sections}).
 
 
address@hidden makeinfo Pointer Creation
address@hidden Creating Pointers with @code{makeinfo}
address@hidden @code{makeinfo} Pointer Creation
address@hidden @code{makeinfo} Pointer Creation
+
 @cindex Creating pointers with @code{makeinfo}
 @cindex Pointer creation with @code{makeinfo}
 @cindex Automatic pointer creation with @code{makeinfo}
@@ -5343,9 +5347,10 @@
 pointers may still be specified explicitly, in full generality.
 
 
address@hidden anchor
address@hidden @code{@@anchor}
 @section @code{@@anchor}: Defining Arbitrary Cross Reference Targets
 
address@hidden@c old name
 @findex anchor
 @cindex Anchors
 @cindex Cross reference targets, arbitrary
@@ -5443,8 +5448,8 @@
 name of the `Previous' node is address@hidden'', and the name of the
 `Up' node is ``Top''.  You can (and should) omit writing out these
 node names if your document is hierarchically organized
-(@pxref{makeinfo Pointer Creation}), but the pointer relationships
-still obtain.
+(@address@hidden Pointer Creation}), but the pointer
+relationships still obtain.
 
 @quotation Note
 `Next' and `Previous' refer to nodes at the @emph{same hierarchical
@@ -5573,8 +5578,8 @@
 structure of the document; even to nodes in a different Info file.
 However, we do not recommend making use of this, because it is hard
 for readers to follow.  Also, the @command{makeinfo} implicit pointer
-creation feature (@pxref{makeinfo Pointer Creation}) and GNU Emacs
-Texinfo mode updating commands work only to create menus of
+creation feature (@address@hidden Pointer Creation}) and GNU
+Emacs Texinfo mode updating commands work only to create menus of
 subordinate nodes in a hierarchically structured document.  It is much
 better to use cross references to refer to arbitrary nodes.
 
@@ -5876,9 +5881,9 @@
 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@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.
 
 @TeX{} also needs nodes to define cross reference locations, but the
 action is less obvious.  When @TeX{} generates a DVI file, it records
@@ -6099,9 +6104,9 @@
 period or comma will appear in the output.
 @end quotation
 
address@hidden@@xref} must refer to a node by name.  Use @code{@@node}
-to define the node (@pxref{Writing a Node}), or @code{@@anchor} 
-(@pxref{anchor,,@code{@@anchor}}).
address@hidden@@xref} must refer to a node by name.  Use @code{@@node} to
+define the node (@pxref{Writing a Node}), or @code{@@anchor}
+(@address@hidden@@anchor}}).
 
 @code{@@xref} is followed by several arguments inside braces,
 separated by commas.  Whitespace before and after these commas is
@@ -7747,7 +7752,7 @@
 @item
 In common English usage, acronyms are a subset of abbreviations: they
 include pronounceable words like address@hidden', `radar', and
-`snafu', and some sources also include syllable acronyms like
+`snafu'; some sources also include syllable acronyms like
 `Usenet', hybrids like address@hidden', and unpronounceable
 initialisms like address@hidden'.
 
@@ -7764,19 +7769,18 @@
 acronyms.
 
 @item
-It often turns out to be quite difficult and/or time-consuming to
+It usually turns out to be quite difficult and/or time-consuming to
 consistently use @code{@@acronym} for all sequences of uppercase
-letters.  Unfortunately, it looks strange for some acronyms to be in
-the normal font size and others to be smaller.  So it may be better to
-simply not use @code{@@acronym} and typeset everything as normal text:
address@hidden, producing `GNU'.  This is in fact what we recommend for
-GNU manuals.
+letters.  Furthermore, it looks strange for some acronyms to be in the
+normal font size and others to be smaller.  Thus, one approach
+(recommended for GNU manuals) is to avoid @code{@@acronym} and typeset
+everything as normal text in all capitals: @samp{GNU}, producing the
+output `GNU'.
 
 @item
 In general, it's not essential to use either of these commands for all
 abbreviations; use your judgment.  Text is perfectly readable without
 them.
-
 @end itemize
 
 
@@ -7903,25 +7907,20 @@
 braces in lowercase, like this:
 
 @example
-Richard @@address@hidden@} founded @@address@hidden@}.
+Richard @@address@hidden@} commenc@'{e} GNU.
 @end example
 
 @noindent
 This produces:
 
 @display
-Richard @sc{Stallman} founded @acronym{GNU}.
+Richard @sc{Stallman} commenc@'{e} GNU.
 @end display
 
-As shown here, we recommend using @code{@@acronym} for actual
-acronyms (@pxref{acronym}), and reserving @code{@@sc} for special
-cases where you want small caps.  The output is not the same
-(@code{@@acronym} prints in a smaller text font, not the small caps
-font), but more importantly it describes the actual text more
-accurately.
-
-Family names are one case where small capitals are sometimes desirable,
-also as shown here.
+As shown here, we recommend reserving @code{@@sc} for special cases
+where you want small caps; family names are one such, especially in
+languages other than English, though there are no hard-and-fast rules
+about such things.
 
 @cindex @code{<small>} tag
 @TeX{} typesets any uppercase letters between the braces of an
@@ -7929,9 +7928,10 @@
 printed in the small caps font.  In the Info output, the argument to
 @code{@@sc} is printed in all uppercase.  In HTML, the argument is
 uppercased and the output marked with the @code{<small>} tag to reduce
-the font size.
+the font size, since HTML cannot easily represent true small caps.
 
-We recommend using regular mixed case wherever possible.
+Overall, we recommend using standard upper- and lowercase letters
+wherever possible.
 
 
 @node Fonts
@@ -19337,8 +19337,8 @@
 restrictive.)
 
 Cross references in Texinfo can refer either to nodes or anchors
-(@pxref{anchor}).  However, anchors are treated identically to nodes
-in this context, so we'll continue to say ``node'' names for
+(@address@hidden@@anchor}}).  However, anchors are treated identically
+to nodes in this context, so we'll continue to say ``node'' names for
 simplicity.
 
 A special exception: the Top node (@pxref{The Top Node}) is always
@@ -19765,7 +19765,7 @@
 preceded by whitespace.
 
 Another approach to preserving links to deleted or renamed nodes is to
-use anchors (@pxref{anchor,, @code{anchor}}).  There is no effective
+use anchors (@address@hidden@@anchor}}).  There is no effective
 difference between the two approaches.
 
 
@@ -20616,7 +20616,7 @@
 @code{@@need}}.
 
 @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
-Begin a new node.  @xref{node, , @code{@@node}}.
+Begin a new node.  @address@hidden@@node}}.
 
 @item @@noindent
 Prevent text from being indented as if it were a new paragraph.
@@ -20985,8 +20985,7 @@
 the @code{@@node} and @code{@@top} lines, are normally enclosed with
 @code{@@ifnottex ... @@end ifnottex}.  In @TeX{} and
 @code{texinfo-format-buffer}, the @code{@@top} command is merely a
-synonym for @code{@@unnumbered}.  @xref{makeinfo Pointer Creation, ,
-Creating Pointers with @code{makeinfo}}.
+synonym for @code{@@unnumbered}.  @address@hidden Pointer Creation}.
 
 @item @@address@hidden@address@hidden
 @itemx @@address@hidden@address@hidden
@@ -21759,7 +21758,7 @@
 as:
 
 @example
-$Id: texinfo.txi,v 1.511 2013/01/05 17:02:09 karl Exp $
+$Id: texinfo.txi,v 1.512 2013/01/06 19:09:12 karl Exp $
 @end example
 
 (This is potentially useful in all sources that use version control,