On Tue, Sep 29, 2026 at 01:06:29AM +0200, Patrice Dumas wrote:
> On Mon, Sep 28, 2026 at 09:48:17PM +0100, Gavin Smith wrote:
> > On Sun, Sep 27, 2026 at 11:32:20PM +0200, Patrice Dumas wrote:
> > > 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.
>
> It is not clear to me how your arguments below support not having a
> way to avoid the insert_nodes_for_sectioning_commands tree
> transformation if it is set in the default case.
That is not exactly what I said. I agree that there should be some way to
change between automatically created nodes and automatically created anchors,
but I wasn't sure that adding a new customization variable was the way to
go, as there were interactions with existing customization variables
(even just semantically).
However, I think I am closer to your point of view now. I was concerned
about what interaction there might be with the variables USE_NODES and SPLIT,
and how users might understand this. However, these latter variables
are explicitly documented as being output-format specific: USE_NODES for
Plaintext and HTML, SPLIT for Plaintext, Info and HTML.
As the adding of nodes takes place in a non-output-format-specific way, in
theory it may affect the output for any output format, although the significance
of this would vary between output formats. To make it easy to understand,
this option should remain separate from output-format specific options such
as USE_NODES and SPLIT. It should be straightforward to explain its function
in terms of a lone sectioning command being equivalent to a use with an
explicit @node command or @anchor.
Could a keyword variable be a better idea than a Boolean, to allow for
the possibility of future extension? I am thinking something like
AUTO_SECTION_TARGET with possible values of "node" and "anchor".
> To me, we set a default, but it does not fit all the users, so there need
> to be a way to reverse the default. It could be different from another
> customization variable, it could be possible to reuse
> TREE_TRANSFORMATIONS with a - prepended, like
> TREE_TRANSFORMATIONS=-insert_nodes_for_sectioning_commands to specify
> that insert_nodes_for_sectioning_commands should not be applied.
I don't actually like recommending a customization variable to users with
a name like TREE_TRANSFORMATIONS as I feel this is too much from the point
of view of implementation details rather than functionality. (In theory
texi2any wouldn't actually need to build a parse tree to represent the
document if was implemented differently - like the old C makeinfo.)
> > 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.
>
> Same for me. That is why I would like to keep separate the change
> related to insert_nodes_for_sectioning_commands becoming the default.
> Indeed, when we add @node because insert_nodes_for_sectioning_commands
> is now the default, we do not only get a target of a link, but
> also a delimitation of output.
I think that this feature (currently
"-c TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands", I propose
"-c AUTO_SECTION_TARGET=node") can be described in terms of the @node command
in order for it to have output-format independent semantics, even if it
won't make a difference for some output formats (TeX with texinfo.tex,
for example).
> > 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,
>
> I do not think that we have to. To me "shadow targets" do not create
> nodes, but, independently, it is a good thing to have a @node created
> when there is section command without node in the default case.
>
> > 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.
>
> I do not think that we can avoid that, because it is conceptually not
> trivial. But I think that we should consider that what is important is
> that
> * defaults are good
> * the use can change the defaults if this leads to a relevant output
I think we just need to be careful about the documentation and reference
the impact of AUTO_SECTION_TARGET (or whatever name we give it) on the
output-format specific variables of USE_NODES and SPLIT.
> > 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.
>
> I do not think that an "output unit" is related to the internal
> implementation of texi2any. It is a concept that can be defined
> independetly of texi2any, but is somehow tied to the Texinfo language,
> with the double entry, @node or sectioning commands. It is however,
> relatively complex, as it is a different concept as the ones already
> known, like page or section.
As I understand, it is only a relevant concept for some output formats
(mainly HTML, and possibly Plaintext), and so is more specific than this
new general feature.
> > 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.
>
> I think that it is a too complicated way to view that.
> TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands needs not be
> related to the shadow targets. To me it is quite simple and can be
> explained easily, it iss the same as adding (manually) a @node
> before each sectioning command that do not already have one.
They are related in that if there is a lone section command "@chapter foo",
then @xref{foo} should reference the location of that command in the output,
whether or not the command creates a node or not. Hence there should be
some consistency between insert_nodes_for_sectioning_commands being
used, and not being used (that consistency could be merely, "foo" exists
as a referenceable target, provided there is no target "foo" defined
with @node, @anchor or @namedanchor, and there is no other sectioning command
with the name "foo" in the input).
> > 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.
>
> I agree that what USE_NODES does is not trivial, but it is true
> independently of
> TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands. And what
> TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands does is
> simple.
>
> As for SPLIT, it seems also to me to be something different.
OK, we can keep SPLIT and USE_NODES as they are.
> > 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.
>
> I do not see any obvious reason why having no effect from USE_NODES
> with insert_nodes_for_sectioning_commands makes extending it a good
> idea. If a user associates systematically nodes with sections,
> USE_NODES also has no effect, it is not a property of
> insert_nodes_for_sectioning_commands, it is a property of having a node
> for each sectioning command.
OK, we'll just be careful about the documentation.
> > 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.
>
> It could be possible to use SPLIT to replace USE_NODES. But it is not
> so obvious, as, at least currently, USE_NODES is relevant to obtain a
> specific organization of the output, but it is quite specialized, the
> vast majority of users do not need to know about it, while SPLIT is
> generally useful.
>
> > 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.
>
> My current view is to consider that they do not have anything in common.
> insert_nodes_for_sectioning_commands has a well-defined easy to
> understand effect. Conversly, USE_NODES effect is harder to understand,
> and it is also unlikely to be useful for most users. For users that want to
> customize the texi2any output in a very precise way (for example like
> the lilypond manual, or if the user wants to avoid using nodes at all...),
> USE_NODES is required, though.
The reason I was confused was because they do appear to cover the same
functionality, at least when you confine your view to split HTML output.
They all affect the question of what part of the output is placed in a
single HTML file.
