tweak r89393 and update bibcite description

git-svn-id: https://svn.r-project.org/R/trunk@89702 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: smeyer

doc/manual/R-exts.texi

@@ -8708,9 +8708,9 @@ UTF-8 in @LaTeX{} is quite low.
 @node Bibliographic citations and references
 @section Bibliographic citations and references
 
-For R at least 4.6.0 one can auto-generate bibliographic citations and
+For @R{} at least 4.6.0 one can auto-generate bibliographic citations and
 references from bibentries in bibliographic databases in R or Bib@TeX{}
-formats.  This is implemented via build stage @code{\Sexpr} macros
+formats.  This is implemented via build-stage @code{\Sexpr} macros
 (@pxref{Dynamic pages}) in the file @file{share/Rd/macros/system.Rd} of
 the @R{} source or home directory.  For @HTML{} output, the citations
 are conveniently hyperlinked to the corresponding references.
@@ -8719,24 +8719,25 @@ Textual and parenthetical citations are obtained via, respectively,
 @code{\bibcitet} and @code{\bibcitep} (the naming follows that of
 @code{\citet} and @code{\citep} in the @LaTeX{} @code{natbib} package
 (@uref{https://mirrors.ctan.org/macros/latex/contrib/natbib, Daly
-2010}).  These macros both take a comma separated @var{citespec} list as
-argument, where a @var{citespec} can be a @var{keyspec} or of the form
+2010}).  These single-argument macros both take either a comma-separated
+list of one or more @var{keyspec}s or a single @var{citespec} of the form
 @code{@var{before}|@var{keyspec}|@var{after}} with both @samp{|}
 mandatory and @var{before} and @var{after} possibly empty text to be
-inserted before and after the citation if not empty.  If these texts
-contain commas, these can be backslash-escaped: see the examples below.
+inserted before and after the citation if not empty.
 
 A @var{keyspec} is either a simple @var{key} or of the form
-@code{@var{pkg}::@var{key}}.  In the former case, @var{key} is taken as
-the key of a bibentry in R's system bibentry data base (available via
-the currently unexported @code{tools:::R_bibentries()} with sources in
-the @file{.R} files in the @file{share/bibentries} directory of the R
-sources).  In the latter case, @var{key} is looked up in the bibentry
+@code{@var{pkg}::@var{key}}.
+In the latter case, @var{key} is looked up in the bibentry
 data base of package @var{pkg}, made available in the packages sources
 either as @file{inst/REFERENCES.R} in R format (an R code file encoded
 in UTF-8 with calls to @code{bibentry()}, as for the
 @file{inst/CITATION} file) or as @file{inst/REFERENCES.bib} in Bib@TeX{}
 format (this needs @CRANpkg{bibtex} to be installed).
+A simple @var{key} without a @var{pkg} prefix is taken as the key of a
+``local'' bibentry (from the package containing the Rd file) or of R's
+system bibentry data base (available via the currently unexported
+@code{tools:::R_bibentries()}, with sources in R's
+@file{share/bibliographies} directory).
 
 References (usually in the @code{\references} section) are obtained via
 @code{\bibshow}, which takes a comma-separated @var{keyspec} list as
@@ -8761,11 +8762,11 @@ For example,
 gives a textual citation of the ``@emph{Blue Book}''
 (`@I{Becker, Chambers, and Wilks (1988)}' when first encountered),
 @example
-\bibcitep@{e.g.\,|R:Chambers+Hastie:1992|page 123@}
+\bibcitep@{|R:Chambers+Hastie:1992|page 123@}
 @end example
 @noindent
 gives a parenthetical citation of a page in the ``@emph{White Book}''
-(`@I{(e.g., Chambers and Hastie 1992, page 123)}' when first encountered).
+(`@I{(Chambers and Hastie 1992, page 123)}' when first encountered).
 An Rd file having cited the above two and also wanting to include the
 ``@emph{Green Book}'' in its references could use
 @example
@@ -8802,7 +8803,7 @@ disambiguate by manually adding the suffixes to the year fields, e.g.
 
 As these macros are evaluated at build stage, packages using these and
 built with R >= 4.6.0 can be used without problems for R < 4.6.0.
-(However, checking such packages with R < 4.6.0 will warn that these
+(However, checking such packages with R < 4.5.3 will warn that these
 macros are unknown.)
 
 @node Processing documentation files

src/library/tools/R/bibtools.R

@@ -62,8 +62,8 @@ function(keys)
                pkg <- if(length(dir)) {
                           basename(dir[1L])
                       } else character()
-               c(R_bibentries(),
-                 .bibentries_from_REFERENCES(dir, pkg))
+               c(.bibentries_from_REFERENCES(dir, pkg),
+                 R_bibentries())
            } else NULL
     if(!any(ind)) {
         ## Special-case for efficiency.