# Update and Manipulate Rd Documentation Objects

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); 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.

# Installing Rdpack

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")


# Inserting Bibtex references and citations

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.

## Preparation

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.

1. 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".

2. Add the following line to file "NAMESPACE":

importFrom(Rdpack,reprompt)


The equivalent line for roxygen2 is

#' @importFrom Rdpack reprompt

3. Create file REFERENCES.bib in subdirectory inst/ of your package and put the BibTeX references in it.

## Inserting references

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).)

## Inserting citations

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}


produces:

\insertCiteOnly{key}{package} is as \insertCite but does not include the key in the list of references for \insertAllCited.

## Changing the style of references

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.

## Troubleshooting

### A puzzling message in devtools development mode

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.

### Typical errors

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.

# Viewing Rd files

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).

# Using Rdpack::reprompt()

## What it does

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.

## Reprompt and open in an editor

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.

# Inserting evaluated examples

There is 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


See vignette Inserting_figures_and_evaluated_examples for more details.

# Inserting figures/graphs/plots

Figures can be inserted with the help of the standard Rd markup command \figure. The Rd macro \insertFig provided by package \pkg{Rdpack} 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

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.02.

Note that if Rdpack (>= x.x.0) is required, it can be abbreviated to Rdpack (>= x.x).

# Footnotes

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 I adopted this versionning scheme from Rdpack 0.7.0.

# Rdpack 0.10-1 (CRAN)

• removed redundant references from REFERENCES.bib (tehy were leftovers from testing).

# Rdpack 0.10-0

• updated vignette 'Inserting_bibtex_references'.

# Rdpack 0.9-1

• 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 Rs 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 Rs 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.)

# Rdpack 0.9-0 (CRAN)

• some brush-up of the documentation for the changes since version 0.8-0 of the package.

# Rdpack 0.8-4

• now simple mathematics in BibTeX entries is rendered natively, no need to replace dollars with \eqn{}.

# Rdpack 0.8-3

• 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.

# Rdpack 0.8-2

• Now text citations use "et al." when there are three or more authors. (Issue#6 reported by Timothy P. Bilton)

# Rdpack 0.8-1

• in this file, added backticks to \insertRef and \insertAllCited (see below) - in the rendered News on CRAN the backslashed words had disappeared.

# Rdpack 0.8-0 (CRAN)

• \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!

# Rdpack 0.7-1

• 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.

• fix a bug in Rdo_locate_core_section().

# Rdpack 0.7-0 (CRAN)

• 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).

# Rdpack 0.6-x

• 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.

# Rdpack 0.5-7

• 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.

# Rdpack 0.5-6

• 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.)

# Rdpack 0.5-5 (CRAN)

• Streamlined the help page of reprompt() and Rdpack-package.

• new argument, edit', inreprompt() opens the Rd file after updating it.

• new function ereprompt() (e' for _edit_)* opensreprompt()with suitable defaults to replace the original Rd file and open it in an editor, otherwise equivalent toreprompt().

• 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).

# Rdpack 0.5-4.9000

• 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.

# Rdpack 0.5-4

• 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.

# Rdpack 0.5-3 (CRAN)

• The warning message about a missing reference key now appears also in the respective help page.

# Rdpack 0.5-2

• 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).

# Rdpack 0.5-1 (CRAN)

• an example was not restoring the working directory.

# Rdpack 0.5-0

• moved gbRd from Depends to Imports and adjusted some examples to use tools::parse_Rd() rather than parse_Rd() (before this was not necessary since 'gbRd' depended on 'tools').

# Rdpack 0.4-23

• new function viewRd() parses and shows an Rd file in a source package.
May be particularly helpful for devtools developers.

• new functions makeVignetteReference() and vigbib() generate Bibtex references for vignettes in a package.

# Rdpack 0.4-22 (CRAN)

• 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.

# Rdpack 0.4-21 (CRAN)

• Edited and amended vignette "Inserting_bibtex_references", including:

• additional explanation and an example,

• requirement to import Rdpack and a mention of travis etc.

• changed the URL for parse_Rd.pdf in REFERENCES.bib to https.

# Rdpack 0.4-20 (CRAN)

• cleaned up some minor CRAN issues.

# Rdpack 0.4-19

• 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.

# Rdpack 0.4-18 (CRAN)

• from now on, put (CRAN) next to versions published on CRAN (as above)

• a minor correction in file NEWS.

# Rdpack 0.4-17

• In file DESCRIPTION, changed reprompt and rebib to reprompt() and rebib().

# Rdpack 0.4-16

• 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.)

• included methods in Imports: - around R-devel version 2015-07-01 r68620 not including it triggers warnings)

# Rdpack 0.4-8

• new functions .whichtageq and .whichtagin; replaced most calls to toolsdotdotdotRdTags with these.

• removed toolsdotdotdotRdTags

# Rdpack 0.4-7

• 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

# Rdpack 0.4-5

• 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

# Rdpack 0.4-1

• 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.

# Rdpack 0.3-11

• 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.

# Rdpack 0.3-10

• Depends field in DESCRIPTION file updated to require R 2.15.0 or later. (because of a few uses of paste0()` in recent code.)

# Rdpack 0.3-8 (CRAN)

• first public version

# Reference manual

install.packages("Rdpack")

0.11-0 by Georgi N. Boshnakov, 10 days ago

https://github.com/GeoBosh/Rdpack https://geobosh.github.io/Rdpack/

Report a bug at https://github.com/GeoBosh/Rdpack/issues

Browse source code at https://github.com/cran/Rdpack

Authors: Georgi N. Boshnakov [aut, cre] , Duncan Murdoch [ctb]

Documentation:   PDF Manual