[6521] document nodename quoting mechanism

[Gavin D. Smith]

Revision: 6521
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6521
Author:   gavin
Date:     2015-08-13 18:37:20 +0000 (Thu, 13 Aug 2015)
Log Message:
-----------
document nodename quoting mechanism

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

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-08-13 18:24:06 UTC (rev 6520)
+++ trunk/ChangeLog     2015-08-13 18:37:20 UTC (rev 6521)
@@ -1,5 +1,11 @@
 2015-08-13  Gavin Smith  <address@hidden>
 
+       * doc/texinfo.texi (Info Format Specification): Uncomment 
+       material on node quoting, and add advice not to use it until 
+       it's more widely supported.
+
+2015-08-13  Gavin Smith  <address@hidden>
+
        * tp/Texinfo/Common.pm (@variable_string_settables): Add 
        'INFO_SPECIAL_CHARS_QUOTE'.
        * tp/Texinfo/Convert/Info.pm (_node) <INFO_SPECIAL_CHARS_QUOTE>: 

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-08-13 18:24:06 UTC (rev 6520)
+++ trunk/doc/texinfo.texi      2015-08-13 18:37:20 UTC (rev 6521)
@@ -24156,8 +24156,8 @@
 following format:
 
 @example
address@hidden  <id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)?
-    <id> = (<lparen><infofile><rparen>)?(<nodename>)?
+   <id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)?
+|  <id> = (<lparen><infofile><rparen>)?(<nodename>)?
 @end example
 
 This @t{<node>} defines @t{<id1>} in file @t{<fn>}, which is typically
@@ -24180,9 +24180,11 @@
 Node names containing periods, commas, colons or parentheses
 (including @@-commands which produce any of these) can confuse
 Info readers.
address@hidden If it is necessary to refer to a node whose name contains any of
address@hidden these, the @t{<nodename>} should be surrounded by a pair of 
@t{<del>}
address@hidden characters.
+If it is necessary to refer to a node whose name contains any of
+these, the @t{<nodename>} should be surrounded by a pair of @t{<del>}
+characters.  There is support in @command{makeinfo} for adding these
+characters; however, we don't recommend you use it until such time as
+Info-reading programs that recognize this syntax are common.
 @xref{Node Line Requirements}.
 
 The use of non-ASCII characters in the names of nodes is permitted,
@@ -24330,8 +24332,8 @@
 @c| * (N|n)ote <label>:<id>(.|,)?
 | * (N|n)ote <label>:<id>(.|,)
 
address@hidden  <id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)?
-    <id> = (<lparen><infofile><rparen>)?(<nodename>)?
+     <id> = (<lparen><infofile><rparen>)?(<del>?<nodename><del>?)?
+|    <id> = (<lparen><infofile><rparen>)?(<nodename>)?
     <label> = <del>?<label text><del>?
 @end example
 
@@ -24348,17 +24350,20 @@
 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 
address@hidden should usually be terminated with a comma or period, to make it
-should be terminated with a comma or period, to make it
+The second form has a descriptive label.  A cross-reference in this form
+should usually be terminated with a comma or period, to make it
 feasible to find the end of the @t{<id>}.
 
address@hidden If @t{<label>} contains a colon character (@t{:}), it should be
address@hidden surrounded with a pair of @t{<del>} characters.  Likewise, if
address@hidden @t{<nodename>} contains problematic characters (such as commas or
address@hidden periods), it should be surrounded by a pair of @t{<del>} 
characters;
address@hidden then a terminating comma or period is not needed.
+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.
 
+As with cross-references, this quoting mechanism has as of the time of 
+writing limited support in Info-reading programs; hence we do not 
+recommend using it until this changes.
+
 The format does not prescribe how to find other manuals to resolve
 such references.
 
@@ -24368,8 +24373,8 @@
 *note GNU Free Documentation License::
 *note Tag table: Info Format Tag Table, for details.
 *Note Overview: (make)Top.
address@hidden *Note ^?:^?: (bash)Bourne Shell Builtins.
address@hidden *Note alloca.h: (gnulib)^?alloca.h^?.
+*Note ^?:^?: (bash)Bourne Shell Builtins.
+*Note alloca.h: (gnulib)^?alloca.h^?.
 @end example
 
 The first shows a reference to a node in the current manual using the 
@@ -24383,8 +24388,8 @@
 The third example refers to the node `Top' in another manual, namely
 @samp{make}, with `Overview' being the label for this cross reference.
 
address@hidden The fourth example shows a colon character being quoted in a 
label,
address@hidden and the fifth example shows a period being quoted in a node name.
+The fourth example shows a colon character being quoted in a label,
+and the fifth example shows a period being quoted in a node name.
 
 @xref{Cross References}.