On Tue, Sep 29, 2026 at 08:09:37PM +0100, Gavin Smith wrote:
> On Tue, Sep 29, 2026 at 01:06:29AM +0200, Patrice Dumas wrote:
>
> 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).
>
> 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".
We do not need AUTO_SECTION_TARGET=anchor, by default a section is used
as target if it is not ambiguous. I think that we need only a boolean
customization variable like
AUTO_SECTION_NODE
> > 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.)
I agree. We can leave TREE_TRANSFORMATIONS for more specialized
transformations.
> 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).
Ok. I propose to have AUTO_SECTION_TARGET=node set in the default case
for Info and HTML only, however.
> > 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.
Ok in principle, but I am not sure that we will have much to say, if we
had, we would already have said it for the case of all sectioning
commands being associated to nodes manually.
> > 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.
It is not really important, but I tend to disagree, even if setting
USE_NODES only has effect for HTML and plaintext, the "output unit"
concept and having it separated at node or section is also relevant for
Info, which is always separated at node. Strictly speaking it is not
relevant for LaTeX and DocBook, as they are never separated, although
one could argue that even without true "output units" sectioning is
always used for the structure, not node, so at least the node or
sectioning for the structure applies, here sectioning being used
unconditionally.
> > > As I understand the current implementation, with
> > 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).
To me this is what we decided to do, but we could also have decided to have
different rules for insert_nodes_for_sectioning_commands and shadow
targets, this consistency is not a necessity.
> > > 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.
Ok, it is not my view (which is tied to the implementation), where there
is a hierarchy between adding node (done first) and delimitating output
units (done afterwards), but I agree that your view is also a valid view.
--
Pat
