[5965] Info Format nodes: small rewordings

[karl]

Revision: 5965
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5965
Author:   karl
Date:     2014-12-14 19:17:45 +0000 (Sun, 14 Dec 2014)
Log Message:
-----------
Info Format nodes: small rewordings

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

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2014-12-14 18:07:22 UTC (rev 5964)
+++ trunk/ChangeLog     2014-12-14 19:17:45 UTC (rev 5965)
@@ -1,5 +1,7 @@
 2014-12-14  Karl Berry  <address@hidden>
 
+       * doc/texinfo.texi (Info Format *): small rewordings.
+
        * doc/texinfo.texi (Macro Details): the linemac example became
        wrong at some point; just have to be vague, it seems.
        Report from Gavin.
@@ -13,7 +15,7 @@
 2014-12-03  Karl Berry  <address@hidden>
 
        * doc/texinfo.tex: oops, \relax not \thisisundefined for
-       \ifx\csname
+       \ifx\csname.
 
        * texindex.tex (\U): new command @U.
        (\DeclareUnicodeCharacter): define a cs for @U to use.

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2014-12-14 18:07:22 UTC (rev 5964)
+++ trunk/doc/texinfo.texi      2014-12-14 19:17:45 UTC (rev 5965)
@@ -23849,10 +23849,10 @@
 @end example
 
 The indirect table is written to the main file in the case of split
-output only.  It specifies as a decimal integer the starting byte position
+output only.  It specifies, as a decimal integer, the starting byte position
 (zero-based) that each subfile would have if the subfiles were concatenated
-together in order, not including the top-level file.  The first actual node
-of content will be pointed to by the first entry.
+together in order, not including the top-level file.  The first node
+of actual content is pointed to by the first entry.
 
 As an example, suppose split output is generated for the GDB manual.
 The top-level file @file{gdb.info} will contain something like this:
@@ -23874,8 +23874,8 @@
 Unfortunately, Info-creating programs such as @code{makeinfo} have not
 always implemented these rules perfectly, due to various bugs and
 oversights.  Therefore, robust Info viewers should fall back to
-searching ``nearby'' the given position for a node, instead of just
-giving up if the position is not perfectly at a node beginning.
+searching ``nearby'' the given position for a node, instead of
+giving up immediately if the position is not exactly at a node beginning.
 
 
 @node Info Format Tag Table
@@ -23974,20 +23974,21 @@
 @end example
 
 This @t{<node>} defines @t{<id1>} in file @t{<fn>}, which is typically
-just @samp{manualname} or perhaps @samp{manualname.info}.  No 
address@hidden<infofile>} component should appear within @t{<id1>}.
+either @samp{manualname} or @samp{manualname.info}.  No parenthesized
address@hidden<infofile>} component may appear within @t{<id1>}.
 
-Each of the identifiers after @code{Next}, @code{Prev} and @code{Up} refer
-to nodes or anchors within a file.  These pointers normally refer within 
-the same file, but @samp{dir} is often used as @t{<infofile>} to point 
-to the top-level dir node.  If an @t{<infofile>} component is used then 
-the node name may be omitted, in which case the node identifier refers 
+Each of the identifiers after @code{Next}, @code{Prev} and @code{Up}
+refer to nodes or anchors within a file.  These pointers normally
+refer within the same file, but @samp{(dir)} is often used to point to
+the top-level dir file.  If an @t{<infofile>} component is used then
+the node name may be omitted, in which case the node identifier refers
 to the @samp{Top} node within the referenced file.
 
-The @code{Next} and @code{Prev} pointers are optional.  The @code{Up} 
-pointer is technically also optional, although this is most likely the 
-case of a wrongly-structured Info manual.  Conventionally the nodes are 
-arranged to form a tree, but this is not a requirement of the format.
+The @code{Next} and @code{Prev} pointers are optional.  The @code{Up}
+pointer is technically also optional, although most likely this
+indicates a mistake in the node structuring.  Conventionally, the
+nodes are arranged to form a tree, but this is not a requirement of
+the format.
 
 Node names containing periods, commas, colons or parentheses
 (including @@-commands which produce any of these) can confuse
@@ -23995,13 +23996,13 @@
 any of these, the @t{<nodename>} should be surrounded by a pair of 
 @t{<del>} characters.  @xref{Node Line Requirements}.
 
