On Tue, Jul 21, 2026 at 09:19:42PM +0100, Gavin Smith wrote:
> Case 2 is not equivalent to the tree transformation, as it
> does not follow the precedence rules I described in my earlier email. For
> example, here's the output from the test input for Texinfo output:
>
> $ TEXINFO_OUTPUT_FORMAT=plaintexinfo ../tta/perl/texi2any.pl -c
> TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands shadow.texi -o -
> --force
> shadow.texi:17: @xref reference to nonexistent node `baz'
> \input texinfo
>
> @xref{two}. --- fails
>
> @node foo 1
> @chapter foo
>
> Aaaaaaaaaa. @xref{bar}.
>
> @node bar
> @chapter bar
>
> Bbbbbbbbbbb. @xref{foo}. -- goes to baz chapter.
>
> @node two
> @section two
>
> CCCCCCC.
>
> @xref{baz}. --- fails
>
> @node foo
> @chapter baz
>
> LLLLLLLLLLL.
>
> @node two 1
> @section two
>
> DDDDDDDDD.
>
>
> @bye
>
>
> You can see that nodes have been added by the tree transformation called
> "foo 1", "two" and "two 1". The "foo 1" node would have been blocked
> by the other node called "foo", and "two" and "two 1" would have been
> blocked by each other (as there are two sections called "two", neither
> of which has a @node).
Then I misunderstood your proposition, as I thought that in case of
many sectioning commands with the same name the first one was used
(unless there is a @node with the same name). It could also have been
another than the first one, but this seems to be the most natural
convention.
> It could be fine to add nodes even if the shadow target is blocked (you
> could say it is "shadowed"), but they should have clearly different names.
> So "two" should not be used for the first "@section two", as then @xref{two}
> would work, which goes against the design.
I think that from a user point of view, @xref{two} would not working
even though there is at least one "@section two" would be surprising.
To me it should work. We could avoid promising to which sectioning
command it would point to, but I think that it should lead to somewhere.
> I'd prefer names even more
> distinctive than "two 1" and "two 2" and make it difficult to link to
> these nodes by whatever names they get. (I'm thinking something like
> "two [ADDED 1]", but you can use your imagination.)
texi2any makes sure that there is no clash with another node named
"two 1", so prepending simply numbers seems simpler to me, as the name
is minimally modified, it is unique and it does not need any
translation.
> I think I favour this approach as it means that a lone section will be
> consistently put into its own node, regardless of what node or anchor
> names are used elsewhere in the document.
>
> > 0, 1 and 2 are relevant for HTML, 1 and 2 are also relevant for Info.
> > 2 would become the default.
> >
> > One possibility to be able to specify 0, 1 and 2 would be to change
> > USE_NODES to have tree possible values, with the value 2 added. Strings
> > could also be used, for example USE_NODE=no for 0, USE_NODE=nodes for 1
> > and USE_NODE=add for 2.
> >
> > Does it look right?
>
> If we extend USE_NODES to have more than two possible values then we should
> use string arguments rather than 0, 1 and 2 as possible values, as at present
> USE_NODES is conceptually a Boolean variable.
Ok.
> There is also the SPLIT variable (--split option on the command line), which
> appears to behave differently depending on whether the output is Info or
> HTML. --split with a string argument is only relevant for HTML so it may
> be worth preserving that. It's worth considering how SPLIT and USE_NODES
> would interact. Probably, if --split=node for HTML output, USE_NODES
> governs splitting (I haven't checked this).
My way of conceptualizing the relationship between USE_NODES and SPLIT
is that they are not at the same "level". USE_NODES determines the
output units boundaries, then SPLIT determines to which file (page)
an output unit is associated to.
--
Pat
