On Sun, Oct 04, 2026 at 10:03:39PM +0300, Eli Zaretskii wrote:
> > From: Gavin Smith <[email protected]>
> > Date: Sun, 4 Oct 2026 19:11:38 +0100
> > Cc: [email protected], [email protected]
> >
> > On Sun, Oct 04, 2026 at 06:49:06PM +0300, Eli Zaretskii wrote:
> > > By trial-and-error I discovered that the Texinfo manual only discusses
> > > "invalid characters" and their escaping in relation to node names.
> > > But in fact, the reference (a.k.a. "label") part of a cross-reference
> > > or menu item can also be quoted if it uses "invalid characters"; this
> > > is not covered in the manual, except in the technical chapter that
> > > describes the Info format in a formal manner.
> > >
> > > I think this should be covered in "Cross Reference Parts".
> >
> > OK, I'll look at it.
You were right that this node said nothing about the label. I've
made this change:
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index c172fed2b4..6799457be0 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -3885,6 +3885,16 @@ @node Cross Reference Parts
ignored. To include a comma in one of the arguments, use
@code{@@comma@{@}} (@pxref{Inserting a Comma}).
+When outputting to Info, you cannot reliably use a colon character
+within a cross-reference label (in the second or third argument to
+one of the cross-reference commands).
+There are also problematic constructs in node or anchor names in Info
+(@pxref{Info Node Names Constraints}). If a label or node or anchor
+name has one of these problems, @command{texi2any} issues a warning and
+uses a @dfn{quoting} mechanism in its output. (@xref{Info Format Cross
+Reference} for more details.) This may not be parsed correctly by all
+Info-reading programs,
+
Cross-references with one, two, three, four, and five arguments are
described separately in following sections.
@@ -3916,10 +3926,6 @@ @node Cross Reference Parts
@noindent instead of
@w{`See Hurricanes, page @var{ppp}, --- for the details'}.
-@command{texi2any} warns and protect names when the text of a cross-reference
-(and node names and menu items) contains a problematic construct that could
-interfere with its parsing in Info. @xref{Info Node Names Constraints}.
-
@raisesections
@node One Argument
> > > Btw, I understand that a comma is also a character that must be
> > > quoted, but it isn't clear to me how can one use a comma in a node
> > > name or in the label of a cross reference in a Texinfo source file,
> > > since a comma delimits arguments of @xref and other cross-referencing
> > > commands. Am I missing something?
> >
> > With @comma{}. @asis{,} may work as well.
>
> I suggest that this also be clearly documented.
This was already covered in this node (see the top part of my diff above).
It's also discussed in the "Info Node Names Constraints" node:
• Unfortunately, you cannot reliably use periods, commas, or colons
within a node name; these can confuse some Info readers.
...
If you insist on using these characters in node names, in order not
to confuse the Texinfo processors you must still escape those
characters, by using either special insertions (*note Inserting a
Comma::) or ‘@asis’ (*note @asis::). For example:
@node foo@asis{::}bar@comma{} baz
By implication, the same constructs would be used when cross-referencing
the node as when defining it.
Let us know if there is somewhere else the manual is lacking on information
on this.
