On Wed, Sep 30, 2026 at 08:37:30PM +0100, Gavin Smith wrote:
> > 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.
Actually, it is on purpose, maybe to cope with past use using
@xref{(Two)} for references external manuals and/or to mimic makeinfo in
C. Could also be because I decided so. The file argument, if there
is one, takes precedence over the (somefile)node parenthized file name.
If we want to change that, we should add it to the TODO (I do not think
that we should make the change in the release, we have changed enough, I
think).
I checked that this use does not appear in the mass_test manuals (it
happens in the guile manual, but it seems to be an error).
> > 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.
We'll have to review the manual quite a bit anyway, maybe it could be in
a footnote or something like that, if mentioned at all.
--
Pat
