Link R manuals from help pages

[bastistician]

From the R-devel NEWS:

• New system Rd macro ‘\manual{<name>}{<node>}’ to refer to a
  specific section _etc_ (possibly empty, for ‘Top’) of one of
  the R manuals (e.g., ‘R-exts’).

This has already been applied for references to some of the R manuals (see, e.g., r88893 for the few links to R-data).

The task is to scan the Rd source files of the base packages in R-devel for remaining references to the

• R-admin
• R-exts
• R-ints

manuals (most easily by grepping the Rd files for the respective manual titles) and turn the references into hyperlinks using the new \manual syntax.

Sometimes the help text simply wants to refer to a manual as a whole, as in the hypothetical example

\manual{R-exts}{} is the most important manual for R package developers.

However, often a single section is relevant for the specific context and it would be nice to refer to it directly. For example, in the 'See Also' section of ?readBin, r88893 changed

-  The \sQuote{R Data Import/Export} manual.
+  \manual{R-data}{Binary connections}.

which will be rendered as

“Binary connections” in R Data Import/Export.

The section title will be hyperlinked in both PDF and HTML help. To see such hyperlinks also in plain-text help (e.g., in Emacs/ESS via C-c C-p that runs Rd-preview-help), you need to set tools::Rd2txt_options(showURLs = TRUE). In any case, R >= 2025-09-15 r88832 is needed to preview the edited help pages (the \manual macro is unknown in R 4.5.z). Non-Emacs users could use

tools::Rd2txt("readBin.Rd", stages = c("install", "render"), options = list(showURLs = TRUE))

to preview an edited Rd file in text format.

[StatsRhian]

Patch submitted by @EllaKaye @StatsRhian & @DCEW.

We searched for sQuote("R Installation and Administration") etc for the three manuals R-exts, R-ints and R-admin and updated to use new \manual{}{}.

We also checked for references to R-exts R-ints and R-admin more generally, which identified a couple of instances using \link() which we also updated.

e.g. \code{\link{RShowDoc}("R-exts#Bibliographic-citations-and-references")} becomes
\manual{R-exts}{Bibliographic citations and references}

[bastistician]

Some tweaks were necessary (see my comment in Bugzilla), but now in R >= r88907, all help pages use hyperlinked references to the manuals. Thanks for your contribution!

[EllaKaye]

Thanks @bastistician. My apologies - I submitted the wrong version of the patch - @StatsRhian had run make check on a patch then found and corrected the change that caused the build failure and prepared a new patch. Thanks for catching and fixing it, and the other improvements to the patch too 😄