On Wed, Jul 22, 2026 at 12:43:31AM +0200, Patrice Dumas wrote:
> > 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.
Suppose there is a "@section two" (with no node line), and there is no node
or anchor called "two". Then @xref{two} would reference that section.
Then suppose the author adds another "@section two" line (with no node
line) earlier in the document. If @xref{two} continued to reference one
of the sections, from the author's point of view, the cross-reference
would suddenly swing from one @section line to the other.
It's possible the author wouldn't notice this swing, leading to an error
in the manual. The part of the manual where they added the new @section
line could have been far away from the @xref referencing the old section.
The point is to avoid ambiguity in user's documents, which could lead to
erroneous output. If user gets an error to say that no target "two" was
defined after they add the new @section line, they will immediately know
there is a problem to be fixed.
> > 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.
The problem is that the names wouldn't be stable. Somebody could put
"@xref{two 1}" in their document and that target could move or disappear
if the document is edited to add, remove or move sectioning commands around.
> > 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.
That makes sense, but I feel the manual could be slightly clearer on this
(Info node "(texinfo)HTML Output Structure Customization"):
By default, each node is output in a separate file. You can change
this with the ‘--split’ command-line option, which is equivalent to
setting the ‘SPLIT’ variable. ‘SPLIT’ can take the values ‘chapter’,
‘section’, or ‘node’, or be set to an empty string to indicate non-split
output. *Note Splitting Output::.
Elementary units called “output units” are used for output, with each
output file containing the content for one or more output units,
depending on the value of ‘SPLIT’. Output units contain the content
associated with a node or a sectioning command. In typical Texinfo
document sources, a node command is almost always associated with an
immediately following sectioning command.
The customization variable ‘USE_NODES’ determines whether the node or
the sectioning command is considered to be the main command. By
default, nodes are used as the main component for the separation of
output units. You can set ‘USE_NODES’ to false to preferentially use
sectioning to decide where output units are separated. When sections
are the main components of output units, "isolated" nodes not directly
associated with a sectioning command are associated with the following
sectioning command, while sectioning commands without nodes constitute
output units. Conversely, when nodes are the main components of output
units, isolated sections not associated with nodes are associated with
the previous node, and isolated nodes are output units.
I'm going to attempt an edit to this node.
