On Sun, Sep 27, 2026 at 11:32:20PM +0200, Patrice Dumas wrote:
> On Sun, Sep 27, 2026 at 06:52:29PM +0100, Gavin Smith wrote:
> > On Thu, Sep 24, 2026 at 10:23:14PM +0200, Patrice Dumas wrote:
> > > Yes, with
> > > -c TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands
> > >
> > > I previously wanted to add another value for USE_NODES, but in the end
> > > using "-c TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands"
> > > seems best to me. The real question is whether we should make is the
> > > default. In that case, maybe we could add a customization variable to
> > > avoid doing it.
> >
> > I'd like to make it the default.
>
> What about the name avoiding the tree transformation?
> Proposal: NO_ADDED_SECTION_NODE
It's a complicated issue, in my opinion, and at present I don't agree that
adding such configuration variable is a good idea, regardless of the name.
Further comments below. Hopefully they make sense.
Upon further reflection, I realise that I haven't been thinking of these
implicitly added targets as either nodes or anchors. I was just thinking
them as possible targets of a link, like nodes and anchors are.
Perhaps the concept of "node" is so ingrained in the output of various
formats from Texinfo (it definitely is in Info, at least), that we do have
to answer the question of whether "shadow targets" create nodes or not,
even for output formats other than Info, where "node" is part of the
definition of the format. (It may not be a meaningful question for other
output formats, like HTML, LaTeX or DocBook.)
I'd like to avoid, if possible, presenting an unclear or even just overly
complicated view of what the interaction among SPLIT, USE_NODES and
insert_nodes_for_sectioning_commands is for users to obtain their desired
result. We should also try to avoid using abstract terms that only make
sense in terms of the internal implementation of texi2any (such as "output
unit", the definition of which I find it hard to remember myself, and possibly
even "node" itself, when it does not result from a @node command in Texinfo
source). We should consider how to present a simple configuration interface
without allowing confusing combinations of options that rely on concepts
of internal implementation.
As I understand the current implementation, with
TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands, these targets
become nodes. (Or to put it in an equivalent way, nodes are created at
the same locations anchor targets would be created were
insert_nodes_for_sectioning_commands not in effect. I haven't looked at the
details of the implementation of this to see how intertwined the two code
paths are.) They are then treated as nodes. This then affects
how USE_NODES operates. Finally, the "output units" resulting from
USE_NODES are placed into output files according to the value of SPLIT.
Note I haven't tested this, but this is my best guess at what
happens based on this discussion and the documentation. Even if
I've got this wrong, I hope how it goes to demonstrate how hard
it may be to understand a process that has (at least) three steps:
insert_nodes_for_sectioning_commands, USE_NODES and SPLIT, the effect
of each of which depends on any previous steps.
Presumably, if insert_nodes_for_sectioning_commands is in effect, then
USE_NODES=0 becomes pretty meaningless. From the manual:
... when nodes are the main components of output
units, isolated sections not associated with nodes are associated with
the previous node ...
If we are adding nodes for such sections, then they won't be "isolated
sections" any more, so this part of the manual wouldn't apply. But I
don't think the user should have to apply such legalistic reasoning
to work out what the program is supposed to do under some combination
of options.
Given that USE_NODES doesn't seem to make sense in combination with whatever
option controls insert_nodes_for_sectioning_commands, doesn't it make more
sense either to extend USE_NODES, or replace USE_NODES completely with a
new variable? That would reduce the number of steps from three to two, at
least.
An obvious variable for the user to use to control how the HTML output is
split is SPLIT, so one idea is that SPLIT should control whether isolated
sections are placed in their own output files. However, the presence of
"nodes" may have other effects (navigation headers perhaps?) so users may
be better advised to use SPLIT in combination with another variable (USE_NODES
or replacement) to control what output files are used to contain parts
of the output.
SPLIT is also not appropriate to control whether lone sections create nodes
for Info, or for other output formats where nodes may be relevant, so some
other variable would be needed in addition.
I haven't thought of a name of a variable to replace USE_NODES yet. Maybe
it would help to think about what the existing USE_NODES functionality and
insert_nodes_for_sectioning_commands have in common.
> I added the disambiguation suffix to the created nodes corresponding to
> sections with the same normalized name.
>
> > shadow-repeated.texi:22: warning: @section `two' already added node
> > shadow-repeated.texi:13: warning: added for @section
>
> The above message is not output anymore.
>
> > In the texinfo.tex implementation, there is a warning printed and the
> > page number is omitted for the cross-reference.
> >
> > l.8: Warning: ambiguous xref to two
> >
> > (texinfo.tex warnings have never been very good so I don't think we need
> > to worry about trying to make the warnings consistent between texinfo.tex
> > and texi2any.)
>
> For texi2any this is an error, the normal error one get when a @*ref
> target does not exist.
>
> --
> Pat
