branch master updated: * doc/texinfo.texi (Node Line Requirements, Menu Parts) (Two Arguments, Three Arguments, @code{@@anchor}) (Info Format Regular Nodes): add an anchor for 'Info Node Names Constraints'. Refer to labels in addition to node names in the text in 'Node Line Requirements'. Update texts referring to constraints in node names to refer to that anchor for all the information on that subject.

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new 5da5f5b9cc * doc/texinfo.texi (Node Line Requirements, Menu Parts) 
(Two Arguments, Three Arguments, @code{@@anchor}) (Info Format Regular Nodes): 
add an anchor for 'Info Node Names Constraints'.  Refer to labels in addition 
to node names in the text in 'Node Line Requirements'. Update texts referring 
to constraints in node names to refer to that anchor for all the information on 
that subject.
5da5f5b9cc is described below

commit 5da5f5b9cc65b693e39f05fca32d6e3151dd6c5e
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Aug 16 15:42:30 2022 +0200

    * doc/texinfo.texi (Node Line Requirements, Menu Parts)
    (Two Arguments, Three Arguments, @code{@@anchor})
    (Info Format Regular Nodes): add an anchor for
    'Info Node Names Constraints'.  Refer to labels in addition to
    node names in the text in 'Node Line Requirements'.
    Update texts referring to constraints in node names to refer to
    that anchor for all the information on that subject.
    
    (Info Format Regular Nodes): do not refer to @@-commands, it is
    confusing in the context of the Info format.
    
    (Info Format Printindex): refer to the menu and not to the node.
---
 ChangeLog        | 20 ++++++++++++++++++--
 doc/texinfo.texi | 55 +++++++++++++++++++++++--------------------------------
 2 files changed, 41 insertions(+), 34 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4e0d70cbfd..27a345f1a9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2022-08-16  Patrice Dumas  <pertusus@free.fr>
+
+       * doc/texinfo.texi (Node Line Requirements, Menu Parts)
+       (Two Arguments, Three Arguments, @code{@@anchor})
+       (Info Format Regular Nodes): add an anchor for
+       'Info Node Names Constraints'.  Refer to labels in addition to
+       node names in the text in 'Node Line Requirements'.
+       Update texts referring to constraints in node names to refer to
+       that anchor for all the information on that subject.
+
+       (Info Format Regular Nodes): do not refer to @@-commands, it is
+       confusing in the context of the Info format.
+
+       (Info Format Printindex): refer to the menu and not to the node.
+
+
 2022-08-16  Gavin Smith  <gavinsmith0123@gmail.com>
 
        * doc/texinfo.texi (Info Format Cross Reference):
@@ -20,7 +36,7 @@
        Merge initial node "References" into chapter introduction.
        Move advice on linear manual structure to "Tips".
 
-2022-08-15  Patrice Dumas  <pertusus@free.fr>
+2022-08-16  Patrice Dumas  <pertusus@free.fr>
 
        Protect node names with comma in node pointers
 
@@ -44,7 +60,7 @@
        avoid quote character appearing before the manual part.
        * tp/t/plaintext_tests.t (quote_node_names): Add examples.
 
-2022-08-15  Patrice Dumas  <pertusus@free.fr>
+2022-08-16  Patrice Dumas  <pertusus@free.fr>
 
        Quote problematic node names in Info in the default case
 
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index fcef43729e..5a5b0bf61c 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -3020,13 +3020,14 @@ specify an external manual.
 @cindex Characters, invalid in node name
 @cindex Invalid characters in node names
 @cindex Node names, invalid characters in
+@anchor{Info Node Names Constraints}
 Unfortunately, you cannot reliably use periods, commas, or colons
 within a node name; these can confuse some Info readers.
