INFO_SPECIAL_CHARS_WARNING doc

[Karl Berry]

Hi Patrice,

Here's (the important part of) what I just committed for the
documentation of INFO_SPECIAL_CHARS_WARNING.  Please take a look.
Essentially the same paragraph for the three cases and the entry in the
reference listing.

We decided not to warn about index entries because people can easily
just go to the node by hand, right?  I couldn't figure out why cross
refs were different, that they needed the warning; do they?

Thanks,
Karl


--- NEWS        (revision 5365)
+++ NEWS        (working copy)
@@ -22,6 +22,11 @@

+* texi2any:
+  . warns about node names, menu items, and cross-references (but not
+    index entries) containing problematic characters; can be disabled
+    with -c INFO_SPECIAL_CHARS_WARNING=0.

--- texinfo.texi        (revision 5365)
+++ texinfo.texi        (working copy)
@@ -5182,15 +5184,22 @@
 @cindex Invalid characters in node names
 @cindex Node names, invalid characters in
 Unfortunately, you cannot reliably use periods, commas, or colons
-within a node name; these confuse the Info reader.  Also, a node name
-may not start with a left parenthesis preceding a right parenthesis,
-as in @code{(not)allowed}, since this syntax is used to specify an
-external manual.  (Perhaps these limitations will be removed some day.)
+within a node name; these can confuse the Info reader.  Also, a node
+name may not start with a left parenthesis preceding a right
+parenthesis, as in @code{(not)allowed}, since this syntax is used to
+specify an external manual.  (Perhaps these limitations will be
+removed some day.)
 
-If you insist on using these characters in node names, accepting the
-resulting substandard Info output, in order not to confuse the Texinfo
-processors, you must still escape those characters, by using either
-special insertions (@pxref{Inserting a Comma}) or @code{@@asis}
address@hidden warns about such problematic usage in node names,
+menu items, and cross references.  If you don't want to see the
+warnings, you can set the customization variable
address@hidden to @samp{0} (@pxref{Other
+Customization Variables}).
+
+Also, if you insist on using these characters in node names (accepting
+the resulting substandard Info output), in order not to confuse the
+Texinfo processors you must still escape those characters, by using
+either special insertions (@pxref{Inserting a Comma}) or @code{@@asis}
 (@address@hidden@@asis}}).  For example:
 
 @example
@@ -5684,10 +5693,17 @@
 * @var{menu-entry-name}: @var{node-name}.   @var{description}
 @end example
 
address@hidden warns when the text of a menu item (and node names
+and cross references) contains a problematic construct that will
+interfere with its parsing in Info.  If you don't want to see the
+warnings, you can set the customization variable
address@hidden to @samp{0} (@pxref{Other
+Customization Variables}).
+
 In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
 command.  The menu entry name is what the user types after the @kbd{m}
 command.
@@ -6063,7 +6080,14 @@
 the @code{@@node} line, including the same capitalization; otherwise, the
 formatters may not find the reference.
 
address@hidden warns when the text of a cross reference (and node
+names and menu items) contains a problematic construct that will
+interfere with its parsing in Info.  If you don't want to see the
+warnings, you can set the customization variable
address@hidden to @samp{0} (@pxref{Other
+Customization Variables}).
 
@@ -17849,6 +17876,11 @@

address@hidden INFO_SPECIAL_CHARS_WARNING
+If set, warn about problematic constructs for Info output (such as the
+string @samp{::}) in node names, menu items, and cross references;
+default true.  Do not warn about index entries, since parsing problems
+there don't prevent navigation; readers can still relatively easily
+find their way to the node in question.