Yes, an @anchor command for the old name is used when
renaming a @node such that old links still jump to the right section
(not just to the top of the page). There were no relevant
renamings in the R manuals over the past few years.
One could add alternative anchors for selected sections but anchors are
treated identically to nodes when it comes to creating XHTML identifiers
(and also regarding allowed characters), so a dash would still be
converted to "_002d", see
<https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Node-Name-Expansion.html>.
The linked URLs are not usually visible, so I'm not too worried about
\manual{R-exts}{User-defined macros} creating a hyperlink to
<https://cloud.R-project.org/doc/manuals/R-exts.html#User_002ddefined-macros>.
The *one* case where I just recently considered adding a custom @anchor
was R-FAQ 7.31
<https://CRAN.R-project.org/doc/manuals/r-devel/R-FAQ.html#Why-doesn_0027t-R-think-these-numbers-are-equal_003f>
as it has been referenced so many times by its number. The simple
@anchor{7.31} turns into #g_t7_002e31 ... only @anchor{FAQ 7 31} gives a
reasonable #FAQ-7-31. Of course that identifier would then only be
available in specific (future) versions of the R-FAQ so it would take a
while until it could be preferred over the long-standing existing ID.
Furthermore, such alternative identifiers wouldn't usually be
known/visible as they would not be used as hyperlinks in the HTML manual
itself: the navigation links would still be based on the node name and
the section id on the section name. So I think there is little benefit
in adding extra anchors.
In the exceptional case of R-FAQ 7.31, renaming the node and adding a
description for the auto-generated menu in the Info manual might be an
option (but I didn't test this thoroughly):
@node FAQ 7 31
@nodedescription Why doesn't R think these numbers are equal?
@anchor{Why doesn't R think these numbers are equal?} @c old name
@section Why doesn't R think these numbers are equal?
Best regards,
Sebastian Meyer
Am 03.10.25 um 20:35 schrieb Michael Chirico:
Hi all,
I happened to notice that linking to the 'User-defined macros' paragraph in
R-exts produces a less-than-fully-scrutable link [1]. grep-ing around I
found others peppered in the manuals, e.g. [2] [3].
In markdown (the flavors I'm used to, at least), we'd use something like
{#User-defined-macros} to customize the link as well as make it more stable.
I'm not particularly familiar with Texinfo, but a quick search around
suggests we could use '@anchor' tags to augment what's produced
automatically from '@node'. [4] [5]
It's fairly minor but would be a nice quality-of-life improvement; if
agreed, I think it would be a nice R-dev-day issue, too. One important
consideration is back-compatibility -- we'd like to ensure any existing
links with the "ugly" text continue to work. I believe that just means
leaving the '@node' unchanged. An advanced 3rd-order consideration would be
to look at the history of the '@node' text and generate new '@anchor'
entries if any have changed to retroactively improve back-compatibility.
Mike C
[1]
https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#User_002ddefined-macros-1
[2]
https://cran.r-project.org/doc/manuals/r-release/R-admin.html#index-Installing-under-Unix_002dalikes
[3]
https://cran.r-project.org/doc/manuals/r-release/R-data.html#Spreadsheet_002dlike-data
[4]
https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#g_t_0040anchor
[aside, somewhat funny that Texinfo themselves leave this messy link here
:) ]
[5] https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Nodes
[[alternative HTML version deleted]]
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
