allow markup in Rd \link text

git-svn-id: https://svn.r-project.org/R/trunk@87442 00db46b3-68df-0310-9c12-caf00c1e9a41
r-devel · Dec 15, 2024 · d2a89d8 · d2a89d8
1 parent 0391ef6
commit d2a89d8
Show file tree

Hide file tree

Showing 10 changed files with 38 additions and 26 deletions.
diff --git a/share/texmf/tex/latex/Rd.sty b/share/texmf/tex/latex/Rd.sty
@@ -1,6 +1,6 @@
 %%% Rd.sty ... Style for printing the R manual
 %%% Part of the R package, https://www.R-project.org
-%%% Copyright (C) 2003-2022 The R Foundation
+%%% Copyright (C) 2003-2024 The R Foundation
 %%% Distributed under GPL 2 or later
 %%%
 %%% Modified 1998/01/05 by Friedrich Leisch
@@ -416,7 +416,10 @@
 \ifthenelse{\boolean{Rd@use@hyper}}
 {\newcommand{\LinkA}[2]{\hyperlink{Rfn.#2}{#1}\index{#1@\texttt{#1}|textit}}}
 {\newcommand{\LinkA}[2]{#1\index{#1@\texttt{#1}|textit}}}
-%
+% \LinkB has no indexing. (added in R 4.5.0)
+\ifthenelse{\boolean{Rd@use@hyper}}
+{\newcommand{\LinkB}[2]{\hyperlink{Rfn.#2}{#1}}}
+{\newcommand{\LinkB}[2]{#1}}
 % \alias{<alias>}{<header>}
 \ifthenelse{\boolean{Rd@use@hyper}}
 {\newcommand{\aliasA}[3]{\hypertarget{Rfn.#3}{\index{#1@\texttt{#1} \textit{(\texttt{#2})}}}}}

diff --git a/src/library/base/man/Bessel.Rd b/src/library/base/man/Bessel.Rd
@@ -108,8 +108,8 @@ besselY(x, nu)
 }
 \seealso{
   Other special mathematical functions, such as
-  \code{\link{gamma}}, \eqn{\Gamma(x)}, and \code{\link{beta}},
-  \eqn{B(x)}.
+  \ifelse{text}{\code{gamma}}{\link[=gamma]{\eqn{\Gamma(x)}}} and
+  \ifelse{text}{\code{beta}}{\link[=beta]{\eqn{B(a,b)}}}.
 }
 \author{
   Original Fortran code:

diff --git a/src/library/tools/R/Rd.R b/src/library/tools/R/Rd.R
@@ -850,7 +850,7 @@ function(x)
         tag <- attr(e, "Rd_tag")
         if(identical(tag, "\\link")) {
             val <- if(length(e)) { # mvbutils has empty links
-                arg <- paste(vapply(e, trimws, ""), collapse = " ")
+                arg <- paste(trimws(unlist(e)), collapse = " ")
                 opt <- attr(e, "Rd_option")
                 c(arg, if(is.null(opt)) "" else as.character(opt))
             } else c("", "")

diff --git a/src/library/tools/R/Rd2HTML.R b/src/library/tools/R/Rd2HTML.R
@@ -29,10 +29,9 @@ get_link <- function(arg, tag, Rdfile) {
     ## \link[pkg:bar]{foo} means show foo and link to topic/file bar in package pkg.
     ## As from 2.10.0, look for topic 'bar' if file not found.
     ## As from 4.1.0, prefer topic 'bar' over file 'bar' (in which case 'targetfile' is a misnomer)
+    ## As from 4.5.0, allow markup in link text for variants 2 and 4.
 
-    if (!all(RdTags(arg) == "TEXT"))
-    	stopRd(arg, Rdfile, "Bad \\link text")
-
+    isTEXT <- all(RdTags(arg) == "TEXT")
     option <- attr(arg, "Rd_option")
 
     topic <- dest <- paste(unlist(arg), collapse = "")
@@ -41,16 +40,21 @@ get_link <- function(arg, tag, Rdfile) {
     if (!is.null(option)) {
         if (!identical(attr(option, "Rd_tag"), "TEXT"))
     	    stopRd(option, Rdfile, "Bad \\link option -- must be text")
-    	if (grepl("^=", option, perl = TRUE, useBytes = TRUE))
+        option <- as.character(option)
+        if (startsWith(option, "="))
     	    dest <- psub1("^=", "", option)
-    	else if (grepl(":", option, perl = TRUE, useBytes = TRUE)) {
+        else if (grepl(":", option, fixed = TRUE)) {
     	    targetfile <- psub1("^[^:]*:", "", option)
     	    pkg <- psub1(":.*", "", option)
     	} else {
+            if (!isTEXT)
+                stopRd(arg, Rdfile, "Bad \\link[pkg]{topic} -- argument must be text")
             targetfile <- dest
-    	    pkg <- as.character(option)
+            pkg <- option
     	}
-    }
+    } else if (!isTEXT)
+        stopRd(arg, Rdfile, "Bad \\link topic -- must be text")
+
     if (tag == "\\linkS4class") dest <- paste0(dest, "-class")
     list(topic = topic, dest = dest, pkg = pkg, targetfile = targetfile)
 }

diff --git a/src/library/tools/R/Rd2latex.R b/src/library/tools/R/Rd2latex.R
@@ -233,11 +233,18 @@ Rd2latex <- function(Rd, out = "", defines = .Platform$OS.type,
 
     ## Currently ignores [option] except for [=dest] form
     ## (as documented)
+    ## FIXME: so should not output cross-package links (unless for refman ...)
     writeLink <- function(tag, block) {
-        parts <- get_link(block, tag)
+        parts <- get_link(block, tag, Rdfile)
         if (concordance)
             conc$saveSrcref(block)
-        of0("\\LinkA{", latex_escape_link(parts$topic), "}{",
+        if (all(RdTags(block) == "TEXT")) {
+            of0("\\LinkA{", latex_escape_name(parts$topic))
+        } else { # don't \index link text containing markup etc
+            of1("\\LinkB{")
+            writeContent(block, tag)
+        }
+        of0("}{",
             latex_link_trans0(parts$dest), "}")
     }
 
@@ -290,13 +297,6 @@ Rd2latex <- function(Rd, out = "", defines = .Platform$OS.type,
         x
     }
 
-    latex_escape_link <- function(x)
-    {
-        ## _ is already escaped
-        x <- fsub("\\_", "_", x)
-        latex_escape_name(x)
-    }
-
     latex_link_trans0 <- function(x)
     {
         x <- fsub("\\Rdash", ".Rdash.", x)

diff --git a/src/library/tools/man/testInstalledPackage.Rd b/src/library/tools/man/testInstalledPackage.Rd
@@ -67,7 +67,8 @@ standard_package_names()
 
   \code{testInstalledBasic} runs the basic tests, if installed or inside
   \code{testSrcdir}.  This
-  should be run with \code{LC_COLLATE=C} set: the function tries to set
+  should be run with \link[=LC_COLLATE]{\env{LC_COLLATE}} set to \samp{C}:
+  the function tries to set
   this but it may not work on all OSes.  For non-English locales it may
   be desirable to set environment variables \env{LANGUAGE} to \samp{en}
   and \env{LC_TIME} to \samp{C} to reduce the number of differences from

diff --git a/tests/testit.Rd b/tests/testit.Rd
@@ -34,7 +34,8 @@ foo(\var{x}, \var{y}, ...)
   \code{\%\{\}}
 
   \link{a link} and some to known destinations:
-  \link[stats]{weighted.mean}, \code{\link[=Paren]{\{}}
+  \code{\link[stats]{weighted.mean}}, \link[stats:weighted.mean]{dito},
+  \code{\link[=Paren]{\{}}, \link[=R_HOME]{\env{R_HOME}}.
 
   var in \var{text}.
 

diff --git a/tests/testit.html.save b/tests/testit.html.save
@@ -55,7 +55,8 @@ conditional content.
 <p><code>%{}</code>
 </p>
 <p>a link and some to known destinations:
-weighted.mean, <code>{</code>
+<code>weighted.mean</code>, dito,
+<code>{</code>, <span class="env">R_HOME</span>.
 </p>
 <p>var in <var>text</var>.
 </p>

diff --git a/tests/testit.tex.save b/tests/testit.tex.save
@@ -30,7 +30,8 @@ Escaped backslash \code{\bsl{}x}.
 \code{\%\{\}}
 
 \LinkA{a link}{a link} and some to known destinations:
-\LinkA{weighted.mean}{weighted.mean}, \code{\LinkA{\{}{Paren}}
+\code{\LinkA{weighted.mean}{weighted.mean}}, \LinkA{dito}{dito},
+\code{\LinkA{\{}{Paren}}, \LinkB{\env{R\_HOME}}{R.Rul.HOME}.
 
 var in \var{text}.
 

diff --git a/tests/testit.txt.save b/tests/testit.txt.save
@@ -22,7 +22,8 @@ _D_e_t_a_i_l_s:
 
      '%{}'
 
-     a link and some to known destinations: weighted.mean, '{'
+     a link and some to known destinations: 'weighted.mean', dito, '{',
+     'R_HOME'.
 
      var in <text>.