Rdpack/ 0000755 0001762 0000144 00000000000 13575267043 011472 5 ustar ligges users Rdpack/NAMESPACE 0000644 0001762 0000144 00000004606 13501141722 012677 0 ustar ligges users import(methods)
importFrom(utils, bibentry, browseURL, capture.output, cite, file.edit,
getAnywhere, getS3method, head, help,
packageDescription, packageVersion, person, prompt, vignette)
importFrom(tools, parse_Rd, toRd, checkRd, Rd2txt,
bibstyle, latexToUtf8, parseLatex, deparseLatex)
importFrom(grDevices, dev.off, png)
importFrom(gbRd, Rd_help2txt)
importFrom(bibtex, read.bib)
S3method(as.character, f_usage)
S3method(print, f_usage)
S3method(print, bibentryRd)
export(
append_to_Rd_list
, as.character.f_usage
, bibentry_key
, c_Rd
, char2Rdpiece
, compare_usage1
, deparse_usage
, deparse_usage1
, format_funusage
, get_bibentries
, get_sig_text
, get_usage
, get_usage_text
, insert_ref
, inspect_args
, inspect_clmethods
, inspect_Rd
, inspect_Rdbib
, inspect_Rdclass
, inspect_Rdfun
, inspect_Rdmethods
, inspect_signatures
, inspect_slots
, inspect_usage
, is_Rdsecname
, list_Rd
, pairlist2f_usage1
, parse_1usage_text
, parse_pairlist
, parse_Rdname
, parse_Rdpiece
, parse_Rdtext
# , parse_text
, parse_usage_text
, promptPackageSexpr
, promptUsage
, rattr
, Rd_combo
, Rdapply
, Rdo_append_argument
, Rdo_collect_aliases
, Rdo_comment
, Rdo_drop_empty
, Rdo_empty_sections
, Rdo_flatinsert
, Rdo_flatremove
, Rdo_get_argument_names
, Rdo_get_insert_pos
, Rdo_get_item_labels
, Rdo_insert
, Rdo_insert_element
, Rdo_is_newline
, Rdo_item
, Rdo_locate
, Rdo_locate_core_section
, Rdo_locate_leaves
# , Rdo_locate_leaves2
# , Rdo_locate_predefined_section
, Rdo_macro
, Rdo_macro1
, Rdo_macro2
, Rdo_modify
, Rdo_modify_simple
, Rdo_newline
, Rdo_piece_types
, Rdo_piecetag
, Rdo_predefined_sections
, Rdo_Rcode
, Rdo_remove_srcref
, Rdo_reparse
, Rdo_replace_section
, Rdo_sections
, Rdo_sectype
, Rdo_set_section
, Rdo_show
, Rdo_sigitem
, Rdo_tag
, Rdo_tags
, Rdo_text
, rdo_text_restore
, rdo_top_tags
, Rdo_verb
, Rdo_which
, Rdo_which_tag_eq
, Rdo_which_tag_in
, Rdo2Rdf
, Rdreplace_section
, Rdtagapply
, rebib
, reprompt
, RStudio_reprompt
, S4formals
# , toolsdotdotdot.Rd_drop_nodes_with_tags
# , toolsdotdotdot.Rd_get_metadata
# , toolsdotdotdotfetchRdDB
# , toolsdotdotdotRdTags
, update_aliases_tmp
# , utilsdotdotdot.getHelpFile
, viewRd
, makeVignetteReference
, vigbib
, ereprompt
, insert_citeOnly
, insert_all_ref
, Rdpack_bibstyles
, set_Rdpack_bibstyle
# , run_examples - commenting out until completed
# , insert_fig - commenting out until completed
, Rdo_fetch
)
Rdpack/README.md 0000644 0001762 0000144 00000051571 13516304252 012747 0 ustar ligges users [](https://cran.r-project.org/package=Rdpack)
[](https://www.r-pkg.org/pkg/Rdpack)
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.
# Table of Contents
1. [Installing Rdpack](#org72231b7)
2. [Inserting Bibtex references and citations](#org2f46fa3)
1. [Preparation](#org90969ce)
2. [Inserting references](#orgcd52e01)
3. [Inserting citations](#org61f6af2)
4. [Changing the style of references](#orgec97bb8)
5. [Troubleshooting](#org509e868)
1. [A puzzling message in devtools development mode](#orga85843f)
2. [Typical errors](#org72d25a0)
6. [Latex markup in BibTeX entries](#org9113c8b)
7. [Encoding of file REFERENCES.bib](#org8a4fbe1)
3. [Viewing Rd files](#org44a5291)
4. [Using Rdpack::reprompt()](#org53a201e)
1. [What it does](#orgdc92cb0)
2. [Reprompt and open in an editor](#org8a77552)
5. [Inserting evaluated examples](#orgdd8791f)
1. [Evaluating the examples in section Examples](#orge939faa)
6. [Inserting figures/graphs/plots](#org6f3fd95)
7. [Versions of Rdpack](#org649c176)
# Installing Rdpack
Install the [latest stable version](https://cran.r-project.org/package=Rdpack) from CRAN:
install.packages("Rdpack")
You can also install the [development version](https://github.com/GeoBosh/Rdpack) 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`](https://cran.r-project.org/package=Rdpack).
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`](https://cran.r-project.org/package=Rdpack)
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)`](https://github.com/GeoBosh/Rdpack/blob/master/vignettes/Inserting_bibtex_references.pdf).)
## 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}
\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`.
## 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
session. 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.
## Latex markup in BibTeX entries
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.bib. 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.
## Encoding of file REFERENCES.bib
If a package has a declared encoding (in file `DESCRIPTION`), `REFERENCES.bib` is read-in
with that encoding. 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 DESCRIPTION:
Encoding: UTF-8
Needless to say, make sure that there are really no characters from encodings like 'latin1'.
# 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. Put quotes around
the function name if it is non-syntactic. For replacement functions (functions with names
ending in `<-`) `reprompt()` will insert the proper usage statement. For example, if the
signature of `xxx<-` is `(x, ..., value)`, then both, `"xxx<-"()` and `xxx() <- value` will
be replaced by `xxx(x, ...) <- value`.
`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](https://github.com/GeoBosh/georgisemacs).
# Inserting evaluated examples
`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
.
Vignette [`Inserting_figures_and_evaluated_examples`](https://github.com/GeoBosh/Rdpack/blob/master/vignettes/Inserting_figures_and_evaluated_examples.pdf) gives further details.
## Evaluating the examples in section Examples
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 files. A small example package
using this feature is at [runExamplesCheck](https://github.com/GeoBosh/reprexes/tree/master/runExamplesCheck).
# Inserting figures/graphs/plots
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`](https://github.com/GeoBosh/Rdpack/blob/master/vignettes/Inserting_figures_and_evaluated_examples.pdf) 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.0`.
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 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`.
Rdpack/man/ 0000755 0001762 0000144 00000000000 13521262240 012226 5 ustar ligges users Rdpack/man/Rdo_insert.Rd 0000644 0001762 0000144 00000002455 13501141722 014632 0 ustar ligges users \name{Rdo_insert}
\alias{Rdo_insert}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Insert a new element in an Rd object possibly surrounding it with new
lines
}
\description{
Insert a new element in an Rd object possibly surrounding it with new
lines.
}
\usage{
Rdo_insert(rdo, val, newline = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
\item{val}{the content to insert, an Rd object.}
\item{newline}{a logical value, controls the insertion of new lines
before and after \code{val}, see `Details'.
}
}
\details{
Argument \code{val} is inserted in \code{rdo} at an appropriate
position, see \code{\link{Rdo_get_insert_pos}} for detailed
explanation.
If \code{newline} is TRUE, newline elements are inserted before and
after \code{val} but only if they are not already there.
Typically, \code{val} is a section of an Rd object and \code{rdo} is
an Rd object which is being constructed or modified.
}
\value{
an Rd object
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
%\keyword{RdoElements}
\keyword{RdoBuild}
Rdpack/man/Rd_combo.Rd 0000644 0001762 0000144 00000002464 13501141722 014246 0 ustar ligges users \name{Rd_combo}
\alias{Rd_combo}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Manipulate a number of Rd files}
\description{Manipulate a number of Rd files.}
\usage{
Rd_combo(rd, f, ..., .MORE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rd}{names of Rd files, a character vector.}
\item{f}{function to apply, see Details.}
\item{\dots}{further arguments to pass on to \code{f}.}
\item{.MORE}{another function to be applied for each file to the
result of \code{f}.}
}
\details{
\code{Rd_combo} parses each file in \code{rd}, applies \code{f} to the
Rd object, and applies the function \code{.MORE} (if supplied) on the
results of \code{f}.
A typical value for \code{.MORE} is \code{reprompt} or another
function that saves the resulting Rd object.
todo: \code{Rd_combo} is already useful but needs further work.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
\dontrun{
rdnames <- dir(path = "./man", pattern=".*[.]Rd$", full.names=TRUE)
Rd_combo(rdnames, reprompt)
for(nam in rdnames) try(reprompt(nam))
for(nam in rdnames) try(reprompt(nam, sec_copy=FALSE))
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{Rd}
%\keyword{Rdprocessing}
Rdpack/man/Rdo_fetch.Rd 0000644 0001762 0000144 00000006330 13501141722 014413 0 ustar ligges users \name{Rdo_fetch}
\alias{Rdo_fetch}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Get help pages as Rd objects}
\description{
Get a help page as an Rd object from an installed or source package.
}
\usage{
Rdo_fetch(Rd_name = character(0), package, dir = ".", installed = TRUE)
}
\arguments{
\item{Rd_name}{
names of one or more Rd help pages. \code{name} here is the name of
an Rd file stripped from the extension.
}
\item{package}{
the package from which to get the Rd object, a character string.
}
\item{dir}{
a character string giving the root directory of a source package.
Used only if \code{package} is missing.
}
\item{installed}{
if \code{TRUE}, the default, the Rd object is taken unconditionally
from the installed \code{package}.
If \code{FALSE}, the help page may be taken from a source tree, if
appropriate (typically if \code{package} is in `developer's mode
under devtools, see Details).
}
}
\details{
If \code{Rd_name} is a character string (typical use case), the
corresponding help page is returned as an object from class
\code{"Rd"}. If the length of \code{Rd_name} is greater than one, the
result is a Rd_named list containing the corresponding \code{"Rd"}
objects. The default \code{Rd_name = character(0)} requests all Rd
pages in the package.
Note that \code{Rd_name} does not contain the extention \code{".Rd"}
but the names in the returned list do.
Argument \code{package} names the package from which to fetch the
documentation object. With the default \code{installed = TRUE} the
object is taken unconditionally from the installed package. To get it
from the source tree of a package, use argument \code{"dir"} instead.
The default, \code{""}, for \code{dir} is suitable for workflows where
the working directory is the root of the desired package.
Argument \code{installed} concerns primarily development under package
\code{"devtools"}. \code{"devtools"} intercepts and modifies several
base \R commands, concerning access to system files and getting help,
with the aim of rerouting them to the source trees of packages under
developer's mode. If argument \code{installed} is \code{TRUE}, the
default, the requested pages are taken from the installed package,
even if it is in development mode. If argument \code{installed} is
\code{FALSE}, the Rd objects are taken from the corresponding source
tree, if the specified package is under developer's mode, and from the
installed package otherwise.
Argument \code{Rd_name} is the name used in the \code{\\name} section
of Rd files.
When working off the source tree of a package, \code{Rdo_fetch}
processes the Rd files, so \code{roxygen2} users need to update
them if necessary.
}
\value{
if \code{length(Rd_name) = 1}, an object of class \code{"Rd"},
otherwise a list of \code{"Rd"} objects.
}
\author{Georgi N. Boshnakov}
%\seealso{
%%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
\examples{
## get a single help page
rdo <- Rdo_fetch("viewRd", package = "Rdpack")
Rdo_show(rdo)
## get a list of help pages
rdo <- Rdo_fetch(c("viewRd", "reprompt"), package = "Rdpack")
names(rdo)
}
\keyword{documentation}
% use one of RShowDoc("KEYWORDS")
Rdpack/man/reprompt.Rd 0000644 0001762 0000144 00000034526 13501141722 014376 0 ustar ligges users \name{reprompt}
\alias{reprompt}
\title{Update the documentation of a topic}
\description{Examine the documentation of functions, methods or classes and
update it with additional arguments, methods or slots, as
appropriate. This is an extention of the promptXXX() family of functions.
}
\usage{
reprompt(object, infile = NULL, Rdtext = NULL, final = TRUE,
type = NULL, package = NULL, methods = NULL, verbose = TRUE,
filename = NULL, sec_copy = TRUE, edit = FALSE, \dots)
}
\arguments{
\item{object}{the object whose documentation is to be updated, such as
a string, a function, a help topic, a parsed Rd object, see
`Details'.}
\item{infile}{a file name containing Rd documentation, see `Details'.}
\item{Rdtext}{a character string with Rd formatted text, see `Details'.}
\item{final}{logical, if \code{TRUE} modifies the output of
\code{prompt} so that the package can be built.}
\item{type}{type of topic, such as \code{"methods"} or
\code{"class"}, see `Details'.}
\item{package}{package name; document only objects defined in this
package, especially useful for methods, see `Details'.}
\item{methods}{
used for documentation of S4 methods only, rarely needed even for
them. This argument is passed on to
\code{\link[methods]{promptMethods}}, see its documentation for
details.
}
\item{verbose}{if \code{TRUE} print messages on the screen.}
\item{filename}{name of the file for the generated Rd content; if
\code{NULL}, a suitable file name is generated, if \code{TRUE} it
will be set to \code{infile},
if \code{FALSE} the Rd text is returned, see `Details'.}
\item{\dots}{currently not used.}
\item{sec_copy}{if \code{TRUE} copy Rd contents of unchanged sections
in the result, see Details.}
\item{edit}{if \code{TRUE} call \code{file.edit} just before
returning. This argument is ignored if \code{filename} is \code{FALSE}.}
}
\details{
The typical use of \code{reprompt} is with one argument, as in
\preformatted{
reprompt(infile = "./Rdpack/man/reprompt.Rd")
reprompt(reprompt)
reprompt("reprompt")
}
\code{reprompt} updates the requested documentation and writes the new
Rd file in the current working directory. When argument \code{infile}
is used, the descriptions of all objects described in the input file
are updated. When an object or its name is given, \code{reprompt}
looks first for installed documentation and processes it in the same
way as in the case of \code{infile}. If there is no documentation for
the object, \code{reprompt} creates a skeleton Rd file similar to the
one produced by the base R functions from the \code{prompt} family (if
\code{final = TRUE}, the default, it modifies the output of
\code{prompt()}, so that the package can be built).
To document a function, say \code{myfun}, in an existing Rd file, just
add \code{myfun()} to the usage section in the file and call
\code{reprompt()} on that file. Put quotes around the function name if
it is non-syntactic. For replacement functions (functions with names
ending in \code{<-}) \code{reprompt()} will insert the proper usage
statement. For example, if the signature of \code{xxx<-} is \code{(x,
..., value)} then both, \code{"xxx<-"()} and \code{xxx() <- value}
will be replaced by \code{xxx(x, ...) <- value}.
For S4 methods and classes the argument "package" is often needed to
restrict the output to methods defined in the package of interest.
\preformatted{
reprompt("myfun-methods")
reprompt("[<--methods", package = "mypackage")
reprompt("[<-", type = "methods", package = "mypackage") # same
reprompt("myclass", type = "class", package = "mypackage")
reprompt("myclass-class", package = "mypackage") # same
}
Without the "package" argument the reprompt for \code{"[<-"} would give
all methods defined by loaded packages at the time of the call.
Currently \code{reprompt} functionality is not implemented for topic
"package" but if \code{object} has the form "name-package" (or the
equivalent with argument \code{topic}) and there is no documentation
for \code{package?name}, \code{reprompt} calls
\code{\link{promptPackageSexpr}} to create the required shell.
Note that the shell produced by \code{promptPackageSexpr} does not
need `reprompting' since the automatically generated information is
included by \verb{\Sexpr}'s, not literal strings.
Below are the details.
Typically, only one of \code{object}, \code{infile}, and \code{Rdtext}
is supplied. Warning messages are issued if this is not the case.
The object must have been made available by the time when
\code{reprompt()} is issued. If the object is in a package this is
typically achieved by a \code{library()} command.
\code{object} may be a function or a name, as accepted by the \code{?}
operator. If it has the form "name-class" and "name-methods" a
documentation shell for class "name" or the methods for generic function
"name" will be examined/created. Alternatively, argument \code{type}
may be set to "class" or "methods" to achieve the same effect.
\code{infile} specifies a documentation file to be updated. If it
contains the documentation for one or more functions, \code{reprompt}
examines their usage statements and updates them if they have
changed. It also adds arguments to the "arguments" section if not all
arguments in the usage statements have entries there. If \code{infile}
describes the methods of a function or a class, the checks made are as
appropriate for them. For example, new methods and/or slots are added
to the corresponding sections.
It is all too easy in interactive use to forget to name the
\code{infile} argument, compare\cr
\code{reprompt("./man/reprompt.Rd")} vs.
\code{reprompt(infile = "./man/reprompt.Rd")}).\cr
A convenience feature is that if \code{infile} is missing
and \code{object} is a character string ending in ".Rd" and containing
a forward slash (i.e. it looks like Rd file in a directory), then it
is taken to be \code{infile}.
\code{Rdtext} is similar to \code{infile} but the Rd content is taken
from a character vector.
If Rd content is supplied by \code{infile} or \code{Rdtext},
\code{reprompt} uses it as a basis for comparison. Otherwise it tries
to find installed documentation for the object or topic requested.
If that fails, it resorts to one of the \code{promptXXX} functions to
generate a documentation shell. If that also fails, the requested
object or topic does not exist.
If the above succeeds, the function examines the current definition of
the requested object(s), methods, or class and amends the
documentation with any additional items it finds.
For Rd objects describing one or more functions, the usage expressions
are checked and replaced, if they have changed. Arguments appearing in
one or more usage expressions and missing from section "Arguments" are
amended to it with content "Describe ..." and a message is
printed. Arguments no longer in the usage statements are NOT removed
but a message is issued to alert the user. Alias sections are inserted
for any functions with "usage" but without "alias" section.
If \code{filename} is a character string, it is used as is, so any
path should be included in the string. Argument \code{filename}
usuallly is omitted since the automatically generated file name is
suitable in most cases. Exceptions are functions with non-standard
names (such as replacement functions whose names end in \code{"<-"})
for which the generated file names may not be acceptable on some
operating systems.
If \code{filename} is missing or \code{NULL}, a suitable name is
generated as follows. If \code{infile} is supplied, \code{filename} is
set to a file with the same name in the current working directory
(i.e. any path information in \code{infile} is dropped). Otherwise,
\code{filename} is obtained by appending the name tag of the Rd object
with \code{".Rd"}.
If \code{filename} is \code{TRUE}, it is set to \code{infile} or, if
\code{infile} is missing or \code{NULL}, a suitable name is generated
as above. This can be used to change \code{infile} in place.
If \code{filename} is \code{FALSE}, the Rd text is returned as a
character vector and not written to a file.
If \code{edit} is \code{TRUE}, the reprompted file is opened in an
editor, see also \code{\link{ereprompt}} (`e' for `edit') which is
like \code{reprompt} but has as default \code{edit = TRUE} and some
other related settings.
\code{file.edit()} is used to call the editor. Which editor is opened
depends on the OS and on the user configuration. RStudio users will
probably prefer the 'Reprompt' add-in or the underlying function
\code{\link{RStudio_reprompt}}. Emacs users would normally have set
up \code{emacsclient} as their editor and this is automatically done
by EMACS/ESS (even on Windows).
If argument \code{sec_copy} is \code{TRUE} (the default),
\code{reprompt} will, effectively, copy the contents of (some)
unchanged sections, thus ensuring that they are exactly the same as in
the original. This needs additional work, since parsing an Rd file
and then exporting the created Rd object to an Rd file does not
necessarilly produce an identical Rd file (some escape sequences may
be changed in the process, for example). Even though the new version
should be functionally equivalent to the original, such changes are
usually not desirable. For example, if such changes creep into the
Details section (which \code{reprompt} never changes) the user may be
annoyed or worried.
}
\value{
if \code{filename} is a character string or \code{NULL}, the name of
the file to which the updated shell was written.
Otherwise, the Rd text is returned as a character vector.
}
\author{Georgi N. Boshnakov}
\note{
The arguments of \code{reprompt} are similar to prompt, with some
additions. As in \code{prompt}, \code{filename} specifies the output
file. In \code{reprompt} a new argument, \code{infile}, specifies the
input file containing the Rd source.
When \code{reprompt} is used to update sources of Rd documentation for
a package, it is best to supply the original Rd file in argument
\code{infile}. Otherwise, if the original Rd file contains
\verb{\Sexpr} commands, \code{reprompt} may not be able to recover the
original Rd content from the installed documentation. Also, the fields
(e.g. the keywords) in the installed documentation may not be were you
expect them to be. (This may be addressed in a future revision.)
While \code{reprompt} adds new items to the documentation, it never
removes existing content. It only issues a suggestion to remove an
item, if it does not seem necessary any more (e.g. a removed argument
from a function definition).
\code{reprompt} handles usage statements for S3 and S4 methods
introduced with any of the macros \verb{\method}, \verb{\S3method} and
\verb{\S4method}, as in \verb{\method{fun}{class}(args...)}.
Usage statements for functions are split over two or more lines if
necessary. The user may edit them afterwards if the automatic
splitting is not appropriate, see below.
The usage section of Rd objects describing functions is left intact if
the usage has not changed. To force \code{reprompt} to recreate the
usage section (e.g. to reformat long lines), invalidate the usage of
one of the described functions by removing an argument from its usage
expression. Currently the usage section is recreated completely if
the usage of any of the described functions has changed. Manual
formatting may be lost in such cases.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{ereprompt}} which by default calls the editor on the
original file
}
\examples{
## note: usage of reprompt() is simple. the examples below are bulky
## because they simulate various usage scenarios with commands,
## while in normal usage they would be due to editing.
## change to a temporary directory to avoid clogging up user's
cur_wd <- getwd()
tmpdir <- tempdir()
setwd(tmpdir)
## as for prompt() the default is to save in current dir as "seq.Rd".
## the argument here is a function, reprompt finds its doc and
## updates all objects described along with `seq'.
## (In this case there is nothing to update, we have not changed `seq'.)
fnseq <- reprompt(seq)
## let's parse the saved Rd file (the filename is returned by reprompt)
rdoseq <- tools::parse_Rd(fnseq) # parse fnseq to see the result.
Rdo_show(rdoseq)
## we replace usage statements with wrong ones for illustration.
## (note there is an S3 method along with the functions)
dummy_usage <- char2Rdpiece(paste("seq()", "\\\\method{seq}{default}()",
"seq.int()", "seq_along()", "seq_len()", sep="\n"),
"usage")
rdoseq_dummy <- Rdo_replace_section(rdoseq, dummy_usage)
Rdo_show(rdoseq_dummy) # usage statements are wrong
reprompt(rdoseq_dummy, file = "seqA.Rd")
Rdo_show(tools::parse_Rd("seqA.Rd")) # usage ok after reprompt
## define function myseq()
myseq <- function(from, to, x){
if(to < 0) {
seq(from = from, to = length(x) + to)
} else seq(from, to)
}
## we wish to describe myseq() along with seq();
## it is sufficient to put myseq() in the usage section
## and let reprompt() do the rest
rdo2 <- Rdo_modify_simple(rdoseq, "myseq()", "usage")
reprompt(rdo2, file = "seqB.Rd") # updates usage of myseq
## show the rendered result:
Rdo_show(tools::parse_Rd("seqB.Rd"))
## Run this if you wish to see the Rd file:
## file.show("seqB.Rd")
reprompt(infile = "seq.Rd", filename = "seq2.Rd")
reprompt(infile = "seq2.Rd", filename = "seq3.Rd")
## Rd objects for installed help may need some tidying for human editing.
#hseq_inst <- help("seq")
#rdo <- utils:::.getHelpFile(hseq_inst)
rdo <- Rdo_fetch("seq", "base")
rdo
rdo <- Rdpack:::.Rd_tidy(rdo) # tidy up (e.g. insert new lines
# for human readers)
reprompt(rdo) # rdo and rdoseq are equivalent
all.equal(reprompt(rdo), reprompt(rdoseq)) # TRUE
## clean up
unlink("seq.Rd") # remove temporary files
unlink("seq2.Rd")
unlink("seq3.Rd")
unlink("seqA.Rd")
unlink("seqB.Rd")
setwd(cur_wd) # restore user's working directory
unlink(tmpdir)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{Rd}
Rdpack/man/insert_ref.Rd 0000644 0001762 0000144 00000014640 13501141722 014661 0 ustar ligges users \name{insert_ref}
\alias{insert_ref}
\alias{insertRef}
\alias{insert_citeOnly}
\title{Insert bibtex references in Rd and roxygen2 documentation}
\description{
Package Rdpack provides Rd macros for inserting references and
citations from bibtex files into R documentation. Function
insert_ref() is the workhorse behind this mechanism. The description
given in this page should be sufficient, for more details see the
vignette.
}
\usage{
insert_ref(key, package = NULL, ...)
}
\arguments{
\item{key}{the bibtex key of the reference, a character string.}
\item{package}{the package in which to look for the the bibtex file.}
\item{\dots}{further arguments to pass on to \code{bibtex::read.bib}}
}
\details{
\code{insert_ref} extracts a reference from a bibtex file, converts
it to Rd format and returns a single string with embedded newline
characters. It is the workhorse in the provided mechanism but most
users do not even need to know about \code{insert_ref}.
The documentation of a package using the mechanism provided here
relies on the Rd macro \verb{\\insertRef}. The description below
assumes that \pkg{Rdpack} has been added to file DESCRIPTION, as
described in \code{\link{Rdpack-package}} and the vignettes.
References can be inserted in documentation using the syntax
\verb{\\insertRef{key}{package}}, where \verb{key} is the bibtex key
of the reference and \verb{package} is an R package containing file
\code{"REFERENCES.bib"} from which the reference should be taken.
This works in manually written Rd files and in `roxygen2' documentation
chunks. The references will appear in the place where the macro is put,
usually in a dedicated references section (\verb{\\references}
in Rd files, \verb{@references} in roxygen chunks).
Argument 'package' can be any installed R package, not necessarily the
one of the documentation object. This works for
packages that have \code{"REFERENCES.bib"} in their installation
directory and for the default packages.
For example, the references in the references section of this help
page are generated by the following lines in the Rd file:
\preformatted{
\\insertRef{Rpack:bibtex}{Rdpack}
\\insertRef{R}{bibtex}
}
A roxygen2 documentation chunk might look like this:
\preformatted{
#' @references
#' \\insertRef{Rpack:bibtex}{Rdpack}
#'
#' \\insertRef{R}{bibtex}
}
The first reference has label \verb{Rpack:bibtex} and is taken from
file \code{"REFERENCES.bib"} in package \pkg{Rdpack}. The second reference
is from the file with the same name in package \pkg{bibtex}.
For more details see vignette:
\code{vignette("Inserting_bibtex_references", package = "Rdpack")}
The references are processed when the package is built.
From version 0.6-1 of \pkg{Rdpack}, additional Rd macros are
available for citations. They can be used in Rd and
roxygen2 documentation.
\code{\\insertCite{key}{package}} cites the key and records it for
use by \code{\\insertAllCited}, see below. \code{key} can contain
more keys separated by commas.
\tabular{ll}{
\code{\\insertCite{parseRd,Rpack:bibtex}{Rdpack}} \tab \insertCite{parseRd,Rpack:bibtex}{Rdpack} \cr
\code{\\insertCite{Rpack:bibtex}{Rdpack}} \tab \insertCite{Rpack:bibtex}{Rdpack}
}
By default the citations are parenthesised
\insertCite{parseRd}{Rdpack}. To get textual citations, like
\insertCite{parseRd;textual}{Rdpack}, put the string \code{;textual}
at the end of the key. The references in the last two sentences were
produced with \code{\\insertCite{parseRd}{Rdpack}} and
\code{\\insertCite{parseRd;textual}{Rdpack}}, respectively.
This also works with several citations, e.g.
\cr
\code{\\insertCite{parseRd,Rpack:bibtex;textual}{Rdpack}}
produces: \insertCite{parseRd,Rpack:bibtex;textual}{Rdpack}.
The macro \code{\\insertNoCite{key}{package}} records one or more
references for \code{\\insertAllCited} but does not cite it. Setting
\code{key} to \code{*} will include all references from the
specified package. For example,
\code{\\insertNoCite{R}{bibtex}} and \code{\\insertNoCite{*}{utils}}
record the specified references for inclusion by \code{\\insertAllCited}.
\code{\\insertAllCited} inserts all references cited with
\code{\\insertCite} or \code{\\insertNoCite}. Putting this macro
in the references section will keep it up to date automatically.
The Rd section may look something like:
\preformatted{
\\insertAllCited{}
}
or in roxygen2, the references chunk might look like this:
\preformatted{
#' @references
#' \\insertAllCited{}
}
To mix the citations with other text, such as \sQuote{see also} and
\sQuote{chapter 3}, write the list of keys as a free text, starting
it with the symbol \code{@} and prefixing each key with it.
The \code{@} symbol will not appear in the output. For example, the following code
\preformatted{
\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:
\tabular{l}{
\insertCiteOnly{@see also @parseRd and @Rpack:bibtex}{Rdpack} \cr
\insertCiteOnly{@see also @parseRd; @Rpack:bibtex}{Rdpack} \cr
\insertCiteOnly{@see also @parseRd and @Rpack:bibtex;textual}{Rdpack}
}
\code{\\insertCiteOnly{key}{package}} is as
\code{\\insertCite} but does not include the key in the list of
references for \code{\\insertAllCited}.
% Provision to add prefixes and suffixes is also envisaged but is currently under testing and not documented.
% \insertCiteOnly{parseRd,Rpack:bibtex;textual}{Rdpack/see also}
%
% \insertCiteOnly{parseRd,Rpack:bibtex;textual}{Rdpack/see also/Chapter 3}
%
% \insertCiteOnly{parseRd,Rpack:bibtex;textual}{Rdpack//Chapter 3}
%
% \insertCiteOnly{parseRd,Rpack:bibtex;textual}{Rdpack//, Chapter 3}
}
\value{
for \code{insert_ref}, a character string
}
\references{
For illustrative purposes there are two sets of citation below
The first set of references is obtained with \code{\\insertRef} for
each reference:
\insertRef{Rpack:bibtex}{Rdpack}
\insertRef{R}{bibtex}
----
The following references are obtained with a single \code{\\insertAllCited{}}:
\insertAllCited{}
}
\author{Georgi N. Boshnakov}
\seealso{
\code{\link{Rdpack-package}} for overview,
the vignettes
}
\examples{
cat(insert_ref("R", package = "bibtex"), sep = "\n")
}
\keyword{documentation}
\keyword{Rd}
Rdpack/man/Rdo_piecetag.Rd 0000644 0001762 0000144 00000002545 13501141722 015107 0 ustar ligges users \name{Rdo_piecetag}
\alias{Rdo_piecetag}
\alias{Rdo_sectype}
\alias{is_Rdsecname}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Give information about Rd elements
}
\description{
Give information about Rd elements.
}
\usage{
Rdo_piecetag(name)
Rdo_sectype(x)
is_Rdsecname(name)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{name}{the name of an Rd macro, a string.}
\item{x}{the name of an Rd macro, a string.}
}
\details{
\code{Rdo_piecetag} gives the "Rd_tag" of the Rd macro \code{name}.
\code{Rdo_sectype} gives the "Rd_tag" of the Rd section \code{x}.
\code{is_Rdsecname(name)} returns TRUE if \code{name} is the name of a
top level Rd section.
The information returned by these functions is obtained from the
charater vectors \code{Rdo_piece_types} and
\code{Rdo_predefined_sections}.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{Rdo_piece_types}} and
\code{\link{Rdo_predefined_sections}}
}
\examples{
Rdo_piecetag("eqn") # ==> "VERB"
Rdo_piecetag("code") # ==> "RCODE"
Rdo_sectype("usage") # ==> "RCODE"
Rdo_sectype("title") # ==> "TEXT"
Rdo_sectype("arguments")
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoProgramming}
Rdpack/man/format_funusage.Rd 0000644 0001762 0000144 00000005172 13501141722 015706 0 ustar ligges users \name{format_funusage}
\alias{format_funusage}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Format the usage text of functions}
\description{Formats the usage text of a function so that each line
contains no more than a given number of characters.}
\usage{
format_funusage(x, name = "", width = 72, realname)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{a character vector containing one element for each argument
of the function, see `Details'.}
\item{name}{the name of the function whose usage is described, a
string.}
\item{width}{maximal width of each line of output.}
\item{realname}{the printed form of \code{name}, see `Details', a
string.}
}
\details{
\code{format_funusage} formats the usage text of a function for
inclusion in Rd documentation files. If necessary, it splits the text
into more lines in order to fit it within the requested width.
Each element of argument \code{x} contains the text for one argument
of function \code{name} in the form \code{arg} or \code{arg = default}.
\code{format_funusage} does not look into the content of
\code{x}, it does the necessary pasting to form the complete usage
text, inserting new lines and indentation to stay within the specified
width. Elements of \code{x} are never split. If an argument (i.e.,
element of \code{x}) would cause the width to be exceeded, the entire
argument is moved to the following line.
The text on the second and subsequent lines of each usage item starts
in the column just after the opening parenthesis which follows the
name of the function on the first line.
In descriptions of S3 methods and S4 methods, argument \code{name} may
be a TeX macro like \verb{\method{print}{ts}}. In that case the number
of characters in \code{name} has little bearing on the actual number
printed. In this case argument \code{realname} is used for counting
both the number of characters on the first line of the usage message
and the indentation for the subsequent lines.
}
\value{
The formatted text as a length one character vector.
}
\author{Georgi N. Boshnakov}
\note{
Only the width of \code{realname} is used (for counting). The
formatted text contains \code{name}.
The width of strings is determined by calling \code{nchar} with
argument \code{type} set to "width".
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{deparse_usage1}}
}
\examples{
# this function is essentially internal,
# see deparse_usage1 and as.character.f_usage which use it.
}
%\keyword{RdoProgramming}
\keyword{RdoUsage}
%\keyword{RdFunction}
Rdpack/man/promptUsage.Rd 0000644 0001762 0000144 00000014767 13501141722 015041 0 ustar ligges users \name{promptUsage}
\alias{promptUsage}
\alias{get_usage}
\title{Generate usage text for functions and methods}
\description{
Generates usage text for a function, S3 method or S4 method. The text
is suitably formatted for inclusion in the usage section of Rd
documentation.
}
\usage{
get_usage(object, name = NULL, force.function = FALSE, \dots,
S3class = "", S4sig = "", infix = FALSE, fu = TRUE,
out.format = "text")
promptUsage(\dots, usage)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{object}{a function object or a character name of one, can be
anonymous function.}
\item{name}{the name of a function, a string.}
\item{force.function}{enforce looking for a function.}
\item{S3class}{the S3 class of the function, a character vector.}
\item{out.format}{if "\verb{text}", return the result as a character
vector.}
\item{S4sig}{(the signature of an S4 method, as used in Rd macro
\verb{\S4method}).}
\item{infix}{if TRUE the function is an infix operator.}
\item{fu}{if TRUE the object is a function, otherwise it is something
else (e.g. a variable or a constant like \code{pi} and \code{Inf}).
}
\item{usage}{an usage object, see Details.}
\item{\dots}{
for \code{promptUsage}, arguments to be passed on to
\code{get_usage}; for \code{get_usage}, currently not used.
}
}
\details{
\code{get_usage()} takes a function object, or the name of one, and
creates text suitable for inclusion in the usage section of Rd
documentation. The usage is generated from the function object. When
in interactive \R session, use \code{cat()} to print the result for
copying and pasting into Rd documentation or saving to a file
(otherwise, if the usage text contains backslashes, they may appear
duplicated). Long text is wrapped on two or more lines. For example,
\printExample{cat( get_usage(lm) )}
Argument \code{"name"} can be used to specify a print name for the function.
This is most often needed for S3 methods. Compare
\printExample{cat( get_usage(summary.lm) )}
and
\printExample{cat( get_usage(summary.lm, name = "summary") )}
The call is just \code{summary()} in the latter. This fairly reflects
the fact that S3 methods are normally called via the generic, but
adding some explanatory text around the command is usually a good
idea. For programmatically generated usage sections in help pages,
argument \code{S3class} can be used to get the standard Rd markup for
S3 methods.
\printExample{cat( get_usage(summary.lm, "summary", S3class = "lm") )}
(Note that \verb{\method} can only be used in Usage sections.)
When \code{object} is an anonymous function, argument \code{name} is compulsory.
For example,
% this code prints ugly: \printExample{cat( get_usage(function(x = 3, y="a"){}, "f") )}
% so do it manually in two steps:
\code{cat( get_usage(function(x = 3, y = "a"){}, "f") )}
% TODO: this is commented out from the pkgdown site, since pkgdown() doesn't handle
% results=verbatim yet.
%\Sexpr[stage=build,results=verbatim]{cat("##: ", get_usage(function(x = 3, y = "a"){}, "f"), "\n" )}
\code{get_usage()} can also be used to insert dynamically signatures
of functions located in other objects, such as environments and lists,
see the examples.
If a function is used as an infix operator, set \code{infix = TRUE}.
\printExample{get_usage("+", infix = TRUE); get_usage("\\\%in\\\%", infix = TRUE)}
The name of the operator may be in a variable:
\printExample{op <- "+"; get_usage(op, infix = TRUE)}
Backticks are ok, as well,
\printExample{get_usage(`+`, infix = TRUE)}
But if a backticked operator is in a variable, surprise springs:
\printExample{op <- `+`; get_usage(op, infix = TRUE)}
In this case, don't use backticks or, if you must, evaluate the argument:
\printExample{op <- `+`; get_usage(eval(op), name = "+", infix = TRUE)}
% \Sexpr[stage=build,results=hide]{wrap_percent <- function(x) paste0("\%", x, "\%")}
% \printExample{op <- wrap_percent("in"); get_usage(op, infix = TRUE)}
% \printExample{op <- as.name(wrap_percent("in")); get_usage(eval(op), name = "in", infix = TRUE)}
% \printExample{op <- as.name(wrap_percent("in")); get_usage(eval(op), name = wrap_percent("in"), infix = TRUE)}
% \printExample{op <- as.name(wrap_percent("in")); get_usage(`\\\%in\\\%`, name = wrap_percent("in"), infix = TRUE)}
% \strong{Sexpr:}
% \Sexpr[stage=build,results=verbatim]{op <- as.name(wrap_percent("in")); get_usage(eval(op), name = wrap_percent("in"), infix = TRUE)}
% \Sexpr[stage=build,results=verbatim]{op}
% \Sexpr[stage=build,results=verbatim]{cat(wrap_percent("in"), "\n")}
% \Sexpr[stage=build,results=verbatim]{e <- environment(); ls(e)}
\code{promptUsage()} is mostly for internal use. It is like
\code{get_usage()} with an additional argument, \code{usage}, used to
pass a specially parsed argument list of class \verb{"f_usage"},
produced by other functions in \pkg{Rdpack}. In particular it could
have been generated by a previous call to \code{get_usage()}.
}
\value{
a character string or an object of S3 class "\verb{f_usage}",
see \code{\link{pairlist2f_usage1}} for its format.
}
\author{Georgi N. Boshnakov}
\note{
For an S3 or S4 generic, use the name of the function, not the object,
see the examples.
These functions are for usage descriptions as they appear in the "usage"
section of Rd files. Descriptions of S4 methods for "Methods" sections
are dealt with by other functions.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{parse_pairlist}}
}
\examples{
u <- get_usage(lm) # a long usage text
cat(u)
# if there are additional arguments in S3 methods,
# use names of the functions, not the objects, e.g.
get_usage("droplevels", S3class = "data.frame")
get_usage(name = "droplevels", S3class = "data.frame")
# (both give "\method{droplevels}{data.frame}(x, except = NULL, \dots)")
# but this gives the args of the generic: "\method{droplevels}{data.frame}(x, \dots)"
get_usage(droplevels, S3class = "data.frame")
## a list containing some functions
summaries <- list(xbar = function(x) mean(x), rho = function(x, y) cor(x,y))
get_usage(summaries$xbar, name = "xbar")
get_usage(summaries$rho, name = "rho")
## functions in an environment
esummaries <- list2env(summaries)
get_usage(esummaries$xbar, name = "xbar")
get_usage(esummaries$rho, name = "rho")
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{documentation}
\keyword{Rd}
Rdpack/man/update_aliases_tmp.Rd 0000644 0001762 0000144 00000001355 13501141722 016363 0 ustar ligges users \name{update_aliases_tmp}
\alias{update_aliases_tmp}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Update aliases for methods in Rd objects}
\description{Update aliases for methods in Rd objects}
\usage{
update_aliases_tmp(rdo, package = NULL)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
\item{package}{the name of a package, a character string.}
}
\details{
This is a quick fix. todo: complete it!
}
\value{
the updated Rd object
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoS4}
Rdpack/man/inspect_slots.Rd 0000644 0001762 0000144 00000001071 13501141722 015404 0 ustar ligges users \name{inspect_slots}
\alias{inspect_slots}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Inspect the slots of an S4 class
}
\description{
Inspect the slots of an S4 class.
}
\usage{
inspect_slots(rdo, final = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
\item{final}{if not TRUE insert text with suggestions, otherwise
comment the suggestions out.
}
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\keyword{RdoS4}
Rdpack/man/Rdo_get_insert_pos.Rd 0000644 0001762 0000144 00000003003 13501141722 016340 0 ustar ligges users \name{Rdo_get_insert_pos}
\alias{Rdo_get_insert_pos}
\title{
Find the position of an "Rd_tag"
}
\description{
Find the position of an "Rd_tag".
}
\usage{
Rdo_get_insert_pos(rdo, tag)
}
\arguments{
\item{rdo}{an Rd object}
\item{tag}{the "Rd_tag" to search for, a string}
}
\details{
This function returns a position in \code{rdo}, where the next element
carrying "Rd_tag" \code{tag} should be inserted. The position is
determined as follows.
If one or more elements of \code{rdo} have "Rd_tag" \code{tag}, then
the position is one plus the position of the last such element.
If there are no elements with "Rd_tag" \code{tag}, the position is one
plus the length of \code{rdo}, unless \code{tag} is a known top level
Rd section. In that case, the position is such that the standard
ordering of sections in an Rd object is followed. This is set in the
internal variable \code{.rd_sections}.
}
\value{
an integer
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
#h <- help("Rdo_macro")
#rdo <- utils:::.getHelpFile(h)
rdo <- Rdo_fetch("Rdo_macro", "Rdpack")
ialias <- which(tools:::RdTags(rdo) == "\\\\alias")
ialias
next_pos <- Rdo_get_insert_pos(rdo, "\\\\alias") # 1 + max(ialias)
next_pos
stopifnot(next_pos == max(ialias) + 1)
ikeyword <- which(tools:::RdTags(rdo) == "\\\\keyword")
ikeyword
next_pos <- Rdo_get_insert_pos(rdo, "\\\\keyword") # 1 + max(ikeyword)
next_pos
stopifnot(next_pos == max(ikeyword) + 1)
}
\keyword{RdoProgramming}
Rdpack/man/Rdo_get_argument_names.Rd 0000644 0001762 0000144 00000002454 13501141722 017171 0 ustar ligges users \name{Rdo_get_argument_names}
\alias{Rdo_get_argument_names}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Get the names of arguments in usage sections of Rd objects}
\description{Get the names of arguments in usage sections of Rd objects.}
\usage{
Rdo_get_argument_names(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rdo object.}
}
\details{
All arguments names in the "arguments" section of \code{rdo} are
extracted. If there is no such section, the results is a character
vector of length zero.
Arguments which have different descriptions for different OS'es
are included and not duplicated.
Arguments which have descriptions for a particular OS are included,
irrespectively of the OS of the running R process.
(\strong{todo:} introduce argument to control this?)
}
\value{
a character vector
}
% \references{
% %% ~put references to the literature/web site here ~
% }
\author{Georgi N. Boshnakov}
% \note{
% %% ~~further notes~~
% }
%
% %% ~Make other sections like Warning with \section{Warning }{....} ~
%
\seealso{
\code{\link{Rdo_get_item_labels}}
}
\examples{
##---- Should be DIRECTLY executable !! ----
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{ ~kwd1 }
Rdpack/man/get_usage_text.Rd 0000644 0001762 0000144 00000002742 13501141722 015530 0 ustar ligges users \name{get_usage_text}
\alias{get_usage_text}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Get the text of the usage section of Rd documentation
}
\description{
Get the text of the usage section of Rd documentation.
}
\usage{
get_usage_text(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object or a character string}
}
\details{
If \code{rdo} is a string, it is parsed to obtain an Rd object.
The content of section "\verb{\usage}" is extracted and converted to string.
}
\value{
a string
}
\author{Georgi N. Boshnakov}
\note{
todo: \code{get_usage_text} can be generalised to any Rd section but it is
better to use a different approach since \code{print.Rd()} does not
take care for some details (escaping \%, for example). Also, the
functions that use this one assume that it returns \R code, which
may not be the case if the usage section contains Rd comments.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
## get the Rd object documenting Rdo_macro
#h <- utils::help("Rdo_macro", lib.loc = .libPaths())
#rdo <- utils:::.getHelpFile(h)
rdo <- Rdo_fetch("Rdo_macro", "Rdpack")
# extract the usage section and print it:
ut <- get_usage_text(rdo)
cat(ut, sep = "\n")
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
\keyword{RdoUsage}
%\keyword{RdFunction}
Rdpack/man/Rdapply.Rd 0000644 0001762 0000144 00000010741 13501141722 014132 0 ustar ligges users \name{Rdapply}
\alias{Rdapply}
\alias{rattr}
\alias{Rdtagapply}
\title{Apply a function over an Rd object}
\description{Apply a function recursively over an Rd object, similarly
to rapply but keeping attributes.}
\usage{
Rdapply(x, \dots)
Rdtagapply(object, FUN, rdtag, classes = "character", how = "replace",
\dots)
rattr(x, y)
}
\arguments{
\item{x}{the Rd object on which to apply a function.}
\item{object}{the Rd object on which to apply a function.}
\item{FUN}{The function to apply, see details}
\item{rdtag}{apply FUN only to elements whose \code{Rd_tag} attribute
is \code{rdtag}.}
\item{y}{an Rd object with the same structure as \code{x}, see `Details'.}
\item{\dots}{arguments to pass to \code{rapply}, see `Details'.}
\item{classes}{a character vector, passed on to \code{\link{rapply}},
see `Details'.
}
\item{how}{a character string, passed on to \code{\link{rapply}},
see `Details'.
}
}
\details{
\code{Rdapply} works like \code{rapply} but preserves the attributes
of \code{x} and (recursively) any sublists of it. \code{Rdapply}
first calls \code{rapply}, passing all arguments to it. Then it
restores recursively the attributes by calling \code{rattr}.
Note that the object returned by \code{rapply} is assumed to have
identical structure to the original object. This means that argument
\code{how} of \code{rapply} must not be "unlist" and normally will be
"replace". \code{Rdtagapply} gives sensible default values for
\code{classes} and \code{how}. See the documentation of
\code{\link{rapply}} for details and the possible choices for
\code{classes}, \code{how} or other arguments passed to it via
\code{"\dots"}.
\code{Rdtagapply} is a convenience variant of \code{Rdapply} for the
common task of modifying or examining only elements with a given
\code{Rd_tag} attribute. Since the Rd equation macros \verb{\eqn} and
\verb{\deqn} are assigned Rd tag "VERB" but are processed differently
from other "VERB" pieces, pseudo-tags
"mathVERB" and "nonmathVERB" are provided, such that "mathVERB" is for
actions on the first argument of the mathematical macros \verb{\eqn} and
\verb{\deqn}, while "nonmathVERB" is for actions on "VERB" macros in
all other contexts. There is also a pseudo-tag "nonmath" for anything
that is not math.
\code{rattr} is an auxilliary function which takes two Rd objects
(with identical structure) and recursively examines them. It makes the
attributes of any lists in the first argument identical to the
corresponding attributes in the second.
}
\value{
For \code{Rdapply} and \code{Rdtagapply}, an Rd object with some of
its leaves replaced as specified above.
For \code{rattr}, the object \code{x} with attributes of any list
elements of it set to the corresponding attributes of \code{y}.
}
\author{Georgi N. Boshnakov}
\note{
todo: may be it is better to rename the argument FUN of \code{Rdtagapply} to
\code{f}, which is its name in \code{rapply}.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{rapply}}
}
\examples{
# create an Rd object for the sake of example
u1 <- list_Rd(name = "Dummyname", alias = "dummyfun",
title = "Dummy title", description = "Dummy description",
usage = "dummyfun(x)",
value = "numeric vector",
author = "A. Author",
examples = "\na <- matrix(1:6,nrow=2)\na \%*\% t(a)\nt(a) \%*\% a",
Rd_class=TRUE )
# correct R code for examples but wrong for saving in Rd files
Rdo_show(u1)
# escape percents everywhere except in comments
# (actually, .anypercent escapes only unescaped percents)
rdo <- Rdapply(u1, Rdpack:::.anypercent, classes = "character", how = "replace")
# syntactically wrong R code for examples but ok for saving in Rd files
Rdo_show(rdo)
# Rdo2Rdf does this by default for examples and other R code,
# so code can be kept syntactically correct while processing.
# (reprompt() takes care of this too as it uses Rdo2Rdf for saving)
fn <- tempfile("u1", fileext="Rd")
Rdo2Rdf(u1, file = fn)
# the saved file contains escaped percents but they disappear in parsing:
file.show(fn)
Rdo_show(tools::parse_Rd(fn))
# if you think that sections should start on new lines,
# the following makes the file a little more human-friendly
# (by inserting new lines).
\dontshow{# todo: additional arg. for list_Rd for this?
}
u2 <- Rdpack:::.Rd_tidy(u1)
Rdo2Rdf(u2, file = fn)
file.show(fn)
unlink(fn)
}
\keyword{RdoProgramming}
Rdpack/man/Rdo_reparse.Rd 0000644 0001762 0000144 00000003007 13501141722 014761 0 ustar ligges users \name{Rdo_reparse}
\alias{Rdo_reparse}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Reparse an Rd object}
\description{Reparse an Rd object.}
\usage{
Rdo_reparse(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
}
\details{
\code{Rdo_reparse} saves \code{rdo} to a temporary file and parses it
with \code{parse_Rd}. This ensures that the Rd object is a "canonical"
one, since one and the same Rd file can be produced by different (but
equivalent) Rd objects.
Also, the functions in this package do not attend to attribute
"srcref" (and do not use it) and reparsing takes care of this.
(todo: check if there is a problem if the tempfile disappears.)
%insertCite{@see @parseRd,@Rpack:bibtex}{Rdpack} % only for testing!
\insertCite{parseRd,Rpack:bibtex}{Rdpack} % only for testing!
}
\references{
\insertAllCited{} % only for testing
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
# the following creates Rd object rdo
dummyfun <- function(x) x
fn <- tempfile("dummyfun", fileext = "Rd")
reprompt(dummyfun, filename = fn)
rdo <- tools::parse_Rd(fn)
dottext <- "further arguments to be passed on."
rdo2 <- Rdo_append_argument(rdo, "\\dots", dottext, create = TRUE)
rdo2 <- Rdo_append_argument(rdo2, "z", "a numeric vector")
Rdo_show(Rdo_reparse(rdo2))
# the following does ot show the arguments. (todo: why?)
# (see also examples in Rdo_append_argument)
Rdo_show(rdo2)
unlink(fn)
}
\keyword{Rd}
Rdpack/man/Rdo_insert_element.Rd 0000644 0001762 0000144 00000002516 13501141722 016341 0 ustar ligges users \name{Rdo_insert_element}
\alias{Rdo_insert_element}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Insert a new element in an Rd object
}
\description{
Insert a new element at a given position in an Rd object.
}
\usage{
Rdo_insert_element(rdo, val, pos)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
\item{val}{the content to insert.}
\item{pos}{position at which to insert \code{val}, typically an integer
but may be anything accepted by the operator "[[".
}
}
\details{
\code{val} is inserted at position \code{pos}, between the elements at
positions \code{pos-1} and \code{pos}. If \code{pos} is equal to 1,
\code{val} is prepended to \code{rdo}. If \code{pos} is missing or
equal to the length of \code{rdo}, \code{val} is appended to
\code{rdo}.
todo: allow vector \code{pos} to insert deeper into the object.
todo: character \code{pos} to insert at a position specified by "tag" for example?
todo: more guarded copying of attributes?
}
\value{
an Rd object
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
%\keyword{RdoElements}
\keyword{RdoBuild}
Rdpack/man/inspect_usage.Rd 0000644 0001762 0000144 00000002611 13501141722 015345 0 ustar ligges users \name{inspect_usage}
\alias{inspect_usage}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Inspect the usage section in an Rd object
}
\description{
Inspect the usage section in an Rd object.
}
\usage{
inspect_usage(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
}
\details{
The usage section in the Rd object, \code{rdo}, is extracted and
parsed. The usage of each function described in \code{rdo} is
obtained also from the actual installed function and compared to the
one from \code{rdo}.
The return value is a list, with one element for each function usage
as returned by \code{compare_usage1}.
One of the consequences of this is that an easy way to add a usage
description of a function, say \code{fu} to an existing Rd file is to
simply add a line \code{fu()} to the usage section of that file and
run \code{reprompt} on it.
}
\value{
a list of comparison results as described in `Details'
(todo: give more details here)
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{inspect_args}}
}
% \examples{
% ##---- Should be DIRECTLY executable !! ----
% }
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{ ~kwd1 }
\keyword{RdoUsage}
%\keyword{RdFunction}
Rdpack/man/compare_usage1.Rd 0000644 0001762 0000144 00000004573 13501141722 015420 0 ustar ligges users \name{compare_usage1}
\alias{compare_usage1}
\title{
Compare usage entries for a function to its actual arguments
}
\description{
Compare usage entries for a function to its actual arguments.
}
\usage{
compare_usage1(urdo, ucur)
}
\arguments{
\item{urdo}{
usage text for a function or S3 method from an Rd object or file.
}
\item{ucur}{usage generated from the actual object.}
}
\details{
Compares the usage statements for functions in the Rd object or file
\code{urdo} to the usage inferred from the actual definitions of the
functions. The comparison is symmetric but the interpretation assumes
that \code{ucur} may be more recent.
Note: do not compare the return value to TRUE with \code{identical} or
\code{isTRUE}. The attribute makes the returned value not identical to
TRUE in any case.
}
\value{
TRUE if the usages are identical, FALSE otherwise.
The return value has attribute "details", which is a list providing
details of the comparison. The elements of this list should be
referred by name, since if one of \code{urdo} or \code{ucur} is NULL
or NA, the list contains only the fields "obj_removed", "obj_added",
"rdo_usage", "cur_usage", and "alias".
\item{identical_names}{a logical value, TRUE if the `name' is the same in both objects.}
\item{obj_removed}{names present in \code{urdo} but not in \code{ucur}}
\item{obj_added }{names present in \code{ucur} but not in \code{urdo}}
\item{identical_argnames }{a logical value,
TRUE if the argument names in both objects are the same.}
\item{identical_defaults }{a logical value,
TRUE if the defaults for the arguments in both objects are the same.}
\item{identical_formals }{a logical value, TRUE if the formals
are the same, i.e. fields \code{identical_argnames} and
\code{identical_defaults} are both TRUE.}
\item{added_argnames }{names of arguments in \code{ucur} but not in \code{urdo}.}
\item{removed_argnames}{names of arguments in \code{urdo} but not in \code{ucur}.}
\item{names_unchanged_defaults }{names of arguments whose defaults are the same.}
\item{rdo_usage }{a copy of \code{urdo}.}
\item{cur_usage }{a copy of \code{ucur}.}
\item{alias }{alias of the name of the object, see `Details'.}
}
\author{Georgi N. Boshnakov}
\seealso{
\code{\link{inspect_usage}}
}
\keyword{RdoUsage}
Rdpack/man/Rdo_set_section.Rd 0000644 0001762 0000144 00000004051 13501141722 015637 0 ustar ligges users \name{Rdo_set_section}
\alias{Rdo_set_section}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Replace a section in an Rd file
}
\description{
Replace a section in an Rd file.
}
\usage{
Rdo_set_section(text, sec, file, \dots)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{text}{the new text of the section, a character vector.}
\item{sec}{name of the section.}
\item{file}{name of the file.}
\item{...}{arguments to be passed on to \code{Rdo_modify}.}
}
\details{
Parses the file, replaces the specified section with the new content
and writes the file back. The text is processed as appropriate for the
particular section (\code{sec}).
For example:
\code{Rdo_set_section("Georgi N. Boshnakov", "author", "./man/Rdo2Rdf.Rd")}
(Some care is needed with the author field for "xxx-package.Rd" files, such
as "Rdpack-package.Rd", where the \verb{Author(s)} field has
somewhat different layout.)
By default \code{Rdo_set_section} does not create the section if it
does not exist, since this may not be desirable for some Rd files. The
"..." arguments can be used to change this, they are passed on to
\code{\link{Rdo_modify}}, see its documentation for details.
}
\value{
This function is used mainly for the side effect of changing \code{file}.
It returns the Rd formatted text as a character vector.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{Rdo_modify}}
}
\examples{
fnA <- tempfile("dummyfun", fileext = "Rd")
dummyfun <- function(x) x
reprompt(dummyfun, filename = fnA)
Rdo_show(tools::parse_Rd(fnA))
## set the author section, create it if necessary.
Rdo_set_section("A.A. Author", "author", fnA, create = TRUE)
Rdo_show(tools::parse_Rd(fnA))
## replace the author section
Rdo_set_section("Georgi N. Boshnakov", "author", fnA)
Rdo_show(tools::parse_Rd(fnA))
unlink(fnA)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoBuild}
Rdpack/man/viewRd.Rd 0000644 0001762 0000144 00000002514 13501141722 013756 0 ustar ligges users \name{viewRd}
\alias{viewRd}
\title{View Rd files in a source package}
\description{View Rd files in a source package.}
\usage{
viewRd(infile, type = "text", stages = NULL)
}
\arguments{
\item{infile}{name of an Rd file, a character string.}
\item{type}{one of \code{"text"} or \code{"html"}}
\item{stages}{
a character vector specifying which stages of the R installation
process to immitate. The default,
\code{c("build", "install", "render")}, should be fine in most cases.
}
}
\details{
This function can be used to view Rd files from the source directory
of a package. The page is presented in text format or in html browser,
according to the setting of argument \code{type}. The default is text.
}
\value{
the function is used for the side effect of showing the help page in a
text help window or a web browser.
}
%\references{
%%% ~put references to the literature/web site here ~
%}
\author{Georgi N. Boshnakov}
\note{
Developers with \code{"devtools"} can use \code{viewRd()} instead of
\code{help()} for documentation objects that contain Rd macros, such
as \code{insertRef}, see vignette:
\code{vignette("Inserting_bibtex_references", package = "Rdpack")}.
}
%\seealso{
%%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
%\examples{
%}
\keyword{documentation}
% use one of RShowDoc("KEYWORDS")
Rdpack/man/Rdpack_bibstyles.Rd 0000644 0001762 0000144 00000004032 13501141722 015777 0 ustar ligges users \name{Rdpack_bibstyles}
\alias{Rdpack_bibstyles}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Set up a custom style for references in help pages}
\description{Set up a custom style for references in help pages.}
\usage{
Rdpack_bibstyles(package, authors)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{package}{the name of a package, a character string.}
\item{authors}{if equal to "LongNames", use full names of authors in
reference lists, see Details.}
}
\details{
This is the initial implementation of support for styles for lists of
bibliography references.
Currently setting "authors" to "LongNames" will cause the references
to appear with full names, eg John Smith rather than in the default
Smith J style.
Package authors can request this feature by adding the following line
to their \code{.onLoad} function (if their package has one):
\preformatted{
Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames")
}
of just copy the following definition in a package that does not have
\code{.onLoad} :
\preformatted{
.onLoad <- function(lib, pkg){
Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames")
invisible(NULL)
}
}
After building and installing the package the references should be
using long names.
}
\value{
in .onLoad(), the function is used purely to set up a bibstyle as
discussed in Details.
Internally, \pkg{Rdpack} uses it to extract styles set up by packages:
- if called with argument \code{package} only, the style requested
by that package;
- if called with no arguments, a list of all styles.
}
%\references{
%}
\author{Georgi N. Boshnakov}
%\note{
%%% ~~further notes~~
%}
%% ~Make other sections like Warning with \section{Warning }{....} ~
%\seealso{
%%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
%\examples{
%}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{documentation}
\keyword{bibtex}
% use one of RShowDoc("KEYWORDS")
Rdpack/man/Rdo_locate.Rd 0000644 0001762 0000144 00000006606 13501141722 014577 0 ustar ligges users \name{Rdo_locate}
\alias{Rdo_locate}
\title{Find positions of elements in an Rd object}
\description{
Find positions of elements for which a function returns
TRUE. Optionally, apply another function to the selected elements and
return the results along with the positions.
}
\usage{
Rdo_locate(object, f = function(x) TRUE, pos_only = TRUE,
lists = FALSE, fpos = NULL, nested = TRUE)
}
\arguments{
\item{object}{an Rd object}
\item{f}{a function returning TRUE if an element is desired and FALSE
otherwise.}
\item{pos_only}{if TRUE, return only the positions; if this argument
is a function, return also the result of applying the function to
the selected element, see Details.}
\item{lists}{if FALSE, examine only leaves, if TRUE, examine also
lists, see Details.}
\item{fpos}{a function with two arguments, \code{object}
and position, it is called and the value is returned along with the
position, see Details.}
\item{nested}{a logical value, it has effect only when \code{lists} is
TRUE, see `Details'.
}
}
\details{
With the default setting of \code{lists = FALSE}, the function
\code{f} is applied to each leave (a character string) of the Rd
object. If \code{lists = TRUE} the function \code{f} is applied also
to each branch (a list). In this case, argument \code{nested} controls
what happens when \code{f} returns TRUE. If \code{nested} is TRUE,
each element of the list is also inspected recursively, otherwise this
is not done and, effectively, the list is considered a leaf. If
\code{f} does not return TRUE, the value of \code{nested} has no
effect and the elements of the list are inspected.
The position of each object for which \code{f} returns TRUE is
recorded as a numeric vector.
\code{fpos} and \code{pos_only} provide two ways to do something with
the selected elements. Argument \code{fpos} is more powerful than
\code{pos_only} but the latter should be sufficient and simpler to use
in most cases.
If \code{fpos} is a function, it is applied to each selected element
with two arguments, \code{object} and the position, and the result
returned along with the position. In this case argument
\code{pos_only} is ignored. If \code{fpos} is NULL the action depends
on \code{pos_only}.
If \code{pos_only = TRUE}, \code{Rdo_locate} returns a list of such
vectors (not a matrix since the positions of the leaves are, in
general, at different depths).
If \code{pos_only} is a function, it is applied to each selected
element and the result returned along with the position.
}
\value{
a list with one entry for each selected element. Each entry is a
numeric vector or a list with two elements:
\item{pos}{the position, a vector of positive integers,}
\item{value}{the result of applying the function to the element at
\code{pos}.}
}
\author{Georgi N. Boshnakov}
\note{
The following needs additional thought.
In some circumstances an empty list, tagged with \code{Rd_tag} may
turn up, e.g. \code{list()} with \verb{Rd_tag="\\dots"} in an
\verb{\\arguments} section.
On the one hand this is a list. On the other hand it may be considered
a leaf. It is not clear if any attempt to recurse into such a list
should be made at all.
}
\seealso{
\code{\link{Rdo_sections}} and
\code{\link{Rdo_locate_core_section}}
which locate top level sections
}
\examples{
# todo: put examples here!
}
\keyword{Rd}
Rdpack/man/set_Rdpack_bibstyle.Rd 0000644 0001762 0000144 00000001642 13501141722 016473 0 ustar ligges users \name{set_Rdpack_bibstyle}
\alias{set_Rdpack_bibstyle}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Set up a bibstyle defined in Rdpack}
\description{Set up a bibstyle defined in Rdpack}
\usage{
set_Rdpack_bibstyle(bibstyle = "JSSRd")
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{bibstyle}{a character string}
}
%\details{
%%% ~~ If necessary, more details than the description above ~~
%}
%\value{
%%% ~Describe the value returned
%%% If it is a LIST, use
%%% \item{comp1 }{Description of 'comp1'}
%%% \item{comp2 }{Description of 'comp2'}
%%% ...
%}
%\references{
%%% ~put references to the literature/web site here ~
%}
%\author{
%%% ~~who you are~~
%}
%\note{
%%% ~~further notes~~
%}
%
%%% ~Make other sections like Warning with \section{Warning }{....} ~
%
%\seealso{
%%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
%\examples{
%}
\keyword{internal}
Rdpack/man/inspect_args.Rd 0000644 0001762 0000144 00000003216 13501141722 015177 0 ustar ligges users \name{inspect_args}
\alias{inspect_args}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Inspect the argument section of an Rd object
}
\description{
Inspect the argument section of an Rd object.
}
\usage{
inspect_args(rdo, i_usage)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object describing functions.}
\item{i_usage}{see Details.}
}
\details{
\code{inspect_args} checks if the arguments in the documentation
object \code{rdo} match the (union of) the actual arguments of the
functions it describes.
If \code{i_usage} is missing, it is computed by inspecting the current
definitions of the functions described in \code{rdo}, see
\code{inspect_usage}. This argument is likely to be supplied if the
function calling \code{inspect_args} has already computed it for other
purposes.
}
\value{
TRUE if the arguments in the documentation match the (union of) the
actual arguments of the described functions, FALSE otherwise.
The returned logical value has attribute `details' which is a list
with the following components.
\item{rdo_argnames}{arguments described in the documentation object, \code{rdo}.}
\item{cur_argnames}{arguments in the current definitions of the
described functions.}
\item{added_argnames}{new arguments}
\item{removed_argnames}{removed (dropped) arguments.}
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
\keyword{RdoUsage}
%\keyword{RdFunction}
Rdpack/man/deparse_usage.Rd 0000644 0001762 0000144 00000005662 13501141722 015334 0 ustar ligges users \name{deparse_usage}
\alias{deparse_usage}
\alias{deparse_usage1}
\alias{as.character.f_usage}
\title{Convert f_usage objects to text appropriate for usage sections in
Rd files
}
\description{Converts f_usage objects to text appropriate for usage sections in
Rd files. Handles S3 methods.
}
\usage{
deparse_usage(x)
deparse_usage1(x, width = 72)
\method{as.character}{f_usage}(x, \dots )
}
\arguments{
\item{x}{
an object from class \code{"f_usage"}. For \code{deparse_usage},
\code{x} can also be a list of \code{"f_usage"} objects.
}
\item{width}{maximal width of text on a line.}
\item{...}{ignored.}
}
\details{
Both, \code{deparse_usage1} and the \code{as.character} method for
class \code{"f_usage"}, convert an \code{"f_usage"} object to a
character string suitable for Rd documentation. The
\code{as.character} method is the user level function (it just calls
\code{deparse_usage1}), \code{deparse_usage1} is internal function for
programming. In the example below the first command creates an
\code{"f_usage"} object, then the second converts it to character string.
\printExample{(a <- pairlist2f_usage1(formals(cor), "cor"));cat(as.character(a))}
Each usage entriy is formatted and, if necessary, split over several
lines. The width (number of characters) on a line can be changed with
argument \code{width}.
\code{deparse_usage} can be used when \code{x} is a list of
\code{"f_usage"} objects. It calls \code{deparse_usage1} with each of
them and returns a character vector with one element for each
component of \code{x}. When \code{x} is an object from class
\code{"f_usage"}, \code{deparse_usage} is equivalent to
\code{deparse_usage1}.
}
\value{
For \code{deparse_usage1} and \code{as.character.f_usage}, a named
character vector of length one (the name is the function name).
For \code{deparse_usage}, a named character vector with one entry for
the usage text for each function.
}
\author{Georgi N. Boshnakov}
\seealso{
\code{\link{pairlist2f_usage1}}
}
\examples{
cur_wd <- getwd()
tmpdir <- tempdir()
setwd(tmpdir)
## prepare a list of "f_usage" objects
fnseq <- reprompt(seq) # get and save the help page of "seq"
rdoseq <- tools::parse_Rd(fnseq) # parse the Rd file
ut <- get_usage_text(rdoseq) # get the contents of the usage section
cat(ut, "\n") # of seq() (a character string)
utp <- parse_usage_text(ut) # parse to a list of "f_usage" objects
## deparse the "f_usage" list - each statement gets a separate string
cat(deparse_usage(utp), sep = "\n")
## explore some of the usage entries individually;
## the generic seq() has a boring signature
utp[[1]]
as.character(utp[[1]])
deparse_usage1(utp[[1]]) # same
## the default S3 method is more interesting
utp[[2]]
cat(deparse_usage1(utp[[2]]))
cat(as.character(utp[[2]])) # same
unlink(fnseq)
setwd(cur_wd)
unlink(tmpdir)
}
%\keyword{RdoProgramming}
\keyword{RdoUsage}
%\keyword{RdFunction}
Rdpack/man/Rdo_flatinsert.Rd 0000644 0001762 0000144 00000001626 13501141722 015500 0 ustar ligges users \name{Rdo_flatinsert}
\alias{Rdo_flatinsert}
\alias{Rdo_flatremove}
\title{Insert or remove content in an Rd fragment}
\description{Insert or remove content in an Rd fragment.}
\usage{
Rdo_flatinsert(rdo, val, pos, before = TRUE)
Rdo_flatremove(rdo, from, to)
}
\arguments{
\item{rdo}{an Rd object.}
\item{val}{the value to insert.}
\item{pos}{position.}
\item{before}{if TRUE, insert the new content at pos, pushing the
element at pos forward.
}
\item{from}{beginning of the region to remove.}
\item{to}{end of the region to remove.}
}
\details{
\code{Rdo_flatinsert} inserts \code{val} at position \code{pos},
effectively by concatenation.
\code{Rdo_flatremove} removes elements from \code{from} to \code{to}.
}
\value{
the modified \code{rdo}
}
\author{Georgi N. Boshnakov}
% \seealso{
% %% ~~objects to See Also as \code{\link{help}}, ~~~
% }
%\examples{
%}
\keyword{ RdoProgramming }
Rdpack/man/Rdo_sections.Rd 0000644 0001762 0000144 00000006326 13501141722 015156 0 ustar ligges users \name{Rdo_sections}
\alias{Rdo_sections}
\alias{Rdo_locate_core_section}
\title{Locate the sections in Rd objects}
\description{Locate the Rd sections in an Rd object and return a list of
their positions and names.}
\usage{
Rdo_sections(rdo)
Rdo_locate_core_section(rdo, sec)
}
\arguments{
\item{rdo}{an Rd object.}
\item{sec}{the name of a section, a character string. For builtin
sections the leading backslash should be included.}
}
\details{
\code{Rdo_sections} locates all sections at the top level in an Rd
object. This includes the predefined sections and the user defined
sections. Sections wrapped in \verb{#ifdef} directives are also found.
\code{Rdo_sections} returns a list with one entry for each section in
\code{rdo}. This entry is a list with components \code{"pos"} and
\code{"title"} giving the position (suitable for use in \verb{"[["})
and the title of the section. For user defined sections the actual
name is returned, not "section".
The names of the sections are returned as single strings without
attributes. The titles of predefined sections are single words but
user defined sections may have longer titles and sometimes contain
basic markup.
\code{Rdo_locate_core_section} works similarly but returns only the
results for section \code{sec}. Currently it simply calls
\code{Rdo_sections} and returns only the results for \code{sec}.
Note that for consistency \code{Rdo_locate_core_section} does not
attempt to simplify the result in the common case when there is only
one instance of the requested section---it is put in a list of length
one.
\insertCite{parseRd}{Rdpack} % only for testing!
\insertCite{Rpack:bibtex}{Rdpack} % only for testing!
}
\value{
A list giving the positions and titles of the sections in \code{rdo}
as described in 'Details'. The format is essentially that of
\code{\link{Rdo_locate}}, the difference being that field "value"
from that function is renamed to "title" here.
\item{pos}{the position, a vector of positive integers,}
\item{title}{a standard section name, such as \verb{"\\name"} or, in
the case of "\\section", the actual title of the section.
}
}
\author{Georgi N. Boshnakov}
\note{
I wrote \code{Rdo_sections} and \code{Rdo_locate_core_section} after
most of the core functionality was tested. Currently these functions
are underused---they can replace a number of internal and exported
functions.
}
\seealso{
\code{\link{Rdo_locate}}
}
\references{
\insertAllCited{} % only for testing
}
\examples{
infile <- system.file("examples", "tz.Rd", package = "Rdpack")
rd <- tools::parse_Rd(infile)
## Locate all top level sections in rd
sections <- Rdo_sections(rd)
## How many sections there are in rd?
length(sections)
## What are their titles?
sapply(sections, function(x) x$title)
## The names of builtin sections include the backslash
Rdo_locate_core_section(rd, "\\\\title")
## Locate a user defined secion
Rdo_locate_core_section(rd, "Further information")
## The names of builtin sections include the backslash
Rdo_locate_core_section(rd, "\\\\details")
## All appearances of the requested section are returned
Rdo_locate_core_section(rd, "\\\\alias")
Rdo_locate_core_section(rd, "\\\\keyword")
}
\keyword{Rd}
Rdpack/man/Rdo_remove_srcref.Rd 0000644 0001762 0000144 00000001624 13501141722 016164 0 ustar ligges users \name{Rdo_remove_srcref}
\alias{Rdo_remove_srcref}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Remove srcref attributes from Rd objects}
\description{Removes srcref attributes from Rd objects.}
\usage{
Rdo_remove_srcref(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
}
\details{
\code{srcref} attrbutes (set by \code{parse_Rd}) may be getting in the
way during manipulation of Rd objects, such as comparisons, addition
and replacement of elements. This function traverses the
argument and removes the \code{srcref} attribute from all of its elements.
}
\value{
an Rd object with no srcref attributes.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoProgramming}
Rdpack/man/Rdo_collect_metadata.Rd 0000644 0001762 0000144 00000004043 13501141722 016606 0 ustar ligges users \name{Rdo_collect_aliases}
\alias{Rdo_collect_aliases}
\alias{Rdo_collect_metadata}
\title{Collect aliases or other metadata from an Rd object}
\description{Collect aliases or other metadata from an Rd object.}
\usage{
Rdo_collect_aliases(rdo)
Rdo_collect_metadata(rdo, sec)
}
\arguments{
\item{rdo}{an Rd object}
\item{sec}{the kind of metadata to collect, a character string, such
as "alias" and "keyword".}
}
\details{
\code{Rdo_collect_aliases} finds all aliases in \code{rdo} and returns
them as a named character vector. The name of an alias is usually the
empty string, \code{""}, but it may also be "windows" or "unix" if
the alias is wrapped in a \verb{#ifdef} directive with the
corresponding first argument.
\code{Rdo_collect_metadata} is a generalisation of the above. It
collects the metadata from section(s) \code{sec}, where \code{sec} is
the name of a section without the leading backslash.
\code{sec} is assumed to be a section containing a single word, such
as "keyword", "alias", "name".
Currently \code{Rdo_collect_metadata} is not exported.
}
\value{
a named character vector, as described in Details.
}
\author{Georgi N. Boshnakov}
\seealso{
\code{tools:::.Rd_get_metadata}
}
\examples{
## this example originally (circa 2012) was:
## infile <- file.path(R.home(), "src/library/base/man/timezones.Rd")
## but the OS conditional alias in that file has been removed.
## So, create an artificial example:
infile <- system.file("examples", "tz.Rd", package = "Rdpack")
## file.show(infile)
rd <- tools::parse_Rd(infile)
## The functions described here handle "ifdef" and similar directives.
## This detects OS specific aliases (windows = "onlywin" and unix = "onlyunix"):
Rdo_collect_aliases(rd)
Rdpack:::Rdo_collect_metadata(rd, "alias") # same
## In contrast, the following do not find "onlywin" and "onlyunix":
sapply(rd[which(tools:::RdTags(rd)=="\\alias")], as.character)
tools:::.Rd_get_metadata(rd, "alias")
Rdpack:::Rdo_collect_metadata(rd, "name")
Rdpack:::Rdo_collect_metadata(rd, "keyword")
}
\keyword{Rd}
Rdpack/man/append_to_Rd_list.Rd 0000644 0001762 0000144 00000004334 13501141722 016151 0 ustar ligges users \name{append_to_Rd_list}
\alias{append_to_Rd_list}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Add content to the element of an Rd object or fragment at a given
position
}
\description{
Add content to the element of an Rd object or fragment at a given
position.
}
\usage{
append_to_Rd_list(rdo, x, pos)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
\item{x}{the content to append, an Rd object or a list of Rd objects.}
\item{pos}{position at which to append \code{x}, typically an integer
but may be anything accepted by the operator "[[".
}
}
\details{
The element of \code{rdo} at position \code{pos} is replaced by its
concatenation with \code{x}. The result keeps the "Rd_tag" of
\code{rdo[[pos]]}.
Argument \code{pos} may specify a position at any depth of the Rd
object.
This function is relatively low level and is mainly for use by other
functions.
}
\value{
the modified \code{rdo} object
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
#rdoseq <- utils:::.getHelpFile(help("seq"))
rdoseq <- Rdo_fetch("seq", "base")
iusage <- which(tools:::RdTags(rdoseq) == "\\\\usage")
iusage
attr(rdoseq[[iusage]], "Rd_tag")
## append a new line after the last usage line
rdoseq2 <- append_to_Rd_list(rdoseq, list(Rdo_newline()), iusage)
## Suppose that we wish to describe the function 'sequence' in the same Rd file.
## We append an usage statement for 'sequence()', without worrying about its
## actual signature.
rdoseq2 <- append_to_Rd_list(rdoseq2, list(Rdo_Rcode("sequence()")), iusage)
Rdo_show(rdoseq2)
## the two operations can be done in one step
rdoseq3 <- append_to_Rd_list(rdoseq, list(Rdo_newline(), Rdo_Rcode("sequence()")), iusage)
Rdo_show(rdoseq3)
## now run reprompt() to update rdoseq3, namely:
## (1) it corrects the signature of 'sequence' in section \usage.
## (2) reports new argument "nvec"
## (3) inserts \item for the new argument(s) in section \arguments.
reprompt(rdoseq3, filename=NA)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
\keyword{RdoBuild}
Rdpack/man/S4formals.Rd 0000644 0001762 0000144 00000002767 13501141722 014402 0 ustar ligges users \name{S4formals}
\alias{S4formals}
\title{Give the formal arguments of an S4 method}
\description{Give the formal arguments of an S4 method.}
\usage{
S4formals(fun, \dots)
}
\arguments{
\item{fun}{name of an S4 generic, a string, or the method, see Details.}
\item{\dots}{further arguments to be passed to \code{getMethod}, see
Details.}
}
\details{
\code{S4formals} gives the formal arguments of the requested method.
If \code{fun} is not of class \code{methodDefinition}, it calls
\code{getMethods}, passing on all arguments.
Typically, \code{fun} is the name of a generic function and the
second argument is the signature of the method as a character
vector. Alternatively, \code{fun} may be the method itself (e.g. obtained
previously from \code{getMethod}) and in that case the \verb{"\dots"}
arguments are ignored. See \code{\link{getMethod}} for full details
and other acceptable arguments.
}
\value{
a pairlist, like \code{\link{formals}}
}
\note{
Arguments of a method after those used for dispatch may be different from
the arguments of the generic. The latter may simply have a \verb{"\dots"}
argument there.
todo: there should be a similar function in the "methods" package, or
at least use a documented feature to extract it.
}
\author{
Georgi N. Boshnakov
}
\examples{
require(stats4) # makes plot() S4 generic
S4formals("plot", c(x = "profile.mle", y = "missing"))
m1 <- getMethod("plot", c(x = "profile.mle", y = "missing"))
S4formals(m1)
}
\keyword{methods}
Rdpack/man/Rdo_append_argument.Rd 0000644 0001762 0000144 00000003176 13521262240 016501 0 ustar ligges users \name{Rdo_append_argument}
\alias{Rdo_append_argument}
\title{
Append an item for a new argument to an Rd object
}
\description{
Append an item for a new argument to an Rd object.
}
\usage{
Rdo_append_argument(rdo, argname, description = NA, indent = " ", create = FALSE)
}
\arguments{
\item{rdo}{an Rd object.}
\item{argname}{name of the argument, a character vector.}
\item{description}{description of the argument, a character vector.}
\item{indent}{a string, typically whitespace.}
\item{create}{not used (todo: remove?)}
}
\details{
Appends one or more items to the section describing arguments of
functions in an Rd object. The section is created if not present.
If \code{description} is missing or NA, a "todo" text is inserted.
The inserted text is indented using the string \code{indent}.
The lengths of \code{argname} and \code{description} should normally
be equal but if \code{description} is of length one, it is repeated to
achieve this when needed.
}
\value{
an Rd object
}
\author{Georgi N. Boshnakov}
\examples{
## the following creates Rd object rdo
dummyfun <- function(x) x
fn <- tempfile("dummyfun", fileext = ".Rd")
reprompt(dummyfun, filename = fn)
rdo <- tools::parse_Rd(fn)
## add documentation for arguments
## that are not in the signature of 'dummyfun()'
dottext <- "further arguments to be passed on."
rdo2 <- Rdo_append_argument(rdo, "\\dots", dottext, create = TRUE)
rdo2 <- Rdo_append_argument(rdo2, "z", "a numeric vector")
## reprompt() warns to remove documentation for non-existing arguments:
Rdo_show(reprompt(rdo2, filename = fn))
unlink(fn)
}
\keyword{RdoBuild}
%\keyword{RdoElements}
Rdpack/man/zzbsdup.Rd 0000644 0001762 0000144 00000001607 13501141722 014221 0 ustar ligges users \name{.bsdup}
\alias{.bsdup}
\alias{.bspercent}
\alias{.anypercent}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Escape backslashes and percent in Rd code}
\description{Escape backslashes and percent in Rd code.}
\usage{
.bspercent(x)
.anypercent(x)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{a character string}
}
\details{
\code{.bsdup(x)} duplicates backslashes.
\code{.bspercent(x)} escapes percent signs.
\code{.anypercent(x)} also escapes percent signs but but only if the
\code{Rd_tag} attribute of \code{x} is not COMMENT.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
##---- Should be DIRECTLY executable !! ----
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{internal}
Rdpack/man/inspect_signatures.Rd 0000644 0001762 0000144 00000003341 13501141722 016426 0 ustar ligges users \name{inspect_signatures}
\alias{inspect_signatures}
\alias{inspect_clmethods}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Inspect signatures of S4 methods
}
\description{
Inspect signatures of S4 methods.
}
\usage{
inspect_clmethods(rdo, final = TRUE)
inspect_signatures(rdo, package = NULL, sec = "Methods")
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
\item{package}{the name of a package, a character string or NULL.}
\item{sec}{the name of a section to look into, a character string.}
\item{final}{If not TRUE insert text with suggestions, otherwise
comment the suggestions out.
}
}
\details{
Signatures in documentation of S4 classes and methods are stored
somewhat differently. \code{inspect_signatures} inspects signatures in
documentation of methods of a function. \code{inspect_clmethods}
inspects signatures in documentation of a class.
\code{inspect_signatures} was written before
\code{inspect_clmethods()} and was geared towards using existing code
for ordinary functions (mainly \code{parse_usage_text()}.
If new methods are found, the functions add entries for them in the Rd
object \code{rdo}.
If \code{rdo} documents methods that do not exist, a message inviting
the user to remove them manually is printed but the offending entries
remain in the object.
At the time of writing, \verb{R CMD check} does not warn about this.
}
\value{
an Rd object
}
\note{todo: need consolidation.}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoS4}
Rdpack/man/Rdo_is_newline.Rd 0000644 0001762 0000144 00000001712 13501141722 015455 0 ustar ligges users \name{Rdo_is_newline}
\alias{Rdo_is_newline}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Check if an Rd fragment represents a newline character
}
\description{
Check if an Rd fragment represents a newline character
}
\usage{
Rdo_is_newline(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
}
\details{
This is a utility function that may be used to tidy up Rd objects.
It returns TRUE if the Rd object represents a newline
character, i.e. it is a character vector of length one containing the
string \verb{"\n"}. Attributes are ignored.
Otherwise it returns FALSE.
}
\value{
TRUE or FALSE
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
%\keyword{RdoElements}
\keyword{RdoBuild}
Rdpack/man/Rdo_modify_simple.Rd 0000644 0001762 0000144 00000002067 13501141722 016165 0 ustar ligges users \name{Rdo_modify_simple}
\alias{Rdo_modify_simple}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Simple modification of Rd objects}
\description{Simple modification of Rd objects.}
\usage{
Rdo_modify_simple(rdo, text, section, ...)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
\item{text}{a character vector}
\item{section}{name of an Rd section, a string.}
\item{\dots}{additional arguments to be passed to \code{Rdo_modify}.}
}
\details{
Argument \code{text} is used to modify (as a replacement of or
addition to) the content of section \code{section} of \code{rdo}.
This function can be used for simple modifications of an Rd object
using character content without converting it separately to Rd.
\code{text} is converted to Rd with \code{char2Rdpiece(text, section)}.
The result is passed to \code{Rdo_modify}, together with
the remaining arguments.
}
\value{
an Rd object
}
\author{Georgi N. Boshnakov}
\seealso{
\code{\link{Rdo_modify}}
}
\keyword{RdoBuild}
Rdpack/man/get_bibentries.Rd 0000644 0001762 0000144 00000010615 13501141722 015504 0 ustar ligges users \name{get_bibentries}
\alias{get_bibentries}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Get all references from a Bibtex file}
\description{Get all references from a Bibtex file.}
\usage{
get_bibentries(\dots, package = NULL, bibfile = "REFERENCES.bib",
url_only = FALSE, stop_on_error = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{\dots}{arguments to be passed on to the file getting functions,
character strings, see `Details'.}
\item{package}{name of a package, a character string or NULL.}
\item{bibfile}{name of a Bibtex file, a character string.}
\item{url_only}{
if TRUE, restrict percent escaping to BibTeX field \code{"URL"}.}
\item{stop_on_error}{
if \code{TRUE} stop on error, otherwise issue a warning and return
an empty \code{bibentryRd} object.
}
}
\details{
\code{get_bibentries} parses the specified file using \code{read.bib}
from package \pkg{bibtex} \insertCite{Rpack:bibtex}{Rdpack} and sets its
\code{names} attribute to the keys of the bib elements
(\code{read.bib()} does this since version version 0.4.0 of
\pkg{bibtex}, as well). Here is what
\code{get_bibentries} does on top of \code{read.bib} (the details are
further below):
\itemize{
\item \code{get_bibentries} deals with percent signs in URL's.
\item if the current working directory is in the development
directory of \code{package}, \code{get_bibentries} will first
search for the bib file under that directory.
}
\code{bibfile} should normally be the base name of the Bibtex file.
Calling \code{get_bibentries} without any \code{"\dots"} arguments
results in looking for the Bibtex file in the current directory if
package is NULL or missing, and in the installation directory of the
specified package, otherwise.
Argument "\dots" may be used to specify directories.
If \code{package} is missing or NULL, the complete path is obtained
with \code{file.path(..., bibfile)}. Otherwise \code{package} must be
a package name and the file is taken from the installation directory
of the package. Again, argument "\dots" can specify subdirectory
as in \code{system.file}.
If the current working directory is in the development directory of
\code{package}, the bib file is first sought there before resorting to
the installation directory.
Although the base \R packages do not have files REFERENCES.bib,
argument \code{package} can be set to one of them,
e.g. \code{"base"}. This works since package \pkg{bibtex} provides bib
files for the core packages.
By default, \code{get_bibentries} escapes unescaped percent signs in
all fields of bibtex objects. To restrict this only to field "url",
set argument \code{url_only} to \code{FALSE}.
\code{get_bibentries} returns an object from class
\code{"bibentryRd"}, which inherits from bibentry. The printing method
for \code{"bibentryRd"} unescapes percent signs in URLs for some
styles where the escapes are undesirable.
}
\value{
a bibentryRd object inheriting from bibentry
}
\references{
\insertAllCited{}
}
\author{Georgi N. Boshnakov}
% \note{
% %% ~~further notes~~
% }
%
% %% ~Make other sections like Warning with \section{Warning }{....} ~
%
% \seealso{
% %% ~~objects to See Also as \code{\link{help}}, ~~~
% }
\examples{
r <- get_bibentries(package = "Rdpack")
r
print(r, style = "html")
b <- get_bibentries(package = "stats")
print(b[[1]], style = "R")
print(b[[1]], style = "citation")
## here the url field contains percent encoding
fn_url <- system.file("examples", "url_with_percents.bib", package = "Rdpack")
u <- get_bibentries(bibfile = fn_url)
## the links produced by all of the following are valid
## and can be put in a browser
print(u, style = "html")
print(u, style = "bibtex")
print(u, style = "R")
print(u, style = "text")
print(u, style = "citation")
## The link here contains escapes but when put in a LaTeX document
## which uses the JSS style it generates correct clickable link,
## (see Details section)
print(u, style = "latex")
## here the journal field contains percent encoding
fn_other <- system.file("examples", "journal_with_percents.bib", package = "Rdpack")
j <- get_bibentries(bibfile = fn_url)
print(j, style = "html")
print(j, style = "bibtex")
print(j, style = "R")
print(j, style = "text")
print(j, style = "citation")
print(j, style = "latex")
}
\keyword{ bibtex }
\keyword{programming}
Rdpack/man/Rdreplace_section.Rd 0000644 0001762 0000144 00000003661 13501141722 016147 0 ustar ligges users \name{Rdreplace_section}
\alias{Rdreplace_section}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{ Replace the contents of a section in one or more Rd files}
\description{Replace the contents of a section in one or more Rd files.}
\usage{
Rdreplace_section(text, sec, pattern, path = "./man", exclude = NULL, ...)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{text}{the replacement text, a character string.}
\item{sec}{the name of the section without the leading backslash, as
for \code{Rdo_set_section}.}
\item{pattern}{regular expression for R files to process, see
Details.}
\item{path}{the directory were to look for the Rd files.}
\item{exclude}{regular expression for R files to exclude, see
Details.}
\item{\dots}{not used.}
}
\details{
\code{Rdreplace_section} looks in the directory specified by
\code{path} for files whose names match \code{pat} and drops those
whose names match \code{exclude}. Then it replaces section \code{sec}
in the files selected in this way.
\code{Rdreplace_section} is a convenience function to replace a
section (such as a keyword or author) in several files in one go.
It calls \code{\link{Rdo_set_section}} to do the work.
}
\value{
A vector giving the full names of the processed Rd files, but the
function is used for the side effect of modifying them as described in
section Details.
}
% \references{
% %% ~put references to the literature/web site here ~
% }
\author{
Georgi N. Boshnakov
}
% \note{
% %% ~~further notes~~
% }
%
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{Rdo_set_section}}
}
\examples{
\dontrun{
# replace the author in all Rd files except pkgname-package
Rdreplace_section("A. Author", "author", ".*[.]Rd$", exclude = "-package[.]Rd$")
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoBuild}
Rdpack/man/macros/ 0000755 0001762 0000144 00000000000 13501141722 013511 5 ustar ligges users Rdpack/man/macros/refmacros.Rd 0000644 0001762 0000144 00000003527 13501141722 015770 0 ustar ligges users % insert reference #1 - key, #2 - package
\newcommand{\insertRef}{\Sexpr[results=rd,stage=build]{Rdpack::insert_ref(key="#1",package="#2")}}
% insert reference #1 - key, #2 - package
\newcommand{\insertCiteOnly}{\Sexpr[results=rd,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(key="#1",package="#2", cached_env=.Rdpack.currefs,cite_only=TRUE)}}
\newcommand{\insertCite}{\Sexpr[results=rd,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(key="#1",package="#2", cached_env=.Rdpack.currefs)}}
\newcommand{\insertNoCite}{\Sexpr[results=hide,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(key="#1",package="#2", cached_env=.Rdpack.currefs,dont_cite=TRUE)}}
\newcommand{\insertAllCited}{\Sexpr[results=rd,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_all_ref(.Rdpack.currefs)}}
% insert reference #1 - key, #2 - package
%\newcommand{\runExamples}{\Sexpr[results=rd,stage=build]{deparse({#1})}}
\newcommand{\runExamples}{\Sexpr[results=rd,stage=build]{Rdpack:::run_examples(quote({#1}))}}
%\newcommand{\printExample}{\Sexpr[results=rd,stage=build]{Rdpack:::run_examples(quote({#1}), Rdsection = "\\\\\\\\preformatted")}}
\newcommand{\printExample}{\Sexpr[results=rd,stage=build]{.Rdpack.e <- environment();Rdpack:::run_examples(quote({#1}), local = .Rdpack.e, Rdsection = "preformatted")}}
%\newcommand{\printExample}{\Sexpr[results=rd,stage=build]{Rdpack:::run_examples(quote({#1}), local = parent.frame(), Rdsection = "preformatted")}}
% insert reference #1 - filename, #2 - package
\newcommand{\insertFig}{\Sexpr[results=rd,stage=build]{Rdpack:::insert_fig("#1","#2", { #3 })}}
\newcommand{\makeFig}{\Sexpr[results=hide,stage=build]{Rdpack:::insert_fig("#1","#2", { #3 }, insert=FALSE)}}
Rdpack/man/zzasym_compare.Rd 0000644 0001762 0000144 00000003267 13501141722 015567 0 ustar ligges users \name{.asym_compare}
\alias{.asym_compare}
\alias{.ocompare}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Tensor comparison and asymmetric comparison between two vectors}
\description{Tensor comparison and asymmetric comparison between two
vectors.}
\usage{
.ocompare(x, y)
.asym_compare(x, y)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{
%% ~~Describe \code{x} here~~
}
\item{y}{
%% ~~Describe \code{y} here~~
}
}
\details{
\code{.ocompare} (for "outer compare") returns a matrix whose (i,j)th
element is TRUE if x[i] is identical to y[j], and FALSE otherwise.
\code{.asym_compare} calls \code{.ocompare} and iterprets its result
asymmetrically. Elements of \code{x} that are not in \code{y} ae
considered "new". Similarly, Elements of \code{y} that are not in
\code{x} ae considered "removed". Elements that are in both are
"common".
Todo: check if the above is correct or the other way round! !!!
}
\value{
For \code{.ocompare}, a matrix as described in Details.
For \code{.asym_compare} a list with indices as follows.
\item{i_new}{new elements, indices in \code{x} of elements that are not
in \code{y}.}
\item{i_removed}{removed elements, indices in \code{y} of elements that are not
in \code{x}.}
\item{i_common}{common elements, indices in \code{x} of elements that
are in both, \code{x} and \code{y}.}
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
##---- Should be DIRECTLY executable !! ----
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{internal}
Rdpack/man/parse_pairlist.Rd 0000644 0001762 0000144 00000007015 13501141722 015540 0 ustar ligges users \name{parse_pairlist}
\alias{parse_pairlist}
%\alias{pairlist2f_usage}
\alias{pairlist2f_usage1}
\title{Parse formal arguments of functions}
\description{Parse formal arguments of functions and convert them to
f_usage objects.}
\usage{
parse_pairlist(x)
pairlist2f_usage1(x, name, S3class = "", S4sig = "", infix = FALSE,
fu = TRUE)
}
\arguments{
\item{x}{a pairlist representing the arguments of a function.}
\item{name}{function name.}
\item{S3class}{S3 class, see `Details'}
\item{S4sig}{S4 signature, see Details.}
\item{infix}{if \code{TRUE} the function usage is in infix form, see
Details.}
\item{fu}{if TRUE the object is a function, otherwise it is something
else (e.g. a variable or a constant like \code{pi} and \code{Inf}).
}
}
\details{
These functions are mostly internal.
% \code{x} is a single pairlist object for \code{parse_pairlist} and
% \code{pairlist2f_usage1}.
% For \code{pairlist2f_usage} it may be a list of pairlist objects.
% (\code{pairlist2f_usage} has been removed)
\code{parse_pairlist} parses the pairlist object, \code{x}, into a
list with two components. The first component contains the names of
the arguments. The second component is a named list containing the
default values, converted to strings. Only arguments with default
values have entries in the second component (so, it may be of length
zero). If \code{x} is empty or \code{NULL}, both components have
length zero. An example:
\printExample{parse_pairlist(formals(system.file))}
\code{pairlist2f_usage1()} creates an object of S3 class
\code{"f_usage"}. The object contains the result of parsing \code{x}
with \code{parse_pairlist(x)} and a number of additional components
which are copies of the remaining arguments to the function (without
any processing). The components are listed in section Values.
\code{S3class} is set to an S3 class for for S3 methods, \code{S4sig}
is the signature of an S4 method (as used in Rd macro
\verb{\S4method}). \code{infix} is \code{TRUE} for the rare occations
when the function is primarily used in infix form.
Class \code{"f_usage"} has a method for \code{as.character()} which
generates a text suitable for inclusion in Rd documentation.
\printExample{pairlist2f_usage1(formals(summary.lm), "summary", S3class = "lm")}
}
\value{
For \code{parse_pairlist}, a list with the following components:
\item{argnames}{the names of all arguments, a character vector}
\item{defaults}{
a named character vector containing the default values, converted to
character strings. Only arguments with defaults have entries in this
vector.
}
For \code{pairlist2f_usage1}, an object with S3 class
\code{"f_usage"}. This is a list as for \code{parse_pairlist} and
the following additional components:
\item{name}{function name, a character string.}
\item{S3class}{
S3 class, a character string; \code{""} if not an S3 method.
}
\item{S4sig}{S4 signature; \code{""} if not an S4 method.}
\item{infix}{a logical value, \code{TRUE} for infix operators.}
\item{fu}{
indicates the type of the object, usually \code{TRUE}, see Details.
}
% For \code{pairlist2f_usage}, a list of \code{"f_usage"} objects.
}
\author{Georgi N. Boshnakov}
\seealso{
\code{\link{promptUsage}} accepts \code{f_usage} objects,
\code{\link{get_usage}}
}
\examples{
parse_pairlist(formals(lm))
parse_pairlist(formals(system.file))
s_lm <- pairlist2f_usage1(formals(summary.lm), "summary", S3class = "lm")
s_lm
as.character(s_lm)
}
\keyword{RdoBuild}
Rdpack/man/Rdo_modify.Rd 0000644 0001762 0000144 00000007042 13501141722 014612 0 ustar ligges users \name{Rdo_modify}
\alias{Rdo_replace_section}
\alias{Rdo_modify}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Replace or modify parts of Rd objects
}
\description{
Replace or modify parts of Rd objects.
}
\usage{
Rdo_modify(rdo, val, create = FALSE, replace = FALSE, top = TRUE)
Rdo_replace_section(rdo, val, create = FALSE, replace = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
\item{val}{an Rd fragment.}
\item{create}{if TRUE, create a new section, see `Details'.}
\item{replace}{a logical, if TRUE \code{val} replaces the old content,
otherwise \code{val} is concatenated with it, see `Details'.
}
\item{top}{a logical, if TRUE examine also the "Rd_tag" of \code{rdo},
see `Details'.
}
}
\details{
Argument \code{rdo} is an Rd object (complete or a fragment) to be
modified. \code{val} is an Rd fragment to use for modification.
Basically, \code{val} is appended to (if \code{replace} is FALSE) or
replaces (if \code{replace} is TRUE) the content of an element of
\code{rdo} which has the same "Rd_tag" as \code{val}.
Argument \code{top} specifies whether to check the "Rd_tag" of
\code{rdo} itself, see below.
Here are the details.
If \code{top} is TRUE and \code{rdo} and \code{val} have the same
(non-NULL) "Rd_tag", then the action depends on \code{replace}
(argument \code{create} is ignored in this case).
If \code{replace} is TRUE, \code{val} is returned. Otherwise
\code{rdo} and \code{val} are, effectively, concatenated. For example,
\code{rdo} may be the "arguments" section of an Rd object and
\code{val} may also be an "arguments" section containing new
arguments.
Otherwise, an element with the "Rd_tag" of \code{val} is searched in
\code{rdo} using \code{tools:::RdTags()}. If such elements are found,
the action again depends on \code{replace}.
\enumerate{
\item
If \code{replace} is a character string, then the first element of
\code{rdo} that is a list whose only element is identical to the
value of \code{replace} is replaced by \code{val}. If such an
element is not present and \code{create} is TRUE, \code{val} is
inserted in \code{rdo}. If \code{create} is FALSE, \code{rdo} is not
changed.
\item
If \code{replace} is TRUE, the first element found is replaced with
\code{val}.
\item
If \code{replace} is FALSE, \code{val} is appended to the first
element found.
}
If no element with the "Rd_tag" of \code{val} is found the action
depends on \code{create}. If \code{create} is TRUE, then \code{val}
is inserted in \code{rdo}, effectively creating a new section. If
\code{create} is FALSE, an error is thrown.
\code{Rdo_replace_section} is like \code{Rdo_modify} with argument
\code{top} fixed to TRUE and the default for argument \code{replace}
set to TRUE. It hardly makes sense to call \code{Rdo_replace_section}
with \code{replace = FALSE} but a character value for it may be
handy in some cases, see the examples.
}
\value{
an Rd object or fragment, as described in `Details'
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
# a <- tools::parse_Rd("./man/promptUsage.Rd")
# char2Rdpiece("documentation", "keyword")
# this changes a keyword from Rd to documentation
# Rdo_replace_section(a, char2Rdpiece("documentation", "keyword"), replace = "Rd")
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoBuild}
Rdpack/man/char2Rdpiece.Rd 0000644 0001762 0000144 00000003706 13501141722 015015 0 ustar ligges users \name{char2Rdpiece}
\alias{char2Rdpiece}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Convert a character vector to Rd piece
}
\description{
Convert a character vector to Rd piece.
}
\usage{
char2Rdpiece(content, name, force.sec = FALSE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{content}{a character vector.}
\item{name}{name of an Rd macro, a string.}
\item{force.sec}{TRUE or FALSE, see `Details'.}
}
\details{
Argument \code{content} is converted to an Rd piece using
\code{name} to determine the format of the result.
The \verb{Rd tag} of \code{content} is set as appropriate for \code{name}.
More specifically, if \code{name} is the name of a macro (without the
leading `\verb{\\}') whose content has a known "Rdtag", that tag is
used. Otherwise the tag is set to "TEXT".
If \code{force.sec} is TRUE, \code{name} is treated as the name of a
top level section of an Rd object. A top level section is exported as
one argument macro if it is a standard section (detected with
\code{\link{is_Rdsecname}}) and as the two argument macro
"\verb{\section}" otherwise.
If \code{force.sec} is FALSE, the content is exported as one argument
macro without further checks.
}
\author{Georgi N. Boshnakov}
\note{
This function does not attempt to escape special symbols like `\%'.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
## add a keyword section
a1 <- char2Rdpiece("graphics", "keyword")
a1
## "keyword" is a standard Rd top level section, so 'force.sec' is irrelevant
a2 <- char2Rdpiece("graphics", "keyword", force.sec = TRUE)
identical(a1, a2)
## an element suitable to be put in a "usage" section
char2Rdpiece("log(x, base = exp(1))", "usage")
## a user defined section "Todo"
char2Rdpiece("Give more examples for this function.", "Todo", force.sec = TRUE)
}
%\keyword{RdoProgramming}
%\keyword{RdoElements}
\keyword{RdoBuild}
Rdpack/man/bibentry_key.Rd 0000644 0001762 0000144 00000001361 13501141722 015203 0 ustar ligges users \name{bibentry_key}
\alias{bibentry_key}
\title{Give the key associated with a bibentry element}
\description{Give the key associated with a bibentry element}
\usage{
bibentry_key(x)
}
\arguments{
\item{x}{a single bibentry element.}
}
\details{
2018-03-24: This function is deprecated (and not used in the package
for a long time).
This is a convenience function to get the "key" attribute of a
reference represented by a bibentry element.
There should be a better way to do this, I must be missing something
here. (2018-03-24: indeed: \code{unlist(x$key)} or \code{x[[1]]$key},
was this available back then?)
}
\value{
a character string
}
\author{Georgi N. Boshnakov}
\keyword{bibtex}
\keyword{programming}
\keyword{internal}
Rdpack/man/inspect_Rd.Rd 0000644 0001762 0000144 00000005101 13501141722 014603 0 ustar ligges users \name{inspect_Rd}
\alias{inspect_Rd}
\alias{inspect_Rdfun}
\alias{inspect_Rdmethods}
\alias{inspect_Rdclass}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Inspect and update an Rd object or file
}
\description{
Inspect and update an Rd object or file.
}
\usage{
inspect_Rd(rdo, package = NULL)
inspect_Rdfun(rdo, alias_update = TRUE)
inspect_Rdmethods(rdo, package = NULL)
inspect_Rdclass(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object or file name}
\item{package}{name of a package}
\item{alias_update}{if \code{TRUE}, add missing alias entries for
functions with usage statements.}
}
\details{
These functions check if the descriptions of the objects in \code{rdo}
are consistent with their current definitions and update them, if
necessary. The details depend on the type of the documented topic.
In general, the functions update entries that can be produced
programmatically, possibly accompanied with a suggestion to the author
to write some additional text.
\code{inspect_Rd} checks the \verb{\name} section of \code{rdo} and
dispatches to one of the other \code{inspect_XXX} functions depening
on the type of the topic.
\code{inspect_Rdfun} processes documentation of functions. It checks
the usage entries of all functions documented in \code{rdo} and
updates them if necessary. It appends "\verb{\alias}" entries for
functions that do not have them. Entries are created for any arguments
that are missing from the "\verb{\arguments}" section. Warning is
given for arguments in the "\verb{\arguments}" section that are not
present in at least one usage entry. \code{inspect_Rdfun} understands
the syntax for S3 methods and S4 methods used in "usage" sections, as
well. The S4 methods may also be in a section as produced by
\code{promptMethods}.
\code{inspect_Rdmethods} checks and updates documentation of an S4
generic function.
\code{inspect_Rdclass} checks and updates documentation of an S4
class.
Since method signatures and descriptions may be present in
documentation of a class, as well as in that of methods, the question
arises where to put "\verb{\alias}" entries to avoid duplication.
Currently, alias entries are put in method descriptions.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% \examples{
% ##---- Should be DIRECTLY executable !! ----
% }
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoProgramming}
Rdpack/man/zzcapture_promptany.Rd 0000644 0001762 0000144 00000005102 13501141722 016652 0 ustar ligges users \name{.capture_promptAny}
\alias{.capture_promptAny}
\alias{.capture_installed_help}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Internal functions used by reprompt}
\description{Internal functions used by reprompt.}
\usage{
.capture_promptAny(fnam, type, package, final, \dots, methods)
.capture_installed_help(fnam, type = NULL, package = NULL,
suffix = NULL)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{fnam}{extended name of the object, such as "fun", "gen-methods",
"S4cl-class" or "pkname-package", see details.}
\item{final}{if TRUE, put dummy title and description to make the
file immediately usable.}
\item{\dots}{further arguments to pass on to the prompt function(s).}
\item{methods}{methods to consider, used only when describing S4 methods.}
\item{type}{type of documentation, such as "methods" and "class", see
Details.}
\item{package}{the package where to look for objects or documentation,
useful if more objects of the same name exist.}
\item{suffix}{a character string to be appended to \code{fnam} to
obtain the complete name of the help topic, e.g. "-class",
"-method".
}
}
\details{
These functions are used internally by \code{reprompt}. It falls back
to them when only when the user has not supplied an Rd file in the
call.
Note that for editing it is preferable to use the source Rd files
(when available), since some hard coded information in the installed
help may have been produced by more elaborated code in the Rd sources,
most notably Sweave expressions.
\code{.capture_promptAny} is used to generate documentation when none
has been supplied by the user or loaded in the session.
\code{.capture_promptAny} parses \code{fnam} to obtain the name of the
object and the type of the required documentation (function, methods,
class), then generates it. Currently this is done with the built in
functions of the \code{promptXXX} family.
\code{.capture_installed_help} does exactly that --- it captures the
currently installed requested help topic. This function needs clean
up. It was originally written at a time when both the old and new help
formats where co-existing.
}
\value{
an Rd object on success or a \code{try-error} object otherwise
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
##---- Should be DIRECTLY executable !! ----
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{internal}
Rdpack/man/parse_usage_text.Rd 0000644 0001762 0000144 00000002654 13501141722 016065 0 ustar ligges users \name{parse_usage_text}
\alias{parse_usage_text}
\alias{parse_1usage_text}
\title{
Parse usage text
}
\description{
Parse usage text.
}
\usage{
parse_1usage_text(text)
parse_usage_text(text)
}
\arguments{
\item{text}{
conceptually, the content of the usage section of one or more Rd objects, a
character vector, see Details.
}
}
\details{
For \code{parse_usage_text}, \code{text} is a character vector
representing the contents of the usage section of an Rdo object.
\code{parse_usage_text} does some preprocessing of \code{text} then
calls \code{parse_1usage_text} for each usage statement.
The preprocessing changes "\verb{\\}\verb{dots}" to "\verb{...}" and
converts S3- and S4-method descriptions to a form suitable for
\code{parse()}. The text is then parsed (with \code{parse}) and
"\verb{srcref}" attribute removed from the parsed object.
todo: currently no checks is made for Rd comments in \code{text}.
\code{parse_1usage_text} processes the usage statement of one object
and calls \code{\link{pairlist2f_usage1}} to convert it to an object
from S3 class \code{"f_usage"}.
}
\value{
for \code{parse_1usage_text}, an object from S3 class
\code{"f_usage"}, see \code{\link{pairlist2f_usage1}} for its
structure.
for \code{parse_usage_text}, a list containing one element for each
usage entry, as prepared by \code{parse_1usage_text}
}
\author{Georgi N. Boshnakov}
\keyword{RdoUsage}
Rdpack/man/rdo_text_restore.Rd 0000644 0001762 0000144 00000003277 13501141722 016120 0 ustar ligges users \name{rdo_text_restore}
\alias{rdo_text_restore}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Ensure exported fragments of Rd are as the original}
\description{
For an Rd object imported from a file, this function ensures that
fragments that were not not changed during the editing of the object
remain unchanged in the exported file. This function is used by
reprompt() to ensure exactly that.
}
\usage{
rdo_text_restore(cur, orig, pos_list, file)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{cur}{an Rd object}
\item{orig}{an Rd object}
\item{pos_list}{a list of srcref objects specifying portions of files
to replace, see 'Details'.}
\item{file}{a file name, essentially a text representation of
\verb{cur}.}
}
\details{
This is essentially internal function. It exists because, in general,
it is not possible to restore the original Rd file from the Rd object
due to the specifications of the Rd format. The file exported from
the parsed Rd file is functionally equivalent to the original but
equivalent things for the computer are not necessarily equally
pleasant for humans.
This function is used by \code{reprompt} when the source is from a
file and the option to keep the source of unchanged sections as in the
original.
\strong{todo:} needs clean up, there are unnecessary arguments in
particular.
}
\value{
the main result is the side effect of replacing sections in
\code{file} not changed by \code{reprompt} with the original ones.
}
\author{
Georgi N. Boshnakov
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{reprompt}}
}
\keyword{RdoProgramming}
Rdpack/man/Rdo_macro.Rd 0000644 0001762 0000144 00000005044 13501141722 014424 0 ustar ligges users \name{Rdo_macro}
\alias{Rdo_macro}
\alias{Rdo_macro1}
\alias{Rdo_macro2}
\alias{Rdo_item}
\alias{Rdo_sigitem}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Format Rd fragments as macros (todo: a baffling title!)
}
\description{
Format Rd fragments as macros, generally by putting them in a list and
setting the "Rd_tag" as needed.
}
\usage{
Rdo_macro(x, name)
Rdo_macro1(x, name)
Rdo_macro2(x, y, name)
Rdo_item(x, y)
Rdo_sigitem(x, y, newline = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{an object.}
\item{y}{an object.}
\item{name}{the "\verb{Rd_tag}", a string.}
\item{newline}{currently ignored.}
}
\details{
\code{Rdo_macro1} wraps \code{x} in a list with "\verb{Rd_tag}"
\code{name}. This is the representation of Rd macros with one argument.
\code{Rdo_macro2} basically wraps a possibly transformed \code{x} and
\code{y} in a list with "\verb{Rd_tag}" \code{name}. More specifically,
if \code{x} has a non-NULL "\verb{Rd_tag}", \code{x} is wrapped in
\code{list}. Otherwise \code{x} is left as is, unless \code{x} is a
character string, when it is converted to a text Rd element and
wrapped in \code{list}. \code{y} is processed in the same way.
This is the representation of Rd macros with two arguments.
\code{Rdo_macro} returns an object with "\verb{Rd_tag}" \code{name},
constructed as follows. If \code{x} is not of class "character", its
attribute "\verb{Rd_tag}" is set to \code{name} and the result
returned without further processing. Otherwise, if it is of class
"character", \code{x} is tagged as an Rd "TEXT" element. It is then
wrapped in a list but only if \code{name} is one of "\verb{\eqn}" or
"\verb{\deqn}". Finally, \code{Rdo_macro1} is called on the
transformed object.
\code{Rdo_item} is equivalent to \code{Rdo_macro2} with \code{name}
set to "\verb{\item}".
\code{Rdo_sigitem} is for items which have the syntax used in
description of signatures. In that case the first argument of
"\verb{\item}" is wrapped in "\verb{\code}". If \code{y} is missing,
a text inviting the author to provide a description of the function
for this signature is inserted.
}
\value{
An Rd element with appropriately set \verb{Rd_tag}, as described in
`Details'.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
%\keyword{RdoElements}
\keyword{RdoBuild}
Rdpack/man/Rdo_which.Rd 0000644 0001762 0000144 00000004201 13501141722 014417 0 ustar ligges users \name{Rdo_which}
\alias{Rdo_which}
\alias{Rdo_which_tag_eq}
\alias{Rdo_which_tag_in}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Find elements of Rd objects for which a condition is true}
\description{Find elements of Rd objects for which a condition is true.}
\usage{
Rdo_which(rdo, fun)
Rdo_which_tag_eq(rdo, tag)
Rdo_which_tag_in(rdo, tags)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
\item{fun}{a function to evaluate with each element of \code{rdo}.}
\item{tag}{a character string.}
\item{tags}{a character vector.}
}
\details{
These functions return the indices of the (top level) elements of
\code{rdo} which satisfy a condition.
\code{Rdo_which} finds elements of \code{rdo} for which
the function \code{fun} gives TRUE.
\code{Rdo_which_tag_eq} finds elements with a specific \code{Rd_tag}.
\code{Rdo_which_tag_in} finds elements whose \code{Rd_tag}'s are among
the ones specified by \code{tags}.
%% ~~ If necessary, more details than the description above ~~
}
\value{
a vector of positive integers
}
% \references{
% %% ~put references to the literature/web site here ~
% }
\author{Georgi N. Boshnakov}
% \note{
% %% ~~further notes~~
% }
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{Rdo_locate}} which searches recursively the Rd object.
}
\examples{
## get the help page for topoc seq()
rdo_seq <- tools::Rd_db("base")[["seq.Rd"]]
## find location of aliases in the topic
( ind <- Rdo_which_tag_eq(rdo_seq, "\\alias") )
## extract the first alias
rdo_seq[[ ind[1] ]]
\dontrun{
## extract all aliases
rdo_seq[ind]
}
db_bibtex <- tools::Rd_db("bibtex")
names(db_bibtex)
## Rdo object for read.bib()
rdo_read.bib <- db_bibtex[["read.bib.Rd"]]
Rdo_tags(rdo_read.bib)
## which elements of read.bib are aliases?
Rdo_which_tag_eq(rdo_read.bib, "\\alias")
rdo_read.bib[[3]]
## which elements of read.bib contain R code?
Rdo_which(rdo_read.bib, function(x) any(Rdo_tags(x) == "RCODE") )
rdo_read.bib[[5]]
## which contain prose?
Rdo_which(rdo_read.bib, function(x) any(Rdo_tags(x) == "TEXT") )
}
\keyword{Rd}
Rdpack/man/list_Rd.Rd 0000644 0001762 0000144 00000003505 13501141722 014117 0 ustar ligges users \name{list_Rd}
\alias{list_Rd}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Combine Rd fragments}
\description{Combine Rd fragments and strings into one object.}
\usage{
list_Rd(..., Rd_tag = NULL, Rd_class = FALSE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{\dots}{named list of objects to combine, see `Details'.}
\item{Rd_tag}{if non-null, a value for the \verb{Rd_tag} of the result.}
\item{Rd_class}{logical; if TRUE, the result will be of class "Rd".}
}
\details{
The names of named arguments specify tags for the corresponding
elements (not arbitrary tags, ones that are converted to macro names
by prepending backslash to them). This is a convenient way to specify
sections, items, etc, in cases when the arguments have not being
tagged by previous processing. Character string arguments are
converted to the appropriate Rd pieces.
Argument \code{...} may contain a mixture of character vactors and Rd
pieces.
}
\value{
an Rd object or list with \verb{Rd_tag} attribute, as specified by the
arguments.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{c_Rd}}
}
\examples{
## see also the examples for c_Rd
dummyfun <- function(x, ...) x
u1 <- list_Rd(name = "Dummyname", alias = "dummyfun",
title = "Dummy title", description = "Dummy description",
usage = "dummyfun(x)",
value = "numeric vector",
author = "A. Author",
Rd_class=TRUE )
Rdo_show(u1)
# call reprompt to fill the arguments section (and correct the usage)
fn <- tempfile("dummyfun", fileext = "Rd")
reprompt(dummyfun, filename = fn)
# check that the result can be parsed and show it.
Rdo_show(tools::parse_Rd(fn))
unlink(fn)
}
\keyword{RdoBuild}
Rdpack/man/parse_text.Rd 0000644 0001762 0000144 00000003430 13501141722 014672 0 ustar ligges users \name{parse_text}
\alias{parse_text}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Parse expressions residing in character vectors}
\description{Parse expressions residing in character vectors.}
\usage{
parse_text(text, ..., keep = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{text}{the text to parse, normally a character vector but can be
anything that \code{parse} accepts for this artgument.}
\item{\dots}{additional arguments to be passed on to \code{parse}.}
\item{keep}{required setting for option \verb{keep.source}, see
details.}
}
\details{
This is like \code{parse(text=text,\dots)} with the additional feature
that if the setting of option "keep.source" is not as requested by
argument \code{keep}, it is set to \code{keep} before calling
\code{parse} and restored afterwards.
This function is no longer exported by \pkg{Rdpack} since it is here
for historical reasons and to avoid unnecessary dependence on
\pkg{gbutils}. Use the equivalent \code{gbutils::parse_text} instead.
}
\value{
an expression representing the parsed text, see \code{link{parse}} for
details
}
\author{Georgi N. Boshnakov}
\note{
The usual setting of option "keep.source" in interactive sessions is
TRUE. However, in `R CMD check' it is FALSE.
As a consequence, examples from the documentation may run fine when
copied and pasted in an R session but (rightly) fail `R CMD check',
when they depend on option "keep.source" being \code{TRUE}.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{parse}},
\code{\link[gbutils]{parse_text}}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{programming}
\keyword{internal}
Rdpack/man/Rdo_empty_sections.Rd 0000644 0001762 0000144 00000003061 13501141722 016365 0 ustar ligges users \name{Rdo_empty_sections}
\alias{Rdo_empty_sections}
\alias{Rdo_drop_empty}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Find or remove empty sections in Rd objects}
\description{Find or remove empty sections in Rd objects}
\usage{
Rdo_empty_sections(rdo, with_bs = FALSE)
Rdo_drop_empty(rdo, sec = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object or Rd source text.}
\item{with_bs}{if \code{TRUE} return the section names with the
leading backslash.}
\item{sec}{not used}
}
\details{
The function \code{checkRd} is used to determine which sections are
empty.
}
\value{
For \code{Rdo_empty_sections}, the names of the empty sections as a
character vector.
For \code{Rdo_drop_empty}, the Rd object stripped from empty
sections.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
dummyfun <- function(x) x
rdo8 <- list_Rd(name = "Dummyname", alias = "dummyfun",
title = "Dummy title", description = "Dummy description",
usage = "dummyfun(x,y)",
value = "numeric vector",
author = "",
details = "",
note = "",
Rd_class=TRUE )
Rdo_empty_sections(rdo8) # "details" "note" "author"
rdo8a <- Rdo_drop_empty(rdo8)
Rdo_empty_sections(rdo8a) # character(0)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{Rdprocessing}
\keyword{RdoBuild}
Rdpack/man/insert_all_ref.Rd 0000644 0001762 0000144 00000004424 13521613435 015517 0 ustar ligges users \name{insert_all_ref}
\alias{insert_all_ref}
\title{Insert references cited in packages}
\description{Insert references cited in packages. }
\usage{
insert_all_ref(refs, style = "")
}
\arguments{
\item{refs}{
% TODO: is this description up-to-date?
a matrix specifying key-package pairs of the references to insert.
Can also be a cached environment, see Details.
}
\item{style}{a bibstyle, see Details.}
}
\details{
\code{insert_all_ref} is the workhorse behind several Rd macros for
inclusion of references in Rd documentation.
Argument \code{refs} is a two-column character matrix. The first
column specifies bibtex keys. To specify more than one key in a
single element, separate them by commas. The second column specifies the
package in which to look for the keys.
A key equal to "*" requests all keys in the corresponding package.
\code{insert_all_ref} drops duplicated keys, collects the references,
and converts them to Rd textual representation for inclusion in Rd
documentation files.
\code{refs} can be a cached environment. This is for internal use and
not documented.
}
\value{
for \code{insert_all_ref}, a character string containing a textual
representation of the references, suitable for inclusion in an Rd
file
}
\references{
Currently there are no citations. Nevethelese, I have put
\verb{\insertAllCited{}} just after this paragraph to show the message
that it prints when there are no citations. This seems better than
printing nothing but it may be argued also that there should be a
warning as well.
\insertAllCited{}
}
\author{Georgi N. Boshnakov}
% \note{
% %% ~~further notes~~
% }
%
% %% ~Make other sections like Warning with \section{Warning }{....} ~
%
% \seealso{
% %% ~~objects to See Also as \code{\link{help}}, ~~~
% }
\examples{
bibs <- bibtex::read.bib(package = "tools")
bibs
## a reference from package Rdpack
cat(insert_all_ref(matrix(c("Rpack:bibtex", "Rdpack"), ncol = 2)), "\n")
## more than one reference from package Rdpack, separate the keys with commas
cat(insert_all_ref(matrix(c("parseRd,Rpack:bibtex", "Rdpack"), ncol = 2)), "\n")
## all references from package Rdpack
cat(insert_all_ref(matrix(c("*", "Rdpack"), ncol = 2)), "\n")
}
\keyword{documentation}
% use one of RShowDoc("KEYWORDS")
Rdpack/man/predefined.Rd 0000644 0001762 0000144 00000005514 13501141722 014626 0 ustar ligges users \name{predefined}
\alias{Rdo_predefined_sections}
\alias{Rdo_piece_types}
\alias{rdo_top_tags}
\title{
Tables of predefined sections and types of pieces of Rd objects
}
\description{
Tables of predefined sections and types of pieces of Rd objects.
}
\usage{
Rdo_predefined_sections
Rdo_piece_types
rdo_top_tags
}
\details{
The Rd syntax defines several tables
\insertCite{parseRd}{Rdpack}. \pkg{Rdpack} stores them in the
variables described here.
\code{Rdo_predefined_sections} is a named character vector of types of the
top level sections of an Rd object.
\code{Rdo_piece_types} is a named character vector giving the types of
the core (all possible?) Rd macros.
\strong{NOTE:} These objects are hard coded and need to be updated if
the specifications of the Rd format are updated.
todo: write functions that go through existing Rd documentation to
discover missing or wrong items.
}
\value{
for \code{Rdo_predefined_sections}, the name-value pairs are given in
the following table. For example,
\code{Rdo_predefined_sections["examples"]} is
\Sexpr[stage=build,results=rd]{Rdo_predefined_sections["examples"]}.
\Sexpr[stage=build,results=rd]{require(Rdpack);
paste(
"\\\\ifelse{latex}{\\\\out{",
"\\\\begin{tabular}{ll|lll}",
paste(names(Rdo_predefined_sections)[1:5], Rdo_predefined_sections[1:5],
" ",
names(Rdo_predefined_sections)[-(1:5)], Rdo_predefined_sections[-(1:5)],
sep=" & ", collapse="\\\\\\\\\\\\\\\\ \n"),
"\\\\end{tabular}",
"}}{",
"\\\\tabular{lllll}{",
paste(names(Rdo_predefined_sections)[1:5], Rdo_predefined_sections[1:5],
" | ",
names(Rdo_predefined_sections)[-(1:5)], Rdo_predefined_sections[-(1:5)],
sep=" \\\\tab ", collapse="\\\\cr\n"),
"}",
"}"
)}
for \code{Rdo_piece_types}, the name-value pairs are:
\Sexpr[stage=build,results=rd]{
paste(
"\\\\ifelse{latex}{\\\\out{",
"\\\\begin{tabular}{ll|ll|ll|ll|ll|ll}",
paste(names(Rdo_piece_types), " & ", Rdo_piece_types, c(rep(" & ",2),"\\\\\\\\\\\\\\\\"),
sep="", collapse="\n"),
"\\\\end{tabular}",
"}}{",
"\\\\tabular{llllllllllll}{",
paste(names(Rdo_piece_types), "\\\\tab ", Rdo_piece_types,
c(rep(paste("\\\\tab ", "|", sep=""),2),
"\\\\cr"),
sep="", collapse="\n"),
"}",
"}"
)}
for \code{rdo_top_tags}, the values are:
\Sexpr[stage=build,results=rd]{
paste("\\\\tabular{lllll}{",
paste(sub("^[#]", "\\\\\\\\verb{#}", sub("^([\\\\])", "{\\\\\\\\\\\\1}", rdo_top_tags)),
c(rep("\\\\tab ",4),"\\\\cr"),
sep="", collapse="\n"),
"}")}
Note that most, but not all, are prefixed with backaslash.
}
\references{
\insertAllCited{}
}
\keyword{Rd}
Rdpack/man/get_sig_text.Rd 0000644 0001762 0000144 00000006446 13501141722 015213 0 ustar ligges users \name{get_sig_text}
\alias{get_sig_text}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Produce the textual form of the signatures of available methods for
an S4 generic function
}
\description{
Produce the textual form of the signatures of available methods for
an S4 generic function.
}
\usage{
get_sig_text(rdo, package = NULL)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
\item{package}{if of class "character", give only methods defined by
\code{package}, otherwise give all methods.
}
}
\details{
Signatures are found using function \code{findMethodSignatures} from
package "methods".
Here we find all methods for \code{show()} defined in package
\code{"methods"} and print the first few of them:
\printExample{fn <- utils::help("show-methods", package = "methods"); rdo <- utils:::.getHelpFile(fn); head(get_sig_text(rdo))}
}
\value{
A character vector with one element for each method.
}
\author{Georgi N. Boshnakov}
\note{
todo: It would be better to call promptMethods() to get the signatures
but in version R-2.13.x I had trouble with argument `where' (could not
figure out how to use it to restrict to functions from a package; also,
promptMethods() seemed to call the deprecated function
getMethods()). Check how these things stand in current versions of \R,
there may be no problem any more (checked, in 2.14-0 it is the same).
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
## load another package with some S4 methods ("methods" is already loaded)
require("stats4")
rdo <- Rdo_fetch("show", package = "methods")
## alternatively:
#fn <- help("show-methods", package = "methods")
#rdo <- utils:::.getHelpFile(fn)
## this will find all methods for "show" in currently loaded packages
## (print only some of them)
head(get_sig_text(rdo))
## this will select only the ones from package "stats4"
get_sig_text(rdo, package = "stats4")
## this is also fine (interactively) but need to choose
## the appropriate element of "fn" if length(fn) > 1
#fn <- help("show-methods")
## this finds nothing
#fn <- help("logLik-methods", package = "methods")
#fn
Rdo_fetch("logLik-methods", package = "methods")
## this does
#fn <- help("logLik-methods", package = "stats4")
#rdo <- utils:::.getHelpFile(fn)
rdo2 <- Rdo_fetch("logLik-methods", package = "stats4")
get_sig_text(rdo2)
get_sig_text(rdo2, package = "stats4")
## only default method defined
## using this:
setGeneric("f1", function(x, y){NULL})
## since the following gives error in pkgdown:
#f1 <- function(x, y){NULL}
#setGeneric("f1")
fn <- tempfile()
reprompt("f1", filename = fn)
rdo <- tools::parse_Rd(fn)
get_sig_text(rdo)
setClass("aRdpack")
setClass("bRdpack")
## several methods defined
setGeneric("f4", function(x, y){NULL})
setMethod("f4", c("numeric", "numeric"), function(x, y){NULL})
setMethod("f4", c("aRdpack", "numeric"), function(x, y){NULL})
setMethod("f4", c("bRdpack", "numeric"), function(x, y){NULL})
setMethod("f4", c("aRdpack", "bRdpack"), function(x, y){NULL})
reprompt("f4", filename = fn)
rdo <- tools::parse_Rd(fn)
get_sig_text(rdo)
unlink(fn)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoS4}
%\keyword{RdoProgramming}
Rdpack/man/parse_Rdpiece.Rd 0000644 0001762 0000144 00000005253 13521263275 015300 0 ustar ligges users \name{parse_Rdpiece}
\alias{parse_Rdpiece}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Parse a piece of Rd source text
}
\description{
Parse a piece of Rd source text.
}
\usage{
parse_Rdpiece(x, result = "")
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{the piece of Rd text, a character vector.}
\item{result}{if "text", converts the result to printable text
(e.g. to be shown to the user), otherwise returns an Rd object.}
}
\details{
\code{parse_Rdpiece} parses a piece of source Rd text. The text may be
an almost arbitrary piece that may be inserted in an Rd source file,
except that it should not be a top level section (use
\code{\link{parse_Rdtext}} for sections). Todo: it probably can be
also a parsed piece, check!
This is somewhat tricky since \code{parse_Rd} does not accept
arbitrary piece of Rd text. It handles either a complete Rd source or
a fragment, defined (as I understand it) as a top level section. To
circumvent this limitation, this function constructs a minimal
complete Rd source putting argument \code{x} in a section (currently
"Note") which does not have special formatting on its own. After
parsing, it extracts only the part corresponding to \code{x}.
\code{parse_Rdpiece} by default returns the parsed Rd piece. However,
if \code{result="text"}, then the text is formatted as the help system
would do when presenting help pages in text format.
\strong{TODO:} add an argument for macros?
}
\value{
a parsed Rd piece or its textual representation as described in Details
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
# the following creates Rd object rdo
dummyfun <- function(x) x
u1 <- list_Rd(name = "Dummyname", alias = "dummyfun",
title = "Dummy title", description = "Dummy description",
usage = "dummyfun(x,y)",
value = "numeric vector",
author = "A. Author",
Rd_class = TRUE )
fn <- tempfile("dummyfun", fileext = "Rd")
reprompt(dummyfun, filename = fn)
rdo <- tools::parse_Rd(fn)
# let's prepare a new item
rd <- "\\\\item{...}{further arguments to be passed on.}"
newarg <- parse_Rdtext(rd, section = "\\\\arguments")
# now append 'newarg' to the arguments section of rdo
iarg <- which(tools:::RdTags(rdo) == "\\\\arguments")
rdoa <- append_to_Rd_list(rdo, newarg, iarg)
Rdo_show(rdoa)
# for arguments and other frequent tasks, there are specialised functions
rdob <- Rdo_append_argument(rdo, "\\dots", "further arguments to be passed on.")
Rdo_show(reprompt(rdob, filename = fn))
unlink(fn)
}
\keyword{RdoProgramming}
Rdpack/man/Rdo_tags.Rd 0000644 0001762 0000144 00000002654 13501141722 014265 0 ustar ligges users \name{Rdo_tags}
\alias{Rdo_tags}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Give the Rd tags at the top level of an Rd object}
\description{Give the Rd tags at the top level of an Rd object.}
\usage{
Rdo_tags(rdo, nulltag = "")
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object.}
\item{nulltag}{a value to use when \code{Rd_tag} is missing or NULL.}
}
\details{
The \verb{"Rd_tag"} attributes of the top level elements of \code{rdo} are
collected in a character vector. Argument \code{nulltag} is used for
elements without that attribute. This guarantees that the result is a
character vector.
\code{Rdo_tags} is similar to the internal function
\code{tools:::RdTags}. Note that \code{tools:::RdTags} may return a
list in the rare cases when attribute \code{Rd_tags} is not present in
all elements of \code{rdo}.
%% ~~ If necessary, more details than the description above ~~
}
\value{
a character vector
}
% \references{
% %% ~put references to the literature/web site here ~
% }
\author{Georgi N. Boshnakov}
% \note{
% %% ~~further notes~~
% }
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{Rdo_which}},
\code{\link{Rdo_which_tag_eq}},
\code{\link{Rdo_which_tag_in}}
%% ~~objects to See Also as \code{\link{help}}, ~~~
}
\examples{
##---- Should be DIRECTLY executable !! ----
}
\keyword{Rd}
Rdpack/man/RStudio_reprompt.Rd 0000644 0001762 0000144 00000002462 13501141722 016041 0 ustar ligges users \name{RStudio_reprompt}
\alias{RStudio_reprompt}
\title{Call reprompt based on RStudio editor contents}
\description{This function uses the RStudio API to call \code{\link{reprompt}} on either the current help file in the editor, or if a name
is highlighted in a \file{.R} file, on that object.}
\usage{
RStudio_reprompt(verbose = TRUE)
}
\arguments{
\item{verbose}{
If \code{TRUE} print progress to console.
}
}
\details{
This function depends on being run in RStudio; it will generate
an error if run in other contexts.
It depends on code being in a package that has already been
built, installed, and attached. In RStudio, this means you
should run \dQuote{Install and Restart} before running this
function.
It is automatically installed into RStudio as an add-in called
\dQuote{Reprompt}. Whether invoked directly or through the
add-in, it looks at the file currently being edited in the
code editor. If it is an \file{.Rd} file, it will run
\code{\link{reprompt}} on that file.
If it is an \R source file, it will look for a selected object
name. It queries the help system to find if there is already
a help page for that name, and if so, works on that. If not,
it will try to create one.
}
\value{
\code{NULL}, invisibly.
}
\author{
Duncan Murdoch
}
\seealso{
\code{\link{reprompt}}, \code{\link{prompt}}
}
Rdpack/man/Rdo_locate_leaves.Rd 0000644 0001762 0000144 00000003013 13521254557 016140 0 ustar ligges users \name{Rdo_locate_leaves}
\alias{Rdo_locate_leaves}
\title{Find leaves of an Rd object using a predicate}
\description{Apply a function to the character leaves of an Rd object
and return the indices of those for which the result is TRUE.}
\usage{
Rdo_locate_leaves(object, f = function(x) TRUE)
}
\arguments{
\item{object}{the object to be examined, usually a list.}
\item{f}{a function (predicate) returning TRUE for elements with the
desired property.
}
}
\details{
\code{object} can be any list whose elements are character strings or
lists. The structure is examined recursively. If \code{object} is a
character vector, it is enclosed in a list.
This function provides a convenient way to locate leaves of an Rd
object with a particular content. The function is not limited to Rd
objects but it assumes that the elements of \code{object} are either
lists or charater vectors and currently does not check if this is the
case.
\strong{todo:} describe the case of \code{list()} (\code{Rd_tag}'ed.)
}
\value{
a list of the positions of the leaves for which the predicate gives
\code{TRUE}. Each position is an integer vector suitable for the
\code{"[["} operator.
}
\author{Georgi N. Boshnakov}
\examples{
dummyfun <- function(x) x
fn <- tempfile("dummyfun", fileext = "Rd")
reprompt(dummyfun, filename = fn)
rdo <- tools::parse_Rd(fn)
f <- function(x) Rdo_is_newline(x)
nl <- Rdo_locate_leaves(rdo, f )
length(nl) # there are quite a few newline leaves!
unlink(fn)
}
%\keyword{Rdlookup}
\keyword{Rd}
Rdpack/man/promptPackageSexpr.Rd 0000644 0001762 0000144 00000006655 13501141722 016347 0 ustar ligges users \name{promptPackageSexpr}
\alias{promptPackageSexpr}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Generates a shell of documentation for an installed package}
\description{
Generates a shell of documentation for an installed package. The
content is similar to `promptPackage' but information that can be
computed is produced with Sexpr's so that it is always up to date.
}
\usage{
promptPackageSexpr(package, filename = NULL, final = TRUE,
overview = FALSE, bib = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{package}{name of a package, a string}
\item{filename}{name of a file where to write the generated Rd
content, a string. The default should be sufficient in most cases.}
\item{final}{logical; if \code{TRUE} the content should be usable
without manual editing.}
\item{overview}{logical; if \code{TRUE} creates sections with hints
what to put in them, otherwise such sections are written to the file
but are commented out.}
\item{bib}{If TRUE, create a comment line in the references section
that will cause \code{\link{rebib}} to import all references from
the default bib file.
}
}
\details{
The generated skeleton is functionally (almost) equivalent to that
produced by \code{promptPackage}. The difference is that while
\code{promptPackage} computes some information and inserts it verbatim
in the skeleton, \code{promptPackageSexpr} inserts Sexpr's for the
computation of the same information at package build time.
In this way there is no need to manually update information like the
version of the package. The index of functions (which contains
their descriptions) does not need manual updating, as well.
\code{promptPackageSexpr} needs to be called only once to create the
initial skeleton. Then the Rd file can be edited as needed.
If the Rd file is generated with the option \code{bib = TRUE} (or the
appropriate lines are added to the refernces section manually) the
references can be updated at any time by a call of \code{rebib}.
todo: At the moment \code{final=FALSE} has the effect
described for \code{overview}. At the time of writing this
(2011-11-18) I do not remember if this is intentional or the
corresponding `if' clause contains \code{|} by mistake.
}
\value{
the name of the file (invisibly)
}
\author{Georgi N. Boshnakov}
\note{
The automatically generated information is that of the installed (or
at least built) package. Usually this is not a problem (and this is
the idea of the function) but it means that if a developer is adding
documentation for previously undocumented functions, they will appear
in the 'Index' section only after the package is installed
again. Similarly, if the description file of the package is changed,
the package needs to be installed again for the changes to appear in
the overview. Since the documentation is installed together with the
package this is no surprise, of course. This may only cause a problem
if documentation is produced with \code{R CMD Rd2pdf} before the
updated version is installed.
This function is not called \code{repromptXXX} since the idea is that
it is called only once and then the Rd file can be edited freely, see
also `Details'.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{Rd}
Rdpack/man/makeVignetteReference.Rd 0000644 0001762 0000144 00000007764 13501141722 016774 0 ustar ligges users \name{makeVignetteReference}
\alias{makeVignetteReference}
\alias{vigbib}
\title{Make bibtex references for vignettes}
\description{Make bibtex references for vignettes}
\usage{
makeVignetteReference(package, vig = 1, verbose = TRUE, title, author,
type = "pdf", bibtype = "Article", key = NULL)
vigbib(package, verbose = TRUE, \dots, vig = NULL)
}
\arguments{
\item{package}{
a character string, the name of an installed package.
}
\item{vig}{
an integer number or a character string identifying a vignette.
}
\item{verbose}{
if \code{TRUE}, print the references in Bibtex format.
}
\item{title}{a character string, title of the vignette, see Details.}
\item{author}{a character string, title of the vignette, see Details.}
\item{type}{a character string, type of the vignette, such as
\code{"pdf"} or \code{"html"}. Currently ignored.
}
\item{bibtype}{a character string, Bibtex type for the reference,
defaults to \code{"Article"}.
}
\item{key}{a character string specifying a key for the Bibtex entry.
If missing, suitable key is generated automatically.
}
\item{...}{
arguments passed by \code{vigbib()} to \code{makeVignetteReference()}.
}
}
\details{
\code{vigbib()} generates Bibtex references for all vignettes in a
package. \code{makeVignetteReference()} produces a Bibtex entry for a
particular vignette.
There seems to be no standard way to cite vignettes in R packages.
For vignettes that are complete journal papers (most notably in the
Journal of Statistical Software), the authors would usually
prefer the papers to be cited, rather than the vignette. In any case,
consulting the output of \code{citation("a_package")} is the best
starting point. If the vignette has been extended substantially after
the paper was published, cite both.
In many cases it is sufficient to give the command that opens the
vignette, e.g.:
\code{vignette("Inserting_bibtex_references", package = "Rdpack")}.
\code{makeVignetteReference()} makes a Bibtex entry for one
vignette. It looks for the available vignettes using
\code{vignette(package=package)}. Argument \code{vig} can be a
character string identifying the vignette by the name that would be
used in a call to \code{vignette()}. It can also be an integer,
identifying the vignette by the index (in the order in which the
vignettes are returned by \code{vignette()}). By default the first
vignette is returned. If \code{vig} is not suitable, a suitable list
of alternatives is printed.
For \code{vigbib()} it is sufficient to give the name of a package. It
accepts all arguments of \code{makeVignetteReference()} except
\code{vig} (actually, supplying \code{vig} is equivallent to calling
\code{makeVignetteReference()} directly).
The remaining arguments can be used to overwrite some automatically
generated entries. For example, the vignette authors may not be the
same as the package authors.
}
\value{
a bibentry object containing the generated references
(the Bibtex entries are also printed, so that they can be copied to a
bib file)
}
%\references{
%%% ~put references to the literature/web site here ~
%}
\author{Georgi N. Boshnakov}
%\note{
%%% ~~further notes~~
%}
%% ~Make other sections like Warning with \section{Warning }{....} ~
%\seealso{
%%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
\examples{
vigbib("Rdpack")
makeVignetteReference("Rdpack", vig = 1)
makeVignetteReference("Rdpack", vig = "Inserting_bibtex_references")
## the first few characters of the name suffice:
makeVignetteReference("Rdpack", vig = "Inserting_bib")
## this gives an error but also prints the available vignettes:
## makeVignetteReference("Matrix", vig = "NoSuchVignette")
vigbib("utils")
makeVignetteReference("utils", vig = 1)
## commented out since can be slow:
## high <- installed.packages(priority = "high")
## highbib <- lapply(rownames(high), function(x) try(Rdpack:::vigbib(x, verbose = FALSE)))
}
\keyword{bibtex}
% use one of RShowDoc("KEYWORDS")
Rdpack/man/Rdo2Rdf.Rd 0000644 0001762 0000144 00000010223 13501141722 013754 0 ustar ligges users \name{Rdo2Rdf}
\alias{Rdo2Rdf}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Convert an Rd object to Rd file format
}
\description{
Converts an Rd object to Rd format and saves it to a file or returns
it as a character vector. It escapes percents where necessary and
(optionally) backslashes in the examples section.
}
\usage{
Rdo2Rdf(rdo, deparse = FALSE, ex_restore = FALSE, file = NULL,
rcode = TRUE, srcfile = NULL)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object or a character vector, see `Details'.}
\item{deparse}{logical, passed to the print method for Rd objects,
see `Details'.
}
\item{ex_restore}{logical, if \code{TRUE} escapes backslashes where
necessary.
}
\item{file}{a filename where to store the result. If \code{NULL} or
"missing", the result is returned as a character vector.
}
\item{rcode}{if TRUE, duplicate backslahes in RCODE elements, see
Details.
}
\item{srcfile}{NULL or a file name, see 'Details'.}
}
\details{
The description here is rather technical and incomplete. In any case
it concerns almost exclusively Rd files which use escape sequences
containing multiple consecutive backslashes or escaped curly braces
(such things appear in regular expressions, for example).
In principle, this function should be redundant, since the
\code{print} and \code{as.character} methods for objects of class "Rd"
would be expected to do the job. I was not able to get the desired
result that way (the \code{deparse} option to \code{print} did not
work completely for me either).
Arguments \code{ex_restore} and \code{rcode} were added on an ad-hoc
basis. \code{rcode} is more recent and causes \code{Rdo2Rdf} to
duplicate backslashes found in any element \code{Rd_tag}-ed with
"RCODE". \code{ex_restore} does the same but only for the examples
section. In effect, if \code{rcode} is TRUE, \code{ex_restore} is
ignored.
The initial intent of this function (and the package Rdpack as a whole
was not to refer to the Rd source file. However, there is some
flexibility in the Rd syntax that does not allow the source file to be
restored identically from the parsed object. This concerns mainly
backslahes (and to some extent curly braces) which in certain contexts
may or may not be escaped and the parsed object is the same. Although
this does not affect functionality, it may be annoying if the escapes
in sections not examined by \code{reprompt} were changed.
If \code{srcfile} is the name of a file, the file is parsed and the Rd
text of sections of \code{rdo} that are identical to sections from
\code{srcfile} is taken directly from \code{srcfile}, ensuring that
they will be identical to the original.
}
\value{
\code{NULL}, if \code{file} is not \code{NULL}. Otherwise the Rd
formatted text as a character vector.
}
\author{Georgi N. Boshnakov}
\note{
Here is an example when the author's Rd source cannot be restored
exactly from the parsed object.
In the Rd source "author" has two backslashes here: \verb{\\author}.
In the Rd source "author" has one backslash here: \verb{\author}.
Both sentences are correct and the parsed file contains only one
backslash in both cases. If \code{reprompt} looks only at the parsed
object it will export one backslash in both cases. So, further
reprompt()-ing will not change them again. This is if \code{reprompt}
is called with \code{sec_copy = FALSE}. With the default
\code{sec_copy = TRUE}, \code{reprompt} calls \code{Rdo2Rdf} with
argument \code{srcfile} set to the name of the Rd file and since
\code{reprompt} does not modify section "Note", its text is copied
from the file and the author's original preserved.
However, the arguments of \verb{\eqn} are parse_Rd-ed differently (or
so it seems) even though they are also in verbatim.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
# # this keeps the backslashes in "author" (see Note above)
# reprompt(infile="./man/Rdo2Rdf.Rd")
# # this output "author" preceded by one backslash only.
# reprompt(infile="./man/Rdo2Rdf.Rd", sec_copy = FALSE)
}
\keyword{Rd}
Rdpack/man/c_Rd.Rd 0000644 0001762 0000144 00000004134 13501141722 013365 0 ustar ligges users \name{c_Rd}
\alias{c_Rd}
\title{Concatenate Rd objects or pieces}
\description{Concatenates Rd objects or pieces}
\usage{
c_Rd(...)
}
\arguments{
\item{\dots}{objects to be concatenated, Rd objects or character
strings, see `Details'.
}
}
\details{
The arguments may be a mixture of lists and character strings. The
lists are typically "Rd" objects or pieces. The character strings may
also be elements of "Rd" objects carrying "Rd_tag" attributes. The
"Rd_tag" attribute of character strings for which it is missing is set
to "TEXT". Finally, each character element of \code{"\dots"} is
enclosed in \code{list}.
Eventually all arguments become lists and they are concatenated using
\code{c()}. If any of the arguments is of class "Rd", the class of the
result is set to "Rd". Otherwise, the "Rd_tag" of the result is set to
the first (if any) non-null "Rd_tag" in the arguments.
The structure of "Rd" objects is described by
\insertCite{parseRd;textual}{Rdpack}.
}
\value{
An Rd object or a list whose attribute "Rd_tag" is set as descibed in
`Details'
}
\author{Georgi N. Boshnakov}
\seealso{
\code{\link{list_Rd}}
}
\references{
\insertAllCited{}
}
\examples{
a1 <- char2Rdpiece("Dummyname", "name")
a2 <- char2Rdpiece("Dummyallias1", "alias")
a3 <- char2Rdpiece("Dummy title", "title")
a4 <- char2Rdpiece("Dummy description", "description")
## The following are equivalent
## (gbRd::Rdo_empty() creates an empty list of class 'Rd')
b1 <- c_Rd(gbRd::Rdo_empty(), list(a1), list(a2), list(a3), list(a4))
c1 <- c_Rd(gbRd::Rdo_empty(), list(a1, a2, a3, a4))
d1 <- c_Rd(gbRd::Rdo_empty(), list(a1, a2), list(a3, a4))
identical(c1, b1)
identical(c1, d1)
Rdo_show(b1)
## insert a newline
d1n <- c_Rd(gbRd::Rdo_empty(), list(a1, a2), Rdo_newline(), list(a3, a4))
str(d1n)
## When most of the arguments are character strings
## the function 'list_Rd' may be more convenient.
u1 <- list_Rd(name = "Dummyname", alias = "Dummyallias1",
title = "Dummy title", description = "Dummy description",
Rd_class = TRUE )
Rdo_show(u1)
}
\keyword{RdoBuild}
%\keyword{RdoProgramming}
Rdpack/man/parse_Rdname.Rd 0000644 0001762 0000144 00000002644 13501141722 015122 0 ustar ligges users \name{parse_Rdname}
\alias{parse_Rdname}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Parse the name section of an Rd object
}
\description{
Parse the name section of an Rd object.
}
\usage{
parse_Rdname(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
}
\details{
The content of section "\verb{\name}" is extracted. If it contains a
hyphen, `-', the part before the hyphen is taken to be the topic
(usually a function name), while the part after the hyphen is the
type. If the name does not contain hyphens, the type is set to the
empty string. }
\value{
a list with two components:
\item{fname}{name of the topic, usually a function}
\item{type}{type of the topic, such as \verb{"method"}}
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
u1 <- list_Rd(name = "Dummyname", alias = "Dummyallias1",
title = "Dummy title", description = "Dummy description",
Rd_class=TRUE )
parse_Rdname(u1)
u2 <- list_Rd(name = "dummyclass-class", alias = "Dummyclass",
title = "Class dummyclass",
description = "Objects and methods for something.",
Rd_class=TRUE )
parse_Rdname(u2)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoProgramming}
Rdpack/man/Rdo_get_item_labels.Rd 0000644 0001762 0000144 00000002232 13501141722 016436 0 ustar ligges users \name{Rdo_get_item_labels}
\alias{Rdo_get_item_labels}
\title{Get the labels of items in an Rd object}
\description{Get the labels of items in an Rd object.}
\usage{
Rdo_get_item_labels(rdo)
}
\arguments{
\item{rdo}{an Rd object.}
}
\details{
\code{Rdo_get_item_labels(rdo)} gives the labels of all
\code{"\item"}s in \code{rdo}. Argument \code{rdo} is often a section
or other Rd object fragment, see the examples.
}
\value{
a character vector
}
\author{Georgi N. Boshnakov}
\examples{
infile <- system.file("examples", "tz.Rd", package = "Rdpack")
rd <- tools::parse_Rd(infile)
## get item labels found anywhere in the Rd object
(items <- Rdo_get_item_labels(rd))
## search only in section "arguments" (i.e., get argument names)
## (note [[1]] - there is only one arguments section)
pos.args <- Rdo_locate_core_section(rd, "\\\\arguments")[[1]]
(args <- Rdo_get_item_labels(rd[[pos.args$pos]]))
## search only in section "value"
pos.val <- Rdo_locate_core_section(rd, "\\\\value")[[1]]
(vals <- Rdo_get_item_labels(rd[[pos.val$pos]]))
## There are no other items in 'rd', so this gives TRUE:
all.equal(items, c(args, vals)) # TRUE
}
\keyword{RdoProgramming}
Rdpack/man/Rdpack-package.Rd 0000644 0001762 0000144 00000041645 13501141722 015323 0 ustar ligges users \name{Rdpack-package}
\alias{Rdpack-package}
\alias{Rdpack}
\docType{package}
\title{
\Sexpr[stage=build,results=hide]{require(Rdpack)}
\Sexpr[stage=build,results=hide]{pd <- utils::packageDescription("Rdpack")}
\Sexpr[stage=build,results=hide]{lb <- library(help="Rdpack", character.only=TRUE)}
\Sexpr[stage=build]{pd$Title}
}
\description{
\Sexpr[stage=build]{pd$Description}
}
\details{
\tabular{ll}{
Package: \tab \Sexpr[stage=build]{pd$Package}\cr
Type: \tab \Sexpr[stage=build]{pd$Type}\cr
Version: \tab \Sexpr[stage=build]{pd$Version} \cr
Date: \tab \Sexpr[stage=build]{pd$Date}\cr
License: \tab \Sexpr[stage=build]{pd$License}\cr
LazyLoad: \tab \Sexpr[stage=build]{pd$LazyLoad}\cr
Built: \tab \Sexpr[stage=build]{pd$Built}
}
%
% 2018-05-24 commenting out
% Index:
%
% \Sexpr[stage=build,results=rd]{paste("\\\\preformatted{", paste(if(!is.null(lb$info[[2]])) lb$info[[2]] else "No entries",collapse="\\n"), "}", sep="")}
%
%
Package \code{Rdpack} provides a number of functions for maintenance
of documentation in \R packages. Although base \R and
package \code{methods} have functions for creation of skeleton
documentation, if a function gets a new argument or a generic gets a
new method, then updating existing documentation is somewhat
inconvenient. This package provides functions that update parts of the
Rd documentation that can be dealt with automatically and leave manual
changes untouched. For example, usage sections for functions are
updated and if there are undescribed arguments, additional items are
put in the `arguments' section.
A set of functions and macros support inclusion of references and
citations from BibTeX files in \R documentation (Rd and
roxygen2). These tools use only facilities provided by base \R and
package \pkg{bibtex} \insertCite{Rpack:bibtex}{Rdpack}.
There are also convenience macros for inclusion of evaluated examples
and graphs, which hide some of the hassle of doing this directly with
the underlying \verb{\Sexpr}'s.
The subsections below give additional details, see also the vignettes.
\subsection{Creating and updating Rd files}{
The main function provided by this package is \code{\link{reprompt}}.
There is also a function \code{\link{promptPackageSexpr}} for creating
initial skeleton for overall package description such as this help
page.
\code{\link{reprompt}} produces a skeleton documentation for the
requested object, similarly to functions like \code{prompt},
\code{promptMethods}, and \code{promptClass}. Unlike those functions,
\code{\link{reprompt}} updates existing documentation (installed or in
an Rd object or file) and produces a skeleton from scratch as a last
resort only. If the documentation object describes more than one
function, all descriptions are updated. Basically,
\code{\link{reprompt}} updates things that are generated
automatically, leaving manual editing untouched.
The typical use of \code{reprompt} is with one argument, as in
\preformatted{
reprompt(infile = "./Rdpack/man/reprompt.Rd")
reprompt(reprompt)
reprompt("reprompt")
}
\code{reprompt} updates the documentation of all objects described in
the Rd object or file, and writes the updated Rd file in the current
working directory, see \code{\link{reprompt}} for details. To describe
a new function in an existing Rd file, just add something like
\code{myfun()} and run reprompt to insert the correct signature,
alias, etc. This works also for replacement functions, see
\code{\link{reprompt}} for details.
\code{\link{ereprompt}} updates the Rd documentation in a file,
overwrites it and opens it in an editor. It calls \code{reprompt} to
do the actual job but has different defaults. Which editor is opened,
is system dependent, see the \code{\link[utils]{edit}} and
\code{\link{ereprompt}} for futher details.
Users who work on Rd files in RStudio can use add-in \dQuote{Reprompt}
to invoke \code{reprompt} conveniently on an Rd file or on a selected
object in an \R source code file, see
\code{\link{RStudio_reprompt}}. This add-in was contributed by Duncan
Murdoch.
Users of Emacs/ESS have various options, depending on their workflow.
One approach is to define a key to call \code{\link{ereprompt}} on the
file being edited, see
\href{https://github.com/GeoBosh/georgisemacs}{georgisemacs} for an
example setup.
\code{\link{promptPackageSexpr}} creates a skeleton for a
package overview in file \verb{name-package.Rd}. Then the file can be
edited as needed. This function needs to be called only once for a
package since automatic generation of information in
\verb{name-package.Rd} is achieved with Sexpr's at build time, not
with verbatim strings (\code{promptPackage} used to insert verbatim
strings but in recent versions of \R it also uses macros.).
For example, the source of this help page is file
`Rdpack-package.Rd'. It was initially produced using
\preformatted{
promptPackageSexpr("Rdpack")
}
The factual information at the beginning of this help topic (the index
above, the version and other stuff that can be determined
automatically) is kept automatically up to date.
}
\subsection{References and Citations}{
Another set of functions is for management of bibliographic references
in Rd files. The old approach based on function \code{\link{rebib}}
is fully functional, see below, but the recommended way to insert
references and citations is based on Rd macros.
The provided Rd macros are fully portable and, in particular, work in
Rd files and roxygen2 comments, see \code{\link{insertRef}} and
vignette \code{vignette("Inserting_bibtex_references", "Rdpack")}
for details and examples.
The Bibtex source for the references and citations produced by the Rd
macros is file "REFERENCES.bib", which should be located in the root
of the package installation directory. \pkg{Rdpack} needs also to be
mentioned in two places in file `DESCRIPTION'. These one-off
preparation steps are enumerated below:
\enumerate{
\item{
Put the following line in file `DESCRIPTION': \cr
\verb{RdMacros: Rdpack} \cr
(If there is already a line starting with 'RdMacros:', add
\pkg{Rdpack} to the list on that line.)
}
\item{
Add \pkg{Rdpack} to the list of imports (\verb{Imports:}
field) in file `DESCRIPTION'.
}
\item{
Add the following line to file `NAMESPACE':
\preformatted{
importFrom(Rdpack,reprompt)
}
Alternatively, if \pkg{devtools} is managing your NAMESPACE file,
the equivalent \pkg{roxygen2} line is:
\preformatted{
#' @importFrom Rdpack reprompt}
}
\item{
Create file \code{"REFERENCES.bib"} in subdirectory
\code{"inst/"} of the package and put the BibTeX references in
that file.
}
}
The Rd macro \code{\\insertRef} takes two arguments: a BibTeX key and
the name of a package. Thus, \code{\\insertRef{key}{package}} inserts
the reference whose key is \code{key} from "REFERENCES.bib" of the
specified package (almost always the one being documented).
% With \pkg{Rdpack (>= 0.6-1)},
Citations can be done with Rd
macro \code{\\insertCite}, which inserts citation(s) for one or more
BibTeX keys and records the keys. \code{\\insertCiteOnly} is similar
to \code{\\insertCite} but does not record the
keys. \code{\\insertNoCite} records the keys but does not produce
citations.
\code{\\insertAllCited} creates a bibliography including
all references recorded by \code{\\insertCite} and
\code{\\insertNoCite}. It is usually put in section
\dQuote{References}, something like:
\preformatted{
\references{
\insertAllCited{}
}
}
in an Rd file.
The analogous documentation chunk in roxygen2 might look like this:
\preformatted{
#' @references
#' \insertAllCited{}
}
Bibliography styles for lists of references are supported as
well. 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.
Convenience functions \code{\link{makeVignetteReference}} and
\code{\link{vigbib}} generate Bibtex entries for vignettes.
}
\subsection{Previewing documentation pages}{
It is convenient during development to be able to view the
rendered version of the document page being edited.
The function \code{\link{viewRd}} renders a documentation file in a
source package and displays it as text or in a browser. It renders
references properly in any workflow, including \pkg{devtools} development
mode \insertCite{Rdevtools}{Rdpack} in Emacs/ESS, Rstudio, Rgui.
This function is a good candidate to be assigned to a key in editors
which support this.
I created this function (in 2017) since the functions provided by
\pkg{devtools} and Emacs/ESS are giving errors when processing pages
containing Rd macros.
}
\subsection{Static Management of References}{
In the alternative approach, the function \code{\link{rebib}} updates
the bibliographic references in an Rd file. Rdpack uses a simple
scheme for inclusion of bibliographic references. The key for each
reference is in a TeX comment line, as in:
\preformatted{
\references{
...
\% bibentry: key1
\% bibentry: key2
...
}
}
\code{rebib} puts each reference after the line containing its
key. It does nothing if the reference has been put by a previous call
of \code{rebib}. If the Bibtex entry for some references changes, it
may be necessary to update them in the Rd file, as well. Call
\code{rebib} with \code{force = TRUE} to get this effect. There is
also a facility to include all references from the Bibtex file, see
the documentation of \code{\link{rebib}} for details.
}
\subsection{Inserting evaluated examples}{
Sometimes the documentation of an object becomes more clear if accompanied by snippets of R
code and their results.
The standard Rd macro \verb{\Sexpr} caters for a number of possibilities to evaluate \R code and
insert the results and the code in the documentation.
The Rd macro \verb{\printExample} provided by package
\pkg{Rdpack} builds on it to print a snippet of \R code and the results of its evaluation, similarly to
console output but the code is not prefixed and the results are prefixed with comment
symbols.
For example, \verb{\printExample{2+2; a <- 2*3; a}} produces the
following in the rendered documentation:
\printExample{2+2; a <- 2*3; a}
The help page of \code{\link{promptUsage}} contains a number of examples created with
\code{\\printExample}. The corresponding Rd file can be obtained from the package tarball or from
\url{https://github.com/GeoBosh/Rdpack/blob/master/man/promptUsage.Rd}.
The argument of \verb{\printExample} must be on a single line with versions of R before
R 3.6.0.
\verb{\printExample} is typically placed in section Details of an
object's documentation, see section Details of \code{\link{get_usage}}
for anumber of examples produced mostly with \verb{\printExample}.
The macro \verb{\runExamples} can be used as a replacement
of section \verb{Examples}.
For example, if the following code is put at the top level in an Rd file (i.e. not in a
section):
\preformatted{
\runExamples{2+2; a <- 2*3; a}
}
then it will be evaluated and replaced by a normal section examples:
\preformatted{
\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 files.
In \R versions before 3.6.0 \verb{R CMD check} used to give a warning about
unknown \verb{\Sexpr} section at top level.
% According to the specification of the Rd format, \insertCite{@see @parseRd,
% p. 4;textual}{Rdpack} \verb{\Sexpr} at top level is legal but I need to check with the CRAN
% team or R devel if such expressions produced by user macros are excluded on purpose.
}
\subsection{Creating and including graphs}{
Figures can be inserted with the help of the standard Rd markup command
\verb{\figure}. The Rd macro \verb{\insertFig} provided by package
\pkg{Rdpack} takes a snipped of \R code, evaluates it and inserts the
plot produced by it (using \verb{\figure}). \verb{\insertFig} takes
three arguments: a filename, the package name and the code to evaluate
to produce the figure. For example,
\preformatted{
\insertFig{cars.png}{mypackage}{x <- cars$speed; y <- cars$dist; plot(x,y)}
}
will evaluate the code, save the graph in file \code{"man/figures/cars.png"} subdirectory of
package \code{"mypackage"}, and include the figure using \verb{\figure}.
Subdirectory \code{"figures"} is created if it doesn't exist.
Currently the graphs are saved in \code{"png"} format only.
In older versions of \R the code should be on a single line for the reasons explained in the
discussion of \verb{\printExample}.
The sister macro \verb{\makeFig} creates the graph in exactly the same
way as \verb{\insertFig} but does not insert it. This can be done with a
separate \verb{\figure} command. This can be used if additional options are
desired for different output formats, see the description of \verb{\figure}
in "Writing R extensions".
}
Other functions that may be useful are \code{Rdo2Rdf}, \code{Rdapply}
and \code{Rd_combo}. Here is also brief information about some more
technical functions that may be helpful in certain circumstances.
\code{\link{get_usage}} generates usage text for functions and
methods. The functions can be located in environments or other
objects. This may be useful for description of function elements of
compound objects.
\code{\link{c_Rd}} concatenates Rd pieces, character strings and lists
to create a larger Rd piece or a complete Rd object.
\code{\link{list_Rd}} is similar to \code{\link{c_Rd}} but provides
additional features for convenient assembling of Rd objects.
\code{\link{parse_Rdpiece}} is a technical function for parsing pieces
of Rd source text but it has an argument to return formatted help text
which may be useful when one wishes to show it to the user.
\code{Rdo_set_section} can be used to set a section, such as
"\verb{\author}".
The remaining functions in the package are for programming with Rd
objects.
}
\author{
\Sexpr[stage=build]{pd$Author}
Maintainer: \Sexpr[stage=build]{pd$Maintainer}
}
\note{
All processing is done on the parsed Rd objects, i.e. objects of class
"Rd" or pieces of such objects \insertCite{parseRd}{Rdpack}.
The following terminology is used (todo: probably not yet
consistently) throughout the documentation.
"Rd object" - an object of class Rd, or part of such object.
"Rd piece" - part of an object of class Rd. Fragment is also used but
note that \code{parse_Rd} defines fragment more restrictively.
"Rd text", "Rd source text", "Rd format" - these refer to the text of
the Rd files.
}
\seealso{
% \code{\link[:-package]{}} ~~
\code{\link{ereprompt}},
\code{\link{reprompt}},
\code{\link{promptPackageSexpr}},
\code{\link{rebib}},
\code{\link{get_usage}},
\code{\link{viewRd}},
\code{\link{vigbib}},
\code{\link{makeVignetteReference}},
\code{vignette("Inserting_bibtex_references", package = "Rdpack")},
\code{vignette("Inserting_figures_and_evaluated_examples", package = "Rdpack")}
}
\references{
\strong{Note:} Reference \insertCite{dummyArticle;textual}{Rdpack}
does not exist. It is a test that simple math in BibTeX entries works.
---
\insertAllCited{}
}
\examples{
## The examples below show typical use but are not executable.
## For executable examples see the help pages of
## reprompt, promptPackageSexpr, and rebib.
## To make the examples executable, replace "myfun" with a real
## function, and similarly for classes and paths to files.
\dontrun{
## update the doc. from the Rd source and save myfun.Rd
## in the current directory (like prompt)
reprompt(infile="path/to/mypackage/man/myfun.Rd")
## update doc of myfun() from the installed doc (if any);
## if none is found, create it like prompt
reprompt("myfun")
reprompt(myfun) # same
## update doc. for S4 methods from Rd source
reprompt(infile="path/to/mypackage/man/myfun-methods.Rd")
## update doc. for S4 methods from installed doc (if any);
## if none is found, create it like promptMethods
reprompt("myfun", type = "methods")
reprompt("myfun-methods") # same
## update doc. for S4 class from Rd source
reprompt(infile="path/to/mypackage/man/myclass-class.Rd")
## update doc. of S4 class from installed doc.
## if none is found, create it like promptClass
reprompt("myclass-class")
reprompt("myclass", type = "class") # same
## create a skeleton "mypackage-package.Rd"
promptPackageSexpr("mypackage")
## update the references in "mypackage-package.Rd"
rebib(infile="path/to/mypackage/man/mypackage-package.Rd", force=TRUE)
}
}
\keyword{ package }
Rdpack/man/rebib.Rd 0000644 0001762 0000144 00000011254 13501141722 013602 0 ustar ligges users \name{rebib}
\alias{rebib}
\alias{inspect_Rdbib}
\title{Work with bibtex references in Rd documentation}
\description{Work with bibtex references in Rd documentation.}
\usage{
rebib(infile, outfile, \dots)
inspect_Rdbib(rdo, force = FALSE, \dots)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{infile}{name of the Rd file to update, a character string.}
\item{outfile}{a filename for the updated Rd object.}
\item{...}{further arguments to be passed to
\code{\link{get_bibentries}}, see `Details'.}
\item{rdo}{an Rd object.}
\item{force}{if TRUE, re-insert previously imported
references. Otherwise do not change such references.}
}
\details{
\code{inspect_Rdbib} takes an Rd object and processes the references
as specified below.
The user level function is \code{rebib}. It parses the Rd file
\code{infile}, calls \code{inspect_Rdbib} to process the references,
and writes the modified Rd object to file \code{outfile}.
If \code{outfile} is missing it is set to the basename of
\code{infile}. If \code{outfile} is the empty string, \code{""}, then
\code{outfile} is set to \code{infile}.
The default Bibtex file is "REFERENCES.bib" in the current working
directory. Arguments "\dots" can be used to change the name of the bib
file and its location. Argument \code{bibfile} can be used to
overwrite the default name of the bib file. Argument \code{package}
can be used to specify that the bib file should be taken from the root
of the installation directory of package \code{package}, see
\code{\link{get_bibentries}} for details.
The following scheme can be used for incorporation of bibliographic
references from BibTeX files. Note however, that usually it is more
convenient to use the approach based on Rd macros like
\code{\\insertRef}, see \code{\link{insert_ref}} and the vignette(s).
The Bibtex key for each reference is put in a comment line in the
references section, as in
\preformatted{
\references{
\% bibentry: key1
\% bibentry: key2
...
}
}
At least one space after the colon, ':', is required, spaces before
"bibentry:" are ignored.
Then run \code{rebib()} on the file, see the example section for a way
to run \code{rebib()} on all files in one go.
Each reference is inserted immediately after the comment line
specifying it and a matching comment line marking its end is
inserted.
Before inserting a reference, a check for the matching ending line is
made, and if such a line is found, the reference is not inserted.
This means that to add new references it is sufficient to give their
keys, as described above and run the function again. References that
are already there will not be duplicated.
The inserted reference may also be edited, if necessary. As long as
the two comment lines enclosing it are not removed, the reference will
not be overwritten by subsequent calls of the functions described
here. Any text outside the markers delineating references inserted by
this mechanism is left unchanged, including references inserted by
other means.
To include all references from the bib file, the following line can be
used:
\preformatted{
\% bibentry:all
}
Notice that there is no space after the colon in this case.
In this case a marker is put after the last reference and the whole
thing is considered one block. So, if the end marker is present and
\code{force} is FALSE, none will will be changed. Otherwise, if
\code{force} is TRUE, the whole block of references will be removed
and all references currently in the bib file will be inserted.
The main purpose of \verb{bibentry:all} is for use in a package
overview file. The reference section in the file "package-package"
generated by \code{\link{promptPackageSexpr}} uses this feature (but
the user still needs to call \code{rebib} to insert the references).
}
\value{
for \code{inspect_Rdbib}, the modified Rd object.
\code{rebib} is used mainly for the side effect of creating a file
with the references updated. It returns the Rd object created by
parsing and modifying the Rd file.
}
% \references{
% %% ~put references to the literature/web site here ~
% }
\author{Georgi N. Boshnakov}
% \note{
% %% ~~further notes~~
% }
%
% %% ~Make other sections like Warning with \section{Warning }{....} ~
%
\seealso{
\code{\link{insert_ref}} and the vignette(s) for the recommended way
to import BibTeX references and citations.
}
\examples{
\dontrun{
# update references in all Rd files in the package's 'man' directory
#
rdnames <- dir(path = "./man", pattern=".*[.]Rd$", full.names=TRUE)
lapply(rdnames, function(x) rebib(x, package="Rdpack"))
}
}
\keyword{bibtex}
\keyword{Rd}
Rdpack/man/parse_Rdtext.Rd 0000644 0001762 0000144 00000003627 13501141722 015170 0 ustar ligges users \name{parse_Rdtext}
\alias{parse_Rdtext}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Parse Rd source text as the contents of a section
}
\description{
Parse Rd source text as the contents of a given section.
}
\usage{
parse_Rdtext(text, section = NA)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{text}{Rd source text, a character vector.}
\item{section}{the section name, a string.}
}
\details{
If \code{section} is given, then \code{parse_Rdtext} parses
\code{text} as appropriate for the content of section \code{section}.
This is achieved by inserting \code{text} as an argument to the TeX
macro \code{section}. For example, if \code{section} is
"\verb{\usage}", then a line "\verb{\usage\{}" is inserted at the
begiinning of \code{text} and a closing "\verb{\}}" at its end.
If \code{section} is NA then \code{parse_Rdtext} parses it without
preprocessing. In this case \code{text} itself will normally be
a complete section fragment.
}
\value{
an Rd fragment
}
\author{Georgi N. Boshnakov}
\note{
The text is saved to a temporary file and parsed using
\code{parse_Rd}. This is done for at least two reasons. Firstly,
\code{parse_Rd} works most reliably (at the time of writing this)
from a file. Secondly, the saved file may be slightly different
(escaped backslashes being the primary example).
It would be a nightmare to ensure that all concerned functions know
if some Rd text is read from a file or not.
The (currently internal) function \code{.parse_Rdlines} takes a
character vector, writes it to a file (using \code{cat}) and calls
\code{parse_Rd} to parse it.
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{parse_Rdpiece}}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{RdoProgramming}
Rdpack/man/Rdo_tag.Rd 0000644 0001762 0000144 00000002664 13501141722 014103 0 ustar ligges users \name{Rdo_tag}
\alias{Rdo_comment}
\alias{Rdo_verb}
\alias{Rdo_Rcode}
\alias{Rdo_text}
\alias{Rdo_tag}
\alias{Rdo_newline}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Set the Rd_tag of an object
}
\description{
Set the Rd_tag of an object.
}
\usage{
Rdo_comment(x = "\%\%")
Rdo_tag(x, name)
Rdo_verb(x)
Rdo_Rcode(x)
Rdo_text(x)
Rdo_newline()
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{an object, appropriate for the requested Rd_tag.}
\item{name}{the tag name, a string.}
}
\details{
These functions simply set attribute "\verb{Rd_tag}" of \code{x}, effectively
assuming that the caller has prepared it as needed.
\code{Rdo_tag} sets the "\verb{Rd_tag}" attribute of \code{x} to \code{name}.
The other functions are shorthands with a fixed name and no second
argument.
\code{Rdo_comment} tags an Rd element as comment.
\code{Rdo_newline} gives an Rd element representing an empty line.
}
\value{
\code{x} with its "\verb{Rd_tag}" set to
\code{name} (\code{Rdo_tag}),
"TEXT" (\code{Rdo_text}),
"VERB" (\code{Rdo_verb}) or
"RCODE" (\code{Rdo_Rcode}).
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
%\keyword{RdoProgramming}
%\keyword{RdoElements}
\keyword{RdoBuild}
Rdpack/man/Rdo_show.Rd 0000644 0001762 0000144 00000001663 13501141722 014306 0 ustar ligges users \name{Rdo_show}
\alias{Rdo_show}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Convert an Rd object to text and show it}
\description{Convert an Rd object to text and show it with \code{file.show()}.}
\usage{
Rdo_show(rdo)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{rdo}{an Rd object}
}
\value{
Invisible \code{NULL}.
The function is used for the side effect of showing the text
representation of \code{rdo}.
}
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\examples{
## create a minimal Rd object
u1 <- list_Rd(name = "Dummyname", alias = "Dummyallias1",
title = "Dummy title", description = "Dummy description",
Rd_class = TRUE )
\dontrun{
## run this interactively:
Rdo_show(u1)
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{Rd}
Rdpack/man/ereprompt.Rd 0000644 0001762 0000144 00000002625 13501141722 014536 0 ustar ligges users \name{ereprompt}
\alias{ereprompt}
\title{Update an Rd file and open it in an editor}
\description{
Update an Rd file and open it in an editor. This is a wrapper for
reprompt with different defaults for some parameters.
}
\usage{
ereprompt(..., edit = TRUE, filename = TRUE)
}
\arguments{
\item{\dots}{
passed on to \code{\link{reprompt}}, see its documentation for
details.}
\item{edit}{if \code{TRUE}, the default, open an editor when finished.}
\item{filename}{if \code{TRUE}, the default, replace and/or edit the
original Rd file.}
}
\details{
\code{ereprompt} calls \code{reprompt} to do the actual job but has
different defaults for the arguments described on this page. By
default, it replaces the original Rd file with the updated
documentation and opens it in an editor.
}
\value{
called for the side effect of updating Rd documentation file and
opening it in an editor
}
%\references{
%%% ~put references to the literature/web site here ~
%}
\author{Georgi N. Boshnakov}
%\note{
%%% ~~further notes~~
%}
%
%%% ~Make other sections like Warning with \section{Warning }{....} ~
%
\seealso{
\code{\link{reprompt}} which does the actual work
}
\examples{
## this assumes that the current working directory is
## in any subdirectory of the development directory of Rdpack
\dontrun{
ereprompt(infile = "reprompt.Rd")
}
}
\keyword{documentation}
% use one of RShowDoc("KEYWORDS")
Rdpack/DESCRIPTION 0000644 0001762 0000144 00000003020 13575267043 013173 0 ustar ligges users Package: Rdpack
Type: Package
Title: Update and Manipulate Rd Documentation Objects
Version: 0.11-1
Date: 2019-12-13
Authors@R: c( person(given = c("Georgi", "N."),
family = "Boshnakov",
role = c("aut", "cre"),
email = "georgi.boshnakov@manchester.ac.uk"),
person(given = "Duncan",
family = "Murdoch",
role = "ctb", email = "murdoch.duncan@gmail.com") )
Description: 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.
URL: https://github.com/GeoBosh/Rdpack
https://geobosh.github.io/Rdpack/
BugReports: https://github.com/GeoBosh/Rdpack/issues
Depends: R (>= 2.15.0), methods
Imports: tools, utils, grDevices, bibtex (>= 0.4.0), gbRd
Suggests: testthat, rstudioapi, rprojroot
License: GPL (>= 2)
LazyLoad: yes
RoxygenNote: 6.1.1
NeedsCompilation: no
Packaged: 2019-12-13 18:02:44 UTC; georgi
Author: Georgi N. Boshnakov [aut, cre],
Duncan Murdoch [ctb]
Maintainer: Georgi N. Boshnakov
Repository: CRAN
Date/Publication: 2019-12-14 23:20:03 UTC
Rdpack/build/ 0000755 0001762 0000144 00000000000 13574751104 012564 5 ustar ligges users Rdpack/build/vignette.rds 0000644 0001762 0000144 00000000525 13574751104 015125 0 ustar ligges users QOK0Oۭځ EQDvc ^xVn~l}IۉM^ۈ k06GhC@"y5(-d\:QB=
a-,RA0dŒi05[TrK[m*$95"TM2].@jE)|ےq2WųsAw_A
a+~r*D+Vv4ѱRlHkNh4;%[bs0XЮ^V P.3lV2u(Rjb.̱lj҂6m8l)7wdU Rdpack/build/partial.rdb 0000644 0001762 0000144 00000211065 13574751102 014714 0 ustar ligges users x\Kv&n`KDG$$W Ruyc"oֽ7 hJUJE,yl˲en"/MGӳxz{fgFl=D^d&K?@^d8qDĉs>ݑJzR[7zz+%dyS{9nNEs=݊n*Gh\i,E?f}w1*j7$Im鯶EX,)^.ѓ^Xnf6^_X\qYD߽>_| |[O~ZÈPΊ#Jed.ӫ/.[K+%Z~굱B?Yq#R
Me}荿]wH꘤Wj=.Ѧ淶̋F{~I6?I%ģƛ
Scہڧe[R B!7
RేwSfD;\`Ϧ'3/\v}zb|u-nEts u6釭ы$ f[%!KR~`NH85\y_Tp3D8=,Vjh3: *x,uV$I,n=4贵5_p_EP& VB