Experiment with auto-generating citations and references in Rd files.

hornik · hornik · commit 0c4353f103bd · 2025-07-28T10:51:21.000Z
git-svn-id: https://svn.r-project.org/R/trunk@88462 00db46b3-68df-0310-9c12-caf00c1e9a41
diff --git a/share/Rd/macros/system.Rd b/share/Rd/macros/system.Rd
@@ -58,4 +58,7 @@
 
 % Experimental:
 \newcommand{\bibcite}{#1}
-\newcommand{\bibshow}{#1}
+% \newcommand{\bibshow}{#1}
+\newcommand{\bibcitep}{\Sexpr[results=rd,stage=build]{tools:::Rd_expr_bibcite("#1", FALSE)}}
+\newcommand{\bibcitet}{\Sexpr[results=rd,stage=build]{tools:::Rd_expr_bibcite("#1", TRUE)}}
+\newcommand{\bibshow}{\Sexpr[results=rd,stage=build]{tools:::Rd_expr_bibshow("#1")}}
diff --git a/src/library/base/man/Random.Rd b/src/library/base/man/Random.Rd
@@ -142,8 +142,12 @@ set.seed(seed, kind = NULL, normal.kind = NULL, sample.kind = NULL)
       (\emph{\I{L'Ecuyer}}, 2007).
     }
     \item{\code{"L'Ecuyer-CMRG"}:}{
-      A \sQuote{combined multiple-recursive generator} from \I{L'Ecuyer}
-      (1999), each element of which is a feedback multiplicative
+      A \sQuote{combined multiple-recursive generator} from
+      %% <FIXME: bibcite>
+      %% \I{L'Ecuyer} (1999),
+      \bibcitet{R:L_Ecuyer:1999},
+      %% </FIXME>
+      each element of which is a feedback multiplicative
       generator with three integer elements: thus the seed is a (signed)
       integer vector of length 6. The period is around
       \eqn{2^{191}}{2^191}.
@@ -301,6 +305,10 @@ set.seed(seed, kind = NULL, normal.kind = NULL, sample.kind = NULL)
   \url{https://simul.iro.umontreal.ca/testu01/tu01.html} or also
   \url{https://github.com/umontreal-simul/TestU01-2009}.
 
+  %% <FIXME bibcite>
+  %% \bibshow{R:Simard+L_Ecuyer:2007}
+  %% </FIXME>
+
   Marsaglia, G. (1997).
   \emph{A random number generator for C}.
   Discussion paper, posting on Usenet newsgroup \code{sci.stat.math} on
@@ -329,6 +337,10 @@ set.seed(seed, kind = NULL, normal.kind = NULL, sample.kind = NULL)
   \emph{Applied Statistics}, \bold{31}, 188--190; Remarks:
   \bold{34}, 198 and \bold{35}, 89.
   \doi{10.2307/2347988}.
+
+  %% <FIXME bibcite>
+  \bibshow{*}
+  %% </FIXME>
 }
 \author{of RNGkind: Martin Maechler. Current implementation, B. D. Ripley
   with modifications by Duncan Murdoch.}
diff --git a/src/library/base/man/sort.Rd b/src/library/base/man/sort.Rd
@@ -78,12 +78,21 @@ sort.int(x, partial = NULL, na.last = NA, decreasing = FALSE,
   are more than 10.)  Names are discarded for partial sorting.
 
   Method \code{"shell"} uses Shellsort (an \eqn{O(n^{4/3})} variant from
-  \bibcite{Sedgewick (1986)}).  If \code{x} has names a stable modification is
+  %% <FIXME bibcite>
+  %% \bibcite{Sedgewick (1986)}).
+  \bibcitet{R:Sedgewick:1986}.
+  %% </FIXME>
+  If \code{x} has names a stable modification is
   used, so ties are not reordered.  (This only matters if names are
   present.)
 
-  Method \code{"quick"} uses Singleton (1969)'s implementation of
-  \I{Hoare}'s Quicksort method and is only available when \code{x} is
+  Method \code{"quick"} uses
+  %% FIXME bibcite
+  %% Singleton (1969)'s implementation of \I{Hoare}'s Quicksort method
+  the implementation of \I{Hoare}'s Quicksort method from
+  \bibcitet{R:Singleton:1969}
+  %% </FIXME>  
+  and is only available when \code{x} is
   numeric (double or integer) and \code{partial} is \code{NULL}.  (For
   other types of \code{x} Shellsort is used, silently.)  It is normally
   somewhat faster than Shellsort (perhaps 50\% faster on vectors of
@@ -146,33 +155,49 @@ sort.int(x, partial = NULL, na.last = NA, decreasing = FALSE,
   refers to element numbers \emph{after removal of \code{NA}s}: see
   \code{\link{order}} if you want the original element numbers.
 
-  All attributes are removed from the return value (see Becker
-  \abbr{et al.}, 1988, p.146) except names, which are sorted.  (If
+  All attributes are removed from the return value
+  %% <FIXME bibcite>
+  %% (see Becker \abbr{et al.}, 1988, p.146)
+  \bibcitep{R:Becker+Chambers+Wilks:1988>p.146}
+  %% </FIXME>
+  except names, which are sorted.  (If
   \code{partial} is specified even the names are removed.)  Note that
   this means that the returned value has no class, except for factors
   and ordered factors (which are treated specially and whose result is
   transformed back to the original class).
 }
 
 \references{
-  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).
-  \emph{The New S Language}.
-  Wadsworth & Brooks/Cole.
-
-  Knuth, D. E. (1998).
-  \emph{The Art of Computer Programming, Volume 3: Sorting and
-    Searching}, 2nd ed.
-  Addison-Wesley.
+  %% <FIXME bibcite>
+  \bibshow{*, R:Knuth:1998}
+  %% </FIXME>
   
-  Sedgewick, R. (1986).
-  A new upper bound for Shellsort.
-  \emph{Journal of Algorithms}, \bold{7}, 159--173.
-  \doi{10.1016/0196-6774(86)90001-5}.
-
-  Singleton, R. C. (1969).
-  Algorithm 347: an efficient algorithm for sorting with minimal storage.
-  \emph{Communications of the ACM}, \bold{12}, 185--186.
-  \doi{10.1145/362875.362901}.
+  %% <FIXME bibcite>  
+  %% Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).
+  %% \emph{The New S Language}.
+  %% Wadsworth & Brooks/Cole.
+  %% </FIXME>
+  
+  %% <FIXME bibcite>    
+  %% Knuth, D. E. (1998).
+  %% \emph{The Art of Computer Programming, Volume 3: Sorting and
+  %%   Searching}, 2nd ed.
+  %% Addison-Wesley.
+  %% </FIXME>
+
+  %% <FIXME bibcite>
+  %% Sedgewick, R. (1986).
+  %% A new upper bound for Shellsort.
+  %% \emph{Journal of Algorithms}, \bold{7}, 159--173.
+  %% \doi{10.1016/0196-6774(86)90001-5}.
+  %% </FIXME>
+
+  %% <FIXME bibcite>
+  %% Singleton, R. C. (1969).
+  %% Algorithm 347: an efficient algorithm for sorting with minimal storage.
+  %% \emph{Communications of the ACM}, \bold{12}, 185--186.
+  %% \doi{10.1145/362875.362901}.
+  %% </FIXME>
 }
 \seealso{
   \sQuote{\link{Comparison}} for how character strings are collated.
diff --git a/src/library/grDevices/man/embedFonts.Rd b/src/library/grDevices/man/embedFonts.Rd
@@ -82,10 +82,13 @@ embedGlyphs(file, glyphInfo, outfile = file, options = character())
   \code{\link{postscriptFonts}},
   \code{\link{Devices}}.
 
-  \bibshow{
-  Paul Murrell and Brian Ripley (2006).
-  \dQuote{Non-standard fonts in PostScript and PDF graphics.}
-  \emph{R News}, \bold{6}(2), 41--47.
-  \url{https://www.r-project.org/doc/Rnews/Rnews_2006-2.pdf}.}
+  %% <FIXME bibcite>
+  %% \bibshow{
+  %% Paul Murrell and Brian Ripley (2006).
+  %% \dQuote{Non-standard fonts in PostScript and PDF graphics.}
+  %% \emph{R News}, \bold{6}(2), 41--47.
+  %% \url{https://www.r-project.org/doc/Rnews/Rnews_2006-2.pdf}.}
+  \bibshow{R:Murrell+Ripley:2006}
+  %% </FIXME>
 }
 \keyword{device}
diff --git a/src/library/grDevices/man/pdf.Rd b/src/library/grDevices/man/pdf.Rd
@@ -443,11 +443,14 @@ pdf(file = if(onefile) "Rplots.pdf" else "Rplot\%03d.pdf",
   More details of font families and encodings and especially handling
   text in a non-Latin-1 encoding and embedding fonts can be found in
 
-  \bibshow{
-  Paul Murrell and Brian Ripley (2006).
-  \dQuote{Non-standard fonts in PostScript and PDF graphics.}
-  \emph{R News}, \bold{6}(2), 41--47.
-  \url{https://www.r-project.org/doc/Rnews/Rnews_2006-2.pdf}.}
+  %% <FIXME bibcite>
+  %% \bibshow{
+  %% Paul Murrell and Brian Ripley (2006).
+  %% \dQuote{Non-standard fonts in PostScript and PDF graphics.}
+  %% \emph{R News}, \bold{6}(2), 41--47.
+  %% \url{https://www.r-project.org/doc/Rnews/Rnews_2006-2.pdf}.}
+  \bibshow{R:Murrell+Ripley:2006}
+  %% </FIXME>
 }
 \examples{
 \donttest{
diff --git a/src/library/grDevices/man/postscript.Rd b/src/library/grDevices/man/postscript.Rd
@@ -274,11 +274,14 @@ postscript(file = if(onefile) "Rplots.ps" else "Rplot\%03d.ps",
   More details of font families and encodings and especially handling
   text in a non-Latin-1 encoding and embedding fonts can be found in
 
-  \bibshow{
-  Paul Murrell and Brian Ripley (2006).
-  \dQuote{Non-standard fonts in PostScript and PDF graphics.}
-  \emph{R News}, \bold{6}(2), 41--47.
-  \url{https://www.r-project.org/doc/Rnews/Rnews_2006-2.pdf}.}
+  %% <FIXME bibcite>
+  %% \bibshow{
+  %% Paul Murrell and Brian Ripley (2006).
+  %% \dQuote{Non-standard fonts in PostScript and PDF graphics.}
+  %% \emph{R News}, \bold{6}(2), 41--47.
+  %% \url{https://www.r-project.org/doc/Rnews/Rnews_2006-2.pdf}.}
+  \bibshow{R:Murrell+Ripley:2006}
+  %% </FIXME>
 }
 
 \author{
diff --git a/src/library/tools/R/RdHelpers.R b/src/library/tools/R/RdHelpers.R
@@ -144,3 +144,100 @@ function(x)
                     u, x)
             )
 }
+
+R_bibliographies_dir <- 
+function()
+    file.path(R.home("share"), "bibliographies")
+
+R_bibentries <-
+function()
+{
+    bib <- readRDS(file.path(R_bibliographies_dir(), "R.rds"))
+    bib[lengths(bib$key) > 0L]
+}
+
+update_R_bibentries <-
+function(dir = NULL)
+{
+    if(is.null(dir))
+        dir <- file.path(.R_top_srcdir_from_Rd(), 
+                         "share", "bibliographies")
+    bibfiles <- Sys.glob(file.path(dir, "*.R"))
+    bibentries <-
+        do.call(c, lapply(bibfiles,
+                          utils::readCitationFile,
+                          list(Encoding = "UTF-8")))
+    saveRDS(bibentries, file.path(dir, "R.rds"))
+}
+
+Rd_expr_bibshow <-
+function(x)
+{
+    x <- trimws(x)
+    if(!nzchar(x)) {
+        ## Provide a way to clear the keys cited cache.
+        Rd_expr_bibcite_keys_cited(NULL)
+        return(x)
+    }
+    bib <- R_bibentries()
+    ## <FIXME>
+    ## Would be nice to have a common reader for possibly multi-line
+    ## comma separated values ...
+    keys <- strsplit(x, ",[[:space:]]*")[[1L]]
+    if(any(keys == "*")) {
+        keys <- c(keys, Rd_expr_bibcite_keys_cited())
+        Rd_expr_bibcite_keys_cited(NULL)
+    }
+    y <- sort(unique(bib[bib$key %in% keys]))
+    paste(sprintf("\\if{html}{\\out{<span id=\"reference+%s\">}}%s\\if{html}{\\out{</span>}}",
+                  string2id(unlist(y$key, use.names = FALSE)),
+                  toRd(y)),
+          collapse =
+              "\\if{html}{\\out{</p>}}\n\n\\if{html}{\\out{<p>}}")
+}
+
+Rd_expr_bibcite_keys_cited <- local({
+    .keys <- NULL
+    function(new, add = FALSE) {
+        if(!missing(new)) 
+            .keys <<- unique(c(if(add) .keys, new))
+        else
+            .keys
+    }
+})
+
+Rd_expr_bibcite <-
+function(x, textual = FALSE)
+{
+    x <- trimws(x)
+    bib <- R_bibentries()
+    keys <- strsplit(x, ",[[:space:]]*")[[1L]]
+    ## Allow b<k>a to specify before b and after a.
+    ## Could also use
+    ##   regmatches(keys, regexec("(.*<)?(.*)(>.*)?", keys))
+    before <- after <- rep_len("", length(keys))
+    if(any(ind <- grepl("<", keys))) {
+        before[ind] <- sub("<.*", "", keys[ind])
+        keys[ind] <- sub(".*<", "", keys[ind])
+    }
+    if(any(ind <- grepl(">", keys))) {
+        after[ind] <- sub(".*>", "", keys[ind])
+        keys[ind] <- sub(">.*", "", keys[ind])
+    }
+    ind <- keys %in% unlist(bib$key)
+    if(!all(ind)) {
+        ## <FIXME>
+        ## Should warn about keys not in the bibentries
+        before <- before[ind]
+        after <- after[ind]
+        keys <- keys[ind]
+    }
+    Rd_expr_bibcite_keys_cited(keys, TRUE)
+    ## <FIXME>
+    ## This really needs a vectorized version of cite() ...
+    before <- sprintf("\\if{html}{\\out{<a href=\"#reference+%s\">}}%s",
+                      string2id(keys), before)
+    after <- sprintf("%s\\if{html}{\\out{</a>}}", after)
+    utils::cite(keys, bib, textual, before, after)
+}
+
