Functions for manipulation of R documentation objects, including functions reprompt() and ereprompt() for updating 'Rd' documentation for functions, methods and classes; 'Rd' macros for citations and import of references from 'bibtex' files for use in 'Rd' files and 'roxygen2' comments; 'Rd' macros for evaluating and inserting snippets of 'R' code and the results of its evaluation or creating graphics on the fly; and many functions for manipulation of references and Rd files.
Rdpack provides functions for manipulation of R documentation objects, including functions
reprompt()
and ereprompt()
for updating existing Rd documentation for functions, methods
and classes; Rd macros for citations and import of references from bibtex
files for use in
Rd
files and roxygen2
comments (\insertRef
, \insertCite
, \insertAllCited
); Rd
macros for evaluating and inserting snippets of R code and the results of its evaluation
(\printExample
) or creating graphics on the fly (\insertFig
); and many functions for
manipulation of references and Rd files.
Install the latest stable version from CRAN:
install_packages("Rdpack")
You can also install the development version of Rdpack
from Github:
library(devtools)
install_github("GeoBosh/Rdpack")
The simplest way to insert Bibtex references is with the Rd macro \insertRef
.
Just put \insertRef{key}{package}
in the documentation to insert item with key
key
from file REFERENCES.bib
in your package package
. Alternatively, use
one or more \insertCite{key}{package}
commands to cite works from
REFERENCES.bib
, then issue a single \insertAllCited{}
directive to produce a
list of all cited references. For this to work
the DESCRIPTION
file of the package needs to be amended, see below the full
details.
To prepare a package for importing BibTeX references it is necessary to tell the
package management tools that package Rdpack and its Rd macros are needed. The
references should be put in file inst/REFERENCES.bib
. These steps are
enumerated below in somewhat more detail, see also the vignette
Inserting_bibtex_references
.
Add the following lines to file "DESCRIPTION":
Imports: Rdpack
RdMacros: Rdpack
Make sure the capitalisation of RdMacros:
is as shown. If the field
RdMacros:
is already present, add "Rdpack" to the list on that
line. Similarly for field "Imports:".
Add the following line to file "NAMESPACE":
importFrom(Rdpack,reprompt)
The equivalent line for roxygen2
is
#' @importFrom Rdpack reprompt
Create file REFERENCES.bib
in subdirectory inst/
of your package and
put the BibTeX references in it.
Once the steps outlined above are done, references can be inserted in the documentation as
\insertRef{key}{package}
where key
is the bibtex key of the reference and package
is your package.
This works in Rd
files and in roxygen
documentation chunks.
Usually references are put in section references
. In an Rd
file this might look
something like:
\references{
\insertRef{Rdpack:bibtex}{Rdpack}
\insertRef{R}{bibtex}
}
The equivalent roxygen2
documentation chunk would be:
#' @references
#' \insertRef{Rpack:bibtex}{Rdpack}
#'
#' \insertRef{R}{bibtex}
The first line above inserts the reference with key Rpack:bibtex
in Rdpack's
REFERENCES.bib. The second line inserts the reference labeled R
in file
REFERENCES.bib from package bibtex
.
The example above demonstrates that references from other packages can be
inserted (in this case bibtex
), as well. This is strongly discouraged for
released versions but is convenient during development. One relatively safe use
is when the other package is also yours - this allows authors of multiple
packages to not copy the same refences to each of their own packages.
For further details see the vignette
Inserting_bibtex_references
or open it from R
:
vignette("Inserting_bibtex_references", package = "Rdpack")
(The latest version of the vignette is at
Inserting_bibtex_references (development version on github)
.)
From version 0.6-1 of "Rdpack", additional Rd macros are available for citations. They can be used in both Rd and roxygen2 documentation.
\insertCite{key}{package}
cites key
and records it for use by
\insertAllCited
, see below. key
can contain more keys separated by commas.
\insertCite{parseRd,Rpack:bibtex}{Rdpack}
produces
(Murdoch 2010; Francois 2014)
and
\insertCite{Rpack:bibtex}{Rdpack}
gives
(Francois 2014).
By default the citations are parenthesised: \insertCite{parseRd}{Rdpack}
produces
(Murdoch 2010). To get
textual citations, like
Murdoch (2010),
put the string ;textual
at the end of the key. The references in the last two sentences
would be produced with \insertCite{parseRd}{Rdpack}
and
\insertCite{parseRd;textual}{Rdpack}
, respectively. This also works with several
citations, e.g.
\insertCite{parseRd,Rpack:bibtex;textual}{Rdpack}
produces:
Murdoch (2010); Francois (2014).
The macro \insertNoCite{key}{package}
records one or more
references for \insertAllCited
but does not cite it. Setting
key
to *
will include all references from the
specified package. For example,
\insertNoCite{R}{bibtex}
and \insertNoCite{*}{utils}
record the specified references for inclusion by \insertAllCited
.
\insertAllCited
inserts all references cited with
\insertCite
or \insertNoCite
. Putting this macro
in the references section will keep it up to date automatically.
The Rd section may look something like:
\insertAllCited{}
or, in roxygen2, the references chunk might look like this:
#' @references
#' \insertAllCited{}
To mix the citations with other text, such as ``see also'' and ``chapter 3'',
write the list of keys as a free text, starting it with the symbol @
and
prefixing each key with it. The @
symbol will not appear in the output. For
example, the following code
\insertCite{@see also @parseRd and @Rpack:bibtex}{Rdpack}
\insertCite{@see also @parseRd; @Rpack:bibtex}{Rdpack}
\insertCite{@see also @parseRd and @Rpack:bibtex;textual}{Rdpack}
produces:
(see also Murdoch 2010 and Francois 2014)
(see also Murdoch 2010; Francois 2014)
see also Murdoch (2010) and Francois (2014)
—
\insertCiteOnly{key}{package}
is as \insertCite
but does not include the key
in the list of references for \insertAllCited
.
Bibliography styles for lists of references are supported from Rdpack (>= 0.8). Currently the only alternative offered is to use long names (Georgi N. Boshnakov) in place of the default style (Boshnakov GN). More comprehensive alternatives can be included if needed or requested.
To cause all lists of references produced by \insertAllCited
in a package to appear with
full names, add .onLoad()
function to your package. If you don't have .onLoad()
, just
copy the following definition:
.onLoad <- function(lib, pkg){
Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames")
invisible(NULL)
}
If you already have .onLoad()
, add the line containing the
Rdpack::Rdpack_bibstyles
call to it.
After installling/reloading your package the lists of references should appear with long author names. "Rdpack" itself now uses this style.
The described procedure works transparently in roxygen2
chunks and with Hadley
Wickham's package devtools
. Packages are built and installed properly with
the devtools
commands and the references are processed as expected.
Currently (2017-08-04) if you run help commands ?xxx
for functions from the
package you are working on in developement mode and their help pages contain
references, you may encounter some puzzling warning messages, something like:
1: In tools::parse_Rd(path) :
~/mypackage/man/abcde.Rd: 67: unknown macro '\insertRef'
These warnings are harmless and can be ignored — the help pages are built
properly and no warnings appear outside developer's mode, e.g. in a separate R
session1. Even better, use the function viewRd()
described
below to view the required help file.
The functions underlying the processing of references and citations intercept errors, such as missing BibTeX labels or badly formed items in REFERENCES.bib, and issue informative warnings during the building and installation of the package, so that the developer is alerted but the package can still be built and installed. In these cases the functions usually insert a suitable text in the documentation, as well. If you encounter a situation contradicting this description, it is probably a bug — please report it (but check first for the typical errors listed below).
A non-decipherable error message is probably caused by one of the following typical errors:
misspelled RdMacros:
field in file DESCRIPTION. The safest way to avoid this
is to copy it from the DESCRIPTION file of a working package.
omitted second argument of a reference or citation macro. Most of these macros have the package name as a second argument.
These errors occur during parsing of the Rd files, before the control is passed
to the Rdpack
's macros.
In principle, BibTeX entries may contain arbitrary Latex markup, while the Rd format supports only a subset. As a consequence, some BibTeX entries may need some editing when included in REFERENCES.bib2. Only do this for entries that do not render properly or cause errors, since most of the time this should not be necessary.
If mathematics doesn't render properly replace the Latex dollar syntax with Rd's \eqn
,
e.g. $x^2$
with \eqn{x^2}
. This should not be needed for versions of Rdpack
0.8-4 or later.
Some Latex macros may have to be removed or replaced with suitable Rd markup. Again,
do this only if they cause problems, since some are supported, e.g. \doi
.
See also the overview help page, help("Rdpack-package")
, of package "Rdpack"
.
Among other things, it contains some dummy references which illustrate the above.
If a package has a declared encoding (in file DESCRIPTION
), REFERENCES.bib
is read-in
with that encoding3. Otherwise, the encoding of REFERENCES.bib
is assumed to be
UTF-8 (which includes ASCII as a subset).
Note that BibTeX entries downloaded from online databases and similar sources may contain unexpected characters in other encodings, e.g. 'latin1'. In such cases the check tools in R-devel (since about 2018-10-01) may give warnings like:
prepare_Rd: input string 1 is invalid in this locale
To resolve this, convert the file to the declared encoding or UTF-8. Alternatively, replace the offending symbols with their classic TeX/LaTeX equivalents (which are ASCII). Non-ASCII symbols in BibTeX entries obtained from online databases are often in fields like "Abstract", which are normally not included in lists of references and can be deleted from REFERENCES.bib.
One way to check for non-ASCII symbols in a file is tools::showNonASCIIfile()
.
Internally, LaTeX sequences standing for accented Latin characters, such as \'e
and \"o
,
are converted to UTF-8. So, even if the file REFERENCES.bib is pure ASCII, it may implicitly
give raise to non-ASCII characters. This may cause R's checking tools to complain about
non-ASCII characters even after it has been verified that there are none. If this happens,
add the encoding declaration to file DESCRIPTION4:
Encoding: UTF-8
Needless to say, make sure that there are really no characters from encodings like 'latin1'.
A function, viewRd()
, to view Rd files in the source directory of a package
was introduced in version 0.4-23 of Rdpack
. A typical user call would look
something like:
Rdpack::viewRd("./man/filename.Rd")
By default the requested help page is shown in text format. To open the page in a browser, set argument 'type' to "html":
Rdpack::viewRd("./man/filename.Rd", type = "html")
viewRd()
renders references and citations correctly, since it understands Rd macros.
Users of 'devtools' can use viewRd
in place of help()
to view rendered Rd
sources in development mode. This should work also in development mode on any
platform (e.g. RStudio, Emacs/ESS, Rgui).
Rdpack::reprompt()
updates Rd
documentation. In the most common case when it
is called on an Rd
file, it updates the documentation of all functions,
methods and classes documented in the file. For functions this includes
updating the usage section, adding missing aliases and \item
's for arguments
not described yet. For methods and classes entries for new methods and slots
are updated in a similar way. See the documentation for details.
Rdpack::reprompt()
can also be invoked on an object or the name of an object,
just as utils::prompt
. In that case it checks for installed documentation for
the object and works on it if found. Otherwise it creates an Rd
file with
initial content similar to the one generated by utils::prompt
but modified
so that the package can be built.
If a new function, say newfun
is to be documented in an existing Rd file, just
add newfun()
to the usage section in the file and call Rdpack::reprompt()
to
insert the correct usage statement, add an alias, and add items for any new
arguments.
Rdpack::reprompt()
does not remove anything that has become obsolete
but it alerts the user to remove aliases, methods, and descriptions of arguments
that have been removed.
To open the reprompt()
-ed file, argument edit
can be used. For this to
work, options("editor")
needs to be set suitably but it usually is. If edit = TRUE
, then Rdpack::reprompt()
will open the Rd file in an editor. For more
convenient access to this feature, use Rdpack::ereprompt()
(edit reprompt),
which calls Rdpack::reprompt()
with edit = TRUE
and sets the output filename
to be the same as the input filename.
In RStudio, reprompt()
can be invoked on the Rd
file being edited or the
selected name of an object in a source code file using RStudio add-in
Repropmpt
(contributed by Duncan Murdoch). Obviously, this makes sense only
for Rd files not generated by roxygen2
.
In Emacs/ESS there are various ways to use Rdpack::reprompt()
and
Rdpack::ereprompt()
. If options("editor")
is set to emacsclient
,
Rdpack::ereprompt
is one option. It can also be assigned to a key (wrapped in
Elisp code), for example to be invoked on the currently edited file. Such a
function and example key binding can be found at georgisemacs.
Rdpack
provides a macro that takes a chunk of R code, evaluates it, and includes both the code and
the results in the rendered documentation. The layout is similar to that in the R console but
the code is not prefixed with anything and the output is prefixed with comment symbols.
For example,
\printExample{2+2; a <- 2*3; a}
gives
2 + 2
##: 4
a <- 2 * 3
a
##: 6
The help page of ?Rdpack::promptUsage
contains a number of examples created with
\printExample
. The corresponding Rd file can be obtained from the package tarball or from
https://github.com/GeoBosh/Rdpack/blob/master/man/promptUsage.Rd.
Vignette Inserting_figures_and_evaluated_examples
gives further details.
The macro \runExamples
can be used as a replacement of section examples
. For example, if
the following code is put at the top level in an Rd file (i.e. not in a section):
\runExamples{2+2; a <- 2*3; a}
then it will be evaluated and replaced by a normal section examples:
\examples{
2 + 2
##: 4
a <- 2 * 3
a
##: 6
}
This generated examples section is processed by the standard R tools (almost) as if it was there from the outset. In particular, the examples are run by the R's quality control tools and tangled along with examples in other documentation files5. A small example package using this feature is at runExamplesCheck.
Figures can be inserted with the help of the standard Rd markup command \figure
. To
generate figures on the fly, package "Rdpack"
provides the Rd macro \insertFig
which
takes a snipped of R code, evaluates it and inserts the plot produced by it (using
\figure
). \insertFig
takes three arguments: a filename, the package name and the code to
evaluate to produce the figure. For example,
\insertFig{cars.png}{mypackage}{x <- cars$speed; y <- cars$dist; plot(x,y)}
will evaluate the code, save the graph in file "man/figures/cars.png"
subdirectory of
package "mypackage"
, and include the figure using \figure
.
See vignette Inserting_figures_and_evaluated_examples
for more details.
Versions of Rdpack
on Github are almost always fully functional (at least
passing R CMD check --as-cran
), and so use a three-part version number. If a
version is really unstable, I would use the conventional fourth part
.9000
. For release on CRAN, the version is incremented to
x.x.0
6.
Note that if Rdpack (>= x.x.0)
is required, it can be abbreviated to
Rdpack (>= x.x)
.
1 If you care, here is what happens. These warnings appear
because devtools
reroutes the help command to process the developer's Rd
sources (rather than the documentation in the installed directory) but doesn't
tell parse_Rd
where to look for additional macros. Indeed, the message above
shows that the error is in processing a source Rd file in the development
directory of the package and that the call to parse_Rd
specifies only the
file.
2 Thanks to Michael Dewey for suggesting the discussion of this.
3 From Rdpack (>=0.9-1)
The issue of not handling the encoding was raised by
Professor Brian Ripley.
4 Admittedly, this is not ideal since the user should not need to care how things are processed internally but I haven't pinpointed the exact cause for this.
5 In versions of R
before 3.6.0
the macro \runExamples
may cause
R CMD check
to give a warning warning about unknown \Sexpr
section at top level.
6 I adopted this versionning scheme from Rdpack 0.7.0
.
Updated the vignette about insertFig
, printExample
and \runExamples
, to
reflect the lifting of some limitations of Rd processing vefore R 3.6.0
.
Vignette /Inserting BibTeX references/ now includes a section on bibliography styles. This section was previously only in README.
The fix in Rdpack 0.10-3 (see below) for an issue introduced in R-devel in Oct
2018 will be made permanent, at least for now. This fix resolves also a
similar issue in package pkgdown
, see the discussion at
https://github.com/GeoBosh/Rdpack/issues/9 for details and further links.
\insertAllCited{}
to appear in a single paragraph in the html
rendering of the Rd documentation.added pkgdown site to DESCRIPTION.
README and the vignette about evaluated examples now state that R-devel no
longer gives warnings about \Sexpr
not being a top level section.
This means that macro runExamples
which creates section 'Examples'
containing code and results of evaluation will be useable in CRAN packages.
new function Rdo_fetch()
gets the Rd object representing a help page from an
installed or source package. It works also for packages under devtool's
developer's mode
The site created with pkgdown contains fewer errors now. (Note that the documentation builds without error with R's tools).
Started moving tests from my local setup to testthat.
now REFERENCES.bib
is read-in using the declared encoding for the
corresponding package. If there is no declared encoding, "UTF-8" is assumed.
Now macros \insertCite
and \insertCiteOnly
use the correct results=rd
instead of results=Rd
. This was not catched by R
s building tools but
caused errors when processed with pkgdown::build_site()
. Fixes issue#8. Also
fixes r-lib/pkgdown#784.
Thanks to Jay Hesselberth for uncovering
this.
now references produced by the citation macros for BibTeX entries of type
@book
and @incollection
treat field 'series' similarly to other BibTeX
styles, including JSS (issue#7 raised by Kisung You). Note that even though
the underlying base R tools are based on JSS, they treat this field
differently.
Bugfix: now Rd macro \printExample
evaluates the expressions in the correct
environment.
help page of get_usage
gets a fairly complete Details section with numerous
evaluated examples.
now run_examples()
escapes %
by default, before returning the text. This is
needed for text that is to be included in an Rd file. It can be turned off by
setting the new argument escape
to FALSE
.
now reprompt()
gives a more informative error message if an Rd file
describes a non-existent S4 class. This is not captured by R
s tools. It can
happen during development if a class is removed.
now reports printed by reprompt()
about methods documented in Usage
sections, but no longer existing, are more readable. This is due to a new
print method for (the mostly internal) class "f_usage".
Many features of Rdpack are best demonstrated on a package. The new package
RdpackTester under ./inst/examples
now makes this easier.
now the help page "predefined.Rd" does not print some tables twice in the pdf
manual. (This was due to using \if{latex}{}{}' instead of
\ifelse{latex}{}{}' for those tables.)
also in "predefined.Rd", removed illegal use of vertical bars (in column
specifications of tabular environments) from the pure LaTeX code in the
\ifelse
clause(s) and wrapped them in \out{}
.
in "get_sig_text.Rd", replace help()
with utils::help()
to avoid warnings
from more stringent R CMD check
. Similarly, in "Rdpack-package.Rd" replace
packageDescription()
with utils::packageDescription()
. This may
be needed in \Sexpr
's more generally (TODO: check if these would still
be needed if the symbols are imported by the package.)
\eqn{}
.new macro \printExample
for inclusion of example computations in narrative sections, such
as Details
. The code is evaluated and printed similarly to R
sessions but the code is
not prefixed and the output is prefixed with comment symbols, eg.
2+2
##: 4
new experimental macro \runExamples
for use as top level section in an Rd
file as a replacement of section \examples
. \runExamples{code}
evaluates
the code and creates section \examples
containing the code and the results
(similarly to \printExample
). So, \runExamples{2 + 2}
produces
\examples{
2 + 2
##: 4
}
The generated section examples
is processed by R's documentation tools
(almost) as if it was there from the outset.
new experimental macro \insertFig
to create a figure with R
code and
include it in the documentation. The related macro \makeFig
just creates a
graphics file, which can be included with the standard Rd command \figure
.
new vignette gives a brief description of the new macros.
\insertRef
and \insertAllCited
(see
below) - in the rendered News
on CRAN the backslashed words had disappeared.\insertRef
and \insertAllCited
macros now support bibstyles
for
formatting references (feature requested by Jamie Halliday, issue#5). Use
Rdpack (>= 0.8)
in Imports:
to use this feature. Currently only long
author names are supported but complete support for styles can be added
trivially if requested.
updates to the documentation, in particular the bulk of Rdpack-package.Rd was from 2011!
improvements to handling of free form citations in textual mode:
(bugfix) now the whole citation is not parenthesised in textual mode,
the handling for textual mode was incomplete in that additional text after the citation was not put inside the parentheses along with the year.
updates to the documentation.
fix a bug in Rdo_locate_core_section()
.
consolidated the changes introduced since the previous CRAN release of Rdpack
(it was 0.5-5) in preparation for the next release. Users of the new macros
for citation can use Rdpack (>=0.7)
in the Imports:
field of file
"DESCRIPTION" to ensure that they are available.
comprehensive overhaul of handling of errors and warnings during processing of
references and citations. In particular, such errors should (in most cases)
produce only warnings during R CMD build
and R CMD INSTALL
, and not
prevent the package from being built and installed.
Unresolved BibTeX keys produce warnings during building and installation of the package, but not errors. Dummy entries are inserted in the documentation explaining what was amiss (currently with 'author' A Adummy).
new Rd macros for citations
\insertCite
inserts citation(s) for one or more keys and records the keys
for \insertAllCited
(see below).
\insertCiteOnly
is similar to \insertCite
but does not record the keys.
\insertNoCite
records the keys but does not produce a citation.
\insertAllCited
prints a bibliography including all references recorded by
\insertCite
and \insertNoCite
.
new entries in this file will use markdown syntax.
updates to the documentation.
get_bibentries()
gets a new argument "everywhere". When is is TRUE, the
default, unescaped percents are escaped in all bibtex fields, otherwise the
replacement is done only in field "URL".
removed several print()
statements which were accidentally left in the
code in v. 0.5-6.
updated help page of get_bibentries()
and included examples.
cleaned up the imports in NAMESPACE.
insert_ref()
and Rd macro \insertRef
should now work ok in the presence
of percent encoded symbols in URL field of a BibTeX entry. Closes issue
"Unexpected END_OF_INPUT error (URL parsing?)", see
Rdpack issue 3, raised by
jdnewmil.
get_bibentries()
now takes care of percent encoded symbols in URLs. It now
returns an object from class "bibentryRd", which inherits from "bibentry" but
has its own print method which escapes or unescapes the percent signs in URLs
depending on the requested output style. This was also reported by by
jdnewmil in issue#3 referenced above.
get_bibentries()
now tries to load the bib
file from the development
directory of argument "package", in case it is in development mode under
"devtools". (Even though the search is with system.file()
, which devtools
replaces with its own version, the bib file still needs to be looked for in
"inst/", i.e. it is not in the root directory as is the case in installed
packages.)
Streamlined the help page of reprompt()
and Rdpack-package
.
new argument, edit', in
reprompt()` opens the Rd file after updating it.
new function ereprompt()
(e' for _edit_)* opens
reprompt()with suitable defaults to replace the original Rd file and open it in an editor, otherwise equivalent to
reprompt()`.
now if infile
does not exist, reprompt()
, and hence ereprompt()
, strips
the directory part, finds the root of the package directory, and looks for the
file under man/
(this uses package rprojroot
'). In particular, if the
working directory is anywhere under the package root, infile
can be simply
the name of the Rd file, without path.
now README.md is generated from README.org. I changed the layout and amended the information in it.
README.* now get links to
georgisemacs for an emacs
function to reprompt()
the Rd file at point.
viewRd()
now works also when the file is from a package under devtools'
development mode on any platform (e.g. RStudio, Emacs/ESS, Rgui).
new RStudio add-in 'Reprompt`, contributed by Duncan Murdoch.
If the file being edited in the code editor is an Rd file it calls
reprompt()
. If the file is as R source file, it looks for the help page of a
selected object name and works on it if found, otherwise creates one.
added the version of Rdpack
to the abstract of the vignette. This seems
more informative than giving the compilation date.
now reprompt()
doesn't give spurious warnings about unknown Rd macros when
the Rd file contains user defined Rd macros. These warnings were harmless and
rare, but alarming and annoying.
fixed a bug in inspect_args()
which caused the warning "In is.na(x) :
is.na() applied to non-(list or vector) of type 'NULL'" in reprompt()
, when
the signature of a function in "Usage" section was empty.
added the github url to DESCRIPTION.
now give a more informative warning if a key is missing from REFERENCES.bib (thanks to Kisung You for suggesting this).
tools::parse_Rd()
rather than parse_Rd()
(before this was not necessary
since 'gbRd' depended on 'tools').new function viewRd()
parses and shows an Rd file in a source package.
May be particularly helpful for devtools developers.
revamped the vignette, added additional explanations of possible issues.
new functions makeVignetteReference()
and vigbib()
generate Bibtex
references for vignettes in a package.
Added the requirement to Import Rdpack to the help page of
insert_ref()
. (It was out of sync with the vignette.)
Updated Description in DESCRIPTION, which was also out of sync with the vignette.
Bug fix in the vignette: changed \@references
to @references
in the
roxygen2 example.
Edited and amended vignette "Inserting_bibtex_references", including:
additional explanation and an example,
requirement to import Rdpack and a mention of travis etc.
paragraph about devtools.
changed the URL for parse_Rd.pdf in REFERENCES.bib to https.
new facility for inserting references from BibTeX files - just put the line:
RdMacros: Rdpack
in the DESCRIPTION
file of your package and the references in
inst/REFERENCES.bib
. Then put \inserRef{key}{yourpackage}
in
documentation chunks to insert item key
from the bib file. This works with
both manually created Rd files and roxygen comments, see the documentation for
details.
from now on, put (CRAN) next to versions published on CRAN (as above)
a minor correction in file NEWS.
reprompt()
and
rebib()
.don't export parse_text
corrected bug in reprompt for S4 classes - new slots were not handled
correctly (see slots.R
for details).
reprompt for S4 methods* if the methods documentation describes methods that do not exist, print an informative message for the user. (Such methods are also printed for debugging purposes but in non-user friendly form.)
methods
in Imports:
- around R-devel version 2015-07-01 r68620
not including it triggers warnings)new functions .whichtageq
and .whichtagin
; replaced most calls to
toolsdotdotdotRdTags
with these.
removed toolsdotdotdotRdTags
removed :::
calls from code; copied some functions from tools
to achieve
this (see "threedots.R"). Renamed the functions replacing :::
with
dotdotdot.
export by name (not the generic export pattern); preparation for more selective export of functions in the future.
new functions: Rdo_get_argument_names
, Rdo_get_item_labels
dependence bibtex
becomes "Imports". tools
and gbRd
remain (for now)
"Depends" since functions from them are used in some examples without
require()
's.
rebib()
: now outfile=""
can be used to request overwriting infile
.
(a small convenience; before the change, one could do this by giving the
outfile
and infile
the same values.)
Bug fix: predefined.Rd
contained \tabular
environments with vertical bars,
|
, in the format specification. This is not documented in "Writing R exts"
but works for LaTeX and remained unnoticed by me and R CMD check. However,
rendering the help page for the objects documented in "predefined.Rd" gave an
error in html and text mode. Package installation failed only if html was
requested at build time.
small changes in the documentation
new major feature: processing references from Bibtex files. The top user
level function is rebib()
, which updates section "references" in an Rd
file. promptPackageSexpr()
has been updated to use this
feature. inspect_Rdbib()
can be used in programming.
new auxiliary functions for work with bibentry
objects.
new convenience programming functions for Rd objects.
some small bug fixes.
some gaps in the documentation filled.
reprompt()
was not handling properly S4 replacement methods. Changed the
parsing of the arguments to rectify this. Some other functions also needed
correction to handle this.Depends
field in DESCRIPTION file updated to require R 2.15.0 or later.
(because of a few uses of paste0()
in recent code.)