-@command{texi2any} quotes problematic node names by default,
-but some Info readers do not recognize this syntax. Node name quoting
-causes @code{DEL} characters (@samp{CTRL-?}, character number 127,
-often rendered as @samp{^?}) to appear around the node name.  To remove
-the quoting of node names, you can set the customization variable
+@command{texi2any} quotes problematic node names and labels by default,
+but some Info readers do not recognize this syntax.  Node name and label
+quoting causes @code{DEL} characters (@samp{CTRL-?}, character number 127,
+often rendered as @samp{^?}) to appear around the name.  To remove
+node names and labels quoting, you can set the customization variable
 @code{INFO_SPECIAL_CHARS_QUOTE} to @samp{0} (@pxref{Other
 Customization Variables}).
 
@@ -3590,13 +3591,9 @@ allows you to format the menu as you wish.  
Unfortunately you must type
 node names without any extra spaces or some versions of some Info
 readers will not find the node (@pxref{Node Line Requirements}).
 
-
-@command{makeinfo} 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
-@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other
-Customization Variables}).
+@command{makeinfo} warns and protect names when the text of a menu item
+(and node names and cross-references) contains a problematic construct that
+could interfere with its parsing in Info.  @xref{Info Node Names Constraints}.
 
 
 @node Less Cluttered Menu Entry
@@ -4520,10 +4517,9 @@ See Section 5.2 [Electrical Effects], page 57.
 @noindent
 in a printed manual, where the node name is printed.
 
-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
-with the parsing of the Info file.
+The second argument to cross-references shares constraints
+with node names.  The potentially problematic character in this
+context is the colon.  @xref{Info Node Names Constraints}.
 
 
 @node Three Arguments
@@ -4600,10 +4596,9 @@ See Section 5.2 [Thunder and Lightning], page 57, for 
details.
 @noindent
 in a printed manual.
 
-The third 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
-with the parsing of the Info file.
+The third argument to cross-references shares constraints
+with node names.  The potentially problematic character in this
+context is the colon.  @xref{Info Node Names Constraints}.
 
 As a practical matter, it is often best to write cross-references with
 just the first argument if the node name and the section title are the
@@ -4995,8 +4990,8 @@ an argument.  (@xref{Go to node,,, info, Info}.).  
Anchors names and float
 labels could also appear in menus (@pxref{Menus}) and node direction
 pointers (@pxref{Writing a Node}), although this is not recommended.
 
-Also like node names, anchor names cannot include some characters
-(@pxref{Node Line Requirements}).
+Anchor names share the same constraints as nodes on the characters
+that can be included (@pxref{Info Node Names Constraints}).
 
 @cindex Nodes, deleting or renaming
 Because of this duality, when you delete or rename a node, it is
@@ -16847,7 +16842,6 @@ be able to process these.  For Info and plaintext only. 
 Default false,
 because parsing problems there don't prevent navigation; readers can still
 relatively easily find their way to the node in question.
 
-@anchor{INFO_SPECIAL_CHARS_QUOTE}
 @item INFO_SPECIAL_CHARS_QUOTE
 If set, whenever there are problematic characters for Info output in
 places such as node names or menu items, surround the part of the
@@ -23907,15 +23901,12 @@ 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
-Info readers.
-If it is necessary to refer to a node whose name contains any of
+Node names containing periods, commas, colons or parentheses can confuse Info
+readers.  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 @code{DEL}
-characters (@samp{CTRL-?}, character number 127).  There is support
-in @command{makeinfo} for adding these
-characters (@pxref{INFO_SPECIAL_CHARS_QUOTE}).  Note that not all Info
-readers recognize this syntax.  @xref{Node Line Requirements}.
+characters (@samp{CTRL-?}, character number 127).  @command{makeinfo} adds
+these characters when needed in the default case.  Note that not all Info
+readers recognize this syntax.  @xref{Info Node Names Constraints}.
 
 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
@@ -23996,7 +23987,7 @@ The format does not prescribe the choice between 
displaying the
 @cindex Indices, in Info format
 
 Indices in Info format are a kind of menu.
-An additional directive at the beginning of a node marks it as an index node,
+An additional directive at the beginning of the menu marks it as an index menu,
 followed by the menu:
 
 @example