On Sat, Mar 08, 2025 at 12:46:14PM +0100, Patrice Dumas wrote:
> On Sun, Mar 02, 2025 at 08:58:19PM +0000, Gavin Smith wrote:
> > I've committed a (very short) change to texinfo.tex to implement @xrefname.
>
> I implemented in texi2any too.
I've written the documentation for it. Could you check if the following
is accurate?
Also, is there anything else we need to do to support the DITA or Mallard
style of topic-oriented documentation?
4.13 Unstructured Nodes
=======================
All the examples of nodes in this chapter so far have used a ‘@node’
line followed by a structuring command (such as ‘@chapter’).
However, you can also create nodes without using a structuring
command. You may find this useful if you do not want your manual (or
parts of a manual) to have a hierarchical structure, with chapters
superior to sections, sections superior to sub-sections and so on. This
unstructured style of documentation is known as “topic-oriented
documentation”.
To do this, follow the ‘@node’ line with one of the heading commands.
For example:
@node Topic
@heading All about the Topic
...
The argument to the heading command will be printed as usual. When
the ‘xrefautomaticsectiontitle’ flag is on (*note
xrefautomaticsectiontitle::), this argument will also be used as the
text for any cross-references to the node.
Such nodes are not part of a hierarchical document structure. This
means that they are not listed in any table of contents, and automatic
node direction pointers (‘Next’, ‘Prev’ or ‘Up’; *note Writing a Node::)
do not link to or from these nodes.
If you wish to create an unstructured node _without_ printing a
heading at the start, you can use the ‘@xrefname’ command in place of
the heading command. For example:
@node Topic
@xrefname All about the Topic
...
The ‘@xrefname’ command provides the text for cross-references to the
node when the ‘xrefautomaticsectiontitle’ flag is on, so ‘@xref{Topic}’
would produce output like "See 'All about the Topic'".
