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. 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. > 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. > 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 > 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 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. > 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. > 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. > 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. -- Pat
