R devel - Oct 2025 - Using '@anchor' in the manuals for nicer anchors/cross-references

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]]

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 at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel