[Rd] Using '@anchor' in the manuals for nicer anchors/cross-references

[Michael Chirico]

To clarify, the idea would be to use an @anchor without '-',
e.g. @anchor{User defined macros} seems suitable here.

However, my goal is that the link generated when clicking '¶' next to a
given heading corresponds to the desired anchor.

If it's not possible to improve that, indeed, the point is moot.

Thanks!

On Tue, Oct 7, 2025 at 11:14 AM Sebastian Meyer <seb.meyer using fau.de> wrote:

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

	[[alternative HTML version deleted]]