-The use of non-ASCII characters in the names of nodes is permitted, but can
-cause problems in cross-references between nodes in Info files with different
-character encodings, and also when node names from many different files are
-listed (for example, with the @option{--apropos} option to the standalone Info
-browser), so consider avoiding them when it is convenient to do so.  For
-example, prefer the use of the ASCII apostrophe character (@t{'}) to Unicode
-directional quotes.
+The use of non-ASCII characters in the names of nodes is permitted,
+but can cause problems in cross-references between nodes in Info files
+with different character encodings, and also when node names from many
+different files are listed (for example, with the @option{--apropos}
+option to the standalone Info browser), so we recommend avoiding them
+whenever feasible.  For example, prefer the use of the ASCII
+apostrophe character (@t{'}) to Unicode directional quotes.
 
 The @t{<general text>} of the node can include the special constructs
 described next.
@@ -24037,10 +24038,10 @@
 (<menu entry> | <menu comment>)*
 @end example
 
-The parts of a @t{<menu entry>} are also described in @ref{Menu Parts}.  They
-have the same syntax as cross-references (@pxref{Info Format Cross
-Reference}).  Indices extend the format to specify the destination line;
address@hidden Format Printindex}.
+The parts of a @t{<menu entry>} are also described in @ref{Menu
+Parts}.  They have the same syntax as cross-references (@pxref{Info
+Format Cross Reference}).  Indices extend menu format to specify the
+destination line; @pxref{Info Format Printindex}.
 
 A @t{<menu comment>} is any line not beginning with @samp{*} that
 appears either at the beginning of the menu or is separated from a
@@ -24068,9 +24069,9 @@
 whitespace between the different parts of the directive in Info files
 is arbitrary.
 
-In the string @t{<image file>}, @t{<txt file contents>} and @t{<alt
+In the strings @t{<image file>}, @t{<txt file contents>} and @t{<alt
 text>}, @samp{"} is quoted as @samp{\"} and @samp{\} is quoted as
address@hidden  The text and alt specifications are optional.
address@hidden  The txt and alt specifications are optional.
 
 The @t{alt} value serves the same purpose as in HTML: A prose
 description of the image.  In text-only displays or speech systems,
@@ -24078,11 +24079,10 @@
 (typically graphical) @t{<image file>}.
 
 The @t{<txt file contents>}, if present, should be taken as an ASCII
-representation of the image, and also may be used on a text-only
-display.
+representation of the image, for possible use on a text-only display.
 
 The format does not prescribe the choice between displaying the
address@hidden<image file>}, the @t{<alt text>} or @t{<txt file contents>}.
address@hidden<image file>}, the @t{<alt text>} or the @t{<txt file contents>}.
 
 
 @node Info Format Printindex
@@ -24115,7 +24115,7 @@
 The @t{<entry text>} is the index term.  The @t{<lineno>} is an
 unsigned integer, given relative to the start of the @t{<entry node>}.
 There may be arbitrary whitespace after the colon and period, as usual
-in menus.  Here is an example:
+in menus, and may be broken across lines.  Here is an example:
 
 @example
 ^@@^H[index^@@^H]
@@ -24144,26 +24144,32 @@
     <label> = <del>?<label text><del>?
 @end example
 
-No space should occur between the @t{*} character and the following @t{N}
-or @t{n}.  @samp{*Note} should be used at the start of a sentence, otherwise
address@hidden should be used.  (Some Info readers, such as the one in Emacs,
-can display @samp{*Note} and @samp{*note} as @samp{See} and @samp{see}
-respectively.) In both cases, @t{<label text>} is descriptive text.
+No space should occur between the @samp{*} character and the following
address@hidden or @samp{n}.  @samp{*Note} should be used at the start of a
+sentence, otherwise @samp{*note} should be used.  (Some Info readers,
+such as the one in Emacs, can display @samp{*Note} and @samp{*note} as
address@hidden and @samp{see} respectively.) In both cases, @t{<label
+text>} is descriptive text.
 
-In both forms the @t{<id>} refers to a node or anchor, in the same way 
-as a reference in the node information line does (@pxref{Info Format 
-Regular Nodes}).  The optional @samp{<infofile>} is the filename of the 
-manual being referenced, and the @t{<nodename>} is the node or anchor 
-within that manual,
+In both forms the @t{<id>} refers to a node or anchor, in the same way
+as a reference in the node information line does (@pxref{Info Format
+Regular Nodes}).  The optional parenthesized @samp{<infofile>} is the
+filename of the manual being referenced, and the @t{<nodename>} is the
+node or anchor within that manual,
 
 The second form has a descriptive label.  A cross-reference in this form 
-should usually be terminated with a comma or period.
+should usually be terminated with a comma or period, to make it
+feasible to find the end of the @t{<id>}.
 
-If the label contains a colon character (@t{:}), it should be surrounded 
-with a pair of @t{<del>} characters.  If @t{<nodename>} contains 
-problematic characters, it should be surrounded by a pair of @t{<del>} 
-characters, and a terminating comma or period is not required.
+If @t{<label>} contains a colon character (@t{:}), it should be
+surrounded with a pair of @t{<del>} characters.  Likewise, if
address@hidden<nodename>} contains problematic characters (such as commas or
+periods), it should be surrounded by a pair of @t{<del>} characters;
+then a terminating comma or period is not needed.
 
+The format does not prescribe how to find other manuals to resolve
+such references.
+
 Here are some examples:
 
 @example
@@ -24179,13 +24185,14 @@
 
 The second also refers to a node in the current manual, namely `Info
 Format Tag Table'; the `Tag table' before the @samp{:} is only a label
-on this particular reference.
+on this particular reference, and the @samp{for details.} is text
+belonging to the sentence, not part of the reference.
 
 The third example refers to the node `Top' in another manual, namely
 @samp{make}, with `Overview' being the label for this cross reference.
 
 The fourth example shows a colon character being quoted in a label, and
-the fifth example shows a full stop being quoted in the node name.
+the fifth example shows a period being quoted in a node name.
 
 @xref{Cross References}.