On Mon, Jul 20, 2026 at 11:45:41PM +0200, Patrice Dumas wrote:
> I think that there are 3 relevant possibilities:
> 0) output units are split at sections, and lone nodes are associated to
> the section. A book-like setup, corresponding to USE_NODES=0.
> Sections have a "shadow" target possibly added.
> 1) output units are split at nodes, and lone sections do not have an
> associated node added (but they have a "shadow" target possibly added.
> This is the current situation with USE_NODES=1, and it
> allows to have a sectioning structure inside an output unit. Per
> uses this setup in one of his nodes.
> 2) output units are split at nodes, but lone sections have an associated node
> automatically added. Same as the tree transformation, and, if I
> understand well, what you would favor as the default. In this case,
> the value of USE_NODES does not make a difference and there is no
> need for separate shadow targets as added nodes fulfill that role.
Case 0: as I understand it, "lone nodes" (@node commands with an associated
sectioning or heading command) are hardly supported in texinfo.tex. That's
part of the reason we invented the @xrefname command.
Case 2 is not equivalent to the tree transformation, as it
does not follow the precedence rules I described in my earlier email. For
example, here's the output from the test input for Texinfo output:
$ TEXINFO_OUTPUT_FORMAT=plaintexinfo ../tta/perl/texi2any.pl -c
TREE_TRANSFORMATIONS=insert_nodes_for_sectioning_commands shadow.texi -o -
--force
shadow.texi:17: @xref reference to nonexistent node `baz'
\input texinfo
@xref{two}. --- fails
@node foo 1
@chapter foo
Aaaaaaaaaa. @xref{bar}.
@node bar
@chapter bar
Bbbbbbbbbbb. @xref{foo}. -- goes to baz chapter.
@node two
@section two
CCCCCCC.
@xref{baz}. --- fails
@node foo
@chapter baz
LLLLLLLLLLL.
@node two 1
@section two
DDDDDDDDD.
@bye
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 "node", 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).
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'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.)
I think I favour this approach as it means that a lone section will be
consistently put into its own node, regardless of what node or anchor
names are used elsewhere in the document.
>
> I do not think that a theoretical case based on 0 where nodes would have
> sectioning commands automatically added is relevant.
Agreed, adding sectioning commands automatically wasn't part of this
proposal.
>
> 0, 1 and 2 are relevant for HTML, 1 and 2 are also relevant for Info.
> 2 would become the default.
>
> One possibility to be able to specify 0, 1 and 2 would be to change
> USE_NODES to have tree possible values, with the value 2 added. Strings
> could also be used, for example USE_NODE=no for 0, USE_NODE=nodes for 1
> and USE_NODE=add for 2.
>
> Does it look right?
If we extend USE_NODES to have more than two possible values then we should
use string arguments rather than 0, 1 and 2 as possible values, as at present
USE_NODES is conceptually a Boolean variable.
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).
