On Mon, Sep 28, 2026 at 11:59:40PM +0200, [email protected] wrote:
> On Mon, Sep 28, 2026 at 05:30:35PM +0100, Gavin Smith wrote:
> > This suggests the lack of a warning is not specific to
> > insert_nodes_for_sectioning_commands. The warning that does exist is
> > probably
> > a syntax error of @node, not from a check of the resulting node name itself.
> >
> > The correct output for a node name of "(Two)" would be for the node name to
> > be wrapped in DEL bytes in most contexts.
>
> I added some DEL-quoting when a node name begins with a ( and there is
> no explicit external manual. I didn't add warning messages, as having
> a parenthesis there is, in general, not erroneous, but means something
> else.
The quoting seems to work pretty well.
The reason for a warning would be that Emacs Info mode wouldn't recognise
the quoting. However, it is not a big deal as it is an unusual use case.
Another reason for a warning is that it makes it harder to reference the
node in an explicit @menu block (as you explain below).
> I did not put DEL-quoting on manually specified parenthesized node name
> with first parenthesis not escaped by @asis.
>
> So for example, in the following, with insert_nodes_for_sectioning_commands
> tree transformation, the @menu is automatically generated, and (Two) in
> the menu is DEL-quoted:
>
> @node Top
> @top
>
> @chapter (Two)
>
> In the following, the (Two) in the explicit @menu is not quoted:
>
> @node Top
> @top
>
> @menu
> * (Two)::
> @end menu
>
> @chapter (Two)
It is right not to quote "(Two)" here, as it follows the syntax of an
external node reference in an Info menu and there's nothing to say that
it doesn't reference an external manual called "Two".
> But in the following, the @asis{(}Two) in the explicit @menu is quoted:
>
> @node Top
> @top
>
> @menu
> * @asis{(}Two)::
> @end menu
>
> @chapter (Two)
I don't know what that menu entry should mean, but referencing a node
(or anchor) named "(Two)" is a reasonable interpretation. Presumably
it is not valid to use Texinfo commands anywhere in a "(MANUAL)" part
of a menu entry, while it is valid to use Texinfo commands in node names,
and so if a Texinfo command occurs it has to be part of a node name.
> In the second case there are warnings since the Texinfo code of the node
> name, which is "@asis{(}Two)" does not match the menu entry, node
> direction Texinfo code or @xref argument, even if their normalized name
> are the same.
That sounds ok to me.
> It seems to me that we could keep the things as they are now, and we
> could even document that the references manually added should have @asis
> protecting the first parenthesis.
As I understand, it is only menu entries in @menu or @detailmenu that have
this problem. References from @xref and similar don't have this problem
as these commands have separate parameters for manual and node. @xref{(Two)}
should unambiguously mean reference the "(Two)" node.
This is not actually what texi2any does though: @xref{(Two)} outputs
"*Note (Two)::", without DEL quotes, which is a reference to the "Two"
manual.
I'm not saying this is important to fix but mentioning it here in case
you want to work on it and for future reference.
> It is not so clear that documenting
> the use of @asis is such a good idea, though, as it is an implementation
> detail that the user should not need to know and could change in the
> future, for example if we add an @-command for an opening parenthesis.
If it's only relevant for explicit menu entries it is not so important
as users often don't need to use explicit @menu blocks.
>
> --
> Pat
