On Sat, Feb 15, 2025 at 01:16:13PM +0000, Werner LEMBERG wrote:
>
> [folding answers to two e-mails into one]
>
> >> Because in Info a `@node` always needs a `@menu` entry, AFAIK,
> >> which is inconsistent with the `@XXXheading` behaviour.
> >
> > The @node directions and @menu entries, if explicit, are, in
> > principle, fully independent from sectioning commands such as
> > @*section and other.
>
> OK.
>
> > So, this is not different if a @node is before an @XXXheading, it
> > may appear in an explicit node direction and in another @node menu.
>
> Well, the behaviour of `@node` in a split HTML document is to start a
> new file. However, this is exactly what I would like to avoid.
Yes, as far as I can tell the primary purpose of @node is to define
units of output. In Info output, these are Info nodes. In split HTML
output, these are files.
These units, or nodes, have names, which can naturally be used for
the target of a cross-reference. This then is the secondary purpose
of @node: define a cross-reference target.
Since we want to be able to make cross-references not just to the
beginning of a node, we further have @anchor.
Section and heading commands complexify the picture. These have
several purposes:
* Produce a heading
* For xrefautomaticsectiontitle, provide a reader-visible label for
a cross reference.
* Produce an entry in the table of contents
* Define the hierarchical structure of the document, for example for
Info menu and pointer generation.
Heading commands only have the first purpose, and possibly the
second. (The fourth purpose listed above is a side point IMHO and
can be ignored for this discussion.)
Formerly, we had this in the Texinfo TODO file:
- use @node for better control over HTML splitting:
https://lists.gnu.org/archive/html/bug-texinfo/2021-10/msg00000.html
https://lists.gnu.org/archive/html/bug-texinfo/2021-12/msg00142.html
https://lists.gnu.org/archive/html/bug-texinfo/2022-01/msg00103.html
I kept a private note of this as I didn't think the issue had really been
resolved.
So what I am thinking now is that we would allow and encourage
multiple section or heading commands within single @node. For example,
@node One
@chapter One
@section Section One
@section Section One
@node ...
In HTML output, the "One" node would be output to "One.html" including
the sections "Sec One" and "Sec Two".
If @heading is used instead of @section, then the (only?) difference would
be that the section did not appear in any table of contents.
(@majorheading and @chapheading are anomalies in the Texinfo language
in that they also affect spacing and page breaks, and are not something to
extend or imitate.)
To make a cross-reference to one of these sections, use an @anchor:
@node One
@chapter One
@anchor{Sec One}
@section Section One
@anchor{Sec Two}
@section Section One
@node ...
It is typical usage for @anchor to precede the position referred to:
if @anchor followed @section, links to e.g. "Section One" would likely
go underneath the section title, and in a HTML web browser the page
would likely be scolled such that the title were not visible.
However, this has implementation problems if section titles are to be
used as cross-reference names. The Texinfo input is parsed from top-to-bottom
with little backtracking, and when an @anchor is read, a following
@section title is not available. In texinfo.tex (for TeX processing),
an entry for the @anchor would be written to the auxiliary file as soon
as @anchor is read.
Methinks a new command could be used instead, @label: exactly as you said
in a recent email:
Well, I think that your `@anchorlabel` suggestion is the way to go.
Actually, I would prefer a shorter name, say, `@label`. Then you can
demote
```
@node Foo
@subsection Foo doodle doo
```
to
```
@label Foo
@subsubheading Foo doodle doo
```
and `@xref` would work identically – such a `@label` command could
even obey `@xrefautomaticsectiontitle`. This would also leave the
`@anchor` command unchanged.
So our example above becomes:
@node One
@chapter One
@label Sec One
@section Section One
@label Sec Two
@section Section One
@node ...
For TeX processing, the implementation of @label would be different from
that of @anchor in that the entry would only be written to the auxiliary
file when the following @section was read. This would allow recording
the label and section name together.
By default, or depending on some setting, the "xrefautomaticsectiontitle"
behaviour would be used so that e.g. @xref{Sec One} produced
"See Section One".
This would be enough for your needs, as far as I can tell, but in case
we also wanted "xrefauto'ed" links to arbitrary locations, not just
headings, then we'd need to extend @anchor as discussed elsewhere in this
discussion:
@table @asis
@item Papilon@namedanchor{Butterfly, Papilon}
...
@end table
(This follows Patrice's suggestion.)
Then the "anchor name" would be "Butterfly"; the name for cross-references
would be "Papilon". (I'm not sure how to refer to the name for
cross-references as both "name" and "label" are confusing terms. The
"refname"?)
