Rdpack/0000755000176200001440000000000015142024312011450 5ustar liggesusersRdpack/tests/0000755000176200001440000000000015102212001012600 5ustar liggesusersRdpack/tests/testthat/0000755000176200001440000000000015142024311014451 5ustar liggesusersRdpack/tests/testthat/test-reprompt.R0000644000176200001440000001175015102212001017414 0ustar liggesuserscontext("reprompt") test_that("reprompt works fine", { tmpfn <- tempfile(fileext = rep(".Rd", 4)) on.exit(unlink(tmpfn)) reprompt("viewRd", filename = tmpfn[1]) reprompt(infile = tmpfn[1], filename = tmpfn[2]) fn1 <- system.file("examples/reprompt.Rd", package = "Rdpack") reprompt(fn1, filename = tmpfn[2]) ## contains S3 method as.character.f_usage reprompt(as.character.f_usage) ## S4 ## from package "methods" - this page is peculiar; eg has no section 'arguments' reprompt("ts", type = "class") reprompt("show", type = "methods", package = "methods") ## (TODO: investigate) Need 'expect_warning' here since the following warning is issued ## for the S4 reprompt's: ## Calling 'structure(NULL, *)' is deprecated, as NULL cannot have attributes. ## Consider 'structure(list(), *)' instead. ## Backtrace: ## 1. Rdpack::reprompt("initialize", type = "methods", package = "methods") test-reprompt.R:20:4 ## 2. Rdpack::inspect_Rd(rdo, package = package) /home/georgi/repos/private/Rdpack/R/repromptAny.R:65:8 ## 3. Rdpack::inspect_Rdfun(rdo) /home/georgi/repos/private/Rdpack/R/inspect.R:60:4 ## 4. Rdpack::inspect_usage(rdo) /home/georgi/repos/private/Rdpack/R/inspect.R:148:4 ## 5. Rdpack::get_usage_text(rdo) /home/georgi/repos/private/Rdpack/R/usage.R:2:4 ## 6. base::structure(rdo_u, Rd_tag = "Rd") /home/georgi/repos/private/Rdpack/R/manip.R:260:4 if(getRversion() >= "4.6.0") { expect_error(reprompt("initialize", type = "methods", package = "methods")) expect_error(reprompt("classRepresentation", type = "class")) } else { expect_warning(reprompt("initialize", type = "methods", package = "methods")) expect_warning(reprompt("classRepresentation", type = "class")) } setClass("Seq", slots = c(from = "numeric", to = "numeric", by = "numeric")) setMethod("show", "Seq", function(object){ print(c(from = object@from, to = object@to, by = object@by)) }) ## this doesn't include "Seq" - TODO: investigate reprompt("show-methods", filename = tmpfn[2]) ## myshow <- function(object) NULL # this doesn't work here TODO: why? setGeneric("myshow", function(object) NULL) setMethod("myshow", "Seq", function(object){ print(c(from = object@from, to = object@to, by = object@by)) }) reprompt(myshow, type = "methods") ## this doesn't work in R CMD check: ## reprompt("Seq", type = "class", filename = tmpfn[2]) ## adapted reprompt.Rd tmpdir <- tempdir() old_wd <- setwd(tmpdir) on.exit({setwd(old_wd); unlink(tmpdir)}, add = TRUE) ## 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 ## TODO: this works in the examples but fails devtools::test() ## reprompt(rdoseq_dummy, filename = "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) } reprompt(myseq, filename = "tmp.Rd") ## 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 }) Rdpack/tests/testthat/char2Rdpiece_b.RDS0000644000176200001440000000015615102212001017610 0ustar liggesusersb```b`fed`b1#, @Z4'?]BG!)8UV!@PS I[PJ|Ib:5QM[Liqbz*HRdpack/tests/testthat/show.Rd0000644000176200001440000000532215102212001015711 0ustar liggesusers\name{show} \alias{show} \alias{show-methods} \alias{show,ANY-method} \alias{show,traceable-method} \alias{show,ObjectsWithPackage-method} \alias{show,MethodDefinition-method} \alias{show,MethodWithNext-method} \alias{show,genericFunction-method} \alias{show,classRepresentation-method} \title{Show an Object} \description{ Display the object, by printing, plotting or whatever suits its class. This function exists to be specialized by methods. The default method calls \code{\link{showDefault}}. Formal methods for \code{show} will usually be invoked for automatic printing (see the details). } \usage{ show(object) } \arguments{ \item{object}{Any R object} } \details{ Objects from an S4 class (a class defined by a call to \code{\link{setClass}}) will be displayed automatically is if by a call to \code{show}. S4 objects that occur as attributes of S3 objects will also be displayed in this form; conversely, S3 objects encountered as slots in S4 objects will be printed using the S3 convention, as if by a call to \code{\link{print}}. Methods defined for \code{show} will only be inherited by simple inheritance, since otherwise the method would not receive the complete, original object, with misleading results. See the \code{simpleInheritanceOnly} argument to \code{\link{setGeneric}} and the discussion in \code{\link{setIs}} for the general concept. } \value{ \code{show} returns an invisible \code{NULL}. } \seealso{ \code{\link{showMethods}} prints all the methods for one or more functions. } \examples{ ## following the example shown in the setMethod documentation ... setClass("track", slots = c(x="numeric", y="numeric")) setClass("trackCurve", contains = "track", slots = c(smooth = "numeric")) t1 <- new("track", x=1:20, y=(1:20)^2) tc1 <- new("trackCurve", t1) setMethod("show", "track", function(object)print(rbind(x = object@x, y=object@y)) ) ## The method will now be used for automatic printing of t1 t1 \dontrun{ [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12] x 1 2 3 4 5 6 7 8 9 10 11 12 y 1 4 9 16 25 36 49 64 81 100 121 144 [,13] [,14] [,15] [,16] [,17] [,18] [,19] [,20] x 13 14 15 16 17 18 19 20 y 169 196 225 256 289 324 361 400 } ## and also for tc1, an object of a class that extends "track" tc1 \dontrun{ [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12] x 1 2 3 4 5 6 7 8 9 10 11 12 y 1 4 9 16 25 36 49 64 81 100 121 144 [,13] [,14] [,15] [,16] [,17] [,18] [,19] [,20] x 13 14 15 16 17 18 19 20 y 169 196 225 256 289 324 361 400 } } \keyword{programming}Rdpack/tests/testthat/test-bib.R0000644000176200001440000001635215104662222016323 0ustar liggesuserscontext("bib") test_that("bib works fine", { fn_Rdpack <- system.file("REFERENCES.bib", package = "Rdpack") bibs_Rdpack <- if(packageVersion("rbibutils") >= '2.1.1') readBib(fn_Rdpack) else readBib(fn_Rdpack, encoding = "UTF-8") fn_rb <- system.file("REFERENCES.bib", package = "rbibutils") bibs_rb <- if(packageVersion("rbibutils") >= '2.1.1') readBib(fn_rb) else readBib(fn_rb, encoding = "UTF-8") .toRd_styled(bibs_rb, "Rdpack") .toRd_styled(bibs_rb[["Rpackage:Rdpack"]], "Rdpack") ## 2025-11-11: argument 'style' removed from .toRd_styled() .toRd_styled(bibs_rb[["Rpackage:Rdpack"]], "rbibutils") # .toRd_styled(bibs_rb[["Rpackage:Rdpack"]], "rbibutils", style = "JSSRd") bibstyle_JSSRd() bibstyle_JSSLongNames("JSSLongNames") ## parenthesised expect_equal(insert_citeOnly("Rpackage:Rdpack", package = "rbibutils"), "(Boshnakov 2020)") expect_equal(insert_citeOnly("Rpackage:Rdpack;nobrackets", package = "rbibutils"), "Boshnakov 2020") ## using @ expect_equal(insert_citeOnly("@see also @Rpackage:Rdpack", package = "rbibutils"), "(see also Boshnakov 2020)") expect_equal(insert_citeOnly("@see also @Rpackage:Rdpack;nobrackets", package = "rbibutils"), "see also Boshnakov 2020") expect_equal(insert_citeOnly("@see also @Rpackage:Rdpack among others;nobrackets", package = "rbibutils"), "see also Boshnakov 2020 among others") ## textual expect_equal(insert_citeOnly("Rpackage:Rdpack;textual", package = "rbibutils"), "Boshnakov (2020)") expect_equal(insert_citeOnly("@@Rpackage:Rdpack;textual", package = "rbibutils"), "Boshnakov (2020)") ## more than one key expect_equal(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd;textual", package = "Rdpack"), "see also Boshnakov and Putman (2020) and Murdoch (2010)") expect_equal(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd, among others;textual", package = "Rdpack"), "see also Boshnakov and Putman (2020) and Murdoch (2010), among others") expect_equal(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd", package = "Rdpack"), "(see also Boshnakov and Putman 2020 and Murdoch 2010)") expect_equal(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd;textual", package = "Rdpack"), "see also Boshnakov and Putman (2020) and Murdoch (2010)") expect_equal(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd;textual", package = "Rdpack", bibpunct = c("[", "]")), "see also Boshnakov and Putman [2020] and Murdoch [2010]") expect_equal(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd;nobrackets", package = "Rdpack"), "see also Boshnakov and Putman 2020 and Murdoch 2010") expect_equal(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd;nobrackets", package = "Rdpack"), "see also Boshnakov and Putman 2020 and Murdoch 2010") ## use brackets instead of parentheses expect_equal(insert_citeOnly("Rpackage:Rdpack;textual", package = "rbibutils", bibpunct = c("[", "]")), "Boshnakov [2020]") expect_equal(insert_citeOnly("Rpackage:Rdpack", package = "rbibutils", bibpunct = c("[", "]")), "[Boshnakov 2020]") expect_equal(insert_citeOnly("Rpackage:Rdpack", package = "rbibutils", bibpunct = c("[", "]"), dont_cite = TRUE), character(0)) expect_error(insert_citeOnly("Rpackage:Rdpack;textual", bibpunct = c("[", "]")), "argument 'package' must be provided") expect_error(insert_citeOnly(c("Rpackage:Rdpack;textual", "xxxxx"), "`keys' must be a character string")) insert_ref("Rpackage:Rdpack", package = "rbibutils") ## missing keys if(getRversion() < "4.5.0") expect_warning(insert_ref("xxx", package = "rbibutils")) else # since R-devel c86938 the warning was changed to error expect_error(insert_ref("xxx", package = "rbibutils")) expect_warning(insert_citeOnly( "@see also @Rpackage:rbibutils and @parseRd;nobrackets @kikiriki", package = "Rdpack")) ## "possibly non-existing or duplicated key(s) in bib file from package ..." ## TODO: this tries to load package "xxx" and gives error but finishes ok and returns a ## dummy reference, as expected. ## ## Why and which instruction tries to load package "yyy"? Maybe in .Rd_styled? ## It is sufficient that the package is installed, it doesn't need to be loadable. ## expect_warning(insert_ref("xxx", package = "yyy")) # missing package expect_warning(insert_ref("xxx", package = "yyy")) insert_all_ref(matrix(c("parseRd,Rpack:bibtex", "Rdpack"), ncol = 2)) insert_all_ref(matrix(c("parseRd,Rpack:bibtex", "Rdpack"), ncol = 2), empty_cited = TRUE) class(bibs_rb) <- c("bibentryRd", class(bibs_rb)) expect_output(print(bibs_rb)) ## after the fix of issue #25: ## (Diaz and López-Ibá{ñ}ez 2021) and Diaz and López-Ibá{ñ}ez (2021) ## (before the fix the braces were escaped and appeared in the rendered citation) expect_false(grepl("\\\\", insert_citeOnly("DiaLop2020ejor", "Rdpack"))) expect_false(grepl("\\\\", insert_citeOnly("DiaLop2020ejor;textual", "Rdpack"))) ## after fix of issue #26: ## before the fix it was necessary to manually remove the backslash from \&, \_, etc. ## in the bib file. Now the backslashes are removed by Rdpack ## ## fix in August 2023 for a change in R-devel (citation.R): ## resaved 'dummyArticle.rds' and conditioned on R-devel r84986. ## ## Previously the rendered version of the 'note' field contained a superfluous ' .'. ## This was fixed in R-devel r84986 (or somewhat earlier). ## After the change in R-devel, we get with the old dummyArticle.rds: ## > waldo::compare(readRDS("tests/testthat/dummyArticle.rds"), ## insert_all_ref(matrix(c("dummyArticle", "Rdpack"), ncol = 2))) ## lines(old) vs lines(new) ## "A. ZZZ (2018)." ## "\\dQuote{A relation between several fundamental constants: \\eqn{e^{i\\pi}=-1}.}" ## "\\emph{A non-existent journal with the formula \\eqn{L_2} in its name & an ampersand which is preceded by a backslash in the bib file.}." ## - "This reference does not exist. It is a test/demo that simple formulas in BibTeX files are OK. A formula in field 'note': \\eqn{c^2 = a^2 + b^2}. ." ## + "This reference does not exist. It is a test/demo that simple formulas in BibTeX files are OK. A formula in field 'note': \\eqn{c^2 = a^2 + b^2}." ## ## (notice '. .' at the end of the old string) if(is.numeric(svnrev <- R.Version()$'svn rev') && svnrev >= 84986) expect_known_value(insert_all_ref(matrix(c("dummyArticle", "Rdpack"), ncol = 2)), "dummyArticle.rds", update = FALSE) ## makeVignetteReference("Rdpack", 1) }) Rdpack/tests/testthat/StructureClasses.Rd0000644000176200001440000001722415102212001020253 0ustar liggesusers\name{StructureClasses} \alias{structure-class} \alias{matrix-class} \alias{array-class} \alias{ts-class} \alias{Math,structure-method} \alias{Ops,structure,vector-method} \alias{Ops,structure,structure-method} \alias{Ops,structure,array-method} \alias{Ops,vector,structure-method} \alias{Ops,array,structure-method} \alias{Ops,array,array-method} \alias{initialize,array-method} \alias{initialize,matrix-method} \alias{initialize,ts-method} \alias{initialize,mts-method} \alias{show,ts-method} \alias{matrix} \alias{array} \alias{ts} \alias{structure} \title{Classes Corresponding to Basic Structures} \description{ The virtual class \code{structure} and classes that extend it are formal classes analogous to S language structures such as arrays and time-series. } \usage{ data matrix nrow matrix ncol matrix byrow matrix dimnames data array dim array dimnames data ts start ts end ts frequency ts deltat ts ts.eps ts class ts names .Data structure ... } \arguments{ \item{data}{~~ TODO: describe this argument. ~~} \item{nrow}{~~ TODO: describe this argument. ~~} \item{ncol}{~~ TODO: describe this argument. ~~} \item{byrow}{~~ TODO: describe this argument. ~~} \item{dimnames}{~~ TODO: describe this argument. ~~} \item{dim}{~~ TODO: describe this argument. ~~} \item{start}{~~ TODO: describe this argument. ~~} \item{end}{~~ TODO: describe this argument. ~~} \item{frequency}{~~ TODO: describe this argument. ~~} \item{deltat}{~~ TODO: describe this argument. ~~} \item{ts.eps}{~~ TODO: describe this argument. ~~} \item{class}{~~ TODO: describe this argument. ~~} \item{names}{~~ TODO: describe this argument. ~~} \item{.Data}{~~ TODO: describe this argument. ~~} \item{...}{~~ TODO: describe this argument. ~~} } \references{ Chambers, John M. (2008) \emph{Software for Data Analysis: Programming with R} Springer. (For the R version.) Chambers, John M. (1998) \emph{Programming with Data} Springer (For the original S4 version.) Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) \emph{The New S Language}. Wadsworth & Brooks/Cole (for the original vector structures). } \section{Objects from the Classes}{ Objects can be created by calls of the form \code{new(Class, ...)}, where \code{Class} is the quoted name of the specific class (e.g., \code{"matrix"}), and the other arguments, if any, are interpreted as arguments to the corresponding function, e.g., to function \code{matrix()}. There is no particular advantage over calling those functions directly, unless you are writing software designed to work for multiple classes, perhaps with the class name and the arguments passed in. Objects created from the classes \code{"matrix"} and \code{"array"} are unusual, to put it mildly, and have been for some time. Although they may appear to be objects from these classes, they do not have the internal structure of either an S3 or S4 class object. In particular, they have no \code{"class"} attribute and are not recognized as objects with classes (that is, both \code{\link{is.object}} and \code{\link{isS4}} will return \code{FALSE} for such objects). However, methods (both S4 and S3) can be defined for these pseudo-classes and new classes (both S4 and S3) can inherit from them. That the objects still behave as if they came from the corresponding class (most of the time, anyway) results from special code recognizing such objects being built into the base code of \R. For most purposes, treating the classes in the usual way will work, fortunately. One consequence of the special treatment is that these two classes\emph{may} be used as the data part of an S4 class; for example, you can get away with \code{contains = "matrix"} in a call to \code{\link{setGeneric}} to create an S4 class that is a subclass of \code{"matrix"}. There is no guarantee that everything will work perfectly, but a number of classes have been written in this form successfully. Note that a class containing \code{"matrix"} or \code{"array"} will have a \code{.Data} slot with that class. This is the only use of \code{.Data} other than as a pseudo-class indicating the type of the object. In this case the type of the object will be the type of the contained matrix or array. See \code{\link{Classes_Details}} for a general discussion. The class \code{"ts"} is basically an S3 class that has been registered with S4, using the \code{\link{setOldClass}} mechanism. Versions of \R through 2.7.0 treated this class as a pure S4 class, which was in principal a good idea, but in practice did not allow subclasses to be defined and had other intrinsic problems. (For example, setting the \code{"tsp"} parameters as a slot often fails because the built-in implementation does not allow the slot to be temporarily inconsistent with the length of the data. Also, the S4 class prevented the correct specification of the S3 inheritance for class \code{"mts"}.) Time-series objects, in contrast to matrices and arrays, have a valid S3 class, \code{"ts"}, registered using an S4-style definition (see the documentation for \code{\link{setOldClass}} in the examples section for an abbreviated listing of how this is done). The S3 inheritance of \code{"mts"} in package \pkg{stats} is also registered. These classes, as well as \code{"matrix"} and \code{"array"} should be valid in most examples as superclasses for new S4 class definitions. All of these classes have special S4 methods for \code{\link{initialize}} that accept the same arguments as the basic generator functions, \code{\link{matrix}}, \code{\link{array}}, and \code{\link{ts}}, in so far as possible. The limitation is that a class that has more than one non-virtual superclass must accept objects from that superclass in the call to \code{\link{new}}; therefore, a such a class (what is called a \dQuote{mixin} in some languages) uses the default method for \code{\link{initialize}}, with no special arguments. } \section{Extends}{ The specific classes all extend class \code{"structure"}, directly, and class \code{"vector"}, by class \code{"structure"}. } \section{Methods}{ \describe{ \item{coerce}{Methods are defined to coerce arbitrary objects to these classes, by calling the corresponding basic function, for example, \code{as(x, "matrix")} calls \code{as.matrix(x)}. If \code{strict = TRUE} in the call to \code{as()}, the method goes on to delete all other slots and attributes other than the \code{dim} and \code{dimnames}. } \item{Ops}{Group methods (see, e.g., \code{\link{S4groupGeneric}}) are defined for combinations of structures and vectors (including special cases for array and matrix), implementing the concept of vector structures as in the reference. Essentially, structures combined with vectors retain the structure as long as the resulting object has the same length. Structures combined with other structures remove the structure, since there is no automatic way to determine what should happen to the slots defining the structure. Note that these methods will be activated when a package is loaded containing a class that inherits from any of the structure classes or class \code{"vector"}. } } } \seealso{Class \linkS4class{nonStructure}, which enforces the alternative model, in which all slots are dropped if any math transformation or operation is applied to an object from a class extending one of the basic classes. } \examples{ showClass("structure") ## explore a bit : showClass("ts") (ts0 <- new("ts")) str(ts0) showMethods("Ops") # six methods from these classes, but maybe many more } \keyword{classes}Rdpack/tests/testthat/as.character.f_usage.Rd0000644000176200001440000000265515102212001020705 0ustar liggesusers\name{as.character.f_usage} \alias{as.character.f_usage} %- Also NEED an '\alias' for EACH other topic documented here. \title{~~ Dummy title ~~} \description{~~ Dummy description ~~} \usage{ as.character.f_usage(x, ...) } %- maybe also 'usage' for other objects documented here. \arguments{ \item{x}{ %% ~~Describe \code{x} here~~ } \item{\dots}{ %% ~~Describe \code{\dots} here~~ } } \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{ ##---- Should be DIRECTLY executable !! ---- ##-- ==> Define data, use random, ##-- or standard data sets, see data(). ## The function is currently defined as function (x, ...) { deparse_usage1(x) } } % Add one or more standard keywords, see file 'KEYWORDS' in the % R documentation directory (show via RShowDoc("KEYWORDS")): % \keyword{ ~kwd1 } % \keyword{ ~kwd2 } % Use only one keyword per line. % For non-standard keywords, use \concept instead of \keyword: % \concept{ ~cpt1 } % \concept{ ~cpt2 } % Use only one concept per line. Rdpack/tests/testthat/initialize-methods.Rd0000644000176200001440000001227415102212001020537 0ustar liggesusers\name{initialize-methods} \alias{initialize-methods} \alias{initialize,ANY-method} \alias{initialize,traceable-method} \alias{initialize,signature-method} \alias{initialize,environment-method} \alias{initialize,.environment-method} \title{Methods to Initialize New Objects from a Class} \description{ The arguments to function \code{\link{new}} to create an object from a particular class can be interpreted specially for that class, by the definition of a method for function \code{initialize} for the class. This documentation describes some existing methods, and also outlines how to write new ones. } \section{Methods}{ \describe{ \item{\code{signature(.Object = "ANY")}}{ The default method for \code{initialize} takes either named or unnamed arguments. Argument names must be the names of slots in this class definition, and the corresponding arguments must be valid objects for the slot (that is, have the same class as specified for the slot, or some superclass of that class). If the object comes from a superclass, it is not coerced strictly, so normally it will retain its current class (specifically, \code{\link{as}(object, Class, strict = FALSE)}). Unnamed arguments must be objects of this class, of one of its superclasses, or one of its subclasses (from the class, from a class this class extends, or from a class that extends this class). If the object is from a superclass, this normally defines some of the slots in the object. If the object is from a subclass, the new object is that argument, coerced to the current class. Unnamed arguments are processed first, in the order they appear. Then named arguments are processed. Therefore, explicit values for slots always override any values inferred from superclass or subclass arguments. } \item{\code{signature(.Object = "traceable")}}{ Objects of a class that extends \code{traceable} are used to implement debug tracing (see class \linkS4class{traceable} and \code{\link{trace}}). The \code{initialize} method for these classes takes special arguments \code{def, tracer, exit, at, print}. The first of these is the object to use as the original definition (e.g., a function). The others correspond to the arguments to \code{\link{trace}}. } \item{\code{signature(.Object = "environment")}, \code{signature(.Object = ".environment")}}{ The \code{initialize} method for environments takes a named list of objects to be used to initialize the environment. Subclasses of \code{"environment"} inherit an initialize method through \code{".environment"}, which has the additional effect of allocating a new environment. If you define your own method for such a subclass, be sure either to call the existing method via \code{\link{callNextMethod}} or allocate an environment in your method, since environments are references and are not duplicated automatically. } \item{\code{signature(.Object = "signature")}}{ This is a method for internal use only. It takes an optional \code{functionDef} argument to provide a generic function with a \code{signature} slot to define the argument names. See \link{Methods_Details} for details. } } } \section{Writing Initialization Methods}{ Initialization methods provide a general mechanism corresponding to generator functions in other languages. The arguments to \code{\link{initialize}} are \code{.Object} and \dots. Nearly always, \code{initialize} is called from \code{new}, not directly. The \code{.Object} argument is then the prototype object from the class. Two techniques are often appropriate for \code{initialize} methods: special argument names and \code{callNextMethod}. You may want argument names that are more natural to your users than the (default) slot names. These will be the formal arguments to your method definition, in addition to \code{.Object} (always) and \dots (optionally). For example, the method for class \code{"traceable"} documented above would be created by a call to \code{\link{setMethod}} of the form: \preformatted{ setMethod("initialize", "traceable", function(.Object, def, tracer, exit, at, print) \{ .... \} ) } In this example, no other arguments are meaningful, and the resulting method will throw an error if other names are supplied. When your new class extends another class, you may want to call the initialize method for this superclass (either a special method or the default). For example, suppose you want to define a method for your class, with special argument \code{x}, but you also want users to be able to set slots specifically. If you want \code{x} to override the slot information, the beginning of your method definition might look something like this: \preformatted{ function(.Object, x, ...) \{ Object <- callNextMethod(.Object, ...) if(!missing(x)) \{ # do something with x } You could also choose to have the inherited method override, by first interpreting \code{x}, and then calling the next method. } \keyword{methods} \keyword{programming}Rdpack/tests/testthat/classRepresentation-class.Rd0000644000176200001440000000726315102212001022072 0ustar liggesusers\name{classRepresentation-class} \alias{classRepresentation-class} \title{Class Objects } \description{ These are the objects that hold the definition of classes of objects. They are constructed and stored as meta-data by calls to the function \code{\link{setClass}}. Don't manipulate them directly, except perhaps to look at individual slots. } \details{ Class definitions are stored as metadata in various packages. Additional metadata supplies information on inheritance (the result of calls to \code{\link{setIs}}). Inheritance information implied by the class definition itself (because the class contains one or more other classes) is also constructed automatically. When a class is to be used in an R session, this information is assembled to complete the class definition. The completion is a second object of class \code{"classRepresentation"}, cached for the session or until something happens to change the information. A call to \code{\link{getClass}} returns the completed definition of a class; a call to \code{\link{getClassDef}} returns the stored definition (uncompleted). In particular, completion fills in the upward- and downward-pointing inheritance information for the class, in slots \code{contains} and \code{subclasses} respectively. It's in principle important to note that this information can depend on which packages are installed, since these may define additional subclasses or superclasses. } \section{Slots}{ \describe{ \item{\code{slots}:}{A named list of the slots in this class; the elements of the list are the classes to which the slots must belong (or extend), and the names of the list gives the corresponding slot names.} \item{\code{contains}:}{A named list of the classes this class \sQuote{contains}; the elements of the list are objects of \code{\linkS4class{SClassExtension}}. The list may be only the direct extensions or all the currently known extensions (see the details).} \item{\code{virtual}:}{Logical flag, set to \code{TRUE} if this is a virtual class.} \item{\code{prototype}:}{The object that represents the standard prototype for this class; i.e., the data and slots returned by a call to \code{\link{new}} for this class with no special arguments. Don't mess with the prototype object directly.} \item{\code{validity}:}{Optionally, a function to be used to test the validity of objects from this class. See \code{\link{validObject}}.} \item{\code{access}:}{Access control information. Not currently used.} \item{\code{className}:}{The character string name of the class.} \item{\code{package}:}{The character string name of the package to which the class belongs. Nearly always the package on which the metadata for the class is stored, but in operations such as constructing inheritance information, the internal package name rules.} \item{\code{subclasses}:}{A named list of the classes known to extend this class'; the elements of the list are objects of class \code{\linkS4class{SClassExtension}}. The list is currently only filled in when completing the class definition (see the details).} \item{\code{versionKey}:}{Object of class \code{"externalptr"}; eventually will perhaps hold some versioning information, but not currently used. } \item{\code{sealed}:}{Object of class \code{"logical"}; is this class sealed? If so, no modifications are allowed. } } } \seealso{ See function \code{\link{setClass}} to supply the information in the class definition. See \link{Classes_Details} for a more basic discussion of class information. } \keyword{classes}Rdpack/tests/testthat/get_sig_text_f1.RDS0000644000176200001440000000010215102212001020056 0ustar liggesusersb```b`fed`b2Hg%jT(*(9E*iA2Rdpack/tests/testthat/myshow-methods.Rd0000644000176200001440000000065615102212001017725 0ustar liggesusers\name{myshow-methods} \docType{methods} \alias{myshow-methods} \alias{myshow,ANY-method} \alias{myshow,Seq-method} \title{~~ Dummy title ~~} \description{~~ Dummy description ~~} \section{Methods}{ \describe{ \item{\code{signature(object = "ANY")}}{ %% ~~describe this method here~~ } \item{\code{signature(object = "Seq")}}{ %% ~~describe this method here~~ } }} \keyword{methods} \keyword{ ~~ other possible keyword(s) ~~ } Rdpack/tests/testthat/test-char2Rdpiece.R0000644000176200001440000000603615102212001020040 0ustar liggesuserscontext("char2Rdpiece") test_that("char2Rdpiece works fine", { ## these two should be identical: expect_equal_to_reference(char2Rdpiece("graphics", "keyword") , "char2Rdpiece_a.RDS") expect_equal_to_reference(char2Rdpiece("graphics", "keyword", force.sec = TRUE) , "char2Rdpiece_a.RDS") expect_equal_to_reference(char2Rdpiece("log(x, base = exp(1))", "usage"), "char2Rdpiece_b.RDS") expect_equal_to_reference(char2Rdpiece("Give more examples.", "Todo", force.sec = TRUE), "char2Rdpiece_c.RDS") }) test_that("c_Rd works fine", { a1 <- char2Rdpiece("Dummyname", "name") a2 <- char2Rdpiece("Dummyallias1", "alias") a3 <- char2Rdpiece("Dummy title", "title") a4 <- char2Rdpiece("Dummy description", "description") if(requireNamespace("gbRd")){ b1 <- c_Rd(gbRd::Rdo_empty(), list(a1), list(a2), list(a3), list(a4)) b1a <- c_Rd(list(a1), gbRd::Rdo_empty(), list(a2), list(a3), list(a4)) expect_identical(class(b1), "Rd") expect_identical(class(b1a), "Rd") } b2 <- c_Rd(list(a1), list(a2), list(a3), list(a4)) expect_identical(class(b2), "list") }) test_that("get_sig_text works fine", { setClass("aRdpack") setClass("bRdpack") fn <- tempfile() on.exit(unlink(fn)) ## TODO: the following passes devtools::test() but not 'R CMD check' ## Why the difference? ## only default method defined #f1 <- function(x, y){NULL} #setGeneric("f1") #setGeneric("f1", function(x, y){NULL}) # #reprompt("f1", filename = fn) #rdo <- tools::parse_Rd(fn) #txt1 <- get_sig_text(rdo) #expect_equal(class(txt1), "character") #expect_equal_to_reference(txt1, "get_sig_text_f1.RDS") ## 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) #txt4 <- get_sig_text(rdo) #expect_equal(class(txt4), "character") #expect_equal_to_reference(txt4, "get_sig_text_f4.RDS") }) test_that("Rdo_fetch works fine", { somenames <- c("reprompt", "Rdpack-package") someRdnames <- paste0(somenames, ".Rd") ## The no-argument call is mostly for interactive use. ## (a test here would be artificial) ## db <- Rdo_fetch() db1 <- Rdo_fetch(package = "Rdpack") expect_equal(class(db1), "list") expect_true(all(someRdnames %in% names(db1))) db2 <- Rdo_fetch(package = "Rdpack", installed = FALSE) expect_equal(class(db2), "list") expect_true(all(someRdnames %in% names(db2))) db3 <- Rdo_fetch("Rdo_macro", "Rdpack") expect_equal(class(db3), "Rd") db4 <- Rdo_fetch(somenames, "Rdpack", installed = FALSE) expect_equal(class(db4), "list") expect_true(setequal(names(db4), someRdnames)) }) Rdpack/tests/testthat/get_sig_text_f4.RDS0000644000176200001440000000015215102212001020066 0ustar liggesusersb```b`fed`b2Hg%jT(*(9E*(T˜PehR aJ\"e&TDr!ͩja9fe# oN;5&T>} O`9C;趣3նa#@%2(Q=6:֣w@eRJW(+ Ɠ=㰒< ׆Z/͈ŊQatTira- 6}^Rdpack/tests/testthat.R0000644000176200001440000000024515102212001014564 0ustar liggesusersif(require("testthat")) { library(testthat) library(Rdpack) test_check("Rdpack") } else warning("package 'testthat' required for 'Rdpack\'s' tests") Rdpack/MD50000644000176200001440000001647115142024312011771 0ustar liggesusersde2c44805349015b874bd610b4f2cd7a *DESCRIPTION 6c40d12108073d4eb556ab81311a3bd3 *NAMESPACE 8709c6c16b55fdebbeef510e8738d14e *NEWS.md e46c5da214213a443b628bd5f3ffe3c9 *R/RStudio.R 7c0d3f36409756364343fd987c096287 *R/Rdo2Rdf.R ae81a25645f62384220411684b33e8cf *R/alias.R 8a41a6b8db2224f736ff8597d477bbbb *R/bib.R bfe06e3d7f729a5614b0ba6fdc30fcfe *R/elements.R b0f4fab12305261072435292e201bbb0 *R/f_usage.R 95eb0f8cc5558175fc9e567c957ad7ba *R/inspect.R fea6530f38874362b59f1c95bc281116 *R/manip.R 03a854cd43c90c99bb3ca5d58b329f49 *R/parse.R b9e4ce86d15977df259070a58545e889 *R/predefined.R 41b3623cb4e992c23c3871dd269ffaa6 *R/promptSexpr.R abd60f89dfacc7bcc33a018b1c1858ff *R/repromptAny.R 90ff49affbc56a8c8c23d5c52be2fa93 *R/runexamples.R 5735fe2d04a7a730872a94786ce2ac2a *R/sections.R 2341d017a688b8470b0ccfef0418eed0 *R/signature.R 4b03c8cfbf7a632aca417756f7ef766e *R/slots.R 085eaf35d4daaa9cbab28dada4062251 *R/threedots.R b4d36330bf64cddf616d79b126677a8e *R/usage.R 7a35e91aa982372631ca464d89ef63fc *R/utils.R dc4224cb43cc6669175bde3108e3d6e3 *R/yytransient.R 05a1981a29b330ee53abf6c7e0367af2 *README.md a28a66123d0a730f960b85ce33a56aec *build/partial.rdb 277716d35f44e059f1e9e30378e31491 *build/vignette.rds b603408b16eb8aac60723a9627a0c6f4 *inst/REFERENCES.bib 66d8527ef38edbb31efd9f926c2db3da *inst/RStudio/addins.dcf 5fd99e045c731ab68b38dbc862017ce5 *inst/doc/Inserting_bibtex_references.R 6263b0dba61b785e9625c802d2cb0c8a *inst/doc/Inserting_bibtex_references.Rnw 31102f8ebf53432f7d447c4d636ad2ef *inst/doc/Inserting_bibtex_references.pdf 65531fadaff311cac822edd83fcbae4f *inst/doc/Inserting_figures_and_evaluated_examples.R 9361c4e2d913b990a29963e80cedf582 *inst/doc/Inserting_figures_and_evaluated_examples.Rnw e9f949729b1b124a7f15d3844ce1257e *inst/doc/Inserting_figures_and_evaluated_examples.pdf 933b5a32e8f91fc64fe3c812954f5f6f *inst/examples/Rdpack-package.Rd db800015ba2282ec1e36c49316fd9cc0 *inst/examples/journal_with_percents.bib e745d512aa7b30cd2a4fc63dc506e20b *inst/examples/reprompt.Rd e8ac73c2782b741df4665121db17b036 *inst/examples/tz.Rd 622b071bcbb4e3124bedfe8507e9046a *inst/examples/url_with_percents.bib 92ec86976bf00de1cefd4eac08ed841f *inst/pkgdown.yml 10a6bd4a97476b86edef5d64b0c17857 *man/RStudio_reprompt.Rd ce5ffdb9202ee9ceb957937ce58caf9c *man/Rd_combo.Rd 0d6b7f6829f85cd59a480d4d029d38c7 *man/Rdapply.Rd 14248e56a1bc53fca2ebc3c82590563b *man/Rdo2Rdf.Rd 2f632e1addaf24df60161cce2d1952ec *man/Rdo_append_argument.Rd 109ada7043a5af057fc5f979833917a7 *man/Rdo_collect_metadata.Rd db377e52ed67dac64fe3ba0368b98cd0 *man/Rdo_empty_sections.Rd 4095fa1ff964ff1eb168a854517727b8 *man/Rdo_fetch.Rd a6ef0c7c48e1b9e4752ceeab0106a046 *man/Rdo_flatinsert.Rd d8144fe53d234d3f7d3f0b3302388eac *man/Rdo_get_argument_names.Rd c519543d648e6df2e422ba2a84ad40b1 *man/Rdo_get_insert_pos.Rd c7afcccdf050cec02aa58447b77bd42a *man/Rdo_get_item_labels.Rd ba691cf053490c91e2a602e704ab6aea *man/Rdo_insert.Rd c2cd1db2705344dd653c0a95893b5c9d *man/Rdo_insert_element.Rd 774cff52e02f2f1526de1e1cc9368fd9 *man/Rdo_is_newline.Rd 4bf76fc9f2b7ae6e62655adfd9ce0d8f *man/Rdo_locate.Rd ecc69e8592337dac7ac3f5ec25eb7ee6 *man/Rdo_locate_leaves.Rd 8f2670e3fe48eb7a042516feb2c31b48 *man/Rdo_macro.Rd 2b51182cd8e4881e3f91263846a7bf77 *man/Rdo_modify.Rd 20a38d61ada82b7c8f50a74ed4f42dd6 *man/Rdo_modify_simple.Rd a7fbf7b0931cfa1a9ecba847f4b6213e *man/Rdo_piecetag.Rd 0bafc9f685261c4c60de5b08a5384a16 *man/Rdo_remove_srcref.Rd 4c126c04463313e680e2dba38863ef4c *man/Rdo_reparse.Rd 5c18d0067046f8c16bec8d2243324964 *man/Rdo_sections.Rd c8eeb761a98d71d7783a83b6d3cf5292 *man/Rdo_set_section.Rd 4d73366a002b9115fc42f3e8f7f95408 *man/Rdo_show.Rd 6e8cfa5234bd29a601daabb172907235 *man/Rdo_tag.Rd 2e6a44748c5507523abc3a66e238f095 *man/Rdo_tags.Rd 02bf3e062c7a016fbb0e57b4264a6d0c *man/Rdo_which.Rd 2ef8f40ecd014ee57180ad30f3efb996 *man/Rdpack-package.Rd a424c0db33e2d6ff156e74e65470a338 *man/Rdpack_bibstyles.Rd 738ef3d5d5951fac76d384c7c7fb2cbf *man/Rdreplace_section.Rd 326506d2c3f9ec1c27d188d93bdf5419 *man/S4formals.Rd d673a08cd551a2e38669a385a1aaf775 *man/append_to_Rd_list.Rd fc7e74a850a3ad6bc8366a4e891eae96 *man/c_Rd.Rd 00e5d6675bbe5bb984361786ae54b361 *man/char2Rdpiece.Rd 197fcb0865331981c7da01765a26786d *man/compare_usage1.Rd 678fad1297c39010dac194e2f653fcd8 *man/deparse_usage.Rd ea64043157fd2165732a69739a588021 *man/ereprompt.Rd 788bac58a666d58081e3f6ef64046d99 *man/format_funusage.Rd 44e99b8b5f282ce83d7ff96318450d31 *man/get_bibentries.Rd 16cd0305de086216c38a33557644404c *man/get_sig_text.Rd 95ef0eb8e847562637859da515b8e094 *man/get_usage_text.Rd f17121bf3ef7336c419a123fb02ec6ea *man/insert_all_ref.Rd deb3eee844eaf503d231b633fb94a33c *man/insert_citeOnly.Rd 3afcbf1b6d4d47a6013373198a6aafdc *man/insert_ref.Rd 952f0b8c2d93c748f06fc89d9c26d0b8 *man/inspect_Rd.Rd a7eb7002a64c5843cb52a0d4cad297c7 *man/inspect_args.Rd 74870e0195d62d2d93d1d7a51063bebd *man/inspect_signatures.Rd 315b02a7da8bfa3d315311a3d3e9bc25 *man/inspect_slots.Rd 86c5b735a5ee57bfc66aa959c903b392 *man/inspect_usage.Rd 0e840f06ba0488b45c399619d06fadf3 *man/list_Rd.Rd 083f3546a8090f4e28a31fdb847261eb *man/macros/refmacros.Rd 0e83966b45528f8ff418fbee5b94e3f7 *man/makeVignetteReference.Rd 0dc7b50269710a091b4b952db4488a0b *man/parse_Rdname.Rd edb0d052a7b6ee35d51696e269f98374 *man/parse_Rdpiece.Rd e750cb7e5453d2c0d333a0cd472ab81e *man/parse_Rdtext.Rd c6d300c58087a5bf50549317bffd6a36 *man/parse_pairlist.Rd 3b064ca8778b0aa86290d7578896d652 *man/parse_text.Rd a1b2f57e1a1f9b27f156c9db254e9e8f *man/parse_usage_text.Rd 9ce51cf2091abb1c8f36def5657da41c *man/predefined.Rd b2cea461095dd10b405d25593717fd92 *man/promptPackageSexpr.Rd adfd5433985dc6278935b774a8e9cb9d *man/promptUsage.Rd 0a3d93f1f4ef6890772d4399e0f40b69 *man/rdo_text_restore.Rd fade6ed3bdb261e336df91ccfa539cd4 *man/rebib.Rd e745d512aa7b30cd2a4fc63dc506e20b *man/reprompt.Rd d884e588e0f5adaf4778ce19b2cc3d31 *man/update_aliases_tmp.Rd b8672aadfcadd035a62d3b824cf51dbb *man/viewRd.Rd d7fcfcf5e3b4d6e025ea1fa0eb9275a9 *man/zzasym_compare.Rd a13a20109cc06181254b976aa58c7dfe *man/zzbsdup.Rd 0a20af2e97069ded300b0a6ca1025c06 *man/zzcapture_promptany.Rd 260b1f23bf3620a4d47b0b06e2aed04c *tests/testthat.R 4ee1a4e0ec700abbd3510cdcef27c9d4 *tests/testthat/StructureClasses.Rd 51fcc0f84ef4d95836df9168289940ec *tests/testthat/as.character.f_usage.Rd a62c0ada2058937d01c0979c411a746c *tests/testthat/char2Rdpiece_a.RDS 2ed49593b0fc0c3c100e32d0240a98ba *tests/testthat/char2Rdpiece_b.RDS 8956358852e44bd8b1a7958831487987 *tests/testthat/char2Rdpiece_c.RDS 5881b171c52fd2b7d252642820c903c1 *tests/testthat/classRepresentation-class.Rd 34b4d027dcf29a9a90f401a1192d7e9f *tests/testthat/dummyArticle.rds af46fe05c6a34fa8a80ee2b0bd297cb3 *tests/testthat/get_sig_text_f1.RDS 916988d6d5aed8c8213ff37afbfa52da *tests/testthat/get_sig_text_f4.RDS 55704c8ed576c3da333d63669920adc3 *tests/testthat/initialize-methods.Rd 16839eae5c3ca7e5a445704fc2eee8a4 *tests/testthat/myshow-methods.Rd 91c3ffcbddc02b20a13b8e252bb93630 *tests/testthat/show.Rd 7b538106a269752d065fa7e93b558180 *tests/testthat/test-bib.R 1a70e90cdbf147bdca609908935ef369 *tests/testthat/test-char2Rdpiece.R 82ea34332b9b6d3e1ac437fdaea9ab5f *tests/testthat/test-reprompt.R 6263b0dba61b785e9625c802d2cb0c8a *vignettes/Inserting_bibtex_references.Rnw b3ba80a34b12df47f62793dbf78d6b2d *vignettes/Inserting_bibtex_references.org 9361c4e2d913b990a29963e80cedf582 *vignettes/Inserting_figures_and_evaluated_examples.Rnw 21418b46c1fba81d122a38010ad40f05 *vignettes/Inserting_figures_and_evaluated_examples.org Rdpack/R/0000755000176200001440000000000015141664036011665 5ustar liggesusersRdpack/R/runexamples.R0000644000176200001440000002152515141664036014360 0ustar liggesusers .comment <- function(x){ x invisible(NULL) } ## see also > utils::example run_examples <- function(excontent, # package = NULL, lib.loc = NULL, character.only = FALSE, give.lines = FALSE, local, # in utils::example() it is: local = FALSE, echo = TRUE, verbose = getOption("verbose"), setRNG = FALSE, ask = FALSE, # in utils::example() it is: getOption("example.ask"), ## prompt.prefix = "Rdpack" # in utils::example() it is: abbreviate(topic, 6), prompt.echo = "Rdpack> ", continue.echo = prompt.echo, run.dontrun = FALSE, run.donttest = FALSE, # in utils::example() it is: interactive() Rdsection = "examples", escape = TRUE ){ ## set the environment where source() evaluates the code; ## 2018-08-13 todo: it is not clear if this is the best choice; ## maybe could pass an environment from the macro \printExample, similarly ## to the citation macros (but first need to check if the cause is the choice ## made here: if(missing(local)) local <- parent.frame() # dontshow <- function(x){ # x # } # saveRDS(excontent, "excontent.RDS") excontent <- deparse(excontent) excontent <- gsub("^[ ]*\\{", "", excontent) excontent <- gsub("\\}[ ]*$", "", excontent) excontent <- gsub(paste0("^[ ]*", ".comment", "[ ]*\\(\"(.*)\"\\)[ ]*$"), "\\1", excontent) ## if(interactive()) ## browser() # file <- tempfile(fileext = ".Rd") tf <- tempfile("Rex") ## tools::Rd2ex(.getHelpFile(file), tf, commentDontrun = !run.dontrun, ## commentDonttest = !run.donttest) writeLines(excontent, tf) ## if (!file.exists(tf)) { ## if (give.lines) ## return(character()) ## warning(gettextf("%s has a help file but no examples", ## sQuote(topic)), domain = NA) ## return(invisible()) ## } on.exit(unlink(tf)) ## if (give.lines) ## return(readLines(tf)) ## if (pkgname != "base") ## library(pkgname, lib.loc = lib, character.only = TRUE) if (!is.logical(setRNG) || setRNG) { if ((exists(".Random.seed", envir = .GlobalEnv))) { oldSeed <- get(".Random.seed", envir = .GlobalEnv) on.exit(assign(".Random.seed", oldSeed, envir = .GlobalEnv), add = TRUE) } else { oldRNG <- RNGkind() on.exit(RNGkind(oldRNG[1L], oldRNG[2L]), add = TRUE) } if (is.logical(setRNG)) { RNGkind("default", "default") set.seed(1) } else eval(setRNG) } zz <- readLines(tf, n = 1L) skips <- 0L ## if (echo) { ## zcon <- file(tf, open = "rt") ## while (length(zz) && !length(grep("^### \\*\\*", zz))) { ## skips <- skips + 1L ## zz <- readLines(zcon, n = 1L) ## } ## close(zcon) ## } if (ask == "default") ask <- echo && grDevices::dev.interactive(orNone = TRUE) if (ask) { if (.Device != "null device") { oldask <- grDevices::devAskNewPage(ask = TRUE) if (!oldask) on.exit(grDevices::devAskNewPage(oldask), add = TRUE) } op <- options(device.ask.default = TRUE) on.exit(options(op), add = TRUE) } ## TODO: argument 'spaced' (and maybe others?) were introduced in R-3.4.0. wrk <- capture.output( if(getRversion() >= '3.4.0') source(tf, local, echo = echo, prompt.echo = prompt.echo, # paste0(prompt.prefix, getOption("prompt")), continue.echo = continue.echo, # paste0(prompt.prefix, getOption("continue")), spaced = FALSE, # do not print empty line before each source line verbose = verbose, max.deparse.length = Inf, encoding = "UTF-8", skip.echo = skips, keep.source = TRUE) else source(tf, local, echo = echo, prompt.echo = prompt.echo, # paste0(prompt.prefix, getOption("prompt")), continue.echo = continue.echo, # paste0(prompt.prefix, getOption("continue")), # spaced = FALSE, - no such argument before R-3.4.0 verbose = verbose, max.deparse.length = Inf, encoding = "UTF-8", skip.echo = skips, keep.source = TRUE) ) # \Sexpr[stage=build,results=rd]{ # paste0("\\\\examples{", { # pf <- "Rdpack" # tmp <- capture.output(utils::example("ES", prompt.prefix = pf)) # flags <- grepl("Rdpack> ", tmp) # tmp[!flags] <- paste0("#> ", tmp[!flags]) # tmp <- gsub("Rdpack> ", "", tmp) # res <- paste0(tmp, collapse = "\n") # }, "}", collapse = "\n")} # browser() flags <- grepl(paste0("^", prompt.echo), wrk) outflags <- !flags & !grepl("^[ ]*$", wrk) wrk[outflags] <- paste0("##: ", wrk[outflags]) wrk <- gsub(paste0("^", prompt.echo, "[ ]*"), "", wrk) ## wrk <- gsub(paste0("^[ ]*", "identity", "[ ]*\\(\"(.*)\"\\)[ ]*$"), "\\1", wrk) wrk <- gsub("^## *$", "", wrk) res <- paste0(paste0(wrk, collapse = "\n"), "\n") if(escape) # 2018-08-25 res <- .bspercent(res) ## TODO: prefix with spaces to indent from surrounding text? if(is.character(Rdsection)){ res <- paste0("\\", Rdsection, "{", res, "}\n") } # if(interactive()) # browser() res } ## cat(Rdpack:::run_examples(quote({2+2 ## ## trig ## sin(pi)}))) ## ## withAutoprint(quote({2+2 ## ## trig ## sin(pi)})) ## ## e1 <- ## (quote({2+2 ## ## trig ## sin(pi)})) ## ## attr(e1, "wholeSrcref") ## ## ## e2 <- ## quote({2+2 ## ## trig ## sin(pi)}) ## ## attr(e2, "wholeSrcref") ## ## e2a <- ## quote({2+2 ## sin(pi)}) ## ## attr(e2a, "wholeSrcref") ## ## unclass(attr(e2a, "wholeSrcref")) ## ## e3 <- ## quote(2+2) ## ## attr(e3, "wholeSrcref") ## Rdpack:::run_examples(quote({cvar::VaR(qnorm, x = c(0.01, 0.05), dist.type = "qf"); 2*3; 2 + 2; a <- 2 - 2; b <- 2/3 })) insert_fig <- function(file, package, code, insert = TRUE){ res <- if(insert) paste0("\\figure{", file, "}") else file dirs <- c("./man/", file.path(".", package, "man")) w <- sapply(dirs, dir.exists) dcur <- dirs[w] if(length(dcur) == 2) { # both, ./man and ./package/man exist warning(paste0("Ambiguity: both, './man' and './", package, "/man' exist,", "choosing the latter.")) dcur <- dcur[2] } else if(length(dcur) == 0) { ## try harder pat <- paste0("^", package, ".+") # dir name is pkg followed by something else (e.g. version) wrk <- intersect(dir(pattern = pat), list.dirs(full.names = FALSE, recursive = FALSE)) if(length(wrk) == 0) { warning("Unable to locate 'man/figure/' to write the graphics,\n", "please contact the maintainer of 'Rdpack';\n\n", "using previously created figure, if available.") return(res) } man_dir <- character(0) for(wdir in wrk) { dirs <- c(file.path(".", wdir, "man"), file.path(".", wdir, package, "man")) w <- sapply(dirs, dir.exists) man_dir <- c(man_dir, dirs[w]) } if(length(man_dir) == 1) { dcur <- man_dir } else if(length(man_dir) > 1) { warning("Ambiguity: more than one package directories found:\n", " ", paste(man_dir, collapse = ", "), "\n", "please contact the maintainer of 'Rdpack';\n\n", "writing to the last directory found.") ## TODO: probably should not write to a potentially unexpected directory; ## should just return(res), as above. dcur <- man_dir[length(man_dir)] } else { # length(man_dir) == 0 warning("Unable to locate 'man/figure/' to write the graphics,\n", "please contact the maintainer of 'Rdpack';\n\n", "using previously created figure, if available.") return(res) } } figpath <- file.path(dcur, "figures") if(!dir.exists(figpath)) { flag <- dir.create(figpath) if(!flag) { warning("Unable to create 'man/figure/' to write the graphics,\n", "using previously created figure, if available.") return(res) } } grDevices::png(file.path(figpath, file)) on.exit(grDevices::dev.off()) force(code) res } Rdpack/R/sections.R0000644000176200001440000001733215102212001013617 0ustar liggesusers.sec_name <- function(x){ # this assumes that x is a section Rd piece. a <- attr(x, "Rd_tag") #TODO: paste tuk e prapka, dobavi treti element! if(a != "\\section") a else paste(as.character(x[[1]]), collapse="") # 'as' is to drop attributes } .sec_content <- function(x){ # this assumes that x is a section Rd piece. a <- attr(x, "Rd_tag") if(a != "\\section") x else x[[2]] } .order_sections <- function(rdo){ # todo: take care of empty lines at top level. old <- Rdo_tags(rdo) n <- length(rdo) newpos <- numeric(n) curpos <- 1 for(i in 1:length(.rd_sections)){ ind <- which(old == .rd_sections[i]) len <- length(ind) if(len > 0){ newpos[curpos:(curpos+len-1)] <- ind curpos <- curpos + len } } if(curpos < n){ # note everything in "old" accounted for. Can there be things # other than newlines? missedpos <- seq_len(n)[ !(seq_len(n) %in% newpos) ] # browser() # for testing newpos[curpos:n] <- missedpos # to make sure that nothing is omitted } if(identical(newpos, seq_along(newpos))){ rdo # nothing to reshuffle here }else{ res <- rdo[newpos] attributes(res) <- attributes(rdo) res } } .replace_dummy <- function(rdo, unchanged_titles){ secall <- Rdo_sections(rdo) for(sec in secall) if(sec$title %in% unchanged_titles) rdo[[ sec$pos ]] <- char2Rdpiece("dummy", sub("^\\\\", "", sec$title), force.sec = TRUE) rdo } .srcrefpos <- function(rdo, rdoorig, pos_list){ secall <- Rdo_sections(rdo) res <- vector(mode="list", length(pos_list)) ind <- 0 for(sec in secall){ pos <- .tmp_pos(sec$title, pos_list) if(!is.null(pos)){ ind <- ind + 1 res[[ind]] <- list(attr(rdo[[sec$pos]], "srcref"), attr(rdoorig[[pos]], "srcref")) } } res } .replace_from <- function(rdo, rdoorig, pos_list){ secall <- Rdo_sections(rdo) for(sec in secall){ pos <- .tmp_pos(sec$title, pos_list) if(!is.null(pos)) rdo[[sec$pos]] <- rdoorig[[pos]] } rdo } Rdo_sections <- function(rdo){ res <- Rdo_locate(rdo, function(x) .tag_in(x, .rd_sections), .sec_name, lists = TRUE, nested = FALSE) # 2012-10-20 new arg. nested used lapply(res, function(x){ names(x)[names(x) == "value"] <- "title"; x}) } Rdo_modify_simple <- function(rdo, text, section, ...){ val <- char2Rdpiece(text, section) Rdo_modify(rdo, val, ...) } Rdo_empty_sections <- function(rdo, with_bs = FALSE){ # rdo is Rd object or filename if(is.character(rdo)) rdo <- permissive_parse_Rd(rdo) pat <- ".*Dropping empty section[ ]+[\\](.*)$" wrk <- checkRd(rdo) ind <- grepl(pat, wrk) res <- gsub(".*Dropping empty section[ ]+[\\]", "", wrk[ind]) if(with_bs) res <- sapply(res, function(x) paste("\\",x,sep="")) # prepend backslash res } Rdo_drop_empty <- function(rdo, sec = TRUE){ # todo: drop other empty things? emptysec <- Rdo_empty_sections(rdo, with_bs = TRUE) rdotags <- Rdo_tags(rdo) stopifnot(length(rdotags) == length(rdo)) # paranoic; but tools:::RdTags above is # non-exported function res <- rdo[ !(rdotags %in% emptysec) ] class(res) <- class(rdo) res } # rd is a character vector of filenames Rdo_replace_section <- function(rdo, val, create = FALSE, replace = TRUE){ Rdo_modify(rdo, val, create=create, replace = replace) } Rdo_set_section <- function(text, sec, file, ...){ piece <- char2Rdpiece(text, sec) rdo <- Rdo_replace_section(permissive_parse_Rd(file), piece, ...) Rdo2Rdf(rdo, file = file) } # todo: this does not consider the possibility for #ifdef # return the location (full index) of the content of a section. for # standard sections this is at the top level but for user defined # sections it is deeper. see also tools:::.Rd_get_section .locate_sec_content <- function(rdo, sec, onlyone = TRUE){ # 2011-12-12 add 'more' arg. tags <- Rdo_tags(rdo) indx_sec <- which(tags == sec) # in case this is a standard section, todo: do it properly! if(length(indx_sec) > 0){ # standard section if(length(indx_sec) > 1 && onlyone){ warning("More than one section with this name, using the first one.") indx_sec <- indx_sec[[1]] } res <- indx_sec # for standard sections the content is simply that tagged list. }else{ # user section; todo: arg. 'onlyone' silently ignored here indx_sec <- which(tags == "\\section") if(length(indx_sec) > 0 ){ # wraps in c() here to get rid of attributes; # note also the two 1's in the index (seems # that each arg of "\\section" is a list). methindx <- sapply(indx_sec, function(x) identical(c(rdo[[c(x,1,1)]]), sec) ) indx_sec <- indx_sec[methindx] # take only those that match. } if(length(indx_sec) == 0) res <- NA # stop("No section `??'. Todo: create it instead of throwing an error.") else{ if(length(indx_sec)>1){ warning("More than 1 sections `Methods' found, using the first one.") indx_sec <- indx_sec[1] } res <- c(indx_sec,2) # for user sections the content is deeper. } } res } .rdo_equal_sections <- function(rdo1, rdo2, sections = NULL){ # todo: arg. sections ne se # izpolzva veche! wrk1 <- Rdo_remove_srcref(rdo1) wrk2 <- Rdo_remove_srcref(rdo2) sec1 <- Rdo_sections(wrk1) sec2 <- Rdo_sections(wrk2) nams1 <- sapply(sec1, function(x) x$title) nams2 <- sapply(sec2, function(x) x$title) u1nam <- names(which(table(nams1) ==1)) # u1nam <- .without_duplicates(nams1) u2nam <- names(which(table(nams2) ==1)) # u2nam <- .without_duplicates(nams2) unam <- intersect(u1nam, u2nam) i1 <- which(nams1 %in% unam) # 2012-10-22 dobavyam all.equal, for some reason sometimes # seeemingly identical things are not "identical", # e.g. Special.Rd dava takova nesto za details. # todo: tova e krapka razibirase. isame <- sapply(i1, function(x){ i2 <- which(nams2 == nams1[x]); if(length(i2)==1 && ( identical(wrk1[[sec1[[x ]]$pos]], wrk2[[sec2[[i2]]$pos]]) || isTRUE(all.equal(wrk1[[sec1[[x ]]$pos]], wrk2[[sec2[[i2]]$pos]])) )) i2 else NA }) # browser() isame <- isame[!is.na(isame)] res <- sec2[isame] res } # tools:::.Rd_get_name # tools:::.Rd_deparse # # . function (x, sec) # get the Rd # { # x <- .Rd_get_section(x, "section") # if (length(x)) # .strip_whitespace(.Rd_deparse(x, tag = FALSE)) # else character() # } # list_files_with_exts("./man","Rd") # list_files_with_type("./man","docs") # Rdo_replace_section(a, char2Rdpiece("documentation", "keyword"), replace = "Rd") # files <- list_files_with_exts(dir, "Rd") Rdpack/R/alias.R0000644000176200001440000000176215102212001013061 0ustar liggesusers # todo: are aliases updated for classes? update_aliases_tmp <- function(rdo, package = NULL){#only for methods, currently; only appends fname <- .get.name_content(rdo)$short # name of the generic rdoaliases <- toolsdotdotdot.Rd_get_metadata(rdo, "alias") # aliases currently in rdo curtxt <- get_sig_text(rdo, package = package) # process signatures described in rdo ucur <- parse_usage_text(curtxt) methaliases <- sapply(ucur, function(x) .methsig2alias(fname, x$defaults)) new_aliases <- methaliases[ !(methaliases %in% rdoaliases) ] if(length(new_aliases) > 0) # update the aliases for(alias in new_aliases){ rdo <- Rdo_insert(rdo, char2Rdpiece(alias, "alias")) } rdo } .methsig2alias <- function(name, sig){ res <- gsub("\"", "", paste(c(name, sig), collapse=",")) paste(res, "-method", sep="") # no comma after the last arg } Rdpack/R/slots.R0000644000176200001440000000423015102212001013125 0ustar liggesusersinspect_slots <- function(rdo, final=TRUE){ fullname <- .get.name_content(rdo)$name # name of the class with '-class' suffix cur <- .capture_promptAny(fullname, final=final) ## 2018-08-27 - non-exiting class (TDO: check if it could be something else here if(inherits(cur, "try-error")){ return(cur) } curnames <- .get_top_labels(cur, "Slots") # current slots rdonames <- .get_top_labels(rdo, "Slots") # slots in rdo icmp <- .asym_compare(rdonames, curnames) # compare; get fields $i_new, $i_rem, $i_com if(length(icmp$i_new)>0){ ## 2014-06-18 the labels contain Rd markup, as in \code{mo.col}, but this seems ## harmless. ## 2014-06-21 new slots were not handled correctly, see the changes below; ## see also inspect_clmethods - there is a lot of common ground. ## todo: consolidate? ## 2019-05-12 was: newnames <- names(icmp$i_new) # 2014-06-21 new newnames <- curnames[icmp$i_new] cat("Undocumented slots:", newnames # 2014-06-21 was: names(icmp$i_new) # 2014-06-18 was: icmp$i_new , "\n") cat("\tAdding items for them.\n") # todo: insert in particular order? cnt_newslots <- .get_top_items(cur, "Slots", newnames) # 2014-06-21 was: icmp$i_new cnt_newslots <- .nl_and_indent(cnt_newslots) # 2014-06-21 new # this ensures that the closing brace for "describe" # is on new line. todo: this needs to be indented. cnt_newslots <- c(cnt_newslots, list(Rdo_newline())) # 2014-06-21 new dindx <- .locate_top_tag(rdo, "Slots") rdo <- append_to_Rd_list(rdo, cnt_newslots, dindx) } if(length(icmp$i_removed)>0){ # todo: maybe put this note in a section in rdo? ## 2019-05-12 was: cat("Slots:", icmp$i_removed, "\n") cat("Slots:", rdonames[icmp$i_removed], "\n") cat("are no longer present. Please remove their descriptions manually.\n") } rdo } Rdpack/R/elements.R0000644000176200001440000001221015102212001013572 0ustar liggesusersRdo_newline <- function(){ structure("\n", Rd_tag = "TEXT") } Rdo_is_newline <- function(rdo){ is.character(rdo) && length(rdo) == 1 && rdo == "\n" } Rdo_comment <- function(x = "%%"){ structure(x, Rd_tag = "COMMENT") } Rdo_text <- function(x){ structure(x, Rd_tag = "TEXT") } # todo: check for % and \\ ? Rdo_verb <- function(x){ structure(x, Rd_tag = "VERB") } Rdo_Rcode <- function(x){ structure(x, Rd_tag = "RCODE") } Rdo_tag <- function(x, name){ structure(x, Rd_tag = name) } Rdo_macro <- function(x, name){ if(!is.character(x)) # the argument has been prepared in advance return(Rdo_tag(x,name)) # (bar the Rd_tag) cnt <- Rdo_text(x) if(name %in% c("\\eqn", "\\deqn")) # these are like two argument macros. cnt <- list(cnt) Rdo_macro1(cnt, name) } .Rdo_elem <- function(x){ if(is.null(attr(x, "Rd_tag"))){ if(is.character(x)) list(Rdo_text(x)) else x }else list(x) } Rdo_macro1 <- function(x, name){ structure(list(x), Rd_tag = name) } Rdo_macro2 <- function(x, y, name){ structure(list(.Rdo_elem(x), .Rdo_elem(y)), Rd_tag = name) } Rdo_item <- function(x,y){ Rdo_macro2(x, y, "\\item") } Rdo_sigitem <- function(x,y, newline=TRUE){ # todo: newline not currently used if(missing(y)) # default as in promptMethods() y <- list( Rdo_newline() , Rdo_comment("%% ~~describe this method here~~") , Rdo_newline() ) Rdo_item( list(Rdo_macro1(Rdo_Rcode(c(x)), "\\code")) # c(x) to remove attributes. , list(y, Rdo_newline()) ) # (todo: does it really do it?) } # as.vector() to remove name attr. Rdo_piecetag <- function(name) as.vector(Rdo_piece_types[name]) Rdo_sectype <- function(x) as.vector( Rdo_predefined_sections[x] ) is_Rdsecname <- function(name) name %in% names(Rdo_predefined_sections) # 2012-10-08 todo: wished to change it to # .rd_sections but those are with backslashes. # need to consolidate. .char2Rdtag <- function(content, name = NULL){ if(is.null(name) || name == "") return(Rdo_text(content)) tag <- Rdo_piecetag(name) if(is.na(tag)) tag <- "TEXT" # todo: check the content and mark it RawText if it contains % or \\ Rdo_tag(content, tag) } char2Rdpiece <- function(content, name, force.sec = FALSE){ content <- .char2Rdtag(content, name = name) if(!force.sec || is_Rdsecname(name)) Rdo_macro1(content, paste("\\", name, sep="")) else Rdo_macro2(Rdo_text(name), content, "\\section") #todo: dali name e "TEXT" tuk } list_Rd <- function(..., Rd_tag=NULL, Rd_class = FALSE){ dots <- list(...) nams <- allNames(dots) mflags <- grepl("^\\\\", nams) # LaTeX macros wrk <- mapply(function(x, i) if(mflags[i]) Rdo_macro(x, nams[i]) else x , dots, seq_along(dots), SIMPLIFY = FALSE, USE.NAMES=FALSE) # process other names - title, name, etc., not starting with backslash sflags <- grepl("^([^\\\\]|$)", nams) # other named elements, including "" wrk <- mapply(function(x, i) if(sflags[i]){ if(is.character(x)) # Rdo_piece(x, nams[i]) char2Rdpiece(x, nams[i]) else # structure(x, Rd_tag = paste("\\", nams[i], sep="")) Rdo_tag(x, paste("\\", nams[i], sep="")) }else x , wrk, seq_along(dots), SIMPLIFY = FALSE, USE.NAMES=FALSE) res <- wrk if(!is.null(Rd_tag)) attr(res, "Rd_tag") <- Rd_tag if(Rd_class) class(res) <- "Rd" res } c_Rd <- function(...){ dots <- list(...) rdtags <- sapply(dots, function(x) attr(x,"Rd_tag") ) if(!is.null(names(rdtags))) names(rdtags) <- NULL for(i in seq_along(dots)){ # process "character" elements elem <- dots[[i]] if(!is.character(elem)) next if(is.null(rdtags[[i]])){ # todo: convert the string to Rd object (parse attr(elem, "Rd_tag") <- "TEXT" # it); for now, simply attach a TEXT Rd_tag (not } # necessarilly correct!) and embed in a list. dots[[i]] <- list(elem) } # now everything should be a list; # tags may have changed res <- do.call("c", dots) if(any(sapply(dots, function(x) inherits(x, "Rd")))) class(res) <- "Rd" # if any arg. is "Rd" res is also "Rd" else{ # set Rd_tag to the 1st non-null rdtag indx <- which(sapply(dots, function(x) !is.null(attr(x,"Rd_tag")))) if(length(indx)>0) attr(res, "Rd_tag") <- rdtags[[ indx[1] ]] } res } Rdpack/R/parse.R0000644000176200001440000000431415102212001013076 0ustar liggesusers## 2018-01-30 experimenting with processing of Rd macros ## pkgmacros <- tools::loadPkgRdMacros(system.file(package = package)) ## rdo <- parse_Rd(infile, macros = pkgmacros) ## 2018-01-30 new function ## as parse_Rd but intercepts warnings about unknown Rd macros permissive_parse_Rd <- function(file, permissive = TRUE, ...){ parse_Rd(file, permissive = permissive, ...) } ## 2018-01-30 new argument 'macros' .parse_Rdlines <- function(lines, macros = NULL){ tmpfile <- tempfile("Rdlines", fileext = ".Rd") # unlist is harmless if `lines' is already a character vector cat(unlist(lines), file = tmpfile, sep = "\n") # todo: catch errors if(is.null(macros)) res <- permissive_parse_Rd(tmpfile) # todo: catch errors else res <- permissive_parse_Rd(tmpfile, macros = macros) # todo: catch errors unlink(tmpfile) res } parse_Rdtext <- function(text, section = NA){ if(!is.na(section)) text <- c(paste(section,"{",sep=""), text, "}") res <- .parse_Rdlines(text) # write(text, sep="\n", file = file); res <- parse_Rd(file) rdtag <- attr(res[[1]], "Rd_tag") if(!is.na(section) && !is.null(rdtag) && rdtag==section) # todo: tova e krapka! res <- res[[1]] if(identical( c(res[[1]]), "\n" )) # c( ) to strip attributes res[[1]] <- NULL res } parse_Rdpiece <- function(x, result=""){ maket <- list_Rd(title="Dummy title" , name="dummyname" , "\\description"="Dummy description" , note = x , Rd_class=TRUE ) fn <- tempfile(pattern = "Rdpiece", fileext = "Rd") cat(as.character(maket), file=fn, sep="") # todo: error processing wrk <- permissive_parse_Rd(fn) unlink(fn) if(result=="text"){ # Rd_help2txt is from gbRd res <- gbRd::Rd_help2txt(wrk, keep_section="\\note", omit_sec_header=TRUE) }else{ indx <- Rdo_which_tag_eq(wrk, "\\note") res <- wrk[[indx]] if(!is.null(attr(res,"Rd_tag"))) attr(res,"Rd_tag") <- NULL } res } Rdpack/R/signature.R0000644000176200001440000002475115102212001013774 0ustar liggesusers # todo: need to setup error processing. E.g. in 2.14-0 signatures # for 'initialize-methods' in package 'methods' have an entry # with a duplicated signature which causes error. .get_signature <- function(rdo, pos){ sigtxt <- rapply(rdo[[pos]], function(x){ if(length(x)>1){ #when Rd_tag = "USERMACRO" "" }else if(grepl("^[ ]*signature\\(", x)){ wrk <- gsub("^[ ]*(signature\\([^)]*\\)).*", "\\1", x) # in case manual formatting has introduced more spaces. However, # this needs to be done more carefully. It would be best to # parse the signature rather than to scrape the string. On the # other hand, signatures are produced (usually) programmatically. gsub("[[:space:]]+", " ", wrk) }else "" }, classes = "character", deflt="") sigtxt[ sigtxt != ""] } .get_item_labsig <- function(rdo, pos, lab=TRUE){ label <- if(lab) .get_item_label(rdo, pos) else as.character(NA) sig <- .get_signature(rdo, pos) if(inherits(try(parse(text=sig),silent=TRUE), "try-error")){ txt <- parse_Rdpiece(rdo[[pos]],result="text") sig <- gsub("^.*(signature\\([^)]*\\)).*", "\\1", paste(txt,collapse=" ")) sig <- gsub("[[:space:]]+", " ", sig) sig <- gsub("'", "", sig) # krapka } c(name = label, signature = sig) } .get_top_signature <- function(rdo, pos = NULL, sec = "Methods", lab = TRUE){ if(is.null(pos)) pos <- .locate_top_items(rdo, sec) lapply(pos, function(x) .get_item_labsig(rdo, x, lab = lab) ) } # this inspect signatures in documentation of a class inspect_clmethods <- function(rdo, final = TRUE){ fullname <- .get.name_content(rdo)$name # name of the class, including suffix `-class' cur <- .capture_promptAny(fullname, final=final) # gather info about the actual methods curnames <- .get_top_labels(cur, "Methods") curitems <- .locate_top_items(cur, "Methods") cursigs <- .get_top_signature(cur, pos = curitems, sec = "Methods") rdonames <- .get_top_labels(rdo, "Methods") # gather info about rdo items <- .locate_top_items(rdo, "Methods") rdosigs <- .get_top_signature(rdo, pos = items, sec = "Methods") cmp <- .asym_compare(rdosigs, cursigs) # compare methods in rdo and cur indxnew <- cmp$i_new indxdrp <- cmp$i_removed if(length(indxnew)>0){ # Now make inference based on cmp. cat("Undocumented methods found.\n") # 2012-10-16 cat("Undocumented methods: ") cat("\tAdding items for them.\n") # print(cursigs[indxnew]) # print(cursigs[indxnew]) curnamesnew <- curnames[indxnew] # todo: some clean up of the code below. # todo: sort by function name (first arg. na \\item) newitems <- .get_subset(cur, curitems[indxnew], rdtag = "\\describe") newitems <- .nl_and_indent(newitems) # 2012-10-16 proverkata za empty items if(length(items) == 0){ # no \describe environment idescr <- .locate_sec_content(rdo, "Methods") if(length(idescr)==1 && is.na(idescr)){ # NA returned if no section Methods # todo: NA is inconvenient to check # not needed: methpos <- Rdo_get_insert_pos(rdo,"\\section") rdo <- Rdo_insert(rdo, char2Rdpiece("Functions with methods for this class:", "Methods", force.sec = TRUE ), newline = FALSE) idescr <- .locate_sec_content(rdo, "Methods") } rdo[[idescr]] <- c(rdo[[idescr]], list(newitems)) }else{ dindx <- .locate_enclosing_tag(rdo, items[[1]], "\\describe") wrk <- c(rdo[[dindx]], newitems ) # ne mozhe tolkova prosto ponezhe v rdo[[indx]] mozhe da ima i # drugi elementi osven \item (napr \n # rdo[[dindx]] <- structure(wrk[ order(c(curnames,rdonames)) ], # Rd_tag = "\\describe") wrk2 <- wrk allnams <- c(rdonames,curnamesnew) rdo[[dindx]] <- if(length(wrk2) == length(allnams)) # only only \item's present structure(wrk2[order(allnams)], Rd_tag = "\\describe") else structure(wrk2 , Rd_tag = "\\describe") } } if(length(indxdrp)>0){ # todo: maybe put this note in a section in rdo? cat("The following methods are no longer present:\n") print(rdosigs[indxdrp]) cat("\tPlease remove their descriptions manually.\n") } rdo } ## This inspects signatures in documentation of methods. Signatures in documentation of ## classes are stored somewhat differently. this was written before inspect_clmethods() and ## was geared towards using existing code for ordinary functions (mainly parse_usage_text() inspect_signatures <- function(rdo, package = NULL, sec = "Methods"){ rdosigs <- .get_top_signature(rdo, sec = "Methods", lab = FALSE) # process signatures sigtxt <- sapply(rdosigs, function(x) x["signature"]) # in `rdo' urdo <- parse_usage_text(sigtxt) curtxt <- get_sig_text(rdo, package=package) # process actual signatures ucur <- parse_usage_text(curtxt) # 2012-09-07 - may tryabva da varne samite elementi, ne technite indeksi. icomp <- .asym_compare(urdo, ucur) removed_sig <- urdo[ icomp$i_removed ] added_sig <- ucur[ icomp$i_new ] if(length(added_sig)>0){ cat(length(added_sig), "new signatures found.\n") # print(added_sig) cat("\tAdding items for them.\n") } # else cat("\tNo new signatures.\n") if(length(removed_sig)>0){ # for testing only; cat(length(removed_sig), "removed signatures:\n") # remove eventually print(removed_sig) }else cat("\tNo removed signatures.\n") list( changed = length(added_sig) != 0 | length(removed_sig) != 0 , added_sig = added_sig, removed_sig = removed_sig ) } # 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 funtions from a package; also, promptMethods() seems to call the deprecated # function getMethods()). Check how these things stand in R-2.14, there may be no problem # any more (checked, in 2.14-0 it is the same). # curtxt0 <- showMethods(fname, printTo=FALSE) # curtxt <- curtxt0[-1] # drop the description string # curtxt <- gsub("^[ ]*\\(inherited from[^)]*\\)[ ]*", "" , curtxt) # curtxt <- curtxt[ curtxt != "" ] # todo: improve! # curtxt <- paste("signature(", curtxt, ")", sep="") get_sig_text <- function(rdo, package = NULL){ # finds the actual signatures without fname <- .get.name_content(rdo)$short # using promptXXX functions meths <- if(is.character(package)) findMethodSignatures(fname,where = asNamespace(package)) else findMethodSignatures(fname) nammeths <- colnames(meths) # insert quotes to make this consistent with parse_usage_text(); # do it defensively (hardly necessary), in case they are already there sig <- apply(meths, c(1,2), function(x) if(!all( grepl("^\"",x))) paste("\"",x,"\"",sep="") else x) # get one column for each signature sig <- apply(sig, 1, function(x) paste(nammeths, x, sep=" = ") ) # adjust `sig' so that `paste()' would do the right thing sig <- if(is.matrix(sig)) apply( t(sig), 1, function(x) paste(x, collapse=", ")) else sig # a vector if one paste("signature(", sig, ")", sep="") } S4formals <- function(fun, ...){ # could be made S4 generic if(!is(fun, "MethodDefinition")) fun <- getMethod(fun, ...) #browser() ## 2019-04-21 was: ## # todo: check that this is ok ## formals(body(fun@.Data)[[c(2,3)]]) # if not, fall back to formals(m1) ## ## This resolves a very old 'todo' (see the commented text above). ## The hack above doesn't always work. Replace it it more enlightened approach. fff <- fun@.Data funbody <- body(fff) if(length(funbody) == 3 && identical(funbody[[1]], as.name("{")) && length(funbody[[2]]) == 3 && identical(funbody[[c(2,1)]], as.name("<-")) && identical(funbody[[c(2,2)]], as.name(".local")) && is.function(funbody[[c(2,3)]]) ){ ## this is the old hack: formals(body(fun@.Data)[[c(2,3)]]) formals(funbody[[c(2,3)]]) }else{ formals(fff) } } # showMethods("plot") # showMethods("plot",includeDefs=TRUE) # showMethods("plot",includeDefs=TRUE,print=FALSE) # s <- showMethods("plot",includeDefs=TRUE, print=FALSE) # # # m1 <- getMethod("plot",c(x="profile.mle", y="missing")) # # class(m1) # showClass(class(m1)) # # m1 # m1@defined # m1@target # m1@.Data # # str(m1) # # formals(m1) # # m1@.Data # m1body <- body(m1@.Data) # m1body # m1body[[1]] # `{` # m1body[[2]] # the expression: .local <- function(...) ... # class(m1body[[2]]) # "<-" # m1body[[c(2,1)]] # `<-` # m1body[[c(2,2)]] # .local # m1body[[c(2,3)]] # the function, what I need # formals(m1body[[c(2,3)]]) # the formals ! Rdpack/R/yytransient.R0000644000176200001440000001026215102212001014354 0ustar liggesusers # 2013-12-01 new; need testing .ascharRd <- function(rdo){ if(is.character(rdo)) # note: applying as.character.Rd, as below gives error in this case res <- as.vector(rdo) # to drop attributes; else{ class(rdo) <- "Rd" res <- as.character(rdo) } paste(res, collapse="") # todo: argument to make this optional? } .safeRdtag <- function(x, nulltag = ""){ # replaces NULL with nulltag res <- attr(x, "Rd_tag") if(is.null(res)) res <- nulltag res } # a replacement for tools:RdTags; takes # 2013-12-08 renamed from .top_RdTags Rdo_tags <- function(rdo, nulltag = ""){ # note: absent Rd_tag's are returned as "" locf <- function(x) .safeRdtag(x, nulltag) res <- sapply(rdo, locf) if (length(res)==0) res <- character() res } Rdo_which <- function(rdo, fun){ # fun - predicate wrk <- sapply(rdo, fun) which(wrk) } # 2013-12-08 renamed from .whichtageq Rdo_which_tag_eq <- function(rdo, tag){ tags <- Rdo_tags(rdo) pos <- which(tags == tag) pos } # 2013-12-08 renamed from .whichtagin Rdo_which_tag_in <- function(rdo, tags){ # TODO: needs testing! alltags <- Rdo_tags(rdo) pos <- which(sapply(alltags, function(x) .tag_in(x,tags) )) pos } Rdo_get_item_labels <- function(rdo){ wrk <- Rdo_locate(rdo, f = function(x){ # attr(x,"Rd_tag") == "\\item" .tag_eq(x, "\\item") }, lists = TRUE, nested = FALSE, pos_only = function(x) if(length(x) > 0) .ascharRd(x[[1]]) else "" #in \itemize items do not have labels ) sapply(wrk, function(x) x$value) } Rdo_get_argument_names <- function(rdo){ # 2013-12-08 was: indx <- Rdo_locate_predefined_section(rdo, "\\arguments") # todo: shouldn't this be using some "locate"-type function? I removed # Rdo_locate_predefined_section() since it simply checks the tags as # below but probably should vreate a ne function based on a "locate" indx <- Rdo_which_tag_eq(rdo, "\\arguments") if(length(indx) == 0) return(character(0)) # no "arguments" section in rdo; initially was: NA_character_ txt <- Rdo_get_item_labels(rdo[[indx]]) if (length(txt)==0) # this chunk: copied from tools:::.Rd_get_argument_names return(character()) txt <- unlist(strsplit(txt, ", *")) txt <- gsub("\\\\l?dots", "...", txt) txt <- gsub("\\\\_", "_", txt) txt <- .strip_whitespace(txt) txt <- unique(txt) # cater for duplication due to #ifdef unix or windows; # see e.g. system.Rd or system2.Rd in base package # # todo: more thought on this? txt } # 2013-10-23 new # pattern = ".*[.]Rd$" would be too dangerous. # but may be exclude could exclude foo-package Rdreplace_section <- function(text, sec, pattern, path = "./man", exclude = NULL, ...){ rdnames <- dir(path, pattern, full.names=TRUE) # todo: allow 'exclude' to have length more than 1 if(!is.null(exclude)){ rdexcl <- dir(path, exclude, full.names=TRUE) rdnames <- setdiff(rdnames, rdexcl) } for(nam in rdnames){ try(Rdo_set_section(text, sec, nam)) } rdnames # todo: return a logical vector of success/failures? } Rdo_locate_core_section <- function(rdo, sec){ # 2013-12-08 # Rdo_which_tag_eq(rdo, sec) secall <- Rdo_sections(rdo) sec.names <- sapply(secall, function(x) x$title) indx <- which(sec.names == sec) if(length(indx)==0) list() else ## 2018-04-21 was: secall[[indx]] secall[indx] } Rdpack/R/bib.R0000644000176200001440000014106615106037225012547 0ustar liggesusers## Do not edit this file manually. ## It has been automatically generated from *.org sources. # TODO: krapka! .patch_latex <- function(txt){ # print(bibentry,"latex") inserts \bsl macros. gsub("\\bsl{}", "", txt, fixed=TRUE) } ## maybe add to package `gbutils'? ## ## if `wd' is a subdirectory of `string' return the path upto and including `string', ## otherwise return NULL. ## If not NULL, it is guaranteed that basename(wd) == string ## NOTE: currently doesn't expand `./', etc.. in_subdirectory <- function(string, wd = getwd()){ if(grepl(string, wd)){ packpat <- paste0(string, "$") while(!grepl(packpat, wd)){ wd <- dirname(wd) if(!grepl(string, wd)) return(NULL) } if(basename(wd) == string) wd else ## the found directory has `string' as a suffix, eg. xxxRdpack, not Rdpack NULL }else NULL } get_bibentries <- function(..., package = NULL, bibfile = "REFERENCES.bib", url_only = FALSE, stop_on_error = TRUE){ if(is.null(package)){ fn <- file.path(..., bibfile) ## check for existence of fn (and length(fn) == 1)? (but see below) }else{ ## first check for development mode in "devtools" ## if the current directory is under `package', first look for the file there devdir <- in_subdirectory(package) if(is.null(devdir)) fn <- "" else{ ## if in development dir of `package', get it from there fn <- file.path(devdir, "inst", ..., bibfile) if(length(fn) > 1){ warning("More than one file found, using the first one only.") fn <- fn[1] } if(!file.exists(fn)) fn <- "" } if(fn == "") ## if the above didn't succeed, try system.file(). In principle, this should work ## also in development mode under devtools, at least for REFERENCES.bib, ## but currently devtools' system.file() doesn't handle it. fn <- system.file(..., bibfile, package = package) if(fn == "") ## if the above didn't succeed try system.file() with subdir "inst". ## This is really for the case when system.file() is the one from devtools, ## see the note above. TODO: check if this is the case? fn <- system.file("inst", ..., bibfile, package = package) ## 2020-09-27 removing this functionality since package 'bibtex' ca no longer be ## relied upon and was dropped from the dependencies. ## ## if(length(fn) == 1 && fn == "") ## ## if system.file() didn't find the bib file, check if file package.bib is ## ## provided by package "bibtex" (it is for core R packages, such as "base") ## fn <- system.file("bib", sprintf("%s.bib", package), package = "bibtex") } if(length(fn) > 1){ warning("More than one file found, using the first one only.") fn <- fn[1] }else if(length(fn) == 1 && fn == ""){ msg <- paste0("Couldn't find file ", file.path(..., bibfile), if(!is.null(package)) paste0(" in package `", package, "'")) if(stop_on_error) stop(msg) else{ warning(msg) ## return an empty bibentryRd object res <- bibentry() class(res) <- c("bibentryRd", class(res)) return(res) } } ## 2018-10-03 ## use package's encoding if specified. ## TODO: maybe this function should have argument 'encoding' ## TODO: in principle the Rd file may have its own encoding, ## but my current understanding is that parse_Rd() first converts it to UTF-8. ## BUT what is the encoding of the strings in the object returned by read.bib? encoding <- if(!is.null(package) && !is.null(utils::packageDescription(package)$Encoding)) utils::packageDescription(package)$Encoding else "UTF-8" ## 2020-09-22 switching to 'rbibutils ## res <- read.bib(file = fn, encoding = encoding) ## current: res <- readBib(file = fn, encoding = encoding) ## test: res <- if(packageVersion("rbibutils") > '2.2.4') ## issue #7 in rbibutils readBib(file = fn, encoding = encoding, direct = TRUE, texChars = "Rdpack") else if(packageVersion("rbibutils") >= '2.1.2') readBib(file = fn, encoding = encoding, direct = TRUE) else readBib(file = fn, encoding = encoding) # 2018-03-10 commenting out # since bibtex v. >= 0.4.0 has been required for a long time in DESCRIPTION # # ## 2016-07-26 Now do this only for versions of bibtex < '0.4.0'. # ## From bibtex '0.4.0' read.bib() sets the names. # if(packageVersion("bibtex") < '0.4.0'){ # names(res) <- sapply(1:length(res), function(x) bibentry_key(res[[x]][[1]])) # } ## 2020-10-02 commenting out since taken care (hopefully) by readBib ## # for(nam in names(res)){ # ## unconditionaly recode %'s in filed URL # if(!is.null(res[nam]$url)) { # res[nam]$url <- gsub("([^\\])%", "\\1\\\\%", res[nam]$url) # } # # if(url_only){ # process also other fields # ## TODO: currently all unescaped %'s in all fields are recoded; # ## Maybe do it more selectively, e.g. only for %'s inside \url{}, # ## or matching something like http(s):// # fields <- names(unclass(res[nam])[[1]]) # # unclassed <- unclass(res[nam]) # flag <- FALSE # for(field in fields){ # wrk <- unclass(res[nam])[[1]][[field]] # if(is.character(wrk) && any(grepl("([^\\])%", wrk))){ # flag <- TRUE # unclassed[[1]][[field]] <- gsub("([^\\])%", "\\1\\\\%", wrk) # } # } # if(flag){ # class(unclassed) <- class(res[nam]) # res[nam] <- unclassed # } # } # } ## new 2020-10-02 - allow \% in url's and doi's in the bib file for(nam in names(res)){ # print(res[nam], style = "R") ## unconditionaly recode %'s in filed URL if(!is.null(res[nam]$doi)) { res[nam]$doi <- gsub("([^\\\\])[\\\\]%", "\\1%", res[nam]$doi) } if(!is.null(res[nam]$url)) { res[nam]$url <- gsub("([^\\\\])[\\\\]%", "\\1%", res[nam]$url) } # if(url_only){ # process also other fields # ## TODO: currently all unescaped %'s in all fields are recoded; # ## Maybe do it more selectively, e.g. only for %'s inside \url{}, # ## or matching something like http(s):// # fields <- names(unclass(res[nam])[[1]]) # # unclassed <- unclass(res[nam]) # flag <- FALSE # for(field in fields){ # wrk <- unclass(res[nam])[[1]][[field]] # if(is.character(wrk) && any(grepl("([^\\])%", wrk))){ # flag <- TRUE # unclassed[[1]][[field]] <- gsub("([^\\])%", "\\1\\\\%", wrk) # } # } # if(flag){ # class(unclassed) <- class(res[nam]) # res[nam] <- unclassed # } # } } ## 2018-03-03 new: class(res) <- c("bibentryRd", class(res)) res } print.bibentryRd <- function (x, style = "text", ...){ class(x) <- class(x)[-1] ## TODO: It would be better to modify the entries and then call ## print(), rather than vice versa as now. res <- capture.output(print(x, style = style, ...)) res <- switch(tolower(style), r = gsub("\\\\\\\\%", "%", res), citation = , bibtex = gsub("\\\\%", "%", res), res ) cat(res, sep = "\n") } rebib <- function(infile, outfile, ...){ # 2013-03-29 rdo <- permissive_parse_Rd(infile) ## 2017-11-25 TODO: argument for RdMacros! if(missing(outfile)) outfile <- basename(infile) else if(identical(outfile, "")) # 2013-10-23 else clause is new outfile <- infile rdo <- inspect_Rdbib(rdo, ...) Rdo2Rdf(rdo, file=outfile, srcfile=infile) rdo } inspect_Rdbib <- function(rdo, force = FALSE, ...){ # 2013-03-29 # 2013-12-08 was: pos <- Rdo_locate_predefined_section(rdo, "\\references") pos <- Rdo_which_tag_eq(rdo, "\\references") if(length(pos) > 1) stop(paste("Found", length(pos), "sections `references'.\n", "There should be only one." )) else if(length(pos) == 0) # no section "references". return(rdo) bibs <- get_bibentries(...) fkey <- function(x){ m <- gregexpr("[ ]+", x) rm <- regmatches(x, m, invert = TRUE)[[1]] if(length(rm) >= 2 && rm[2] != "bibentry:") rm[2] # e.g. bibentry:all else if(length(rm) < 3) # % bibentry: xxx_key_xxx "" # NA_character_ else rm[3] } fbib <- function(x) grepl("[ ]+bibentry:", x) posbibs <- Rdo_locate(rdo[[pos]], f = fbib, pos_only = fkey) poskeys <- sapply(posbibs, function(x) x$value) print(posbibs) fendkey <- function(x){ m <- gregexpr("[ ]+", x) rm <- regmatches(x, m, invert = TRUE)[[1]] if(length(rm) >= 2 && rm[2] != "end:bibentry:") rm[2] # e.g. end:bibentry:all else if(length(rm) < 3) # % end:bibentry: xxx_key_xxx "" # NA_character_ else rm[3] } fendbib <- function(x) grepl("end:bibentry:", x) posendbibs <- Rdo_locate(rdo[[pos]], f = fendbib, pos_only = fendkey) posendkeys <- sapply(posendbibs, function(x) x$value) toomit <- which(poskeys %in% posendkeys) # note: en@bibkeys:all is different! todo: if(length(toomit) > 0 && !force){ poskeys <- poskeys[-toomit] posbibs <- posbibs[-toomit] } if(length(poskeys)==0) "nothing to do." else if(any(poskeys == "bibentry:all")){ poskey <- posbibs[[ which(poskeys == "bibentry:all") ]]$pos ## 2021-04-29 TODO: the following line(s) needs to be replaced with ## .toRd_styled(bibs[poskeys[i], ???) ## For testing use REFERENCES.bib in rbibutils ## (the doi's are currently rendered horribly) ## DONE! was: # bibstxt <- capture.output(print(bibs, "latex")) # # bibstxt <- .patch_latex(bibstxt) # TODO: krapka! ## TODO: the bibstyles used below should probably be arguments # 2025-11-11 was: sort(bibs, .bibstyle = "JSSRd") bibs <- sort(bibs, .bibstyle = Rdpack_bibstyles("")) bibstxt <- .toRd_styled(bibs, "Rdpack") # bibstxt <- paste0(bibstxt, collapse = "\\cr\\cr ") bibstxt <- paste0(bibstxt, collapse = "\n\n ") bibstxt <- paste(c("", bibstxt), "\n", sep="") endbibline <- Rdo_comment("% end:bibentry:all") keyflag <- "end:bibentry:all" %in% posendkeys if(keyflag && force){ #todo: more careful! endposkey <- posendbibs[[ which(posendkeys == "end:bibentry:all") ]]$pos rdo[[pos]] <- Rdo_flatremove(rdo[[pos]], poskey+1, endposkey) } if(!keyflag || force){ rdo[[pos]] <- Rdo_flatinsert(rdo[[pos]], list(endbibline), poskey, before = FALSE) rdo[[pos]] <- Rdo_flatinsert(rdo[[pos]], bibstxt, poskey, before = FALSE) } }else{ for(i in length(poskeys):1){ bibkey <- posbibs[[i]]$value poskey <- posbibs[[i]]$pos ## 2021-04-29 TODO: the following line(s) needs to be replaced with ## .toRd_styled(bibs[poskeys[i], ???) ## For testing use REFERENCES.bib in rbibutils ## (the doi's are currently rendered horribly) ## DONE! was: # bibstxt <- capture.output(print(bibs[poskeys[i]],"latex")) # # bibstxt <- .patch_latex(bibstxt) # TODO: krapka! bibstxt <- .toRd_styled(bibs[poskeys[i]], "Rdpack") bibstxt <- list( paste( c("", bibstxt), "\n", sep="") ) endbibline <- Rdo_comment(paste("% end:bibentry: ", bibkey)) keyflag <- bibkey %in% posendkeys if(keyflag && force){ #todo: more careful! endposkey <- posendbibs[[ which(posendkeys == bibkey) ]]$pos rdo[[pos]] <- Rdo_flatremove(rdo[[pos]], poskey+1, endposkey) } if(!keyflag || force){ # this is always TRUE here but is left for common look # with "all". todo: needs consolidation rdo[[pos]] <- Rdo_flatinsert(rdo[[pos]], list(endbibline), poskey, before = FALSE) rdo[[pos]] <- Rdo_flatinsert(rdo[[pos]], bibstxt, poskey, before = FALSE) } } } rdo } Rdo_flatremove <- function(rdo, from, to){ # 2013-03-30 todo: more careful! res <- rdo[-(from:to)] attributes(res) <- attributes(rdo) # todo: more guarded copying of attributes? res } # todo: move to another file later Rdo_flatinsert <- function(rdo, val, pos, before = TRUE){ # 2013-03-29 depth <- length(pos) if(depth > 1){ rdo[[pos]] <- Recall(rdo[[ pos[-depth] ]], val, pos[-depth]) # todo: dali zapazva attributite na rdo? return(rdo) } n <- length(rdo) if(!before) pos <- pos + 1 res <- if(pos==1) c(val, rdo) else if(pos==n+1) c(rdo, val) else c( rdo[1:(pos-1)], val, rdo[pos:n]) attributes(res) <- attributes(rdo) # todo: more guarded copying of attributes? res } ## 2020-11-01: use local() .bibs_cache <- local({ ## initialise the cache ## TODO: remove refsmat, it is not needed here, maybe refsmat <- matrix(character(0), nrow = 0, ncol = 2) allbibs <- list() ## TODO: time stamp for auto clearing .get_bibs0 <- function(package, ..., cached_env) { if(is.null(package)) stop("argument 'package' must be provided") bibs <- allbibs[[package]] if(is.null(bibs)){ ## message(" bibs is NULL") bibs <- get_bibentries(package = package, ..., stop_on_error = FALSE) allbibs[[package]] <<- bibs } ## else ## message(" bibs is nonNULL") bibs } .get_all_bibs <- function() allbibs list(.get_bibs0 = .get_bibs0, .get_all_bibs = .get_all_bibs) }) ## TODO: auto-deduce 'package'? ## 2020-09-30: changing to cache bib as \insertCite does (new arg. cached_env, etc) insert_ref <- function(key, package = NULL, ..., cached_env = NULL) { # 2020-09-30: replaced by a single call # if(is.null(package)) # stop("argument 'package' must be provided") # # bibs <- get_bibentries(package = package, ..., stop_on_error = FALSE) # # TODO: this is for testing only! # message("\nkey is ", key) # if(is.null(cached_env)) # message(" cached_env is NULL") # else # message(" cached_env is nonNULL") bibs <- .bibs_cache$.get_bibs0(package, ..., cached_env = cached_env) if(length(bibs) == 0){ note <- paste0("\"Failed to insert reference with key = ", key, " from package = '", package, "'.", " Possible cause --- missing REFERENCES.bib in package '", package, "' or '", package, "' not installed.\"" ) note <- paste0("\\Sexpr[results=rd,stage=install]{{warning(", note, ");", note, "}} ") item <- bibentry( bibtype = "Misc", title = "Not avalable", author = person("A", "Adummy"), year = format(Sys.time(), "%Y"), note = note, key = key ) .toRd_styled(item, package) }else if(length(key) == 1){ item <- tryCatch(bibs[[key]], warning = function(c) { if(grepl("subscript out of bounds", c$message)){ ## tell the user the offending key. s <- paste0("possibly non-existing key '", key, "'") c$message <- paste0(c$message, " (", s, ")") } warning(c) # res <- paste0("\nWARNING: failed to insert reference '", key, # "' from package '", package, "' - ", # s, ".\n") # return(res) ## setup a dummy entry bibentry( bibtype = "Misc", title = "Not avalable", author = person("A", "Adummy"), year = format(Sys.time(), "%Y"), note = paste0("Failed to insert reference with key = ", key, " from package = '", package, "'.", " Possible cause --- missing or misspelled key." ), key = key ) }, ## 2024-08-04 ## R-devel c86938 recently changed the warning to error, ## for now, copying verbatim the function for handling the warning. error = function(c) { if(grepl("subscript out of bounds", c$message)){ ## tell the user the offending key. s <- paste0("possibly non-existing key '", key, "'") c$message <- paste0(c$message, " (", s, ")") } warning(c) # res <- paste0("\nWARNING: failed to insert reference '", key, # "' from package '", package, "' - ", # s, ".\n") # return(res) ## setup a dummy entry bibentry( bibtype = "Misc", title = "Not avalable", author = person("A", "Adummy"), year = format(Sys.time(), "%Y"), note = paste0("Failed to insert reference with key = ", key, " from package = '", package, "'.", " Possible cause --- missing or misspelled key." ), key = key ) } ) # # 2018-03-01 Bug: Unexpected END_OF_INPUT error (URL parsing?) #3 # # I don't know why toRd() doesn't do this... # # # # escape percents that are not preceded by backslash # # (`if' is because in case of error above, item will be simply a string) # # Commenting out since get_bibentries() does it. # if(inherits(item, "bibentry") && !is.null(item$url)) # item$url <- gsub("([^\\])%", "\\1\\\\%", item$url) # if(interactive()) browser() # wrk <- .toRd_styled(item, package) # TODO: add styles? (doesn't seem feasible here) # fn <- tempfile() # cat(wrk, file = fn) # res <- permissive_parse_Rd(fn) ## tools::parse_Rd(fn) # tools::toRd(res) # # wrk <- .toRd_styled(item, package) # Encoding(wrk) <- "bytes" # wrk # .toRd_styled(item, package) }else{ ## key is documented to be of length one, nevertheless handle it too kiki <- FALSE items <- withCallingHandlers(bibs[[key]], warning = function(w) {kiki <<- TRUE}) ## TODO: deal with URL's as above txt <- .toRd_styled(items, package) if(kiki){ # warning(s) in bibs[[key]] s <- paste0("WARNING: failed to insert ", "one or more of the following keys in REFERENCES.bib:\n", paste(key, collapse = ", \n"), ".") warning(s) txt <- c(txt, s) } paste0(paste(txt, collapse = "\n\n"), "\n") } } ## 2017-11-25 new ## see utils:::print.help_files_with_topic() viewRd <- function(infile, type = getOption("help_type"), stages = NULL){ infile <- normalizePath(infile) if(is.null(type)) type <- "text" else if(!is.character(type) || length(type) != 1) stop("'type' should be 'html' or 'text'") if(is.null(stages)) # stages <- c("install", "render") stages <- c("build", "install", "render") # stages <- c("build", "render") else if(!is.character(stages) || !all(stages %in% c("build", "install", "render"))) stop('stages must be a character vector containing one or more of the strings "build", "install", and "render"') pkgname <- basename(dirname(dirname(infile))) outfile <- tempfile(fileext = paste0(".", type)) ## 2020-05-19: added pkgdir to read also current package macros, see below pkgdir <- dirname(dirname(infile)) ## here we need to expand the Rd macros, so don't use permissive_parse_Rd() ## 2020-05-19: read also the macros from pkgdir, ## load those from Rdpack anyway, in case Rdpack is not in 'DESCRIPTION' yet ## TODO: could issue warning here but this could be intrusive here since ## the user may not need Rdpack for the current package. e <- tools::loadPkgRdMacros(system.file(package = "Rdpack")) e <- tools::loadPkgRdMacros(pkgdir, macros = e) ## finally load the Rd system macros (though I haven't noticed errors without this step). e <- tools::loadRdMacros(file.path(R.home("share"), "Rd", "macros", "system.Rd"), macros = e) ## check if mathjaxr is needed descpath <- file.path(pkgdir, "DESCRIPTION") need_mathjaxr <- if(file.exists(descpath)){ ## rdmac is NA if there is no RDMacros field in DESCRIPTION rdmac <- as.character(read.dcf(descpath, fields = "RdMacros")) grepl("mathjaxr", as.character(rdmac)) }else{ ## try installed package pkgdesc <- packageDescription(pkgname) !is.null(pkgdesc$RdMacros) && grepl("mathjaxr",pkgdesc$RdMacros) } ## this loads mathjax from CDN, so internet connection needed if(need_mathjaxr){ ## code borrowed from package "mathjaxr" mjcdn <- Sys.getenv("MATHJAXR_USECDN") on.exit(Sys.setenv(MATHJAXR_USECDN = mjcdn)) Sys.setenv(MATHJAXR_USECDN = "TRUE") } ## Rdo <- parse_Rd(infile, macros = e) ## can't do this (the file may be deleted before the browser opens it): ## on.exit(unlink(outfile)) switch(type, text = { temp <- tools::Rd2txt(infile, # was: Rdo, out = outfile, package = pkgname, stages = stages , macros = e) file.show(temp, delete.file = TRUE) # text file is deleted }, html = { temp <- tools::Rd2HTML(infile, # was: Rdo, out = outfile, package = pkgname, stages = stages , macros = e) browseURL(temp) ## html file is not deleted }, stop("'type' should be one of 'text' or 'html'") ) } ## temporary; not exported vigbib <- function(package, verbose = TRUE, ..., vig = NULL){ if(!is.null(vig)) return(makeVignetteReference(package, vig, ...)) vigs <- vignette(package = package) if(nrow(vigs$results) == 0){ if(verbose) cat("No vignettes found in package ", package, "\n") return(bibentry()) } wrk <- lapply(seq_len(nrow(vigs$results)), function(x) makeVignetteReference(package = package, vig = x, verbose = FALSE, ...) ) res <- do.call("c", wrk) if(verbose) print(res, style = "Bibtex") invisible(res) } makeVignetteReference <- function(package, vig = 1, verbose = TRUE, title, author, type = "pdf", bibtype = "Article", key = NULL ){ publisher <- NULL # todo: turn this into an argument some day ... if(missing(package)) stop("argument 'package' is missing with no default") cranname <- "CRAN" cran <- "https://CRAN.R-Project.org" cranpack <- paste0(cran, "/package=", package) ## todo: for now only cran if(is.null(publisher)){ publisher <- cran publishername <- cranname publisherpack <- cranpack } desc <- packageDescription(package) vigs <- vignette(package = package) if(is.character(vig)){ vig <- pmatch(vig, vigs$results[ , "Item"]) if(length(vig) == 1 && !is.na(vig)){ wrk <- vigs$results[vig, "Title"] }else stop(paste0( "'vig' must (partially) match one of:\n", paste0("\t", 1:nrow(vigs$results), " ", vigs$results[ , "Item"], "\n", collapse = "\n"), "Alternatively, 'vig' can be the index printed in front of the name above.")) }else if(1 <= vig && vig <= nrow(vigs$results)){ wrk <- vigs$results[vig, "Title"] }else{ stop("not ready yet, should return all vigs in the package.") } if(missing(author)) author <- desc$Author title <- gsub(" \\([^)]*\\)$", "", wrk) # drop ' (source, pdf)' item <- vigs$results[vig, "Item"] vigfile <- paste0(item, ".", type) journal <- paste0("URL ", publisherpack, ".", " Vignette included in R package ", package, ", version ", desc$Version ) if(is.null(desc$Date)){ # built-in packages do not have field "year" if(grepl("^Part of R", desc$License[1])){ ## title <- paste0(title, "(", desc$License, ")") publisherpack <- cran ## do not add package=... to https in this case journal <- paste0("URL ", publisherpack, ".", " Vignette included in R package ", package, " (", desc$License, ")" ) } year <- R.version$year }else year <- substring(desc$Date, 1, 4) # stop(paste0("argument 'vig' must be a charater string or an integer\n", # "between 1 and the number of vignettes in the package")) if(is.null(key)) key <- paste0("vig", package, ":", vigs$results[vig, "Item"]) res <- bibentry( key = key, bibtype = bibtype, title = title, author = author, journal = journal, year = year, ## note = "R package version 1.3-4", publisher = publishername, url = publisherpack ) if(verbose){ print(res, style = "Bibtex") cat("\n") } res } ## 2018-03-13 new ## 2023-08-19 TODO: this function was patched and its functionality extended via patches so ## many times that it needs consolidation. insert_citeOnly <- function(keys, package = NULL, before = NULL, after = NULL, bibpunct = NULL, ..., cached_env = NULL, cite_only = FALSE, dont_cite = FALSE) { ##print("kiki") if(!is.null(cached_env)){ if(is.null(cached_env$refsmat)) cached_env$refsmat <- matrix(character(0), nrow = 0, ncol = 2) ## if(is.null(cached_env$allbibs)) ## cached_env$allbibs <- list() } if(is.null(package)) stop("argument 'package' must be provided") if(length(keys) > 1) stop("`keys' must be a character string") if(!cite_only) cached_env$refsmat <- rbind(cached_env$refsmat, c(keys, package)) if(dont_cite) return(character(0)) nobrackets <- grepl(";nobrackets$", keys) # new 2022-02-05; related to issue #23 if(nobrackets) keys <- gsub(";nobrackets$", "", keys) textual <- grepl(";textual$", keys) if(textual) keys <- gsub(";textual$", "", keys) if(grepl("[^a-zA-Z.0-9]", package)){ delims <- gsub("[a-zA-Z.0-9]", "", package) ch <- substr(delims, 1, 1) wrk <- strsplit(package, ch, fixed = TRUE)[[1]] # note: [[1]] package <- wrk[1] if(length(wrk) > 1){ if(nchar(wrk[2]) > 1 || nchar(wrk[2]) == 1 && wrk[2] != " ") before <- wrk[2] if(length(wrk) > 2 && (nchar(wrk[3]) > 1 || nchar(wrk[3]) == 1 && wrk[3] != " ")) after <- wrk[3] } } # 2020-11-05 was: # # if(is.null(cached_env)){ # bibs <- get_bibentries(package = package, ..., stop_on_error = FALSE) # }else{ # bibs <- cached_env$allbibs[[package]] # if(is.null(bibs)){ # bibs <- get_bibentries(package = package, ..., stop_on_error = FALSE) # cached_env$allbibs[[package]] <- bibs # } # } # bibs <- .bibs_cache$.get_bibs0(package, ..., cached_env = cached_env) # This wouldn't work since roxygen2 will change it to citation # TODO: check # if(substr(keys, 1, 1) == "["){ # rmarkdown syntax (actually roxygen2?) # keys <- substr(keys, 2, nchar(keys) - 1) # drop "[" and the closing "]" # splitkeys <- strsplit(keys, ";", fixed = TRUE)[[1]] # note: [[1]] # # # # } refch <- "@" refchpat <- paste0("^[", refch, "]") if(grepl(refchpat, keys)){ ch <- substr(keys, 1, 1) # 'ch' is not used currently keys <- substr(keys, 2, nchar(keys)) # drop refch ## TODO: check if there are still @'s at this point refpat <- paste0("(", refch, "[^;,()[:space:]]+)") # "(@[^;,[:space:]]+)" refpat2 <- paste0( refch, "[^;,()[:space:]]+\\)") if(textual){ wrkkeys <- strsplit(keys, "@")[[1]] # note [[1]] !!! ## 2023-08-19 Note: ## ## The code until the assignment to 'keys' puts a ')' at the end of each key. ## presumably to designate the end of the key for gregexpr below. But these ')' ## need to be removed later. ## ## first process the last key - it is special, since there is none after it nk <- length(wrkkeys) wrkkeys[nk] <- if(grepl("[;,]$", wrkkeys[nk])) sub("([;,])$", ")\\1", wrkkeys[nk]) else if(grepl("[;,]", wrkkeys[nk])) sub("([;,][^;,]*)$", ")\\1" , wrkkeys[nk]) else paste0(wrkkeys[nk], ")") ## the 2nd element contains the first key even if the string starts with '@' ## (if that is the case the first string is "") if(nk > 2){ for(i in 2:(nk - 1)){ wrkkeys[i] <- if(grepl("([;,][^;,]*)$", wrkkeys[i])) sub("([;,][^;,]*)$", ")\\1" , wrkkeys[i]) else sub("^([^;,()[:space:]]+)", "\\1)" , wrkkeys[i]) } } keys <- paste0(wrkkeys, collapse = refch) } ## find the positions of the keys (used further below to replace them with the cites m <- gregexpr(refpat, keys) allkeys <- regmatches(keys, m)[[1]] # note: [[1]] allkeys <- gsub(refch, "", allkeys) if(textual){ bibpunct0 = c("(", ")", ";", "a", "", ",") if(!is.null(bibpunct)){ if(length(bibpunct) < length(bibpunct0)) bibpunct <- c(bibpunct, bibpunct0[-seq_len(length(bibpunct))]) ind <- which(is.na(bibpunct)) if(length(ind) > 0) bibpunct[ind] <- bibpunct0[ind] #cat("bibpunct is: ", bibpunct, "\n") }else bibpunct <- bibpunct0 }else{ ## for now ignore bibpunct in this case bibpunct <- c("", "", ";", "a", "", ",") } refs <- sapply(allkeys, function(key) safe_cite(key, bibs, textual = textual, bibpunct = bibpunct, from.package = package) ) if(textual){ ## 2023-08-19 Note: need to drop the ')' added above. The commented out solution ## below drop the last symbol in the prepared cites instead, which is ## equivalent but only if bibpunct is missing or specifies ')' as closing for ## the likes of Boshnakov (2020). The new solution matches again with a ## pattern including the ')' at the end of the key, so that ')' gets replaced ## along with the key. ## was: refs <- sapply(refs, function(s) substr(s, 1, nchar(s) - 1)) m <- gregexpr(refpat2, keys) } ## replace keys with citations text <- keys regmatches(text, m) <- list(refs) ## parentheses around the whole cite; 2022-02-05: also if !nobrackets if(!textual && !nobrackets) # 2018-03-28 don't put parentheses in textual mode text <- paste0("(", text, ")") }else{ if(is.null(bibpunct)){ if(!textual && nobrackets) # 2022-02-05 bibpunct0 = c("", "", ";", "a", "", ",") else bibpunct0 = c("(", ")", ";", "a", "", ",") text <- safe_cite(keys, bibs, textual = textual, before = before, after = after, bibpunct = bibpunct0, from.package = package) }else{ bibpunct0 = c("(", ")", ";", "a", "", ",") if(length(bibpunct) < length(bibpunct0)) bibpunct <- c(bibpunct, bibpunct0[-seq_len(length(bibpunct))]) ind <- which(is.na(bibpunct)) if(length(ind) > 0) bibpunct[ind] <- bibpunct0[ind] text <- safe_cite(keys, bibs, textual = textual, before = before, after = after, bibpunct = bibpunct, from.package = package) } } ## 2022-06-05: was: toRd(text) ## workaround for issue #25; effectively assumes that citation text ## doesn't contain braces that need escaping .toRd_cite(text) } ## modified tools:::toRd.default .toRd_cite <- function (obj, ...) { fsub <- function(from, to, x) gsub(from, to, x, fixed = TRUE) fsub("%", "\\%", # fsub("}", "\\}", # fsub("{", "\\{", fsub("\\", "\\\\", as.character(obj))) # )) } safe_cite <- function(keys, bib, ..., from.package = NULL){ wrk.keys <- unlist(strsplit(keys, ",")) if(!all(wrk.keys %in% names(bib))){ ok <- wrk.keys %in% names(bib) miss.keys <- wrk.keys[!ok] warning("possibly non-existing or duplicated key(s)", if(!is.null(from.package)) paste0(" in bib file from package '", from.package, "'"), ":\n ", paste(miss.keys, sep = ", "), "\n") keys <- wrk.keys[ok] } # 2018-06-02 was: cite(keys = keys, bib = bib, ...) cite(keys = keys, bib = bib, longnamesfirst = FALSE, ...) } insert_all_ref <- function(refs, style = "", empty_cited = FALSE){ if(is.environment(refs)){ refsmat <- refs$refsmat allbibs <- .bibs_cache$.get_all_bibs() # 2020-11-05 was: refs$allbibs if(is.null(allbibs)) ## TODO: this can be removed, since .get_all_bibs() allbibs <- list() ## returns an initialised list() }else{ refsmat <- refs allbibs <- list() } if(is.null(refs) || is.null(refsmat) || nrow(refsmat) == 0) ## Returning the empty string is probably preferable but 'R CMD check' does not see ## that the references are empty in this case (although the help system see this and ## drops the section "references". To avoid confusing the user, print some ## informative text. return("There are no references for Rd macro \\verb{\\insertAllCites} on this help page.") all.keys <- list() for(i in 1:nrow(refsmat)){ keys <- refsmat[i, 1] nobrackets <- grepl(";nobrackets$", keys) # new 2022-02-05; related to issue #23 if(nobrackets) keys <- gsub(";nobrackets$", "", keys) textual <- grepl(";textual$", keys) if(any(textual)) keys <- gsub(";textual", "", keys) refch <- "@" refchpat <- paste0("^[", refch, "]") if(grepl(refchpat, keys)){ ch <- substr(keys, 1, 1) keys <- substr(keys, 2, nchar(keys)) # drop refch refpat <- paste0("(", refch, "[^;,[:space:]]+)") # "(@[^;,[:space:]]+)" m <- gregexpr(refpat, keys) keys <- regmatches(keys, m)[[1]] # note: [[1]] keys <- gsub("@", "", keys) }else{ keys <- unlist(strsplit(keys, ",")) } package <- refsmat[i, 2] if(is.null(all.keys[[package]])) all.keys[[package]] <- keys else all.keys[[package]] <- c(all.keys[[package]], keys) } bibs <- NULL for(package in names(all.keys)){ cur <- unique(all.keys[[package]]) be <- allbibs[[package]] if(is.null(be)) be <- get_bibentries(package = package, stop_on_error = FALSE) if(length(be) == 0){ be <- bibentry( bibtype = "Misc", title = "Not avalable", author = person("A", "Adummy"), year = format(Sys.time(), "%Y"), note = paste0("Failed to insert reference with keys = \n ", paste0(cur, collapse = " "), "\n", "from package = '", package, "'.", " Possible cause --- missing REFERENCES.bib in package '", package, "' or '", package, "' not installed." ), key = paste0(cur, collapse = ":") ) }else if(all(cur != "*")){ be <- tryCatch( be[cur], warning = function(c) { if(grepl("subscript out of bounds", c$message)){ ## tell the user the offending keys. c$message <- paste0(c$message, " (", paste(cur, collapse = " "), "' from package '", package, "'", ")" ) } warning(c) ## setup a dummy entry dummy <- bibentry( bibtype = "Misc", title = paste0("Some keys from package ", package, " are not avalable"), author = person("A", "Adummy"), year = format(Sys.time(), "%Y"), note = paste0("Failed to insert reference with keys:\n ", paste0(cur, collapse = ", "), "\n", "from package = '", package, "'.", " Possible cause - missing REFERENCES.bib in package '", package, "' or '", package, "' not installed." ), key = paste0(cur, collapse = ":") ) c(be[cur], dummy) }) } if(is.null(bibs)) bibs <- be else bibs <- c(bibs, be) # TODO: duplicate keys in different packages? } # 2025-11-11 was: sort(bibs, .bibstyle = "Rdpack") bibs <- sort(bibs, .bibstyle = Rdpack_bibstyles("")) # 2021-04-24 was: sort(bibs) pkgs <- names(all.keys) # \Sexpr[stage=build,results=hide]{requireNamespace("cvar")} # 2016-06-02 was: # if(length(pkgs) > 0){ # pkg <- pkgs[1] ## TODO: for now should do # if(!isNamespaceLoaded(pkg) && !requireNamespace(pkg) ) # sty <- NULL # else{ # sty <- Rdpack_bibstyles(pkg) # } # }else # sty <- NULL # # if(!is.null(sty)) # res <- sapply(bibs, function(x) tools::toRd(x, style = "JSSLongNames")) # else { # if(style == "") # res <- sapply(bibs, function(x) tools::toRd(x)) # else{ # res <- sapply(bibs, function(x) tools::toRd(x, style = "JSSLongNames")) # } # } pkg <- if(length(pkgs) > 0) ## TODO: for now should do pkgs[1] else character(0) res <- .toRd_styled(bibs, pkg) # 2018-10-01 use \par since pkgdown ignores the empty lines # TODO: needs further thought # was: # (for now restoring the old one, to check if pkgdown would consider this as a bug) if(empty_cited) refs$refsmat <- matrix(character(0), nrow = 0, ncol = 2) # paste0(res, collapse = "\n\n") paste0(res, collapse = "\\cr\\cr ") } `%notin%` <- function(x, y) is.na(match(x, y)) ## based on ## tools::deparseLatex() in /home/georgi/svn/r-devel/R/src/library/tools/R/parseLatex.R ## original by Sebastian Meyer and Duncan Murdoc. ## ## Below is a version suitable for Rdpack. ## for now drop the new argument 'math' since deparseLatexToRd is specifically for conversion to Rd, ## while deparseLatex is more general ## was: deparseLatex <- function(x, dropBraces = FALSE, math = c("$", "$")) ## eventually my modification should become unnecessary. deparseLatexToRd <- function(x, dropBraces = FALSE) { # stopifnot(length(math) == 2, is.character(math)) specials <- c("\\", "#", "$", "%", "&", "~", "_", "^", "{", "}") result <- character() lastTag <- "TEXT" expectArg <- FALSE for (i in seq_along(x)) { a <- x[[i]] tag <- attr(a, "latex_tag") if (is.null(tag)) tag <- "NULL" result <- c(result, switch(tag, TEXT = c(if (lastTag == "MACRO" && expectArg && grepl("^[[:alpha:]]", a)) ## restore space that the parser has eaten ('\item text') " ", a), MACRO = { ## TODO: R-4.5.2 \& and similar are now taken care of, no need to do it here. ## Check from which version on of R this is true. Maybe will need to have here ## conditional versions for of the function for 'before' and 'after' ## ## NOTE: No, it is only \& that R-4.5.2 takes care of, the rest still raise warnings. ## So, can't omit the check here. ## ## see issue #26 ## regex in r-devel/R/src/library/tools/R/RdConv2.R: ## pat <- "([^\\]|^)\\\\[#$&_^~]" ## here we add grouping for substitution ## pat <- "([^\\]|^)(\\\\)([#$&_^~])" # with more grouping if(grepl(pat, a)){ a <- gsub(pat, "\\1\\3", a) } c(if (lastTag == "MACRO" && expectArg && grepl("^[[:alpha:]]", a)) ## restore space that the parser has eaten ('\item text') " ", a) }, BLOCK = if (dropBraces && !expectArg) Recall(a) else c("{", Recall(a), "}"), VERB = , COMMENT = a, ENVIRONMENT = c( "\\begin{", a[[1L]], "}", Recall(a[[2L]]), "\\end{", a[[1L]], "}"), # enclose maths in \eqn{...}, not $ ... $; # \( and \) parse as MACRO # was: MATH = c(math[1L], Recall(a), math[2L]), MATH = c("\\eqn{", Recall(a), "}"), # #DISPLAYMATH and DEFINITION: new in R-4.5.2? or earlier? DISPLAYMATH = c("\\deqn{", Recall(a), "}"), # was: DISPLAYMATH = c("$$", Recall(a), "$$"), DEFINITION = Recall(a), NULL = stop("Internal error, no tag", domain = NA) )) lastTag <- tag expectArg <- if (tag == "MACRO") a %notin% paste0("\\", c(specials, "(", ")")) else expectArg && tag %in% c("BLOCK", "COMMENT") # \cmd{}{}, \cmd% ## currently ignoring \cmd {}, \cmd[]{}, \cmd*{} } paste(result, collapse="") } Rdpack_bibstyles <- local({ styles <- list() exists_JSSRd <- FALSE exists_JSSLongNames <- FALSE function(package, authors){ if((n <- nargs()) > 1){ styles[[package]] <<- authors }else if(n == 1){ if(length(package) == 0 || is.null(styles[[package]]) || package == "" || # 2025-11-11 new TODO: document (!isNamespaceLoaded(package) && !requireNamespace(package))) { if(!exists_JSSRd) { bibstyle_JSSRd() exists_JSSRd <<- TRUE } "JSSRd" }else{ if(!exists_JSSLongNames) { bibstyle_JSSLongNames() exists_JSSLongNames <<- TRUE } "JSSLongNames" } } else styles } }) # was: function(bibs, package, style = "") .toRd_styled <- function(bibs, package){ sty <- Rdpack_bibstyles(package) f <- function(x){ if(!is.null(x$doi) && !is.null(x$url) && grepl("https?://doi.org/", x$url)) x$url <- NULL tools::toRd(x, style = sty) } res <- sapply(bibs, f) res } bibstyle_JSSRd <- function(style = "JSSRd", reset = FALSE, make_default = FALSE){ ## check if 'style' is registered; if so, return it unless reset is TRUE env_style <- tools::bibstyle(style, .default = make_default) if(!is.null(env_style) && !reset) return(env_style) ## we need a separate clone of env_style here, so reset = TRUE env_style <- bibstyle_JSSextra(style, reset = TRUE) ## deparseLatexToRd lives in the namespace of Rdpack, so use assign assign("deparseLatexToRd", deparseLatexToRd, envir = env_style) ## for functions that need to see objects in the environment of the bibstyle ## 'with' is convenient (though not the only was or even the preferred one. with(env_style, { ## Clean up LaTeX accents and braces ## this is a copy of unexported tools:::cleanupLatex by Duncan Murdoch. ## but it calls deparseLatexToRd in place of deparseLatex cleanupLatex <- function(x) { if (!length(x)) return(x) latex <- tryCatch(tools::parseLatex(x), error = function(e)e) if (inherits(latex, "error")) { x } else { deparseLatexToRd(tools::latexToUtf8(latex), dropBraces=TRUE) } } }) env_style } ## This adds to and/or modifies some functions in the environment created by ## tools::bibstyle (R Core Team [cph]) bibstyle_JSSLongNames <- function(style = "JSSLongNames", reset = FALSE, make_default = FALSE){ ## check if 'style' is registered; if so, return it unless reset is TRUE env_style <- tools::bibstyle(style, .default = make_default) if(!is.null(env_style) && !reset) return(env_style) ## we need a separate clone of JSSRd here, so reset = TRUE env_style <- bibstyle_JSSRd(style, reset = TRUE) with(env_style, { shortName = function(person) { paste(paste(cleanupLatex(person$given), collapse=" "), cleanupLatex(person$family), sep = " ") } }) env_style } .onLoad <- function(lib, pkg){ ## define the styles but not set any of them as default ## bibstyle_JSSRd() ## bibstyle_JSSLongNames() ## set "LongNames" style for this package (Rdpack) Rdpack_bibstyles(package = pkg, authors = "LongNames") invisible(NULL) } Rdpack/R/manip.R0000644000176200001440000003215615102212001013075 0ustar liggesusers## Do not edit this file manually. ## It has been automatically generated from *.org sources. # generic rdo manipulation functions append_to_Rd_list <- function(rdo, x, pos){ # pos is a numeric vector rdo[[pos]] <- structure( c(rdo[[pos]], x), Rd_tag = attr(rdo[[pos]],"Rd_tag") ) rdo } # todo: allow vector `pos' to insert deeper into the object # todo: character `pos' to insert at a position specified by "tag" for example? Rdo_insert_element <- function(rdo, val, pos){ n <- length(rdo) if(missing(pos)) pos <- n+1 stopifnot(1 <= pos, pos <= n+1) res <- if(pos==1) c(list(val), rdo) else if(pos==n+1) c(rdo, list(val)) else c( rdo[1:(pos-1)], list(val), rdo[pos:n]) attributes(res) <- attributes(rdo) # todo: more guarded copying of attributes? res } Rdo_get_insert_pos <- function(rdo, tag){ tags <- Rdo_tags(rdo) pos <- which(tags == tag) pos <- if(length(pos)>0) max(pos) + 1 # put after the last occurence of the same section else if(tag %in% .rd_sections){ indx <- which(.rd_sections == tag) iafter <- which( tags %in% .rd_sections[-seq_len(indx)] ) iafter[1] # put in front of the next section in .rd_sections }else{ # otherwise put at the end of rdo length(rdo)+1 } pos } Rdo_insert <- function(rdo, val, newline = TRUE){ tag <- attr(val,"Rd_tag") if(is.null(tag)) stop("val has no Rd_tag attribute.") pos <- Rdo_get_insert_pos(rdo, tag) # 2013-03-29 - additional check for pos # todo: this is incomplete! if(newline && ( (length(pos) == 1 && pos <= length(rdo) && !Rdo_is_newline(rdo[[pos]])) || (length(pos) == 1 && pos > length(rdo)) || length(pos) > 1 # todo: this is incomplete ) ) rdo <- Rdo_insert_element(rdo, Rdo_newline(), pos) rdo <- Rdo_insert_element(rdo, val, pos) if(newline && pos > 1 && !Rdo_is_newline(rdo[[pos-1]])) rdo <- Rdo_insert_element(rdo, Rdo_newline(), pos) rdo } # this is not specific to "sections", any Rd_tag in 'val' will do Rdo_modify <- function(rdo, val, create=FALSE, replace=FALSE, top = TRUE){ sec <- attr(val,"Rd_tag") if(is.null(sec)) stop("val has no Rd_tag attribute.") rdotag <- attr(rdo,"Rd_tag") if(top && !is.null(rdotag) && rdotag == sec){ # rdo is the section `sec'; if(replace) # todo: character 'replace' not handled yet. # append to the end return(val) else{ rdo <- append_to_Rd_list( list(rdo), val, 1) return( rdo[[1]] ) } } pos <- Rdo_which_tag_eq(rdo, sec) if(length(pos)>0){ if(is.character(replace)){ # the value to replace goodpos <- sapply(pos, # todo: the check below is simplistic function(x){ locval <- rdo[[x]] is.list(locval) && length(locval) == 1 && locval[[1]] == replace }) goodpos <- pos[goodpos] if(length(goodpos) > 0) rdo[[ goodpos[1] ]] <- val else if(create) rdo <- Rdo_insert(rdo, val) }else if(replace) rdo[[ pos[1] ]] <- val # pos[1] in case there are more else rdo <- append_to_Rd_list(rdo, val, pos[1]) }else if(create) # argument section not present, create one rdo <- Rdo_insert(rdo, val) # rdo[[ length(rdo)+1 ]] <- val else stop("No section ", sec, " to replace or modify.") rdo } ## The 'locate_' family of functions finds (recursively) positions of elements of rdo objects. ## A position is a vector suitable for use in '[[' or a list of such vectors. # find the index the element enclosing rdo[[ind]] that has Rd_tag 'tag'. # (e.g. if rdo[[ind]] is an '\item', we may wish to grab the enclosing '\describe'.) .locate_enclosing_tag <- function(rdo, ind, tag, baseind = numeric(0), mindepth=0){ repeat{ fullind <- c(baseind,ind) rdtag <- if(length(fullind) > 0) attr(rdo[[fullind]], "Rd_tag") else attr(rdo , "Rd_tag") if(is.character(rdtag) && rdtag == tag) return(ind) else if(length(ind)==mindepth) return(as.numeric(NA)) ind <- head(ind,-1) # drop the last level } } ## The '_top_' family of functions look only at the top level of rdo, in the sense that they ## examine the elements of rdo at the top level and do not search recursively its structure. ## Some of these functions examine also rdo as a whole (todo: maybe all of them should do ## this for consistency). .locate_top_tag <- function(rdo, sec, tag = "\\describe"){ if(sec == ""){ # search at top level of rdo indx1 <- integer(0) }else{ indx1 <- .locate_sec_content(rdo, sec) if(sec %in% c("\\arguments", "\\value")) # these sections are themselves lists return(indx1) rdo <- rdo[[indx1]] } indx3 <- Rdo_which_tag_eq(rdo, tag) if(length(indx3)==0) return(integer(0)) indx3 <- indx3[[1]] # playing safe, in case more than one c(indx1,indx3) # todo: option to return a list of all matches? } .locate_top_items <- function(rdo, sec, labels=FALSE){ indx1 <- .locate_top_tag(rdo, sec) if(length(indx1) == 0) return(list()) indx2 <- Rdo_which_tag_eq(rdo[[indx1]], "\\item") res <- lapply( indx2, function(x) c(indx1, x)) # returns a list of positions # todo: item labels (i.e., the 1st arg. of \item) may be long, is this a problem? if(isTRUE(labels) || is.character(labels)) # set names attribute if requested names(res) <- sapply(res, function(x) .get_item_label(rdo,x) ) if(is.character(labels)) # take only the requested items res <- res[labels] res } .nl_and_indent <- function(rdo, newlines = TRUE, indent = " "){ nl <- Rdo_newline() tab <- indent # todo: allow it to be dropped wrk <- lapply(rdo, function(x) list(nl, tab, x) ) res <- do.call("c", wrk) # todo: is this the correct arrangement - ne, gubi Rd_tag attr(res, "Rd_tag") <- attr(rdo, "Rd_tag") # 2012-10-16 todo: "Rd" attribute? - use c_Rd? res } .get_subset <- function(rdo, pos, rdtag = FALSE, keep.class = FALSE, newlines = FALSE){ if(newlines){ nl <- Rdo_newline() wrk <- lapply(pos, function(x) list(nl, rdo[[x]]) ) res <- do.call("c", wrk) # todo: check if this is the correct arrangement }else res <- lapply(pos, function(x) rdo[[x]]) if(isTRUE(rdtag)) attr(res, "Rd_tag") <- attr(rdo, "Rd_tag") else if(is.character(rdtag)) attr(res, "Rd_tag") <- rdtag if(keep.class) class(res) <- class(rdo) res } .get_item_label <- function(rdo, pos){ # 2013-12-01 no need of looking for leaves after introducing .ascharRd() # indx <- c(pos, .locate_item_label(rdo, pos)) # res <- rdo[[indx]] indx <- c(pos, 1) res <- .ascharRd(rdo[[indx]]) res } # 'labels' is a logical or a character vector of labels .get_top_items <- function(rdo, sec, labels){ # e.g. sec = "Slots", "arguments" itemind <- .locate_top_items(rdo, sec, labels=labels) lapply(itemind, function(x) rdo[[ x ]] ) # see also .get_subset() } .get_top_labels <- function(rdo, sec){ indx <- .locate_top_items(rdo, sec) sapply(indx, function(x) .get_item_label(rdo,x)) } # manipulation of specific sections # todo: this is very similar to parse_Rdname # 2012-11-04 partly done, introduced function .parse_long_name() .get.name_content <- function(rdo){ # todo: error processing Rd section \name name <- rdo[[ Rdo_which_tag_eq(rdo, "\\name") ]] # 2012-11-04 # dropping "-methods" or similar, if present # short <- gsub("^([^-]+)-.*", "\\1", name) short <- .parse_long_name(name)["name"] c(name = name, short = short) } # Rd section \arguments Rdo_append_argument <- function(rdo, argname, description = NA, indent = " ", create=FALSE){ if(is.na(description)) description <- "~~ TODO: describe this argument. ~~" if(length(description) == 1 && length(argname) > 1) description <- rep(description, length(argname)) wrk1 <- lapply(1:length(argname), function(i) list(indent, Rdo_item(argname[i], description[i]), Rdo_newline()) ) wrk <- Rdo_macro( do.call("c", wrk1), "\\arguments") Rdo_modify(rdo, wrk, create=TRUE) } # Rd section \usage # todo: get_usage_text can be generalised to any Rd section but it is better to use a # different approach since 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. # get_usage_text("../gbRd/man/Rd_title.Rd") get_usage_text <- function(rdo){ # ut <- get_usage_text("../gbRd/man/Rd_fun.Rd") if(is.character(rdo) && length(rdo)==1) rdo <- permissive_parse_Rd(rdo) # Alternatives: pos <- .locate_sec_content(rdo, "\\usage") # wrk <- Rdo_section(rdo, "\\usage") # wrk <- tools:::.Rd_get_section(rdo, "usage") # todo: maybe the following 3 lines would be more generally useful? #2012-10-04 drop comments and specials rdo_u <- toolsdotdotdot.Rd_drop_nodes_with_tags(rdo[[pos]], c("COMMENT","\\special")) wrk <- structure(rdo_u, Rd_tag = "Rd") class(wrk) <- "Rd" paste(capture.output(print(wrk)), collapse="\n") } Rdo_show <- function(rdo){ # 2012-09-22 renamed, was Rd_show outfile <- tempfile(fileext = ".txt") file.show(Rd2txt(rdo, outfile)) unlink(outfile) invisible(NULL) } Rdo_reparse <- function(rdo){ outfile <- tempfile(fileext = "Rd") Rdo2Rdf(rdo, file = outfile) rdo <- permissive_parse_Rd(outfile) unlink(outfile) rdo } Rdo_collect_aliases <- function(rdo){ pos <- Rdo_locate(rdo, function(x) .tag_eq(x,"\\alias"), lists=TRUE) res <- sapply(pos, function(x) as.character(rdo[[ x ]])) nams <- sapply(pos, function(x){ if( length(x) == 1) "" else # 2012-10-13 as.character(rdo[[ c(x[1:(length(x)-2)],1) ]]) as.character(rdo[[ c(x[seq_len(length(x)-2)],1) ]]) }) names(res) <- gsub("[ \n]" , "", nams) res } # 2013-12-02 derived from Rdo_collect_aliases() Rdo_collect_metadata <- function(rdo, sec){ #sec is "alias", "keyword" or similar simple one secname <- paste0("\\", sec) pos <- Rdo_locate(rdo, function(x) .tag_eq(x, secname), lists=TRUE) res <- sapply(pos, function(x) as.character(rdo[[ x ]])) nams <- sapply(pos, function(x){ if( length(x) == 1) "" else # 2012-10-13 as.character(rdo[[ c(x[1:(length(x)-2)],1) ]]) as.character(rdo[[ c(x[seq_len(length(x)-2)],1) ]]) }) names(res) <- gsub("[ \n]" , "", nams) res } Rdo_fetch <- function(Rd_name = character(0), package, dir = ".", installed = TRUE){ db <- if(missing(package)){ tools::Rd_db(dir = dir) }else{ if(installed) # use lib.loc to avoid highjacking by devtools tools::Rd_db(package, lib.loc = .libPaths()) else{ # d <- find.package(package) if(dir.exists(file.path(d, "man"))) # in source directory tools::Rd_db(dir = d) else # installation directory tools::Rd_db(package) } } if(length(Rd_name) == 1) db[[paste0(Rd_name, ".Rd")]] else if(length(Rd_name) == 0) db else db[paste0(Rd_name, ".Rd")] } Rdpack/R/usage.R0000644000176200001440000004642615102212001013102 0ustar liggesusersinspect_usage <- function(rdo){ ut <- get_usage_text(rdo) if(grepl("=[ ]*[,)]", ut)){ # TODO: this is a patch; should be sorted out properly! cat("Encountered formal arguments in the form 'arg ='\n") cat("\twithout righ-hand side, dropping the equal sign to proceed.\n") ut <- gsub("=[ ]*([,)])", "\\1", ut) } urdo <- parse_usage_text(ut) ucur <- lapply(seq_along(urdo), function(x) get_usage(name = urdo[[x]]$name, S3class = urdo[[x]]$S3class, S4sig = urdo[[x]]$S4sig, infix = urdo[[x]]$infix, fu = urdo[[x]]$fu, out.format="list")) mapply(compare_usage1, urdo, ucur, SIMPLIFY=FALSE)# ucur is of the same length as urdo but } # it may contain NULLs in some positions inspect_args <- function(rdo, i_usage){ argnames_rdo <- Rdo_get_argument_names(rdo) # TODO: this is for testing! # stopifnot(all( tools:::.Rd_get_argument_names(rdo) == # Rdo_get_argument_names(rdo) )) if(missing(i_usage)) i_usage <- inspect_usage(rdo) argnames_cur <- unique(unlist(lapply(i_usage, function(x) attr(x,"details")$cur_usage$argnames))) ## 2018-01-31 in case argnames_cur is NULL, ## since sort used on NULL inside identical() gives warning. if(length(argnames_cur) == 0) argnames_cur <- character(0) structure(identical(sort(argnames_rdo), sort(argnames_cur)), details = list( rdo_argnames = argnames_rdo , cur_argnames = argnames_cur , added_argnames = argnames_cur[!(argnames_cur %in% argnames_rdo)] , removed_argnames = argnames_rdo[!(argnames_rdo %in% argnames_cur)] )) } # new 2012-09-22 parse_text <- function(text, ..., keep = TRUE){ # see comments in parse_usage_text ks <- options("keep.source") if(identical(keep, ks)){ # comment on 2014-03-28 : this condition will never be TRUE # since ks is named! res <- parse(text=text, ...) }else{ options(keep.source = keep) res <- parse(text=text, ...) options(ks) # restore previous value } res } parse_usage_text <- function(text){ text <- gsub("\\\\dots", "...", text) # deal with \dots # deal with \method and \S3method macros for desciption of S3 methods. text <- gsub("\\\\(S3)?method\\{([^}]*)\\}\\{([^}]*)\\}", "S3_usage(\\2,\\3)", text) # todo: tova sa krapki za S3 metodi. Need to pass # syntactically correct text to parse below. text <- gsub("S3_usage\\((\\[+),", "S3_usage(`\\1`,", text) # [, [[ text <- gsub("S3_usage\\((\\$+),", "S3_usage(`\\1`,", text) # $ if(any(grepl("S3_usage\\([^,]*,function[ ]*\\)", text))){ # 2012-10-12 dobavyam "any" fun_flag <- TRUE text <- gsub("(S3_usage\\([^,]*,)function[ ]*\\)", "\\1fufufu_function)", text) }else fun_flag <- FALSE # deal with \S4method macro text <- gsub("\\\\S4method\\{([^}]*)\\}\\{([^}]*)\\}", "S4_usage(\\1,\\2)", text) # parse_text ensures that the srcref attribute will be set. # parse() normally does that but 'R CMD check' for example sets tmp <- parse_text(text) # keep.source to FALSE, leading to errors in the examples. # todo: check for errors after parse() # a character vector with one element for each usage expression in text usages <- sapply(attr(tmp, "srcref"), function(x) paste(as.character(x), sep="\n", collapse="\n")) if(fun_flag) usages <- gsub("fufufu_function", "function", usages) lapply(usages, parse_1usage_text) } # TODO: x %% y i podobni tyabva da se opravyat! vzh Arithmetic.Rd ot base parse_1usage_text <- function(text){ # modify usage texts to become function bodies embedded in calls to formals() f <- function(x) paste0(sub("^[^(]+\\(", "formals(function(", x), " NULL )") fu <- TRUE # in most cases we are dealing with functions if(grepl("^[[:alpha:]._][[:alnum:]._]*$", text)){ # a variable, not function call fu <- FALSE name <- text S3class <- "" S4sig = "" infix <- FALSE res <- NULL }else if(grepl("^S3_usage",text)){ S3class <- gsub("[^,]*,([^)]*)\\).*", "\\1", text) # patch, undo the quotes maybe put by parse_usage_text text <- gsub("S3_usage\\([`\"']([^,`]+)[`\"']", "S3_usage(\\1", text) name <- gsub("[^(]*\\(([^,]*),.*", "\\1", text) if(grepl("S3_usage\\(.*\\)[ ]* <-[ ]*value[ ]*$", text)){ # S3 assignment method text <- gsub("(S3_usage\\()([^,]*)(.*)\\)[ ]* <-[ ]*value[ ]*$", "\\1`\\2<-`\\3,value)", text) name <- paste0(name, "<-") }else if(!grepl("^[[:alpha:]._:][[:alnum:]._:]+$", name)){ # non-syntactic name text <- gsub("S3_usage\\(([^,]*,)", "S3_usage(`\\1`,", text) } text <- gsub("[^)]*\\)(.*)", paste(name, ".", S3class, "\\1", sep=""), text) S4sig = "" infix <- FALSE wrk <- f(text) res <- eval(parse(text = wrk)) }else if(grepl("^S4_usage",text)){ name <- gsub("[^(]*\\(([^,]*),.*", "\\1", text) # same as for S3 name above S3class <- "" #browser() # similar to S3 but there may be commas in the signature, so change accordingly if(grepl("S4_usage\\(.*\\)[ ]* <-[ ]*value[ ]*$", text)){ # S4 assignment method text <- gsub("(S4_usage\\()([^,]*)(.*)\\)[ ]* <-[ ]*value[ ]*$", "\\1`\\2<-`\\3,value)", text) if(grepl("\\([ ]*,[ ]*value", text)) # patch for 0 arguments in the current signature text <- sub("\\([ ]*,[ ]*value", "(dummyvar, value", text) name <- paste0(name, "<-") }# TODO: non-syntactic names? S4sig <- gsub("[^,]*,([^)]*)\\).*", "\\1", text) # same as for S3class above # but S4 signatures may have more than 1 element, # make a character vector from the single string s <- paste("names(formals(function(", S4sig, ") NULL))", sep="") S4sig <- eval(parse(text = s)) text <- gsub("[^)]*\\)(.*)", paste0(name, "\\1"), text) infix <- FALSE wrk <- f(text) res <- eval(parse(text = wrk)) }else{ # extract the function names from `usages' S3class <- "" S4sig = "" e <- parse(text = text) name <- as.character(e[[1]][[1]]) # !grepl( paste0("^",name)) - s regexp tryabva da se vnimava # ponezhe ako name e "+", tova e drugo. # ne mozhe i fixed = TRUE, ponezhe iskam da match-na ot nachaloto infix <- !(substr(text,1,nchar(name)) == name) ec <- lapply(1:length(e[[1]]), function(x) as.character(e[[1]][[x]])) res <- NULL if(name == "<-"){ # todo: more care needed here e2 <- e[[1]][[2]] if(is.call(e2)){ e2_named <- .make_named(e2) name <- paste0(e2[[1]], "<-") wrk <- paste0("formals(function(", paste(e2_named[-1], collapse=","), ",", e[[1]][[3]], # rhs (i.e., value) should have 1 elem only ") NULL )" ) }else{ # simple assignment (todo: can it be anything else here?) wrk <- paste0("formals(function(", paste(ec[-1], collapse=","), ") NULL )" ) } }else if(name == "!"){ wrk <- sub("!", "", text) wrk <- paste0("formals(function(", wrk, ") NULL)") }else if(name == ":"){ wrk <- "formals(function(from,to) NULL)" }else if(name %in% c("if", "for", "while", "repeat", "break", "next")){ # control res <- as.character(sapply(e[[1]], identity)) }else if(infix){ e <- parse(text = paste0("quote(",text,")")) ec <- .make_named(lapply(e[[1]][[2]], identity)) wrk <- paste0("formals(function(", paste(ec[-1], collapse=","), ") NULL )" ) }else{ wrk <- f(text) } if(is.null(res)) res <- eval(parse(text = wrk)) } pairlist2f_usage1(res, name, S3class, S4sig, infix, fu) # convert pairlists obtained from } # `formals()' into named "f_usage" objects. .make_named <- function(v, sep = " = "){ if(length(v) == 0) return(character(0)) nams <- allNames(v) wrk <- sapply(seq_along(v), function(x) if(nams[x]=="") paste(v[x]) else paste(nams[x], v[x], sep=sep)) wrk } # generate f_usage object for a function (needs clean up) # todo: argument `...' not used? get_usage <- function(object, name = NULL, force.function = FALSE, ..., S3class = "", S4sig = "", infix = FALSE, fu = TRUE, out.format = "text"){ if (missing(name)) # based on a chunk from utils::prompt if (is.character(object)){ name <- object object <- NULL }else { name <- substitute(object) if (is.name(name)) name <- as.character(name) else if (is.call(name) && (as.character(name[[1L]]) %in% c("::", ":::", "getAnywhere"))) { name <- as.character(name) name <- name[length(name)] } else stop("cannot determine a usable name") } # get(name, envir = asNamespace("mixAR")) # do.call(getAnywhere,list(x)) x <- if(!missing(object) && !is.null(object)) object else if(!fu){ x0 <- try(get(name), silent=TRUE) if(inherits(x0,"try-error")){ spec_values <- c("NULL", "TRUE", "FALSE", "NA", sapply(c(Inf, NaN, -Inf), as.character)) if(name %in% spec_values) x0 <- spec_values[ name == spec_values ][1] else x0 <- NULL } "OK: variable" # this value is not used further, it must not be NULL though }else if(!identical(S3class, "")){ # 2012-10-16 dobavyam getAnywhere, etc. x0 <- try(getS3method(name, S3class), silent=TRUE) if(inherits(x0,"try-error")){ x0 <- do.call(getAnywhere, list(paste0(name, ".", S3class))) if(length(x0$objs) > 0) x0$objs[[1]] else NULL }else x0 }else if(!identical(S4sig, "")) # todo: coordinate with the rest! getMethod(name, S4sig) # transform S4sig here if it is not convenient to # keep it ready for use entry in f_usage objects. else{ name0 <- if(grepl('^".*"$', name)) # non-syntactic name sub('^"(.*)"$', "\\1", name) else name x0 <- try(get(name0, envir = parent.frame()), silent=TRUE) if(inherits(x0,"try-error")){ x0 <- do.call(getAnywhere, list(name0)) if(length(x0$objs) > 0) # todo: needs more work here. IN particular, there x0$objs[[1]] # should be a package argument to avoid taking # blindly whatever comes up. else NULL }else x0 } if(is.null(x)) return(x) if (fu && !(is.function(x) || force.function)){ warning("The object is not a function.") # The return value may be appropriate return(name) # for data objects. # todo: Rethink! } argls <- if(fu){ if(!identical(S4sig, "")) S4formals(x) else if(!identical(S3class, "")) formals(x) else{ spec_args <- .special_args[name] if(is.na(spec_args)){ wrk <- formals(x) if(is.null(wrk)) # takes care for primitive functions, napr. seq.int wrk <- formals(args(x)) # argls will still be NULL if x is a function with no arguments. # Note that formals returns pairlist and the pairlist with # zero elements is NULL (unlike list()). Taka che # pairlist2f_usage() needs to know how to deal with this case. wrk }else eval(parse(text = paste0("formals(function(", spec_args, ") NULL)"))) } }else NULL # 2012-10-11 smenyam pairlist2f_usage na pairlist2f_usage1 res <- pairlist2f_usage1(argls, name, S3class = S3class, S4sig = S4sig, infix = infix, fu = fu) if(out.format != "list") res <- as.character(res) res } .special_args <- c("~" = "y, model", "@" = "object, name", "$" = "x, name", "||" = "x, y", "&&" = "x, y", "[" = "x, i, j, ..., drop = TRUE", "[[" = "x, i, j, ..., exact = TRUE", "@<-" = "object, name, value", # formals("@<-") actually works "$<-" = "x, name, value", "[<-" = "x, i, j, ..., value", "[[<-" = "x, i, value", ":" = "from, to" ) # the comparison is symmetric but the interpretation assumes that ucur may be more recent. compare_usage1 <- function(urdo, ucur){ # urdo - usage from Rdo file/object; # ucur - generated from actual object ## 2019-04-14 in R-devel for R-3.7.0 this gives error. ## What is the intent in is.na(ucur) and is.na(urdo)? The documentation of ## compare_usage1() clearly shows that the intent is that of gbutils::isNA(). I ## can't find now what may set ucur or urdo to NA, probably initially I was setting ## NA, not NULL, and the check is.na() remained as a guard, which is not needed ## now. ## ## For typical input here, is.na() gives something like: ## ## --- value of length: 7 type: logical --- ## name S3class S4sig infix fu argnames defaults ## FALSE FALSE FALSE FALSE FALSE FALSE FALSE ## ## TODO: check if it is necessary in the code below to be more defensive ## e.g. (urdo$S3class != "") is potentially troublesome. ## ## obj_removed <- is.null(ucur) || is.na(ucur) ## obj_added <- is.null(urdo) || is.na(urdo) obj_removed <- is.null(ucur) || ( is.atomic(ucur) && length(ucur) == 1 && is.na(ucur) ) obj_added <- is.null(urdo) || ( is.atomic(urdo) && length(urdo) == 1 && is.na(urdo) ) if(!obj_added && !obj_removed && urdo$S3class != ""){ fn <- paste(urdo$name, ".", urdo$S3class, sep="") if(ucur$name == fn){ ucur$name <- urdo$name ucur$S3class <- urdo$S3class } } status <- identical(urdo, ucur) alias <- if(obj_removed) "" else if(ucur$S3class != "") paste(ucur$name, ".", ucur$S3class, sep="") else if(!identical(ucur$S4sig, "")) paste0(ucur$name, ",", paste(ucur$S4sig, collapse=","), "-method") else ucur$name if(grepl('^".*"$', alias)){ # non-syntactic name, drop the quotes alias <- sub('^"(.*)"$', "\\1", alias) } if(obj_removed || obj_added) return( structure( status, details = list( obj_removed = obj_removed , obj_added = obj_added , rdo_usage = urdo , cur_usage = ucur , alias = alias )) ) identical_names <- urdo$name == ucur$name identical_argnames <- identical(urdo$argnames, ucur$argnames) identical_defaults <- identical(urdo$defaults, ucur$defaults) identical_formals <- identical_argnames & identical_defaults added_argnames <- ucur$argnames[ !(ucur$argnames %in% urdo$argnames) ] removed_argnames <- urdo$argnames[ !(urdo$argnames %in% ucur$argnames) ] # note: !!! intersect() is binary operation s <- intersect( intersect(names(urdo$argnames), names(ucur$argnames)), intersect(names(urdo$defaults), names(ucur$defaults)) ) unchanged_defaults <- urdo$defaults[ ucur$defaults[s] == urdo$defaults[s] ] names_unchanged_defaults <- names(unchanged_defaults)[unchanged_defaults] # todo: more details for the case when !identical, e.g. equal up to reordering, # added/removed defaults structure( status, details = list( identical_names = identical_names , obj_removed = obj_removed , obj_added = obj_added , identical_argnames = identical_argnames , identical_defaults = identical_defaults , identical_formals = identical_formals , added_argnames = added_argnames , removed_argnames = removed_argnames , names_unchanged_defaults = names_unchanged_defaults , rdo_usage = urdo , cur_usage = ucur , alias = alias )) } Rdpack/R/Rdo2Rdf.R0000644000176200001440000002442415102212001013232 0ustar liggesusers # backslashes need to be escaped before braces # otherwise backslahes in \{ and \} may get escaped. .bs2 <- function(x) gsub("([\\]+)", "\\1\\1", x) # escape backslash (bs) .esc_br <- function(x) gsub("([{}])", "\\\\\\1", x) # escape {, } .bspercent <- function(x) gsub('([^\\%]?([\\][\\])*)%', '\\1\\\\%', x) # escape percents .anypercent <- function(x){ tag <- attr(x, "Rd_tag") if(is.null(tag) || tag != "COMMENT" ) .bspercent(x) # expects, correctly that `tag' does not disappear else # but see the comment above about usage with Rdapply. x } # this seems incomplete, since \v and \l should be doubled only in R strings when # in RCODE but in contexts where parse_Rd considers them (and other # escaped sequences) to be markup macros, they will be in the Rd_tag # attribute, not in the string. So, it seems that more complicated # processing is not needed. # 2012-10-14 dobavyam obrabotka na poveche ot edna cherta. Togava vsichki osven # poslednata tryabva da se udvoyat (may), a poslednata se udvoyava ako e # posledvana ot v, l ili kray na string. .escape_bs_in_Rcode <- function(rdo){ f <- function(x) if(grepl("\\\\", x)){ # if x contains any backslashes # before 2012-10-14: gsub("(\\\\+)(v|l)", "\\1\\1\\2", x) res <- x res <- gsub("(\\\\+)(\\\\)", "\\1\\1\\2", res) res <- gsub("(\\\\)(v|l)", "\\1\\1\\2", res) res <- gsub("(\\\\)$", "\\1\\1", res) res <- gsub("(\\\\)('|`|\")", "\\1\\1\\2", res) # browser() res }else x Rdtagapply(rdo, f, "RCODE") } # 2012-09-29 included srcref processing # todo: this function was patched many times, needs rewrite Rdo2Rdf <- function(rdo, deparse = FALSE, ex_restore = FALSE, file = NULL, rcode = TRUE, srcfile = NULL){ if(is.character(rdo)) # otherwise print(rdo) may go into infinite recursion rdo <- list(rdo) if(class(rdo)[1] != "Rd") # to force using print.Rd() class(rdo) <- "Rd" if(is.character(srcfile)){ # remember which sections have not changed rdoorig <- permissive_parse_Rd(srcfile) unchanged_sec <- .rdo_equal_sections(rdo, rdoorig) } # browser() if(rcode){ rdo <- .escape_bs_in_Rcode(rdo) # this also does the examples }else if(ex_restore){ # 2012-09-27 promenyam da izpolzva .escape_bs_in_Rcode # There should be no more than one `examples' section in a proper Rd object # and no `NULL' Rd_tag's at the top level. Allow them here since `rdo' may # be an `Rd' piece, not a whole Rd object or fragment. In this way this # function can be used for intermediate transformations. Note though that # print.Rd used below to produce the text output may be more picky. indx <- Rdo_which_tag_eq(rdo, "\\examples") for(i in seq_along(indx)){ if(!is.null(indx[[i]])) rdo[[ indx[[i]] ]] <- .escape_bs_in_Rcode(rdo[[ indx[[i]] ]]) } } rdo <- Rdtagapply(rdo, .esc_br, "nonmathVERB") # escape \{, \} rdo <- Rdtagapply(rdo, .anypercent, "nonmath") # escape % # 2012-10-14 # rdo<-Rdtagapply(rdo, function(x) gsub("((^|[^\\])([\\][\\])*)[\\]$", "\\1\\\\\\\\", x), # "VERB") rdo <- Rdtagapply(rdo, function(x) gsub("(^|[^\\])(\\\\+)$", "\\1\\2\\2", x), "VERB") # pos_only = function(x){ res <- 1; browser(); res } pos_filecmd <- Rdo_locate(rdo, function(x) .tag_eq(x,"\\file"), lists = TRUE) for(pos in pos_filecmd) rdo[[pos]] <- Rdtagapply(rdo[[pos]], function(x) gsub("(\\\\)", "\\1\\1", x), "TEXT") # pos_filecmd <- Rdo_locate(rdo, function(x) .tag_eq(x,"\\samp"), lists = TRUE) # for(pos in pos_filecmd) # rdo[[pos]] <- Rdtagapply(rdo[[pos]], # function(x) gsub("(\\\\+)([^\\])", "\\1\\1\\2", x), # "VERB") # krapka, za nesta kato \code{\\} (see in base R: basename.Rd, body.Rd, Arithmetic.Rd) # 2012-10-14 promenyam tozi (cautious) variant, koyto samo udvoyava edna cherta # kogato sa necheten broy s variant koyto udvoyava vsichki v kraya na \code{} string. # todo: da ne go pravi v examples section (no tam to trudno ste se sluchi) # rdo <- Rdtagapply(rdo, function(x) gsub("((^|[^\\])([\\][\\])*)[\\]$", # "\\1\\\\\\\\", x), "RCODE") # 2012-10-14 otkomentiram, promenich v escape_bs po-gore. # rdo <- Rdtagapply(rdo, function(x) gsub("([\\]+)$", "\\1\\1", x), "RCODE") if(is.character(srcfile)){ # replace unchanged sections with dummy contents unchanged_titles <- sapply(unchanged_sec, function(x) x$title) rdo <- .replace_dummy(rdo, unchanged_titles) } # this was used for saving before introducing tfn, etc. # res <- capture.output(print(rdo, deparse = deparse), file = file) # as.character.Rd ima bug svarzana s newcommand i/ili argumentite # na href, vzh. naprimer which.min.Rd v base, tam as.character dava # \href{{http://CRAN.R-project.org/package=nnet}{\pkg{nnet}}} # (nay-vanshnite skobi {} sa izlishni). todo: tova e krapka! rdotxt <- paste0(as.character(rdo, deparse = deparse), collapse="") rdotxt <- gsub("\\\\href\\{(\\{[^{}]*\\}\\{[^}]*\\}+)\\}", "\\\\href\\1", rdotxt) # todo: krapka; \code{\{} becomes \code{{} which wrecks havoc for parse_Rd; \code{\}} rdotxt <- gsub("(\\\\code\\{)(\\{|\\})(\\})", "\\1\\\\\\2\\3", rdotxt) tfn <- tempfile() # use a temporary file in case file and srcfile are the same on.exit(unlink(tfn)) if(is.character(srcfile)){ # 2018-02-07 removed the following, since redundant (see above): # tfn <- tempfile() # 2018-02-07 (removed the assignment) was: # res <- capture.output(cat(rdotxt, sep = "", collapse = ""), # file = tfn)# writes to tfn # but res is re-assigned below without being used. # Also, dropping capture.output() and moving 'file =' to cat() cat(rdotxt, sep = "", collapse = "", file = tfn) rdocur <- permissive_parse_Rd(tfn) # to set srcref srcrefpos <- .srcrefpos(rdocur, rdoorig, unchanged_sec) rdotxt <- rdo_text_restore(rdocur, rdoorig, srcrefpos, file = tfn) nc_ind <- Rdo_which_tag_in(rdoorig, c("\\newcommand", "\\renewcommand")) if(length(nc_ind) > 0){ nclines <- sapply(nc_ind, function(x) as.character(attr(rdoorig[[x]],"srcref"))) rdotxt <- c(nclines, rdotxt) # put before anything else todo: could try to put at } # original place or at least after any comments? writeLines(rdotxt, tfn) #overwrites tfn res <- if(is.null(file)) paste0(rdotxt, collapse = "\n") else{ file.copy(tfn, file, overwrite = TRUE) # todo: check success NULL # for clarity; capture.output above set it to NULL as tfn is not NULL } }else ## 2012-10-14 res <- capture.output(cat(rdotxt, sep = "", collapse = ""), file = file) ## 2018-02-07 was: ## res <- capture.output(cat(rdotxt, sep = "", collapse = "", file = file)) ## restoring the syntax from 2012, since it works also in the case file = NULL; ## res <- capture.output(cat(rdotxt, sep = "", collapse = ""), file = file) if(is.null(file)) res else{ cat("\tThe Rd content was written to file ", file, "\n") invisible(res) # res is NULL here } } .tmp_pos <- function(name, pos_list){ for(elem in pos_list) if(elem$title == name) return(elem$pos) NULL } .rdo_srcref <- function(rdo, tag){ # todo: special cases! pos <- Rdo_which_tag_eq(rdo, tag) attr(rdo[[ pos[1] ]], "srcref") } .rdo_replace_at <- function(text, pospair){ newtext <- as.character(pospair[[2]]) m <- length(pospair[[1]]) beg_line <- pospair[[1]][1] beg_col <- if(m > 4) pospair[[1]][5] else pospair[[1]][2] end_line <- pospair[[1]][3] end_col <- if(m > 4) pospair[[1]][6] else pospair[[1]][4] res <- c(text[seq_len(beg_line - 1)], if(beg_col > 1) paste0(substr(text[beg_line], 1, beg_col - 1), newtext[1]) else newtext[1], newtext[-1] ) le <- nchar(text[end_line]) # 2012-10-13 was: length(text[end_line]) (!?) if(end_col < le) res[length(res)] <- paste0(res[length(res)], substr(text[end_line], end_col + 1, le)) c(res, text[-(1:end_line)]) } # 2012-10-13 dobavyam 'ends' po-dolu, sluchva se sections da ne zapochvat na nov red! # vzh. NumericConstants.Rd v base ( stava: \note{dummy} \seealso{dummy} ) rdo_text_restore <- function(cur, orig, pos_list, file){ res <- readLines(file) if(length(pos_list) == 1){ res <- .rdo_replace_at(res, pos_list[[1]]) }else{ starts <- sapply(pos_list, function(x) x[[1]][[1]]) ends <- sapply(pos_list, function(x) if(length(x[[1]]) > 4) x[[1]][5] else x[[1]][2] ) p <- order(starts, ends, decreasing = TRUE) dec_pos_list <- pos_list[p] for(pos in dec_pos_list) res <- .rdo_replace_at(res, pos) } res } .without_duplicates <- function(x){ x[!(x %in% unique(x[duplicated(x)]))] } Rdpack/R/threedots.R0000644000176200001440000000424515102212001013770 0ustar liggesusers# > tools:::.strip_whitespace .strip_whitespace <- function (x) { x <- sub("^[[:space:]]+", "", x) x <- sub("[[:space:]]+$", "", x) x } ## tools:::.Rd_drop_nodes_with_tags, but tools:::RdTags(e) => Rdo_tags(e) toolsdotdotdot.Rd_drop_nodes_with_tags <- function (x, tags) { recurse <- function(e) { if (is.list(e)) structure(lapply(e[is.na(match(Rdo_tags(e), tags))], recurse), Rd_tag = attr(e, "Rd_tag")) else e } recurse(x) } ## > tools:::.Rd_get_metadata, but tools:::RdTags() => Rdo_tags() toolsdotdotdot.Rd_get_metadata <- function (x, kind) # e.g. kind = "keyword", see help page of Rd_db() { x <- x[Rdo_tags(x) == sprintf("\\%s", kind)] if (!length(x)) character() else unique(.strip_whitespace(sapply(x, as.character))) } ## > utils:::.getHelpFile utilsdotdotdot.getHelpFile <- function (file) { path <- dirname(file) dirpath <- dirname(path) if (!file.exists(dirpath)) stop(gettextf("invalid %s argument", sQuote("file")), domain = NA) pkgname <- basename(dirpath) RdDB <- file.path(path, pkgname) if (!file.exists(paste(RdDB, "rdx", sep = "."))) stop(gettextf("package %s exists but was not installed under R >= 2.10.0 so help cannot be accessed", sQuote(pkgname)), domain = NA) toolsdotdotdotfetchRdDB(RdDB, basename(file)) } ## > tools:::fetchRdDB toolsdotdotdotfetchRdDB <- function (filebase, key = NULL) { fun <- function(db) { vals <- db$vals vars <- db$vars datafile <- db$datafile compressed <- db$compressed envhook <- db$envhook fetch <- function(key) lazyLoadDBfetch(vals[key][[1L]], datafile, compressed, envhook) if (length(key)) { if (!key %in% vars) stop(gettextf("No help on %s found in RdDB %s", sQuote(key), sQuote(filebase)), domain = NA) fetch(key) } else { res <- lapply(vars, fetch) names(res) <- vars res } } res <- lazyLoadDBexec(filebase, fun) if (length(key)) res else invisible(res) } Rdpack/R/promptSexpr.R0000644000176200001440000000660215102212001014331 0ustar liggesusers # like promptPackage but uses \Sexpr{} for automatic information updating promptPackageSexpr <- function(package, filename= NULL, final = TRUE, overview = FALSE, bib = TRUE){ # 2013-03-30 neew arg. `bib' paste0 <- function(...) paste(..., sep="") overv <- if(overview | !final) "" else "% " hide <- "\\Sexpr[stage=build,results=hide]" pd <- paste0("{pd <- packageDescription(\"", package, "\")}") lb <- paste0("{lb <- library(help=\"", package, "\", character.only=TRUE)}") lbflag <- "lbflag <- !is.null(lb$info[[2]])" Rdtxt <- list( paste0("\\name{", package, "-package}") , paste0("\\alias{", package, "-package}") , paste0("\\alias{", package, "}") , paste0("\\docType{", "package", "}") , "\\title{" , paste0(" ", hide, c(pd, lb)) # init. commands, cannot be outside sections. , " \\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}\\cr" , " }" , "" , " Index:" , paste0(" \\Sexpr[stage=build,results=rd]{paste(\"\\\\\\\\preformatted{\"" , ", paste(if(!is.null(lb$info[[2]])) lb$info[[2]] else \"No entries\",collapse=\"\\n\"), \"}\", sep=\"\")}") , "" , paste0(overv, c("~~ An overview of how to use the package, including the most important ~~" , "~~ functions ~~")) , "}" , "\\author{" , " \\Sexpr[stage=build]{pd$Author}" , "" , paste0("Maintainer: ", "\\Sexpr[stage=build]{pd$Maintainer}") , "}" , "\\references{" , if(bib) "% bibentry:all" else "% ~~ Literature or other references for background information ~~" , "}" , "% ~~ Optionally other standard keywords, one per line, from file KEYWORDS in ~~" , "% ~~ the R documentation directory ~~" , "\\keyword{ package }" , "% \\seealso{" , "% ~~ Optional links to other man pages, e.g. ~~" , "% ~~ \\code{\\link[:-package]{}} ~~" , "% }" , "% \\examples{" , "% ~~ simple examples of the most important functions ~~" , "% }" ) if(is.null(filename)) filename <- paste0(package, "-package.Rd") if(is.na(filename)) return(Rdtxt) cat(unlist(Rdtxt), file = filename, sep = "\n") message(gettextf("Created file named %s.", sQuote(filename)), "\n", gettext("Edit the file and move it to the appropriate directory."), domain = NA) invisible(filename) } Rdpack/R/utils.R0000644000176200001440000002166015102212001013127 0ustar liggesusers.tag_in <- function(x, tags){ a <- attr(x,"Rd_tag") is.character(a) && length(a) == 1 && a %in% tags } .tag_eq <- function(x, tag){ a <- attr(x,"Rd_tag") is.character(a) && length(a) == 1 && a == tag } .ocompare <- function(x,y){ # outer compare f <- function(z) sapply(x, function(w) identical(z,w)) sapply(y,f) } .asym_compare <- function(x,y){ cmp <- .ocompare(x,y) if(length(x) == 1){ # 2012-10-03 added this if cmp <- matrix(cmp, nrow=1) } if(length(x) == 0){ inew <- seq_along(y) irem <- icom <- integer(0) }else if(length(y) == 0){ irem <- seq_along(x) inew <- icom <- integer(0) }else{ inew <- which( ! apply(cmp, 2, any) ) # in y but not in x irem <- which( ! apply(cmp, 1, any) ) # in x but not in y icom <- which( !(seq_along(x) %in% c(inew, irem)) ) # in both, x and y } list( i_new = inew, i_removed = irem, i_common = icom ) } rattr <- function(x,y){ # restore attributes, see Rdapply below if(is.list(x)){ if(!identical(attributes(x), attributes(y))) attributes(x) <- attributes(y) for(i in seq_along(x)) x[[i]] <- Recall(x[[i]], y[[i]]) } x } Rdapply <- function(x, ...){ # needed since rapply loses attributes of x wrk <- rapply(x, ...) rattr(wrk, x) } .pos_in_eqnpos <- function(verb, eqn){ # not a complete solution f <- function(x,y) length(x) > length(y) && all( x[seq_along(y)] == y ) flag <- FALSE res <- vector(mode="logical", length = length(verb)) for(i in seq_along(verb)){ for(j in seq_along(eqn)){ flag <- f(verb[[i]], eqn[[j]]) if(flag) break } res[i] <- flag } res } # 2012-09-08 new Rdtagapply <- function(object, FUN, rdtag, classes = "character", how = "replace", ...){ if(rdtag %in% c("mathVERB", "nonmathVERB", "nonmath")){ # special care for \eqn and \deqn feqnpos <- function(x) .tag_in(x, c("\\eqn", "\\deqn")) eqnpos <- Rdo_locate(object, feqnpos, lists = TRUE) eqnpos <- lapply(eqnpos, function(x) c(x,1)) # 1st arg. of \eqn or \deqn if(rdtag == "nonmath"){ anypos <- Rdo_locate_leaves(object) pos <- anypos[ !.pos_in_eqnpos(anypos, eqnpos) ] }else{ # is it better to use Rdo_locate_leaves here? fverbpos <- function(x) .tag_eq(x, "VERB") verbpos <- Rdo_locate(object, fverbpos, lists = FALSE) pos <- if(rdtag == "mathVERB") # verbpos[ verbpos %in% eqnpos ] verbpos[ .pos_in_eqnpos(verbpos, eqnpos) ] else # (rdtag == "nonmathVERB") # verbpos[ !( verbpos %in% eqnpos) ] verbpos[ !.pos_in_eqnpos(verbpos, eqnpos) ] } for(ind in pos) object[[ind]] <- FUN(object[[ind]], ...) object }else{ locfun <- function(x,...) if(.tag_eq(x, rdtag)) FUN(x,...) else x Rdapply(object,locfun, classes = classes, how = how, ...) } } .aux_Rdo_locate_leaves <- function(x, i){ if(is.logical(x)){ if(isTRUE(x)) i else FALSE }else{ # here x is a list of integer vectors lapply(x, function(x){ c(i,x)}) } } # inn1 <- parse_Rd("inner-methods.Rd") # Rdo_locate_leaves(inn1, function(x) grepl("^signature\\(", x)) Rdo_locate_leaves <- function(object, f = function(x) TRUE){ fxx <- function(x){ if(is.character(x)){ return(f(x)) # evaluate `f' for this leaf }else if(is.list(x)){ if(length(x)==0) # list() return(x) wrk <- lapply(x, fxx) for(i in seq_along(wrk)) wrk[[i]] <- .aux_Rdo_locate_leaves(wrk[[i]], i) indx <- sapply(wrk, function(y) !identical(y,FALSE) ) wrk <- wrk[indx] wrk <- do.call("c",wrk) return(wrk) }else{ return(FALSE) # todo: replace this with a function and additional argument } } fxx(object) } .merge_pos0 <- function(a, b){ # 2012-09-25 new if(is.numeric(b)) c(a,b) else if(is.list(b)){ res <- vector(mode="list", length=length(b)) for(i in seq_along(b)){ res[[i]] <- Recall(a, b[[i]]) } res }else if(is.logical(b)){ if(isTRUE(b)) a else as.numeric(NA) # numeric(0) }else{ attr(a, "merge_tag") <- b # obache tozi tag se gubi po-kasno a } } .merge_pos <- function(a, b, ...){ # 2012-09-25 new if(is.numeric(a) && length(a)==1){ a <- as.list(1:a) # todo: process the case a=0 } wrk <- list() for(i in a){ wrk <- c(wrk, .merge_pos0(a[[i]], b[[i]]) ) } res <- wrk len <- sapply(res, length) res <- res[len>0] # drop zero length values drop <- sapply(res, function(x) any(is.na(x))) res[ !drop] } .notFALSE <- function(x) !identical(x, FALSE) .notTRUE <- function(x) !isTRUE(x) # !identical(x, TRUE) # 2012-10-20 dobavyam argument nested # 2012-10-07 dobavyam argument fpos Rdo_locate <- function(object, f = function(x) TRUE, pos_only = TRUE, lists = FALSE, fpos = NULL, nested = TRUE){ fxx <- function(x){ if(is.character(x)){ # a leaf, evaluate `f' for it f(x) }else if(is.list(x)){ fli <- if(lists) f(x) else FALSE if(!nested && fli) return(TRUE) wrk <- if(fli) list(fli) else list() if(length(x)>0) wrk <- c(wrk, .merge_pos(length(x), lapply(x, fxx)) ) # recurse wrk }else{ # this should not happen for Rd objects FALSE # todo: replace this with a function and additional argument? } } pos <- fxx(object) f <- if(is.function(fpos)) function(x) list(pos = x, value = fpos(object, x)) else if(isTRUE(pos_only)) NULL else if(is.function(pos_only)) function(x) list(pos = x, value = pos_only(object[[x]])) else function(x) list(pos = x, value = object[[x]]) if(!is.null(f)) lapply(pos, f) else pos } # insert sep between successive elements of x .Rdinter <- function(x, sep = Rdo_newline(), before_first = FALSE, after_last = FALSE){ indx <- c(rbind(seq_along(x), length(x) + 1)) if(before_first) indx <- c( length(x) + 1, indx) if(!after_last) indx <- head(indx,-1) c(x, list(sep))[indx] } .Rd_tidy <- function(rdo){ # todo: optionally remove empty sections? tags <- Rdo_tags(rdo) # todo: remove multiple empty lines? secpos <- which(tags != "TEXT") # remove empty lines at top level? secpos <- secpos[secpos > 1] if(length(secpos)==0) return(rdo) nl <- Rdo_newline() nlpos <- integer(0) for(i in secpos){ # 2012-09-20 smenyam (!identical(rdo[[i-1]], nl)) s dolnoto. if(!Rdo_is_newline(rdo[[i-1]])) # inache tryabva da se grizha za "srcref" attribute nlpos <- c(nlpos, i) } if(length(nlpos)==0) return(rdo) # todo: this is lazy for(i in sort(nlpos, TRUE)){ # sort in decreasing order, otherwise indices change rdo <- Rdo_insert_element(rdo, nl, i) } rdo } Rdo_remove_srcref <- function(rdo){ f <- function(x){ a <- attributes(x) if(is.list(x)){ x <- lapply(x,f) if(!is.null(a)) # 2012-10-07 check for NULL attributes(x) <- a } if(!is.null(attr(x,"srcref"))) attr(x,"srcref") <- NULL x } f(rdo) } Rd_combo <- function(rd, f, ..., .MORE){ # todo: allow a directory? dots <- list(...) flag <- missing(.MORE) locfun <- function(x){ locwrk <- permissive_parse_Rd(x) locargs <- c(list(locwrk), dots) locres <- try( do.call(f, locargs), silent=TRUE) if(flag || inherits(locres,"try-error")) locres else{ try( do.call(.MORE, list(locres)), silent=TRUE) } } lapply(rd, locfun) } Rdpack/R/inspect.R0000644000176200001440000002311315102212001013427 0ustar liggesusers.parse_long_name <- function(fnam){ # 2012-11-04 new, code from .capture_promptAny() namreg <- "^(.+)-([^-]+)$" if(grepl(namreg, fnam)){ # fnam is of the form xxxx-yyy (non-empty rhs) fname <- gsub(namreg, "\\1", fnam) type <- gsub(namreg, "\\2", fnam) # without "-" ## suffix <- gsub("^([^-]+)(-.*)", "\\2", fnam) # with "-" }else{ fname <- fnam type = "" } c(name = fname, type = type) } parse_Rdname <- function(rdo){ # 2012-10-01 todo: Rdpack-internal ste dade type="internal" # 2012-10-01 otkomentiram tova, to raboteshe vyarno po sluchaynost! # (ponezhe gsub() po-dolu go prevrasta v character()!) # nam <- rdo[[ which( tools:::RdTags(rdo) == "\\name" ) ]] ind <- Rdo_which_tag_eq(rdo, "\\name") nam <- c( rdo[[ c(ind, 1) ]]) # assumes length(ind) == 1 # 2012-11-04 changed with the code after the commented out section # # if(grepl("^([^-]+)-.*", nam)){ # nam is of the form xxxx-yyy # fname <- gsub("^([^-]+)-.*", "\\1", nam) # type <- gsub("^([^-]+)-(.*)", "\\2", nam) # suffix without the '-' # # suffix <- gsub("^([^-]+)(-.*)", "\\2", nam) # with the "-" # }else{ # fname <- nam # type = "" # } wrknam <- .parse_long_name(nam) fname <- wrknam["name"] type <- wrknam["type"] # malko kato krapka doctype <- Rdo_which_tag_eq(rdo, "\\docType") if(length(doctype) > 0 && type == "" ){ # todo: sravni s gornoto! type <- c( rdo[[ c(doctype[1],1) ]] ) # wrap n c() to remove attr. } list(fname = fname, type = type) } inspect_Rd <- function(rdo, package = NULL){ # rdo: Rd object or file name if(is.character(rdo) && length(rdo)==1) rdo <- permissive_parse_Rd(rdo) if(!inherits(rdo, "Rd") && is.null(attr(rdo,"Rd_Tag"))) return(structure(FALSE, details = "inspect_Rd: 1st arg. must be an Rd object or filename.")) type <- toolsdotdotdot.Rd_get_metadata(rdo,"docType") if(length(type) == 0){ type <- parse_Rdname(rdo)$type # todo: clean up if(!(type %in% c("package", ""))) # for now; there is, e.g. ts-methods which type <- "" # describes S3 methods. } switch(type, methods = inspect_Rdmethods(rdo, package = package), class = inspect_Rdclass(rdo), package = {cat("Currently reprompt for packages is not implemented.", "\tHowever, you could use the function promptPackageSexpr()", "\tto create a self-updating shell. 'promptPackageSexpr'", "\tis like 'promptPackage' but uses \\Sexpr commands rather", "\tthan strings for automatically generated information.", "Returning the Rd object unchanged.\n", sep = "\n") rdo }, data = {cat("Currently reprompt for data is not available.", "Returning the Rd object unchanged.\n", sep = "\n") rdo }, ## default inspect_Rdfun(rdo) ) } inspect_Rdclass <- function(rdo){ # rdo: Rd object cur <- inspect_slots(rdo) # methods: items have the form \item{fname}{signature}, ## 2018-08-27 - non-exiting class (TDO: check if it could be something else here ## TODO: think of a better way to handle this. if(inherits(cur, "try-error")){ cat(cur) return(rdo) } rdo <- inspect_clmethods(cur) # compare with those from promptClass rdo # todo: inspect other things too? } inspect_Rdmethods <- function(rdo, package = NULL){ # rdo: Rd object i_usage <- inspect_signatures(rdo, package = package) # i_usage$added_sig # i_usage$removed_sig if(i_usage$changed) cat("\tMethods in the documentation are not the same as the current ones.\n") # 2014-08-23 new 'if' to tell the user to removed the doc. of non-existen methods if(length(i_usage$removed_sig) > 0){ cat("\tMethods for the following signatures ", "where not found", if(is.null(package)) "" else paste0(" in package ", package) , ":\n", sep = "") for( sigus in i_usage$removed_sig){ txt <- paste(sigus$argnames, sigus$defaults, collapse = ",\t", sep = " = ") cat("\t ", txt, "\n") } # 2014-08-23 todo: maybe give a more cautious advice here? cat("\tPlease remove these from the documentation.\n\n") } if(length(i_usage$added_sig) > 0){ cat("\tAppending new signatures to section \"Methods\"\n") ## 2014-08-23 TODO: ## the code below now is executed only when length(i_usage$added_sig) > 0; ## before it was executed whenever i_usage$changed was TRUE. newsigs <- sapply(i_usage$added_sig, function(x) deparse_usage1(x)) wrk <- lapply(c(newsigs), Rdo_sigitem) # todo: slozhi blank line predi vseki item, names(wrk) <- NULL # no da ne e chast ot itemite, # a mezhdu tyach. idescr <- .locate_top_tag(rdo, "Methods") if(length(idescr) == 0){ # no descibe enviroment there. wrk <- Rdo_macro(wrk, "\\describe") idescr <- .locate_sec_content(rdo, "Methods") rdo[[idescr]] <- c(rdo[[idescr]], list(wrk)) }else rdo <- append_to_Rd_list(rdo, wrk, pos = idescr) } # 2012-09-07 new; not under the if above, # since aliases may be mismatched by manual editing (or otherwise) rdo <- update_aliases_tmp(rdo, package = package) # if "\\usage" section exists. if(length(Rdo_which_tag_eq(rdo, "\\usage")) > 0) rdo <- inspect_Rdfun(rdo, alias_update = FALSE) # alias_update was added to Rd_fun # to be used here rdo } # todo: more systematic messages about what has changed (or not) inspect_Rdfun <- function(rdo, alias_update = TRUE){ # rdo: Rd object i_usage <- inspect_usage(rdo) if(length(i_usage) == 0) # todo: processing of arguments may still be needed here return(rdo) i_args <- inspect_args(rdo, i_usage) # 2011-12-08 new; corresponding additions to compare_usage1 # 2012-10-05 slagam as.character, ponezhe nyakoi mozhe da sa ot class `name` # todo: make sure that they are character in the first place? aliases <- sapply(i_usage, function(x) as.character(attr(x, "details")$alias)) aliases <- aliases[aliases != ""] rdoaliases <- Rdo_collect_aliases(rdo) # 2012-10-05 promenyam za da otchitam #ifdef new_aliases <- aliases[ !(aliases %in% rdoaliases) ] if(alias_update && length(new_aliases) > 0) # update the aliases for(alias in unique(new_aliases)) rdo <- Rdo_insert(rdo, char2Rdpiece(alias, "alias")) flag_removed <- sapply(i_usage, function(x) attr(x, "details")$obj_removed) if(any(flag_removed)){ nams_removed <- sapply(i_usage, function(x) attr(x, "details")$rdo_usage$name) nams_removed <- nams_removed[flag_removed] obs_aliases <- nams_removed[ nams_removed %in% rdoaliases ] cat("The following objects are no longer described in this Rd object\n") cat("but it contains alias entries for them:\n") cat("\t", paste(obs_aliases), "\n") cat("You may wish to remove these \\alias{} entries from the Rd file.\n\n") } usage_changed <- !all( sapply(i_usage, identity)) # usage_changed <- TRUE # for testing if(usage_changed){ # update usage if changed f <- function(x){ a <- as.character(attr(x,"details")$cur_usage) parse_Rdtext(a, section = "\\usage") } u <- lapply(i_usage, f) u <- .Rdinter(u, before_first = TRUE) wrk <- structure(do.call("c", u), Rd_tag = "\\usage") rdo <- Rdo_replace_section(rdo, wrk) } # todo: Rdo_append_argument probably should check length(newargs)>0 anyway? if(!i_args){ # update arguments if changed newargs <- attr(i_args,"details")$added_argnames if(length(newargs)>0){ cat("\nnewargs is:", newargs, "\n") rdo <- Rdo_append_argument(rdo, newargs) } remargs <- attr(i_args,"details")$removed_argnames if(length(remargs)>0){ cat("Argument(s): ", remargs, "\n") cat("\tare no longer in any usage statements in this Rd object.\n") cat("Please remove the corresponding \\item's from section '\\arguments'.\n") cat("\n") } } rdo } Rdpack/R/RStudio.R0000644000176200001440000000362415102212001013360 0ustar liggesusers# In RStudio, call reprompt on function that cursor is pointing to. RStudio_reprompt <- function(verbose = TRUE) { if (!requireNamespace("rstudioapi") || !requireNamespace("rprojroot")) stop("RStudio support requires you to install the 'rprojroot' and 'rstudioapi' packages") sourceContext <- rstudioapi::getSourceEditorContext() infile <- sourceContext$path if(length(infile) == 0) stop("Nothing to do. See ?Rdpack::RStudio_reprompt for information about this add-in.") if (grepl("[.][rR]d$", infile)) # editing a help file reprompt(infile = infile, filename = infile, verbose = verbose) else if (grepl("[.][rRsSq]$", infile)) { # editing R source pkgdir <- rprojroot::find_package_root_file(path = dirname(infile)) pkg <- basename(pkgdir) if (length(sourceContext$selection) == 1) { fnname <- sourceContext$selection[[1]]$text } else fnname <- "" if (!nchar(fnname)) stop("Select a function name") if (!exists(fnname)) stop("Object ", sQuote(fnname), " not found. Run 'Install and Restart'?") existing <- help(fnname) ## Subset to the ones in the current package existing <- existing[basename(dirname(dirname(existing))) == pkg] if (length(existing) == 1) { infile <- file.path(pkgdir, "man", paste0(basename(existing), ".Rd")) reprompt(infile = infile, filename = infile, verbose = verbose) } else if (!length(existing)) infile <- reprompt(fnname, filename = file.path(pkgdir, "man", paste0(fnname, ".Rd")), verbose = verbose) else stop("Multiple matches to ", sQuote(fnname), ". Open one help file manually.") } else stop("This tool only works on .Rd or .R files.") rstudioapi::navigateToFile(infile) } Rdpack/R/repromptAny.R0000644000176200001440000003143315102212001014306 0ustar liggesusers## 2018-02-07 new ereprompt <- function(..., edit = TRUE, filename = TRUE){ reprompt(..., filename = filename, edit = edit) } ## 2018-02-07 new argument `edit' reprompt <- function(object, infile = NULL, Rdtext = NULL, final = TRUE, type = NULL, package = NULL, methods = NULL, # for the call to promptMethods verbose = TRUE, filename = NULL, sec_copy = TRUE, edit = FALSE, ...){ objmis <- missing(object) tidyflag <- from_infile <- FALSE # If 'object' is a string ending in ".Rd" and containing # at least one "/", it is taken to be "infile"; a # (somewhat dubious) convenience feature for the common # mistake of omitting the name of the "infile" argument. if(is.null(infile) && length(object) == 1 && is.character(object) && grepl("/.*[.][Rr]d$", object) ) infile <- object if(!is.null(Rdtext)){ # process Rdtext, if present if(is.null(infile)){ infile <- tempfile() cat(Rdtext, file = infile, sep = "\n") # save parsed Rdtext to 'infile' on.exit(unlink(infile)) }else cat("both 'infile' and 'Rdtext' are given, ignoring Rdtext\n") } if(!objmis && inherits(object, "Rd")){ if(verbose) cat("Processing the Rd object...\n") if(!is.null(infile)) cat("ignoring 'infile' and/or 'Rdtext' since 'object' is of class 'Rd'\n") rdo <- object }else if(!is.null(infile)){ if(verbose) cat("\nParsing the Rd documentation in file", infile, "...\n") else cat("\n", basename(infile), ": ") if(!file.exists(infile)){ # 2018-02-07 new wrk <- try(rprojroot::find_root_file("man", basename(infile), criterion = rprojroot::is_r_package), silent = TRUE) if(inherits(wrk, "try-error")) stop("Input file ", infile, " not found") else infile <- wrk } rdo <- permissive_parse_Rd(infile) from_infile <- TRUE }else{ if(verbose) cat("Rd source not supplied, looking for installed documentation.\n") fnam <- if(is.character(object)) object else deparse(substitute(object)) rdo <- .capture_installed_help(fnam, type = type, package=package) if(inherits(rdo,"try-error")) cat("Rd source not supplied and installed documentation not found.\n") else{ if(verbose) cat("Installed documentation found, processing it...\n") rdo <- .order_sections(rdo) # the sections may not be in canonical order in tidyflag <- TRUE # instaled help } } if(inherits(rdo, "Rd")){ # do the main job: inspect the documentation object res <- inspect_Rd(rdo, package = package) }else{ # documentation not found, try to generate fresh one if(verbose) cat("Trying a 'prompt' function to generate documentation for the object.\n") # 2012-11-04 arg. type, package res <- .capture_promptAny(fnam, type = type, package = package, final = final, methods = methods) if(inherits(res,"try-error")) stop("unsuccessful attempt to create Rd doc. using a 'prompt' function.") else if (verbose) cat("\tsuccess: documentation generated using a 'prompt' function.\n") } if(tidyflag) res <- .Rd_tidy(res) # tidy() could do more, if(is.null(filename)){ # generate appropriate file name; todo: may need some mangling? filename <- if(is.null(infile)) paste(res[[ Rdo_which_tag_eq(res, "\\name") ]], ".Rd", sep="") else basename(infile) # do not overwrite unless in the current dir }else if(isTRUE(filename)){ # 2018-02-07 new filename <- if(is.null(infile)) paste(res[[ Rdo_which_tag_eq(res, "\\name") ]], ".Rd", sep="") else infile # will overwrite } # todo: error checking if(is.character(filename) || identical(filename, FALSE)){ # convert to Rdtext res <- Rdo2Rdf(res, ex_restore = TRUE, file = if(is.character(filename)) filename else NULL, srcfile = if(from_infile && sec_copy) infile else NULL ) if(is.character(filename)) res <- invisible(filename) # return only the file name in this case } if(edit && is.character(filename)){ ## 2018-02-07 new argument `edit' file.edit(res) # TODO: check that it is a filename res }else res } # (promptMethods) todo: filename = FALSE is a useful # alternative. In that case the text is returned in a named list # containing one element for each Rd section (multiple occurences # of sections like '\alias' are grouped together. # 2012-11-04 new arg. type, package .capture_promptAny <- function(fnam, type, package, final, ..., methods){ # 2012-11-04 promenyam za da raboti is replacement methods, e.g. "[<--methods" # # if(grepl("^([^-]+)-.*", fnam)){ # fnam is of the form xxxx-yyy # fname <- gsub("^([^-]+)-.*", "\\1", fnam) # type <- gsub("^([^-]+)-(.*)", "\\2", fnam) # without "-" # ## suffix <- gsub("^([^-]+)(-.*)", "\\2", fnam) # with "-" # }else{ # fname <- fnam # type = "" # } # 2012-11-04 replacing with the code after the comments # # namreg <- "^(.+)-([^-]+)$" # if(grepl(namreg, fnam)){ # fnam is of the form xxxx-yyy (non-empty rhs) # fname <- gsub(namreg, "\\1", fnam) # namtype <- gsub(namreg, "\\2", fnam) # without "-" # ## suffix <- gsub("^([^-]+)(-.*)", "\\2", fnam) # with "-" # }else{ # fname <- fnam # namtype = "" # } wrknam <- .parse_long_name(fnam) fname <- wrknam["name"] namtype <- wrknam["type"] if(missing(type) || is.null(type)) type <- namtype else if(namtype != "" && !identical(type, namtype)){ cat("The name and type arguments give conflicting 'type' information.\n") cat("\tUsing argument 'type'.\n") }# else 'type' has the value needed. ## 2019-04-26 print a message since otherwise the error is not clear, ## e.g. if the call has 'type = class' (note: no quotes around class) if(!is.character(type) || length(type) != 1L) print("!!! if not missing, 'type' must be a character string") wrk <- try(switch(type, methods = { if(is.null(methods) && !is.null(package)) methods <- findMethods(fname, where = asNamespace(package)) if(is.null(methods)) promptMethods(f=fname, filename = NA) else promptMethods(f=fname, filename = NA, methods=methods) }, class = promptClass(clName=fname, filename = NA), package = promptPackageSexpr(fname, filename = NA), ## default # v tozi variant ima problemi za funktsii ot Rdpack, za koito parviyat # "if" dava TRUE i sled tova stava greshka. Za funktsii ot drugi paketi # tova ne e problem, ponezhe za tyach "if"-at dava FALSE, ako sa # nevidimi. # # Tay kato tazi situatsiya mozhe da vaznikne po razlichni nachini, # promenyam koda. Tryabva oste rabota za sluchaya kogato ima poveche ot # edno ime... ### if(exists(fname, envir = parent.frame())){ ### prompt(object=fname, filename = NA, force.function=TRUE, ...) ### }else{ # todo: needs more work here ### x0 <- do.call(getAnywhere,list(fname)) ### browser() ### prompt(object=x0$objs[[1]], filename = NA, force.function=TRUE, ### name = fname, ...) ### } { wrk0 <- try(prompt(name=fname, filename = NA, ...), silent=TRUE) if(inherits(wrk0,"try-error")){ x0 <- do.call(getAnywhere,list(fname)) wrk0 <- prompt(object=x0$objs[[1]], filename=NA, name = fname, # force.function=TRUE, ...) } wrk0 # todo: needs more work here. IN particular, there should be a # package argument to avoid taking blindly whatever comes up. } ) , silent = TRUE) if(inherits(wrk,"try-error")) res <- wrk else{ res <- .parse_Rdlines(wrk) # if successful, res is not inspected here # since it is generated from the actual definitions. if(final && type != "package"){ # put dummy title and description # to avoid errors when installing a package wrk <- char2Rdpiece("~~ Dummy title ~~", "title") res <- Rdo_replace_section(res, wrk) wrk <- char2Rdpiece("~~ Dummy description ~~", "description") res <- Rdo_replace_section(res, wrk) # tidy a bit, e.g. to start each section on new line, # which may not be the case for installed documentation res <- .Rd_tidy(res) # tidy() could do more; e.g. reorder sections } } res } .capture_installed_help <- function(fnam, type = NULL, package = NULL, suffix = NULL){ # this does not work, package seems not evaluated or deparsed # hlp <- help(paste(fnam, "-methods", sep=""), package=package) # TODO: the last example in "help()" amy be helpful here. # namreg <- "^(.+)-([^-]+)$" # 2012-11-04 new namreg and related fullname <- if(grepl(namreg, fnam)) # fnam is of the form xxxx-yyy fnam else if(!is.null(type) && is.character(type) && type!="") paste(fnam, "-", type, sep="") else if(!is.null(suffix)) paste(fnam, suffix, sep="") else fnam hlp <- help(fullname) # todo: more care! hlpfile <- as.vector(hlp) # removes attributes # todo: but may be of length > 1, e.g. for "initialize" # cat("hlpfile has ", length(hlpfile), " element(s):\n") # print(hlpfile) if(!is.null(package)){ # try first "/package/" to avoid surprise matches; # see what happens with package = "methods", without the slashes; # also, 'package' may be part of the name of another package. indx <- which( grepl(paste("/", package, "/", sep=""), hlpfile)) if(length(indx)==0) # ... but if nothing matched, try without the slashes. indx <- which(grepl(package, hlpfile)) hlpfile <- hlpfile[ indx ] } if(length(hlpfile) > 1){ # todo: mozhe da se napravi v loop to collect a bunch of sig's hlpfile <- hlpfile[1] cat("length(hlpfile)>1, taking the first element.\n") } try(utilsdotdotdot.getHelpFile(hlpfile), silent=TRUE) } # 'usage' may be an "f_usage" object obtained e.g. by a # previous call to get_usage() or generated programmatically. promptUsage <- function (..., usage){ # todo: add formatting options? if(missing(usage)) get_usage(..., out.format="text") else as.character(usage) } Rdpack/R/f_usage.R0000644000176200001440000001434115102212001013376 0ustar liggesusersparse_pairlist <- function(x){ is.missing.arg <- function(arg) typeof(arg) == "symbol" && deparse(arg) == "" # x == NULL corresponds to functions with no arguments (also # length(NULL) is 0) also, NULL is a pairlist with length 0. # Is this function used with x other than pairlist? if(is.null(x) || length(x) == 0) # If not, the test of length(x) is redundant. return(list(argnames = character(0), defaults = character(0))) nonmis <- x[ !sapply(x, is.missing.arg) ] wrk <- character(length(nonmis)) names(wrk) <- names(nonmis) for(s in names(nonmis)){ wrk[[s]] <- paste(deparse(nonmis[[s]], backtick = TRUE, width.cutoff = 500L) , collapse = "\n") } list(argnames = names(x), defaults = wrk ) } # 2012-10-03 new arg. infix pairlist2f_usage1 <- function(x, name, S3class = "", S4sig = "", infix = FALSE, fu = TRUE){ structure(c(list(name=name, S3class=S3class, S4sig=S4sig, infix=infix, fu = fu), parse_pairlist(x)), class="f_usage") } print.f_usage <- function(x, ...){ tab <- max(nchar(names(x))) for(nam in names(x)){ if(is.null(nam)) next if(nam != "defaults") cat(nam, strrep(" ", tab - nchar(nam)), "=", x[[nam]], "\n") else{ defnams <- names(x$defaults) for(i in seq_along(defnams)){ if(i == 1) cat(nam, strrep(" ", tab - nchar(nam[i])), ":", defnams[i], "=", x$defaults[i], "\n") else cat(strrep(" ", tab + 3), defnams[i] , "=", x$defaults[i], "\n") } } } cat("\n") } format_funusage <- function(x, name = "", width = 72, realname){ res <- paste(name, "(", paste(x, collapse = ", "), ")", sep="") if(is.numeric(width) && nchar(res, type="width") > width){ delim <- c("(", rep(", ", length(x) - 1), ")") wrk <- paste(c(name, x), delim, sep="") lens <- nchar(wrk, type="width") if(!missing(realname)) lens[1] <- nchar(realname, type="width") + 1 indent <- paste(rep(" ", lens[1]), collapse="") res <- character(0) curlen <- 0 for(i in seq_along(wrk)){ if(curlen + lens[i] > width){ res <- paste(res, "\n", indent, sep="") curlen <- lens[1] # = number of chars in `indent' } res <- paste(res, wrk[i], sep="") curlen <- curlen + lens[i] } } res } deparse_usage1 <- function(x, width = 72){ if(!x$fu) # a variable, not function return( structure( x$name, names = x$name ) ) # todo: maybe x$name tryabva da e character, as.character here should not be needed. if(as.character(x$name) %in% c("[","[[", "$", "@", "[<-", "[[<-", "$<-", "@<-", "!")) "dummy" else if(x$infix){ # infix operator if(grepl(".+<-$", x$name)){ # name end is "<-" but is not equal to it name2 <- sub("^(.+)<-$", "\\1", x$name) m <- length(x$argnames) res <- paste(name2, "(", paste(x$argnames[-m], collapse=", "), ")", "<-", x$argnames[m]) }else # todo: make sure that the name is not in quotes! res <- paste(x$argnames, collapse = paste0(" ", x$name, " ")) return(res) } res <- x$argnames names(res) <- x$argnames nams <- names(x$defaults) res[nams] <- paste(res[nams], "=", x$defaults) assop <- grepl(".+<-$", x$name) # name end is "<-" but is not equal to it name <- x$name if(assop){ name <- sub("<-$", "", x$name) value <- res[length(res)] res <- res[-length(res)] } res <- if(!identical(x$S3class, "")) format_funusage(res, paste("\\method{", name, "}{", x$S3class, "}", sep=""), realname = name ) else if(!identical(x$S4sig, "")) format_funusage(res, paste("\\S4method{", name, "}{", paste0(x$S4sig, collapse = ", "), "}", sep=""), realname = name ) else switch(name, "$" =, "@" = paste0(res[1], name, res[2]), "[" =, "[[" = paste0(res[1], name, paste0(res[-1], collapse = ", "), .closeOp[name]), "!" = paste0("!", res[1]), ## default format_funusage(res, name) ) if(assop) # if assignment, add to the last line, usually the only one res[length(res)] <- paste0(res[length(res)], " <- ", value) # "[<-" = paste0(res[1], "[", paste0(res[c(-1,-length(res))], # collapse = ", "), "]", " <- ", res[length(res)]), # "[[<-" = paste0(res[1], "[[", paste0(res[c(-1,-length(res))], # collapse = ", "), "]]", " <- ", res[length(res)]), # "$<-" = paste0(res[1], "$", res[2], " <- ", res[3]), # "@<-" = paste0(res[1], "@", res[2], " <- ", res[3]), res <- gsub("...", "\\dots", res, fixed=TRUE) structure( paste(res, collapse = ""), names=x$name ) } as.character.f_usage <- function(x,...){ deparse_usage1(x) } deparse_usage <- function (x){ if(inherits(x, "f_usage")) return(deparse_usage1(x)) nams <- names(x) if(!is.null(nams)) # remove names since sapply merges them with the names of names(x) <- NULL # the list obtained by lapply() res <- sapply(x, deparse_usage1) if(is.null(names(res))) # in most cases names(res) will be the same as nams names(res) <- nams # but give preference to the ones returned by # deparse_usage1 which takes names from the objects. # This `if' will hardly ever kick in... res } .closeOp <- list("[" = "]", "[[" = "]]", "(" = ")", "{" = "}") Rdpack/R/predefined.R0000644000176200001440000000670215102212001014074 0ustar liggesusers.rd_sections <- # note: user defined sections are typeset before note, seealso, examples. c("\\name", "\\Rdversion", "\\docType", "\\alias", "\\encoding", "\\concept", "\\title", "\\description", "\\usage", "\\format", "\\source", "\\arguments", "\\details", "\\value", "\\references", "\\section", "\\note", "\\author", "\\seealso", "\\examples", "\\keyword") ## todo: "\\Sexpr", "\\Rdopts", "\\newcommand", "\\renewcommand" rdo_top_tags <- unique(c(.rd_sections, "#ifdef", "#ifndef", "\\newcommand", "\\renewcommand", "COMMENT", "TEXT" )) Rdo_piece_types <- c( name = "VERB" # sections , alias = "VERB" , concept = "TEXT" , docType = "TEXT" , title = "TEXT" , description = "TEXT" , examples = "RCODE" , usage = "RCODE" , Rdversion = "VERB" , synopsis = "VERB" , Sexpr = "RCODE" , RdOpts = "VERB" , code = "RCODE" # macros , dontshow = "RCODE" , donttest = "RCODE" , testonly = "RCODE" , dontrun = "VERB" , env = "VERB" , kbd = "VERB" , option = "VERB" , out = "VERB" , preformatted = "VERB" , samp = "VERB" , special = "VERB" , url = "VERB" , verb = "VERB" , deqn = "VERB" , eqn = "VERB" , renewcommand = "VERB" , newcommand = "VERB" ) # todo: not complete. Skaniray instalirana # dokumentatsiya za tezi raboti! Rdo_predefined_sections <- c( name = "VERB" , alias = "VERB" , concept = "TEXT" , docType = "TEXT" , title = "TEXT" , description = "TEXT" , examples = "RCODE" , usage = "RCODE" , Rdversion = "VERB" , synopsis = "VERB" , section = "TEXT" # not clear what to put for this element # (and the following) 2012-09-23 new entries below. (maybe # their absence was the reason for some strange behaviour of # char2Rdpiece). Slagam vsichkite "TEXT", no (todo:) tryabva da # se proveri. , arguments = "TEXT" , keyword = "TEXT" , note = "TEXT" , format = "TEXT" , source = "TEXT" , details = "TEXT" , value = "TEXT" , references = "TEXT" , author = "TEXT" , seealso = "TEXT" ) Rdpack/vignettes/0000755000176200001440000000000015141664153013474 5ustar liggesusersRdpack/vignettes/Inserting_bibtex_references.Rnw0000644000176200001440000004316015134452141021662 0ustar liggesusers% Created 2022-07-20 Wed 17:30 % Intended LaTeX compiler: pdflatex \documentclass[a4paper,twoside,11pt,nojss,article]{jss} \usepackage[T1]{fontenc} \usepackage[left=2cm,right=2cm,bottom=15mm]{geometry} \usepackage{graphicx,color,alltt} \usepackage[authoryear,round,longnamesfirst]{natbib} \usepackage{hyperref} % \usepackage{Sweave} \author{Georgi N. Boshnakov} \Plainauthor{Georgi N. Boshnakov} \Address{ Georgi N. Boshnakov\\ School of Mathematics\\ The University of Manchester\\ Oxford Road, Manchester M13 9PL, UK\\ URL: \url{https://personalpages.manchester.ac.uk/staff/georgi.boshnakov/} } <>= library(Rdpack) pd <- packageDescription("Rdpack") @ \Abstract{ Package \pkg{Rdpack} provides a straightforward way to insert BibTeX references in the documentation of an R package, using the RdMacros feature introduced in R~3.2.0. It works for `roxygen2' documentation, as well. \par This vignette is part of package Rdpack, version~\Sexpr{pd$Version}. } \Keywords{bibliographic references, Rd, bibtex, citations, \proglang{R}} \Plainkeywords{bibliographic references, Rd, bibtex, citations, R} \author{Georgi N. Boshnakov} \date{\today} \title{Inserting references in Rd and roxygen2 documentation} \hypersetup{ pdfauthor={Georgi N. Boshnakov}, pdftitle={Inserting references in Rd and roxygen2 documentation}, pdfkeywords={bibliographic references, Rd, bibtex, citations, R}, pdfsubject={}, pdfcreator={Emacs 26.3 (Org mode 9.1.9)}, pdflang={English}} \begin{document} \maketitle %\SweaveOpts{engine=R,eps=FALSE} %\VignetteIndexEntry{Inserting references in Rd and roxygen2 documentation} %\VignetteDepends{Rdpack} %\VignetteKeywords{bibliographic references, Rd, bibtex, citations, R} %\VignettePackage{Rdpack} \section{Setup} \label{sec:org778a336} To prepare a package for importing BibTeX references it is necessary to tell the package management tools that package \pkg{Rdpack} and its Rd macros are needed. The references should be put in file \texttt{inst/REFERENCES.bib}. These steps are enumerated below in somewhat more detail for convenince: \begin{enumerate} \item Add the following lines to file `DESCRIPTION': \begin{verbatim} Imports: Rdpack RdMacros: Rdpack \end{verbatim} Make sure the capitalisation of \texttt{RdMacros} is as shown. If the field 'RdMacros' is already present, add `Rdpack' to the list on that line. Similarly for field 'Imports'. \item Add the following line to file `NAMESPACE'\footnote{Any function for package \pkg{Rdpack} will do. This is to avoid getting a warning from 'R CMD check'.}: \begin{verbatim} importFrom(Rdpack,reprompt) \end{verbatim} The equivalent line for `roxygen2' is \begin{verbatim} #' @importFrom Rdpack reprompt \end{verbatim} \item Create file \texttt{REFERENCES.bib} in subdirectory \texttt{inst/} of your package and put the bibtex references in it. \end{enumerate} \section{Inserting references in package documentation} \label{sec:orgd4ad0fc} Once the steps outlined in the previous section are done, references can be inserted in the documentation as \texttt{\textbackslash{}insertRef\{key\}\{package\}}, where \texttt{key} is the bibtex key of the reference and \texttt{package} is your package. This works in Rd files and in roxygen documentation chunks. In fact, argument 'package' can be any installed R package\footnote{There is of course the risk that the referenced entry may be removed from the other package. So this is probably only useful for one's own packages. Also, the other package would better be one of the packages mentioned in DESCRIPTION.\}}, not necessarily the current one. This means that you don't need to copy references from other packages to your \texttt{"REFERENCES.bib"} file. This works for packages that have \texttt{"REFERENCES.bib"} in their installation directory and for the default packages. See also the help pages \texttt{?Rdpack::insertRef} and \texttt{?Rdpack::Rdpack-package}. For example, the help page \texttt{?Rdpack::insertRef} contains the following lines in section ``References'' of the Rd file: \begin{verbatim} \insertRef{Rpack:bibtex}{Rdpack} \end{verbatim} The first line above inserts the reference labeled \texttt{Rpack:bibtex} in Rdpack's \texttt{REFERENCES.bib}. The second line inserts the reference labeled \texttt{R} in file \texttt{REFERENCES.bib} in package `bibtex'. A roxygen2 documentation chunk might look like this: \begin{verbatim} #' @references #' \insertRef{Rpack:bibtex}{Rdpack} \end{verbatim} \section{Inserting citations} \label{sec:orgb97375b} From version 0.7 of \pkg{Rdpack}, additional Rd macros are available for citations\footnote{They were introduced in the development version 0.6-1, but 0.7 is the first version with them released on CRAN.}. They can be used in both Rd and roxygen2 documentation. If you are using these, it will be prudent to require at least this version of Rdpack in the ``Imports:'' directive in file DESCRIPTION: \texttt{Rdpack (>= 0.7)}. \subsection{Macros for citations} \label{sec:org3007a43} \label{sec:macros-citations} \texttt{\textbackslash{}insertCite\{key\}\{package\}} cites the key and records it for use by \texttt{\textbackslash{}insertAllCited\{\}}, see below. The style of the citations is author-year. The ''et al'' convention is used when there are more than two authors\footnote{This feature was introduced in Rdpack 0.8-2.}. \code{key} can contain more keys separated by commas. Here are some examples (on the left is the code in the documentation chunk, on the right the rendered citation): \begin{center} \begin{tabular}{ll} Documentation source & rendered\\ \hline \texttt{\textbackslash{}insertCite\{parseRd\}\{Rdpack\}} & (Murdoch 2010)\\ \texttt{\textbackslash{}insertCite\{Rpack:bibtex\}\{Rdpack\}} & (Francois 2014)\\ \texttt{\textbackslash{}insertCite\{parseRd,Rpack:bibtex\}\{Rdpack\}} & (Murdoch 2010; Francois 2014)\\ \end{tabular} \end{center} By default the citations are parenthesised \texttt{\textbackslash{}insertCite\{parseRd\}\{Rdpack\}} produces \Sexpr{ insert_citeOnly("parseRd", "Rdpack") }, as in the examples above. To get textual citations, like \Sexpr{ insert_citeOnly("parseRd;textual", "Rdpack") }, put the string \texttt{;textual} at the end of the key. Here are the examples from the table above, rendered as textual citations: \begin{center} \begin{tabular}{ll} Documentation source & rendered\\ \hline \texttt{\textbackslash{}insertCite\{parseRd;textual\}\{Rdpack\}} & Murdoch (2010)\\ \texttt{\textbackslash{}insertCite\{Rpack:bibtex;textual\}\{Rdpack\}} & Francois (2014)\\ \texttt{\textbackslash{}insertCite\{parseRd,Rpack:bibtex;textual\}\{Rdpack\}} & Murdoch (2010); Francois (2014)\\ \end{tabular} \end{center} The last line in the table demonstrates that this also works with several citations. 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 \texttt{@} and prefixing each key with it. The \texttt{@} symbol will not appear in the output. For example, the following code: \begin{verbatim} \insertCite{@see also @parseRd and @Rpack:bibtex}{Rdpack} \insertCite{@see also @parseRd; @Rpack:bibtex}{Rdpack} \insertCite{@see also @parseRd and @Rpack:bibtex;textual}{Rdpack} \end{verbatim} produces: \qquad \begin{tabular}{l} Rendered\\ \hline \Sexpr{insert_citeOnly("@see also @parseRd and @Rpack:bibtex", "Rdpack")}\\ \Sexpr{insert_citeOnly("@see also @parseRd; @Rpack:bibtex", "Rdpack")}\\ \Sexpr{insert_citeOnly("@see also @parseRd and @Rpack:bibtex;textual", "Rdpack")}\\ \end{tabular} The text of the arguments of the macro in this free form should have no markup. For example, if you want to put the phrase \texttt{see also} in italic, enclosing it with \texttt{\textbackslash{}emph\{...\}} (in Rd) or the equivalent \texttt{\_...\_} (in markdown) will not work\footnote{For details see \href{https://github.com/GeoBosh/Rdpack/issues/23}{Github issue \#23} raised by Martin R. Smith.}. For textual citations a workaround is to invoke \texttt{\textbackslash{}insertCite} for each key and type the markup outside the macro arguments. For parenthetical citations the solutions is to ask \texttt{\textbackslash{}insertCite} to omit the parentheses by putting \texttt{;nobrackets} at the end of the argument\footnote{With \pkg{Rdpack} versions greater than 2.1.3.}. The parentheses can then be put manually where needed. For example, \begin{verbatim} (\emph{see also} \insertCite{@@parseRd and @Rpack:bibtex;nobrackets}{Rdpack}) \end{verbatim} produces: (\emph{see also} \Sexpr{insert_citeOnly("@@parseRd and @Rpack:bibtex;nobrackets", "Rdpack")}). \subsubsection{Further macros for citations} \label{sec:org89632ba} The macro \texttt{\textbackslash{}insertNoCite\{key\}\{package\}} records one or more references for \texttt{\textbackslash{}insertAllCited} but does not cite it. Setting \texttt{key} to \texttt{*} will record all references from the specified package. For example, \texttt{\textbackslash{}insertNoCite\{R\}\{bibtex\}} records the reference whose key is \texttt{R}, while \texttt{\textbackslash{}insertNoCite\{*\}\{utils\}} records all references from package ``utils'' for inclusion by \texttt{\textbackslash{}insertAllCited}. \texttt{\textbackslash{}insertCiteOnly\{key\}\{package\}} is as \texttt{\textbackslash{}insertCite} but does not record the key for the list of references assembled by \texttt{\textbackslash{}insertAllCited}. \subsection{Automatically generating lists of references} \label{sec:orgfdcfa4f} The macro \texttt{\textbackslash{}insertAllCited\{\}} can be used to insert all references cited with \texttt{\textbackslash{}insertCite} or \texttt{\textbackslash{}insertNoCite}. A natural place to put this macro is the references section. The Rd section may look something like: \begin{verbatim} \references{ \insertAllCited{} } \end{verbatim} The analogous documentation chunk in roxygen2 might look like this: \begin{verbatim} #' @references #' insertAllCited{} \end{verbatim} Don't align the backslash with the second 'e' of \texttt{@references}, since roxygen2 may interpret it as verbatim text, not macro. Rd macro \texttt{\textbackslash{}insertCited\{\}} works like \texttt{\textbackslash{}insertAllCited} but empties the references list after finishing its work. This means that the second and subsequent \texttt{\textbackslash{}insertCited} in the same help page will list only citations done since the preceding \texttt{\textbackslash{}insertCited}. Prompted by issue 27 on github to allow separate references lists for each method and the class in R6 documentation. \subsection{Changing the style of references} \label{sec:orgb5b1c57} Package \texttt{Rdpack} supports bibliography styles for lists of references\footnote{Support for styles is available since \texttt{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 \texttt{\textbackslash{}insertAllCited} in a package to appear with full names, add \texttt{.onLoad()} function to your package. If you don't have \texttt{.onLoad()}, just copy the following definition: <<>>= .onLoad <- function(lib, pkg){ Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames") invisible(NULL) } @ %def If you already have \texttt{.onLoad()}, add the line containing the \texttt{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. \section{Possible issues} \label{sec:org98c15ef} \subsection{Warning from 'R CMD build'} \label{sec:org5c929bd} If 'R CMD build' or \texttt{devtools::build()} gives a warning along the lines of: \begin{verbatim} Warning: C:/temp/RtmpqWQqji/.../XXX.Rd:52: unknown macro '\insertRef' \end{verbatim} then check the syntax in file DESCRIPTION --- the most common cause of this is misspelling \texttt{RdMacros:}. Make sure in particular that `M' is uppercase. \subsection{Development using `devtools'} \label{sec:org9e2f214} The described procedure works transparently in `roxygen2' chunks and with Hadley Wickham's `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 \texttt{?xxx} for functions from the package you are working on and their help pages contain references, you may encounter some puzzling warning messages in `developer' mode, something like: \begin{verbatim} 1: In tools::parse_Rd(path) : ~/mypackage/man/abcde.Rd: 67: unknown macro '\insertRef' \end{verbatim} These warnings are again about unknown macros but the reason is completely different: they pop up 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 \texttt{parse\_Rd} where to look for additional macros\footnote{The claims in this sentence can be deduced entirely from the informative message. Indeed, (1)\textasciitilde{}the error is in processing a source Rd file in the development directory of the package, and (2)\textasciitilde{}the call to \texttt{\textbackslash{}parse\_Rd} specifies only the file.}. These warnings are harmless - the help pages are built properly and no warnings appear outside ``developer'' mode, e.g. in a separate R\textasciitilde{}session. You may also consider using the function \texttt{viewRd()}, discussed below, for viewing Rd files. \subsection{Latex markup in BibTeX entries} \label{sec:org83922f5} 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\footnote{Thanks to Michael Dewey for suggesting the discussion of this.}. Only do this for entries that do not render properly or cause errors, since most of the time this should not be necessary. For encoding related issues of REFERENCES.bib see the dedicated subsection below. If mathematics doesn't render properly replace the Latex dollar syntax with Rd's \texttt{\textbackslash{}eqn}, e.g. \texttt{\$x\textasciicircum{}2\$} with \texttt{\textbackslash{}eqn\{x\textasciicircum{}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. \texttt{\textbackslash{}doi}. See also the overview help page, \code{help("Rdpack-package")}, of \pkg{Rdpack}. Among other things, it contains some dummy references which illustrate the above. \subsection{Encoding of file REFERENCES.bib} \label{sec:org663630e} If a package has a declared encoding (in file \texttt{DESCRIPTION}), \texttt{REFERENCES.bib} is read-in with that encoding\footnote{From \texttt{Rdpack (>=0.9-1)} The issue of not handling the encoding was raised by Professor Brian Ripley.}. Otherwise, the encoding of \texttt{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: \begin{verbatim} prepare_Rd: input string 1 is invalid in this locale \end{verbatim} 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 \texttt{tools::showNonASCIIfile()}. Since \pkg{Rdpack} switched to the bibtex parser in package \pkg{rbibutils}, if the bib file contains Latex escape sequences standing for accented Latin characters, such as \texttt{\textbackslash{}'e} and \texttt{\textbackslash{}"o}, they are imported as is. They are converted to UTF-8 only when the text is rendered for output. If R's checking tools complain about non-ASCII characters add the following encoding declaration to file DESCRIPTION\footnote{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.}: \begin{verbatim} Encoding: UTF-8 \end{verbatim} Needless to say, make sure that there are really no characters from encodings like 'latin1'. With the previous bibtex parser (before Rdpack version 1.1.0) the conversion was done earlier, which resulted in confusing messages about non-ASCII characters, even when the file REFERENCES.bib was pure ASCII. This should no longer happen. \section{Viewing Rd files} \label{sec:org54eca5d} A function, \code{viewRd}, to view Rd files in the source directory of a package was introduced in version 0.4-23 of \pkg{Rdpack}. A typical user call would look something like: \begin{verbatim} Rdpack::viewRd("./man/filename.Rd") \end{verbatim} By default the requested help page is shown in text format. To open the page in a browser, set argument \code{type} to \code{"html"}: \begin{verbatim} Rdpack::viewRd("./man/filename.Rd", type = "html") \end{verbatim} Users of 'devtools' can use \code{viewRd()} in place of \code{help()} to view Rd sources\footnote{Yes, your real sources are the \texttt{*.R} files but \code{devtools::document()} transfers the roxygen2 documentation chunks to Rd files (and a few others), which are then rendered by \pkg{R} tools.}. \end{document} Rdpack/vignettes/Inserting_figures_and_evaluated_examples.Rnw0000644000176200001440000001656215134450641024433 0ustar liggesusers% Created 2026-01-22 Thu 16:34 % Intended LaTeX compiler: pdflatex \documentclass[a4paper,twoside,11pt,nojss,article]{jss} \usepackage[T1]{fontenc} \usepackage[left=2cm,right=2cm,bottom=15mm]{geometry} \usepackage{graphicx,color,alltt} \usepackage[authoryear,round,longnamesfirst]{natbib} \usepackage{hyperref} % \usepackage{Sweave} \author{Georgi N. Boshnakov} \Plainauthor{Georgi N. Boshnakov} \Address{ Georgi N. Boshnakov\\ School of Mathematics\\ The University of Manchester\\ Oxford Road, Manchester M13 9PL, UK\\ URL: \url{https://personalpages.manchester.ac.uk/staff/georgi.boshnakov/} } <>= library(Rdpack) pd <- packageDescription("Rdpack") @ \Abstract{ This vignette discusses Rd macros provided by package \pkg{Rdpack} for inserting evaluated examples and programmatically created figures. These macros are convenience wrappers around the native capabilities provided by the Rd parser. The macros work in Rd files and roxygen2 comments. \par This vignette is part of package Rdpack, version~\Sexpr{pd$Version}. } \Keywords{examples, graphics, figures, Rd, R} \Plainkeywords{examples, graphics, figures, Rd, R} \author{Georgi N. Boshnakov} \date{\today} \title{Inserting figures and evaluated examples} \hypersetup{ pdfauthor={Georgi N. Boshnakov}, pdftitle={Inserting figures and evaluated examples}, pdfkeywords={examples, graphics, figures, Rd, R}, pdfsubject={}, pdfcreator={Emacs 30.2 (Org mode 9.7.11)}, pdflang={English}} \begin{document} \maketitle %\SweaveOpts{engine=R,eps=FALSE} %\VignetteIndexEntry{Inserting figures and evaluated examples} %\VignetteDepends{Rdpack} %\VignetteKeywords{examples, graphics, figures, Rd, R} %\VignettePackage{Rdpack} \section{Evaluated examples} \label{sec:orgc1085d5} Sometimes the documentation of an object becomes more clear if accompanied by snippets of R code and their results. The standard Rd macro \texttt{\textbackslash{}Sexpr} caters for a number of possibilities to evaluate R code and insert the results and the code in the documentation. The Rd macro \texttt{\textbackslash{}printExample} provided by package \texttt{"Rdpack"} builds on it to print a snippet of R code and the results of its evaluation. For example, \begin{verbatim} \printExample{2+2; a <- 2*3; a} \end{verbatim} gives \begin{verbatim} 2 + 2 ##: 4 a <- 2 * 3 a ##: 6 \end{verbatim} Note that each command is printed on a separate line even though in this example the source code is on a single line, separated by semicolons\footnote{The argument of \texttt{\textbackslash{}printExample} needed to be on a single line with versions of R before \texttt{R-3.6.0}, since the lines after the first were silently ignored, with no errors and no warnings. This should not be a concern if your package requires \texttt{R >= 3.6.0} anyway or if you can live with somewhat inferior documentation in older versions or \texttt{R}.}. Similarly to \texttt{knitr}, the results are prefixed with comment symbols but the code is not prefixed with anything. The help page of \texttt{?Rdpack::promptUsage} contains a number of examples created with \texttt{\textbackslash{}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}. \section{Section examples with results} \label{sec:org26259f1} The macro \texttt{\textbackslash{}printExample} can be used as many times as needed and is typically placed in section \emph{Details} of an object's documentation. In contrast, the macro \texttt{\textbackslash{}runExamples} can be used as a replacement of the whole \texttt{\textbackslash{}examples} section in the Rd file. The code and its results are printed just as by \texttt{\textbackslash{}printExample}. For example, if the following code is put at the top level in an Rd file (i.e. not in a section): \begin{verbatim} \runExamples{2+2; a <- 2*3; a} \end{verbatim} then it will be evaluated and replaced by a normal section examples: \begin{verbatim} \examples{ 2 + 2 ##: 4 a <- 2 * 3 a ##: 6 } \end{verbatim} 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\footnote{In versions of R before 3.6.0, \texttt{R CMD check} used to give warnings about unknown \texttt{\textbackslash{}Sexpr} section at top level. See also the note about multiline argument for \texttt{\textbackslash{}printExample}.}. A small example package using this feature is at \href{https://github.com/GeoBosh/reprexes/tree/master/runExamplesCheck}{runExamplesCheck}. \section{Creating and including graphs} \label{sec:orgebef252} Figures can be inserted with the help of the standard Rd markup command \texttt{\textbackslash{}figure}. The Rd macro \texttt{\textbackslash{}insertFig} provided by package \pkg{Rdpack} takes a snipped of R code, evaluates it and inserts the plot produced by it (using \texttt{\textbackslash{}figure}). \texttt{\textbackslash{}insertFig} takes three arguments: a filename, the package name and the code to evaluate to produce the figure. For example, \begin{verbatim} \insertFig{cars.png}{mypackage}{x <- cars$speed; y <- cars$dist; plot(x,y)} \end{verbatim} will evaluate the code\footnote{See also the remark about using miltiline code in \texttt{\textbackslash{}printExample}. For figures this is not a problem at all even in older versions of R, since all preparatory code can be put in a separate \texttt{\textbackslash{}Sexpr}, and then \texttt{\textbackslash{}insertFig} can be given only the final command producing the graph.}, save the graph in file \texttt{"man/figures/cars.png"} subdirectory of package \texttt{"mypackage"}, and include the figure using \texttt{\textbackslash{}figure}. Subdirectory \texttt{"figures"} is created if it doesn't exist. Currently the graphs are saved in \texttt{"png"} format only. The sister macro \texttt{\textbackslash{}makeFig} creates the graph in exactly the same way as \texttt{\textbackslash{}insertFig} but does not insert it. This can be done with a separate \texttt{\textbackslash{}figure} command. This can be used if additional options are desired for different output formats, see the description of \texttt{\textbackslash{}figure} in "Writing R extensions". \subsection{A technical note} \label{sec:org8441c26} The above description should just work. This note is for users who wonder about technicalities. The R documentation can be built in many ways and as a result the directory \texttt{"man/figures/"} does not necessarily refer to the developers source package. Indeed, when a package is built, R works on a modified and cleaned-up temporary copy of the source directory, so the figures are created in that copy and then included in the package tarball. Similarly during the package check. On the other hand, \texttt{R CMD Rd2pdf} and some other tools and R functions work directly on the source tree of the package and they will create the figures there. The net effect is that a package tarball always contains freshly generated up-to-date graphs. Developers who never generate the documentation by other means may not even have the directory \texttt{man/figures} in the source tree of their package (but it will be present in the package tarball). \newpage \end{document} Rdpack/vignettes/Inserting_figures_and_evaluated_examples.org0000644000176200001440000001711615134450444024451 0ustar liggesusers#+PROPERTY: header-args:R :cache yes :session ravel01-r :results value :exports both #+OPTIONS: toc:nil #+LaTeX_CLASS: Rvignette #+LaTeX_CLASS_OPTIONS: [a4paper,twoside,11pt,nojss,article] #+TITLE: Inserting figures and evaluated examples #+AUTHOR: Georgi N. Boshnakov #+MACRO: keywords examples, graphics, figures, Rd, R #+MACRO: Rpackage Rdpack #+KEYWORDS: examples, graphics, figures, Rd, R #+LATEX_HEADER: % \usepackage{Sweave} #+LATEX_HEADER: \author{Georgi N. Boshnakov} #+LATEX_HEADER: \Plainauthor{Georgi N. Boshnakov} #+LATEX_HEADER: \Address{ #+LATEX_HEADER: Georgi N. Boshnakov\\ #+LATEX_HEADER: School of Mathematics\\ #+LATEX_HEADER: The University of Manchester\\ #+LATEX_HEADER: Oxford Road, Manchester M13 9PL, UK\\ #+LATEX_HEADER: URL: \url{https://personalpages.manchester.ac.uk/staff/georgi.boshnakov/} #+LATEX_HEADER: } #+LATEX_HEADER: <>= #+LATEX_HEADER: library(Rdpack) #+LATEX_HEADER: pd <- packageDescription("Rdpack") #+LATEX_HEADER: @ #+LATEX_HEADER: \Abstract{ #+LATEX_HEADER: This vignette discusses Rd macros provided by package \pkg{Rdpack} for #+LATEX_HEADER: inserting evaluated examples and programmatically created figures. These #+LATEX_HEADER: macros are convenience wrappers around the native capabilities provided #+LATEX_HEADER: by the Rd parser. The macros work in Rd files and roxygen2 comments. #+LATEX_HEADER: \par #+LATEX_HEADER: This vignette is part of package Rdpack, version~\Sexpr{pd$Version}. #+LATEX_HEADER: } #+LATEX_HEADER: #+LATEX_HEADER: \Keywords{examples, graphics, figures, Rd, R} #+LATEX_HEADER: \Plainkeywords{examples, graphics, figures, Rd, R} @@latex:%@@\SweaveOpts{engine=R,eps=FALSE} @@latex:%@@\VignetteIndexEntry{{{{title}}}} @@latex:%@@\VignetteDepends{{{{Rpackage}}}} @@latex:%@@\VignetteKeywords{{{{keywords}}}} @@latex:%@@\VignettePackage{{{{Rpackage}}}} #+BEGIN_SRC R :results value silent :exports none library(Rdpack) pd <- packageDescription("Rdpack") #+END_SRC * 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 ~\Sexpr~ caters for a number of possibilities to evaluate R code and insert the results and the code in the documentation. The Rd macro ~\printExample~ provided by package ="Rdpack"= builds on it to print a snippet of R code and the results of its evaluation. For example, #+BEGIN_EXAMPLE \printExample{2+2; a <- 2*3; a} #+END_EXAMPLE gives #+BEGIN_EXAMPLE 2 + 2 ##: 4 a <- 2 * 3 a ##: 6 #+END_EXAMPLE Note that each command is printed on a separate line even though in this example the source code is on a single line, separated by semicolons[fn:1]. Similarly to =knitr=, the results are prefixed with comment symbols but the code is not prefixed with anything. The help page of ~?Rdpack::promptUsage~ contains a number of examples created with ~\printExample~. The corresponding Rd file can be obtained from the package tarball or from https://github.com/GeoBosh/Rdpack/blob/master/man/promptUsage.Rd. [fn:1] The argument of ~\printExample~ needed to be on a single line with versions of R before =R-3.6.0=, since the lines after the first were silently ignored, with no errors and no warnings. This should not be a concern if your package requires ~R >= 3.6.0~ anyway or if you can live with somewhat inferior documentation in older versions or =R=. # The argument of ~\printExample~ must be on a single line with released versions of R. # This limitation has been lifted in =R-devel= starting from June 2018 and in =R-3.6.0=. # # From NEWS in R 3.6.0: User macros in Rd files now accept empty and multi-line arguments * Section examples with results The macro ~\printExample~ can be used as many times as needed and is typically placed in section /Details/ of an object's documentation. In contrast, the macro ~\runExamples~ can be used as a replacement of the whole ~\examples~ section in the Rd file. The code and its results are printed just as by ~\printExample~. For example, if the following code is put at the top level in an Rd file (i.e. not in a section): #+BEGIN_EXAMPLE \runExamples{2+2; a <- 2*3; a} #+END_EXAMPLE then it will be evaluated and replaced by a normal section examples: #+BEGIN_EXAMPLE \examples{ 2 + 2 ##: 4 a <- 2 * 3 a ##: 6 } #+END_EXAMPLE 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[fn:2]. A small example package using this feature is at [[https://github.com/GeoBosh/reprexes/tree/master/runExamplesCheck][runExamplesCheck]]. [fn:2] In versions of R before 3.6.0, ~R CMD check~ used to give warnings about unknown ~\Sexpr~ section at top level. See also the note about multiline argument for ~\printExample~. # (Amendment on 2018-10-11: R-devel does no longer give the warning at least since 2018-10-02 # r75388.) # # According to the specification of the Rd format (see [[https://developer.r-project.org/parseRd.pdf][Murdoch (2010), p. 4]] ~\Sexpr~'s at top # level are legal. I need to check with the CRAN team or R devel if such expressions # produced by user macros are excluded on purpose. * Creating and including graphs Figures can be inserted with the help of the standard Rd markup command ~\figure~. The Rd macro ~\insertFig~ provided by package \pkg{Rdpack} takes a snipped of R code, evaluates it and inserts the plot produced by it (using ~\figure~). ~\insertFig~ takes three arguments: a filename, the package name and the code to evaluate to produce the figure. For example, #+BEGIN_EXAMPLE \insertFig{cars.png}{mypackage}{x <- cars$speed; y <- cars$dist; plot(x,y)} #+END_EXAMPLE will evaluate the code[fn:3], save the graph in file ~"man/figures/cars.png"~ subdirectory of package ~"mypackage"~, and include the figure using ~\figure~. Subdirectory ~"figures"~ is created if it doesn't exist. Currently the graphs are saved in ~"png"~ format only. The sister macro ~\makeFig~ creates the graph in exactly the same way as ~\insertFig~ but does not insert it. This can be done with a separate ~\figure~ command. This can be used if additional options are desired for different output formats, see the description of ~\figure~ in "Writing R extensions". [fn:3] See also the remark about using miltiline code in =\printExample=. For figures this is not a problem at all even in older versions of R, since all preparatory code can be put in a separate =\Sexpr=, and then =\insertFig= can be given only the final command producing the graph. ** A technical note The above description should just work. This note is for users who wonder about technicalities. The R documentation can be built in many ways and as a result the directory ~"man/figures/"~ does not necessarily refer to the developers source package. Indeed, when a package is built, R works on a modified and cleaned-up temporary copy of the source directory, so the figures are created in that copy and then included in the package tarball. Similarly during the package check. On the other hand, ~R CMD Rd2pdf~ and some other tools and R functions work directly on the source tree of the package and they will create the figures there. The net effect is that a package tarball always contains freshly generated up-to-date graphs. Developers who never generate the documentation by other means may not even have the directory ~man/figures~ in the source tree of their package (but it will be present in the package tarball). # To avoid splitting 'Affiliation' on two pages #+BEGIN_EXPORT latex \newpage #+END_EXPORT Rdpack/vignettes/Inserting_bibtex_references.org0000644000176200001440000004767715134452054021727 0ustar liggesusers#+PROPERTY: header-args:R :cache yes :session ravel01-r :results value :exports both #+OPTIONS: toc:nil #+LaTeX_CLASS: Rvignette #+LaTeX_CLASS_OPTIONS: [a4paper,twoside,11pt,nojss,article] #+TITLE: Inserting references in Rd and roxygen2 documentation #+AUTHOR: Georgi N. Boshnakov #+MACRO: keywords bibliographic references, Rd, bibtex, citations, R #+MACRO: Rpackage Rdpack #+KEYWORDS: bibliographic references, Rd, bibtex, citations, R #+LATEX_HEADER: % \usepackage{Sweave} #+LATEX_HEADER: \author{Georgi N. Boshnakov} #+LATEX_HEADER: \Plainauthor{Georgi N. Boshnakov} #+LATEX_HEADER: \Address{ #+LATEX_HEADER: Georgi N. Boshnakov\\ #+LATEX_HEADER: School of Mathematics\\ #+LATEX_HEADER: The University of Manchester\\ #+LATEX_HEADER: Oxford Road, Manchester M13 9PL, UK\\ #+LATEX_HEADER: URL: \url{https://personalpages.manchester.ac.uk/staff/georgi.boshnakov/} #+LATEX_HEADER: } #+LATEX_HEADER: <>= #+LATEX_HEADER: library(Rdpack) #+LATEX_HEADER: pd <- packageDescription("Rdpack") #+LATEX_HEADER: @ #+LATEX_HEADER: \Abstract{ #+LATEX_HEADER: Package \pkg{Rdpack} provides a straightforward way to insert BibTeX references in the #+LATEX_HEADER: documentation of an R package, using the RdMacros feature introduced in R~3.2.0. It #+LATEX_HEADER: works for `roxygen2' documentation, as well. #+LATEX_HEADER: \par #+LATEX_HEADER: This vignette is part of package Rdpack, version~\Sexpr{pd$Version}. #+LATEX_HEADER: } #+LATEX_HEADER: #+LATEX_HEADER: \Keywords{bibliographic references, Rd, bibtex, citations, \proglang{R}} #+LATEX_HEADER: \Plainkeywords{bibliographic references, Rd, bibtex, citations, R} @@latex:%@@\SweaveOpts{engine=R,eps=FALSE} @@latex:%@@\VignetteIndexEntry{{{{title}}}} @@latex:%@@\VignetteDepends{{{{Rpackage}}}} @@latex:%@@\VignetteKeywords{{{{keywords}}}} @@latex:%@@\VignettePackage{{{{Rpackage}}}} # DO NOT CHANGE Latex to LaTeX since Org-ravle changes this to \LaTeX{}, a command which # seems to cause problems with this LaTeX style. #+BEGIN_SRC R :results value silent :exports none library(Rdpack) pd <- packageDescription("Rdpack") #+END_SRC * Setup To prepare a package for importing BibTeX references it is necessary to tell the package management tools that package \pkg{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 for convenince: 1. Add the following lines to file `DESCRIPTION': #+BEGIN_EXAMPLE Imports: Rdpack RdMacros: Rdpack #+END_EXAMPLE 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'[fn:2]: #+BEGIN_EXAMPLE importFrom(Rdpack,reprompt) #+END_EXAMPLE The equivalent line for `roxygen2' is #+BEGIN_EXAMPLE #' @importFrom Rdpack reprompt #+END_EXAMPLE 3. Create file =REFERENCES.bib= in subdirectory =inst/= of your package and put the bibtex references in it. # [fn:1] Currently `R CMD check' doesn't complain if you don't import `Rdpack', # as long as `Rdpack' is installed on the system (yours, CRAN, win-builder, # etc.). However, services like `appveyor' or `travis-ci' do raise # errors. Thanks to Clemens Schmid and Tim Riffe for allerting me about this. [fn:2] Any function for package \pkg{Rdpack} will do. This is to avoid getting a warning from 'R CMD check'. * Inserting references in package documentation Once the steps outlined in the previous section 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. In fact, argument 'package' can be any installed R package[fn:3], not necessarily the current one. This means that you don't need to copy references from other packages to your ="REFERENCES.bib"= file. This works for packages that have ="REFERENCES.bib"= in their installation directory and for the default packages. See also the help pages ~?Rdpack::insertRef~ and ~?Rdpack::Rdpack-package~. For example, the help page ~?Rdpack::insertRef~ contains the following lines in section ``References'' of the Rd file: #+BEGIN_EXAMPLE \insertRef{Rpack:bibtex}{Rdpack} #+END_EXAMPLE The first line above inserts the reference labeled =Rpack:bibtex= in Rdpack's =REFERENCES.bib=. The second line inserts the reference labeled =R= in file =REFERENCES.bib= in package `bibtex'. A roxygen2 documentation chunk might look like this: #+BEGIN_EXAMPLE #' @references #' \insertRef{Rpack:bibtex}{Rdpack} #+END_EXAMPLE # %\paragraph*{Note:} # % 2017-08-04 commented out, # % The references are processed when the package is built. So, there is \emph{no need} to # % depend/import/suggest package ="Rdpack"=, it only needs to be installed on your machine. [fn:3] There is of course the risk that the referenced entry may be removed from the other package. So this is probably only useful for one's own packages. Also, the other package would better be one of the packages mentioned in DESCRIPTION.} * Inserting citations From version 0.7 of \pkg{Rdpack}, additional Rd macros are available for citations[fn:4]. They can be used in both Rd and roxygen2 documentation. If you are using these, it will be prudent to require at least this version of Rdpack in the ``Imports:'' directive in file DESCRIPTION: ~Rdpack (>= 0.7)~. [fn:4] They were introduced in the development version 0.6-1, but 0.7 is the first version with them released on CRAN. ** Macros for citations \label{sec:macros-citations} ~\insertCite{key}{package}~ cites the key and records it for use by ~\insertAllCited{}~, see below. The style of the citations is author-year. The ''et al'' convention is used when there are more than two authors[fn:etal]. [fn:etal] This feature was introduced in Rdpack 0.8-2. \code{key} can contain more keys separated by commas. Here are some examples (on the left is the code in the documentation chunk, on the right the rendered citation): # \begin{center} # \begin{tabular}{l|l} # Documentation source & rendered \\ \hline # =\insertCite{parseRd}{Rdpack}= & # \Sexpr{insert_citeOnly("parseRd", "Rdpack")} \\ # =\insertCite{Rpack:bibtex}{Rdpack}= & # \Sexpr{insert_citeOnly("Rpack:bibtex", "Rdpack")} \\ # =\insertCite{parseRd,Rpack:bibtex}{Rdpack}= & # \Sexpr{insert_citeOnly("parseRd,Rpack:bibtex", "Rdpack")} # \end{tabular} # \end{center} # # By default the citations are parenthesised =\insertCite{parseRd}{Rdpack}= produces # \Sexpr{insert_citeOnly("parseRd", "Rdpack")}, as in the examples above. To get textual # citations, like \Sexpr{insert_citeOnly("parseRd;textual", "Rdpack")} put the string # \code{;textual} at the end of the key. Here are the examples from the table above, rendered # as textual citations: # \begin{center} # \begin{tabular}{l|l} # Documentation source & rendered \\ \hline # =\insertCite{parseRd;textual}{Rdpack}= & # \Sexpr{insert_citeOnly("parseRd;textual", "Rdpack")} \\ # =\insertCite{Rpack:bibtex;textual}{Rdpack}= & # \Sexpr{insert_citeOnly("Rpack:bibtex;textual", "Rdpack")} \\ # =\insertCite{parseRd,Rpack:bibtex;textual}{Rdpack}= & # \Sexpr{insert_citeOnly("parseRd,Rpack:bibtex;textual", "Rdpack")} # \end{tabular} # \end{center} #+name: R-inscite #+BEGIN_SRC R :var x="", textual=0 :results value silent :exports none insert_citeOnly(if(textual == 0) x else paste0(x, ";textual"), "Rdpack") #+END_SRC | Documentation source | rendered | |---------------------------------------------+-------------------------------| | ~\insertCite{parseRd}{Rdpack}~ | (Murdoch 2010) | | ~\insertCite{Rpack:bibtex}{Rdpack}~ | (Francois 2014) | | ~\insertCite{parseRd,Rpack:bibtex}{Rdpack}~ | (Murdoch 2010; Francois 2014) | #+TBLFM: @2$2='(org-sbe "R-inscite" (x "\"parseRd\""))::@3$2='(org-sbe "R-inscite" (x "\"Rpack:bibtex\""))::@4$2='(org-sbe "R-inscite" (x "\"parseRd,Rpack:bibtex\"")) By default the citations are parenthesised =\insertCite{parseRd}{Rdpack}= produces src_R{insert_citeOnly("parseRd", "Rdpack")}, as in the examples above. To get textual citations, like src_R{insert_citeOnly("parseRd;textual", "Rdpack")}, put the string =;textual= at the end of the key. Here are the examples from the table above, rendered as textual citations: | Documentation source | rendered | |-----------------------------------------------------+---------------------------------| | ~\insertCite{parseRd;textual}{Rdpack}~ | Murdoch (2010) | | ~\insertCite{Rpack:bibtex;textual}{Rdpack}~ | Francois (2014) | | ~\insertCite{parseRd,Rpack:bibtex;textual}{Rdpack}~ | Murdoch (2010); Francois (2014) | #+TBLFM: @2$2='(org-sbe "R-inscite" (x "\"parseRd\"") (textual 1))::@3$2='(org-sbe "R-inscite" (x "\"Rpack:bibtex\"") (textual 1))::@4$2='(org-sbe "R-inscite" (x "\"parseRd,Rpack:bibtex\"") (textual 1)) The last line in the table demonstrates that this also works with several citations. 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: #+BEGIN_EXAMPLE \insertCite{@see also @parseRd and @Rpack:bibtex}{Rdpack} \insertCite{@see also @parseRd; @Rpack:bibtex}{Rdpack} \insertCite{@see also @parseRd and @Rpack:bibtex;textual}{Rdpack} #+END_EXAMPLE produces: \qquad #+ATTR_LATEX: :center nil | Rendered | |-----------------------------------------------------------------------------------| | \Sexpr{insert_citeOnly("@see also @parseRd and @Rpack:bibtex", "Rdpack")} | | \Sexpr{insert_citeOnly("@see also @parseRd; @Rpack:bibtex", "Rdpack")} | | \Sexpr{insert_citeOnly("@see also @parseRd and @Rpack:bibtex;textual", "Rdpack")} | The text of the arguments of the macro in this free form should have no markup. For example, if you want to put the phrase =see also= in italic, enclosing it with =\emph{...}= (in Rd) or the equivalent =_..._= (in markdown) will not work[fn:noparen]. For textual citations a workaround is to invoke =\insertCite= for each key and type the markup outside the macro arguments. For parenthetical citations the solutions is to ask =\insertCite= to omit the parentheses by putting =;nobrackets= at the end of the argument[fn:nobracket]. The parentheses can then be put manually where needed. For example, [fn:nobracket] With \pkg{Rdpack} versions greater than 2.1.3. [fn:noparen] For details see [[https://github.com/GeoBosh/Rdpack/issues/23][Github issue #23]] raised by Martin R. Smith. #+BEGIN_EXAMPLE (\emph{see also} \insertCite{@@parseRd and @Rpack:bibtex;nobrackets}{Rdpack}) #+END_EXAMPLE produces: (/see also/ \Sexpr{insert_citeOnly("@@parseRd and @Rpack:bibtex;nobrackets", "Rdpack")}). *** Further macros for citations The macro =\insertNoCite{key}{package}= records one or more references for =\insertAllCited= but does not cite it. Setting =key= to =*= will record all references from the specified package. For example, =\insertNoCite{R}{bibtex}= records the reference whose key is =R=, while =\insertNoCite{*}{utils}= records all references from package ``utils'' for inclusion by =\insertAllCited=. =\insertCiteOnly{key}{package}= is as =\insertCite= but does not record the key for the list of references assembled by =\insertAllCited=. ** Automatically generating lists of references The macro ~\insertAllCited{}~ can be used to insert all references cited with ~\insertCite~ or ~\insertNoCite~. A natural place to put this macro is the references section. The Rd section may look something like: #+BEGIN_EXAMPLE \references{ \insertAllCited{} } #+END_EXAMPLE The analogous documentation chunk in roxygen2 might look like this: #+BEGIN_EXAMPLE #' @references #' insertAllCited{} #+END_EXAMPLE Don't align the backslash with the second 'e' of =@references=, since roxygen2 may interpret it as verbatim text, not macro. Rd macro =\insertCited{}= works like =\insertAllCited= but empties the references list after finishing its work. This means that the second and subsequent =\insertCited= in the same help page will list only citations done since the preceding =\insertCited=. Prompted by issue 27 on github to allow separate references lists for each method and the class in R6 documentation. ** Changing the style of references Package ~Rdpack~ supports bibliography styles for lists of references[fn:styles]. 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: #+BEGIN_SRC R .onLoad <- function(lib, pkg){ Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames") invisible(NULL) } #+END_SRC 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. [fn:styles] Support for styles is available since ~Rdpack (>= 0.8)~. * Possible issues ** Warning from 'R CMD build' If 'R CMD build' or =devtools::build()= gives a warning along the lines of: #+BEGIN_EXAMPLE Warning: C:/temp/RtmpqWQqji/.../XXX.Rd:52: unknown macro '\insertRef' #+END_EXAMPLE then check the syntax in file DESCRIPTION --- the most common cause of this is misspelling =RdMacros:=. Make sure in particular that `M' is uppercase. ** Development using `devtools' The described procedure works transparently in `roxygen2' chunks and with Hadley Wickham's `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 and their help pages contain references, you may encounter some puzzling warning messages in `developer' mode, something like: #+BEGIN_EXAMPLE 1: In tools::parse_Rd(path) : ~/mypackage/man/abcde.Rd: 67: unknown macro '\insertRef' #+END_EXAMPLE These warnings are again about unknown macros but the reason is completely different: they pop up 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[fn:5]. These warnings are harmless - the help pages are built properly and no warnings appear outside ``developer'' mode, e.g. in a separate R~session. You may also consider using the function ~viewRd()~, discussed below, for viewing Rd files. [fn:5] The claims in this sentence can be deduced entirely from the informative message. Indeed, (1)~the error is in processing a source Rd file in the development directory of the package, and (2)~the call to =\parse_Rd= specifies only the file. ** 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[fn:6]. Only do this for entries that do not render properly or cause errors, since most of the time this should not be necessary. For encoding related issues of REFERENCES.bib see the dedicated subsection below. 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, \code{help("Rdpack-package")}, of \pkg{Rdpack}. Among other things, it contains some dummy references which illustrate the above. [fn:6] Thanks to Michael Dewey for suggesting the discussion of this. ** Encoding of file REFERENCES.bib If a package has a declared encoding (in file =DESCRIPTION=), =REFERENCES.bib= is read-in with that encoding[fn:enc]. Otherwise, the encoding of =REFERENCES.bib= is assumed to be UTF-8 (which includes ASCII as a subset). [fn:enc] From =Rdpack (>=0.9-1)= The issue of not handling the encoding was raised by Professor Brian Ripley. 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: #+BEGIN_EXAMPLE prepare_Rd: input string 1 is invalid in this locale #+END_EXAMPLE 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()=. Since \pkg{Rdpack} switched to the bibtex parser in package \pkg{rbibutils}, if the bib file contains Latex escape sequences standing for accented Latin characters, such as =\'e= and =\"o=, they are imported as is. They are converted to UTF-8 only when the text is rendered for output. If R's checking tools complain about non-ASCII characters add the following encoding declaration to file DESCRIPTION[fn:enc2]: #+BEGIN_EXAMPLE Encoding: UTF-8 #+END_EXAMPLE Needless to say, make sure that there are really no characters from encodings like 'latin1'. With the previous bibtex parser (before Rdpack version 1.1.0) the conversion was done earlier, which resulted in confusing messages about non-ASCII characters, even when the file REFERENCES.bib was pure ASCII. This should no longer happen. [fn:enc2] 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. * Viewing Rd files A function, \code{viewRd}, to view Rd files in the source directory of a package was introduced in version 0.4-23 of \pkg{Rdpack}. A typical user call would look something like: #+BEGIN_EXAMPLE Rdpack::viewRd("./man/filename.Rd") #+END_EXAMPLE By default the requested help page is shown in text format. To open the page in a browser, set argument \code{type} to \code{"html"}: #+BEGIN_EXAMPLE Rdpack::viewRd("./man/filename.Rd", type = "html") #+END_EXAMPLE Users of 'devtools' can use \code{viewRd()} in place of \code{help()} to view Rd sources[fn:7]. [fn:7] Yes, your real sources are the \texttt{*.R} files but \code{devtools::document()} transfers the roxygen2 documentation chunks to Rd files (and a few others), which are then rendered by \pkg{R} tools. # % * Inserting references interactively # % \label{sec:insert-refer-inter} # % # % It is possible to use the underlying R function to insert references interactively. # % For example, # % <<>>= # % library(Rdpack) # % cat(insert_ref("R", package = "bibtex"), sep ="\n") # % @ # % # % I would put the (commented out) command on top of the above reference as a reminder where it # % came from: # % #+BEGIN_EXAMPLE # % % insert_ref("R", package = "bibtex"), sep ="\n") # % #+END_EXAMPLE # % # % For a different approach, see the documentation of function ={Rdpack::rebib()}=. Rdpack/NAMESPACE0000644000176200001440000000500715104361123012673 0ustar liggesusersimport(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) # commented out 2020-11-25 #importFrom(bibtex, read.bib) importFrom(rbibutils, readBib, bibstyle_JSSextra) 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 # 2025-11=09 rremoved # , run_examples - commenting out until completed # , insert_fig - commenting out until completed , Rdo_fetch ##, deparseLatexToRd ) Rdpack/NEWS.md0000644000176200001440000006502615141664142012571 0ustar liggesusers# Rdpack 2.6.6 - rewrote the function beside Rd macro `\insertFig` defensively and to work harder to locate and/or create the directory for the figures (see issue #39). # Rdpack 2.6.5 - Rdpack's bibstyles are no longer created at load time. - refactored the bibstyles. Needs `rbibutils > 2.4`, due to a missing export in rbibutils v2.4. - fixed the name of a subsection in `insert_ref.Rd`. It was wrongly mentioning 'insertNoCite`, while actually describing 'insertCiteOnly' (and causing a duplicated html anchor, now caught by recent R checks). - padded the last table in 'predefined.Rd' so that the last row now has the same number of entries as the rest (pkgdown was omitting it and the R checks started flagged it with a NOTE). # Rdpack 2.6.4 - no user visible changes. - fixed a couple of tests that were expecting warnings to expect error in things like `structure(NULL, xxx = "something")`, since R-devel circa start of April 2025 turned that construct to an error. # Rdpack 2.6.3 - changed the condition in the test fixing the issue in Rdpack v2.6.1 to `getRversion() < "4.5.0"`, which is less likely to need further change for R-4.4.x releases. - removed 'RdpackTester' from `./inst/examples`. It was meant to provide a convenient way to create bug examples but was left incompletee. # Rdpack 2.6.2 - `RStudio_reprompt` now issues a more informative error message when not called on a suitable file or function. Fixes issue #30, reported by @daattali. - now the LaTeX macro `\slash` is wrapped in a condition, so that it is passed on for LaTeX related output but converted to `/` for other formats (such as html). Fixes GeoBosh/rbibutils#9, reported by @MLopez-Ibanez. - fixed the test for the fix in Rdpack v2.6.1 (see below) to work with R-4.4.2, since that R-devel change was not carried on to R-4.4.2. (Note: the error concerns the test only. The fix in the code of the package works for any R version.) Fixes issue #37, reported by @charles-plessy. # Rdpack 2.6.1 - R-devel c86938 turned to error the warning for a non-existing key in the bib file. Fixed `insert_bib` (and a related test) to handle that. # Rdpack 2.6 - fixed issues causing 'lost braces' (actually, superfluous braces) NOTEs from checks in R-devel occuring with some accented LaTeX characters. These NOTEs are not yet activated on CRAN but if/when they do, developers using Rd macros `\insertRef` and `\insertCite` can eliminate them by building their packages with Rdpack (>= 2.6) and rbibutils (>= 2.2.16). Thanks to Sebastian Meyer for tracing down the issues. - fixed a `Sweave` expression in 'man/predefined.Rd' to not emit unnecessary braces (see the note above). # Rdpack 2.5 - Rd macros `insertCite` and friends were calling `\insert_citeOnly()` with argument `key` instead of `keys`. This was not an error since partial matching is ok here but not good practice. Fixes issue #28 reported by Marcel Ramos. - changed the saved value in "tests/testthat/dummyArticle.rds" used in 'test-bib.R' with a value obtained with R-devel r84896 n previu versins of R there wasasuperfluous final ' .'). - in some cases when square brackets were requested, rather than round ones, `\insertCiteOnly` was using closing round parenthesis. - in some cases `\insertCiteOnly` was not handling well the last cite when it was followed by free text. # Rdpack 2.4 - new Rd macro `\insertCited{}` works like `\insertAllCited` but empties the references list after finishing its work. This means that the second and subsequent `\insertCited` in the same help page will list only citations done since the preceding `\insertCited`. Prompted by issue #27 to allow separate references lists for each method and the class in R6 documentation. - It is no longer necessary to remove backslashes from `\&` and similar in bibtex files (e.g. in "John Wiley \& Sons"). The backslash was appearing in the rendered pdf manual but R-devel's checks started to warn about it recently with something like `checkRd: (-1) pcts-package.Rd:287: Escaped LaTeX specials: \&` (starting June 2022). This could be avoided by removing the superfluous backslash in the bib file but this is annoying since this is proper syntax for the latter. Concerned packages should rebuild the tarball with Rdpack (>= 2.4) or remove the offending backslashes from their bib files. (addresses issue #26) # Rdpack 2.3.1 - in Rd macro `\insertCite`, two or more accented Latin characters were rendered with superfluous curly braces, see issue#25 (reported by Manuel López-Ibáñez) and https://stat.ethz.ch/pipermail/r-devel/2022-April/081604.html. # Rdpack 2.3 - reverted the change in v2.2, since a further fix in R-devel, https://stat.ethz.ch/pipermail/r-devel/2022-March/081570.html, made it unnecessary and dependent on the versions of R used to build and install a package. This concerns developers who use the Bibtex related macros - they should not build their package with v2.2 of `Rdpack` and could require `Rdpack >= 2.3` to ensure that users installing their package don't do that accidentally with `Rdpack 2.2`. # Rdpack 2.2 - a change in R-devel (around built r81914, March 2022) in the processing of `\doi` Rd macros resulted in warnings from R-devel's checks for packages that use Rdpack built with the released versions of R. This fixes it. (fixes #24) # Rdpack 2.1.4 - Rdmacro `\insertCite` gets a new feature allowing to drop parentheses for parenthesised citations, analogous to natbib's `\citealp` in latex. This makes it possible to use markup around the citations outside the arguments of the macro. This fixes github issue #23 by @ms609. - updated vignette "Inserting_bibtex_references" and other documentation. - the pkgdown site now has a `Search` button on the navigation bar. # Rdpack 2.1.3 - fixed a test that was failing with versions of rbibutils before v2.1.1 (issue reported by Andreas Tille). - if the version of rbibutils is greater than v2.2.5, parsing bib files with `rbibutils::readBib` now uses `texChars = "Rdpack"`. This ensures proper rendering of `\'i` in references (by converting `\'i` to `\'\i` which base R renders correctly). For detailed discussion of this see issue GeoBosh/bibutils#7 and NEWS.md in rbibutils v2.2.4 and v2.2.5. # Rdpack 2.1.2 - Rdmacros generating references now drop the `URL` field if a `doi` field generating the same URL is present. This avoids repetition of the URL since rendering the `doi` field produces the URL anyway. - now references with identical authors are sorted by year. - fixed rebib() to process doi's properly. - now checks on github (using github actions) are done on the three major platforms for the following versions of R: release, devel, oldrel, and 3.3. - now a warning (rather than error) is issued if package 'testthat' is not available for tests. - now bibtex files are parsed with option `direct = TRUE` when the version of `rbibutils` is >= ‘2.1.2’. This fixes GeoBosh/rbibutils#3 for Rdpack users (although that needs fixing also for `direct = FALSE`). # Rdpack 2.1.1 - In `viewRd`, the default for the help type now is `options("help_type")` (previously the default was `"text"`). - for `roxygen2` users, added a note in README and `Rdpack-package.Rd` not to indent by exactly four spaces `\insertAllCited{}` relative to `@references` when markdown mode is activated. This is to avoid it being translated by `roxygen2` as verbatim (`\preformatted`) text, see issue (#18). - moved package `gbRd` to Suggests. - fixed uses of \dots in several examples (necessitated by a change in R-devel circa February 2021). # Rdpack 2.1 - dramatic speed up of processing of bibliography references, most noticeable for users with large number of help pages and large `REFERENCES.bib`. (prompted by Kisung You, issue #17) - amended the warning message from bibliography macros to mention duplicated keys. - added entry for `rbibutils` in REFERENCES.bib. - corrected wrong citation of `rbibutils`. # Rdpack 2.0 - removed `bibtex` from `Suggests` and elsewhere. # Rdpack 1.1.0 (not on CRAN) - imported `rbibutils` and made suitable adjustments to the code. - moved `bibtex` to `Suggests` (since `bibtex` has been orphaned for several years). # Rdpack 1.0.1 (not on CRAN) - removed a documentation link to a function in `gbutils`, which is not among the dependencies of `Rdpack`. This was raising a NOTE on one of the CRAN testing machines. # Rdpack 1.0.0 - `viewRd()` now loads also Rd macros declared by the package to which the rendered Rd file belongs. Previously only macros from `Rdpack` were loaded but now there is at least one other package, `mathjaxr`, which defines Rd macros. - moved `grDevices` to `Suggests`. - edited some documentation files. # Rdpack 0.11-1 - in documentation of S4 classes, such as `"classname-class.Rd"`, `reprompt()` was sometimes inserting entries for slots already listed in the Slots section. The same bug was causing the new slots not to be reported properly to the user. - in some cases `reprompt()` failed to process properly `\S4method` entries in the Usage section of Rd files. Now fixed. - `reprompt()` now handles `\S4method` statements for replacement methods. As for other functions and methods (S3 and S4), it is sufficient to put a declaration with empty argument list in the Usage section and `reprompt()` will insert the correct formal arguments for the method (they may be different from those of the generic). - `reprompt()` now gives a more helpful error message when `type` is invalid. - corrected some minor typo's in the documentation. - README and the documentation of `reprompt()` and `Rdpack-package` now give more details on `reprompt()`ing replacement functions. - README.md and README.org now give the correct `install.packages` instruction for CRAN (pull request #10 from @katrinleinweber). - some examples were leaving a stray file, `dummyfun.Rd`, after `R CMD check`. # Rdpack 0.11-0 - Updated the vignette about `\insertFig`, `\printExample` and `\runExamples`, to reflect the lifting in `R 3.6.0` of some limitations of Rd processing in previous R versions. - Vignette 'Inserting BibTeX references' now includes a section on bibliography styles. This section was previously only in README. - The fix in Rdpack 0.10-3 (see below) for an issue introduced in R-devel in Oct 2018 will be made permanent, at least for now. This fix resolves also a similar issue in package `pkgdown`, see the discussion at https://github.com/GeoBosh/Rdpack/issues/9 for details and further links. # Rdpack 0.10-3 (not on CRAN) * fixed issue#9 (reported by by @aravind-j) appearing when a package is built with R-devel (since about Oct 2018) causing references by `\insertAllCited{}` to appear in a single paragraph in the `html` rendering of the Rd documentation. # Rdpack 0.10-2 (not on CRAN) * added pkgdown site to DESCRIPTION. * README and the vignette about evaluated examples now state that R-devel no longer gives warnings about `\Sexpr` not being a top level section. This means that macro `runExamples` which creates section 'Examples' containing code and results of evaluation will be useable in CRAN packages. * new function `Rdo_fetch()` gets the Rd object representing a help page from an installed or source package. It works also for packages under devtool's developer's mode * The site created with pkgdown contains fewer errors now. (Note that the documentation builds without error with R's tools). * Started moving tests from my local setup to testthat. # Rdpack 0.10-1 * removed redundant references from REFERENCES.bib (they were leftovers from testing). # Rdpack 0.10-0 (not on CRAN) * updated vignette 'Inserting_bibtex_references'. # Rdpack 0.9-1 (not on CRAN) * now `REFERENCES.bib` is read-in using the declared encoding for the corresponding package. If there is no declared encoding, "UTF-8" is assumed. * Now macros `\insertCite` and `\insertCiteOnly` use the correct `results=rd` instead of `results=Rd`. This was not catched by `R`s building tools but caused errors when processed with `pkgdown::build_site()`. Fixes issue#8. Also fixes r-lib/pkgdown#784. Thanks to [Jay Hesselberth](https://github.com/jayhesselberth) for uncovering this. * now references produced by the citation macros for BibTeX entries of type `@book` and `@incollection` treat field 'series' similarly to other BibTeX styles, including JSS (issue#7 raised by Kisung You). Note that even though the underlying base R tools are based on JSS, they treat this field differently. * Bugfix: now Rd macro `\printExample` evaluates the expressions in the correct environment. * help page of `get_usage()` gets a fairly complete Details section with numerous evaluated examples. * now `run_examples()` escapes `%` by default, before returning the text. This is needed for text that is to be included in an Rd file. It can be turned off by setting the new argument `escape` to `FALSE`. * now `reprompt()` gives a more informative error message if an Rd file describes a non-existent S4 class. This is not captured by `R`s tools. It can happen during development if a class is removed. * now reports printed by `reprompt()` about methods documented in Usage sections, but no longer existing, are more readable. This is due to a new print method for (the mostly internal) class "f_usage". * Many features of Rdpack are best demonstrated on a package. The new package RdpackTester under `./inst/examples` now makes this easier. * now the help page "predefined.Rd" does not print some tables twice in the pdf manual. (This was due to using `\if{latex}{}{}` instead of `\ifelse{latex}{}{}` for those tables.) * also in "predefined.Rd", removed illegal use of vertical bars (in column specifications of tabular environments) from the pure LaTeX code in the `\ifelse` clause(s) and wrapped them in `\out{}`. * in "get_sig_text.Rd", replace `help()` with `utils::help()` to avoid warnings from more stringent `R CMD check`. Similarly, in "Rdpack-package.Rd" replace `packageDescription()` with `utils::packageDescription()`. This may be needed in `\Sexpr`'s more generally (__TODO:__ check if these would still be needed if the symbols are imported by the package.) # Rdpack 0.9-0 * some brush-up of the documentation for the changes since version 0.8-0 of the package. # Rdpack 0.8-4 (not on CRAN) * now simple mathematics in BibTeX entries is rendered natively, no need to replace dollars with `\eqn{}`. # Rdpack 0.8-3 (not on CRAN) * new macro `\printExample` for inclusion of example computations in narrative sections, such as `Details`. The code is evaluated and printed similarly to `R` sessions but the code is not prefixed and the output is prefixed with comment symbols, eg. ``` 2+2 ##: 4 ``` * new experimental macro `\runExamples` for use as top level section in an Rd file as a replacement of section `\examples`. `\runExamples{code}` evaluates the code and creates section `\examples` containing the code and the results (similarly to `\printExample`). So, `\runExamples{2 + 2}` produces ``` \examples{ 2 + 2 ##: 4 } ``` The generated section `examples` is processed by R's documentation tools (almost) as if it was there from the outset. * new experimental macro `\insertFig` to create a figure with `R` code and include it in the documentation. The related macro `\makeFig` just creates a graphics file, which can be included with the standard Rd command `\figure`. * new vignette gives a brief description of the new macros. # Rdpack 0.8-2 (not on CRAN) * Now text citations use "et al." when there are three or more authors. (Issue#6 reported by Timothy P. Bilton) # Rdpack 0.8-1 (not on CRAN) * in this file, added backticks to `\insertRef` and `\insertAllCited` (see below) - in the rendered `News` on CRAN the backslashed words had disappeared. # Rdpack 0.8-0 * `\insertRef` and `\insertAllCited` macros now support `bibstyles` for formatting references (feature requested by Jamie Halliday, issue#5). Use `Rdpack (>= 0.8)` in `Imports:` to use this feature. Currently only long author names are supported but complete support for styles can be added trivially if requested. * updates to the documentation, in particular the bulk of Rdpack-package.Rd was from 2011! # Rdpack 0.7-1 (not on CRAN) * improvements to handling of free form citations in textual mode: * (bugfix) now the whole citation is not parenthesised in textual mode, * the handling for textual mode was incomplete in that additional text after the citation was not put inside the parentheses along with the year. * updates to the documentation. * fix a bug in `Rdo_locate_core_section()`. # Rdpack 0.7-0 * consolidated the changes introduced since the previous CRAN release of Rdpack (it was 0.5-5) in preparation for the next release. Users of the new macros for citation can use `Rdpack (>=0.7)` in the `Imports:` field of file "DESCRIPTION" to ensure that they are available. * comprehensive overhaul of handling of errors and warnings during processing of references and citations. In particular, such errors should (in most cases) produce only warnings during `R CMD build` and `R CMD INSTALL`, and not prevent the package from being built and installed. * Unresolved BibTeX keys produce warnings during building and installation of the package, but not errors. Dummy entries are inserted in the documentation explaining what was amiss (currently with 'author' A Adummy). # Rdpack 0.6-x (not on CRAN) * new Rd macros for citations * `\insertCite` inserts citation(s) for one or more keys and records the keys for `\insertAllCited` (see below). * `\insertCiteOnly` is similar to `\insertCite` but does not record the keys. * `\insertNoCite` records the keys but does not produce a citation. * `\insertAllCited` prints a bibliography including all references recorded by `\insertCite` and `\insertNoCite`. * new entries in this file will use markdown syntax. * updates to the documentation. # Rdpack 0.5-7 (not on CRAN) * `get_bibentries()` gets a new argument "everywhere". When is is TRUE, the default, unescaped percents are escaped in all bibtex fields, otherwise the replacement is done only in field "URL". * removed several `print()` statements which were accidentally left in the code in v. 0.5-6. * updated help page of `get_bibentries()` and included examples. * cleaned up the imports in NAMESPACE. # Rdpack 0.5-6 (not on CRAN) * `insert_ref()` and Rd macro `\insertRef` should now work ok in the presence of percent encoded symbols in URL field of a BibTeX entry. Closes issue "Unexpected END_OF_INPUT error (URL parsing?)", see [Rdpack issue 3](https://github.com/GeoBosh/Rdpack/issues/3), raised by [jdnewmil](https://github.com/jdnewmil). * `get_bibentries()` now takes care of percent encoded symbols in URLs. It now returns an object from class "bibentryRd", which inherits from "bibentry" but has its own print method which escapes or unescapes the percent signs in URLs depending on the requested output style. This was also reported by by [jdnewmil](https://github.com/jdnewmil) in issue#3 referenced above. * `get_bibentries()` now tries to load the `bib` file from the development directory of argument "package", in case it is in development mode under "devtools". (Even though the search is with `system.file()`, which `devtools` replaces with its own version, the bib file still needs to be looked for in "inst/", i.e. it is not in the root directory as is the case in installed packages.) # Rdpack 0.5-5 * Streamlined the help page of `reprompt()` and `Rdpack-package`. * new argument, `edit`, in `reprompt()` opens the Rd file after updating it. * new function `ereprompt()` (`e' for _edit_)* opens `reprompt()` with suitable defaults to replace the original Rd file and open it in an editor, otherwise equivalent to `reprompt()`. * now if `infile` does not exist, `reprompt()`, and hence `ereprompt()`, strips the directory part, finds the root of the package directory, and looks for the file under `man/` (this uses package `rprojroot`'). In particular, if the working directory is anywhere under the package root, `infile` can be simply the name of the Rd file, without path. * now README.md is generated from README.org. I changed the layout and amended the information in it. * README.* now get links to [georgisemacs](https://github.com/GeoBosh/georgisemacs) for an emacs function to `reprompt()` the Rd file at point. * `viewRd()` now works also when the file is from a package under devtools' development mode on any platform (e.g. RStudio, Emacs/ESS, Rgui). * new RStudio add-in `Reprompt`, contributed by Duncan Murdoch. If the file being edited in the RStudio's code editor is an Rd file it calls `reprompt()`. If the file is as R source file, it looks for the help page of a selected object name and works on it if found, otherwise creates one. # Rdpack 0.5-4 (not on CRAN) * added the version of `Rdpack` to the abstract of the vignette. This seems more informative than giving the compilation date. * now `reprompt()` doesn't give spurious warnings about unknown Rd macros when the Rd file contains user defined Rd macros. These warnings were harmless and rare, but alarming and annoying. * fixed a bug in `inspect_args()` which caused the warning _"In is.na(x) : is.na() applied to non-(list or vector) of type 'NULL'"_ in `reprompt()`, when the signature of a function in "Usage" section was empty. # Rdpack 0.5-3 * The warning message about a missing reference key now appears also in the respective help page. # Rdpack 0.5-2 (not on CRAN) * added the github url to DESCRIPTION. * now give a more informative warning if a key is missing from REFERENCES.bib (thanks to Kisung You for suggesting this). # Rdpack 0.5-1 * an example was not restoring the working directory. # Rdpack 0.5-0 (not on CRAN) * moved gbRd from Depends to Imports and adjusted some examples to use `tools::parse_Rd()` rather than `parse_Rd()` (before this was not necessary since 'gbRd' _depended on_ 'tools'). # Rdpack 0.4-23 (not on CRAN) * new function `viewRd()` parses and shows an Rd file in a source package. May be particularly helpful for devtools developers. * revamped the vignette, added additional explanations of possible issues. * new functions `makeVignetteReference()` and `vigbib()` generate Bibtex references for vignettes in a package. # Rdpack 0.4-22 * Added the requirement to **Import Rdpack** to the help page of `insert_ref()`. (It was out of sync with the vignette.) * Updated Description in DESCRIPTION, which was also out of sync with the vignette. * Bug fix in the vignette: changed `\@references` to `@references` in the roxygen2 example. # Rdpack 0.4-21 * Edited and amended vignette _"Inserting_bibtex_references"_, including: * additional explanation and an example, * requirement to import Rdpack and a mention of travis etc. * paragraph about devtools. * changed the URL for parse_Rd.pdf in REFERENCES.bib to https. # Rdpack 0.4-20 * cleaned up some minor CRAN issues. # Rdpack 0.4-19 (not on CRAN) * new facility for inserting references from BibTeX files - just put the line: RdMacros: Rdpack in the `DESCRIPTION` file of your package and the references in `inst/REFERENCES.bib`. Then put `\inserRef{key}{yourpackage}` in documentation chunks to insert item `key` from the bib file. This works with both manually created Rd files and roxygen comments, see the documentation for details. # Rdpack 0.4-18 * from now on, put next to versions published on CRAN (as above) * a minor correction in file NEWS. # Rdpack 0.4-17 (not on CRAN) * In file DESCRIPTION, changed reprompt and rebib to `reprompt()` and `rebib()`. # Rdpack 0.4-16 (not on CRAN) * don't export `parse_text` * corrected bug in reprompt for S4 classes - new slots were not handled correctly (see `slots.R` for details). * in reprompt for S4 methods: if the methods documentation describes methods that do not exist, print an informative message for the user. (Such methods are also printed for debugging purposes but in non-user friendly form.) - included `methods` in `Imports:` - around R-devel version 2015-07-01 r68620 not including it triggers warnings) # Rdpack 0.4-8 (not on CRAN) * new functions `.whichtageq` and `.whichtagin`; replaced most calls to `toolsdotdotdotRdTags` with these. * removed `toolsdotdotdotRdTags` # Rdpack 0.4-7 (not on CRAN) * removed `:::` calls from code; copied some functions from `tools` to achieve this (see "threedots.R"). Renamed the functions replacing `:::` with dotdotdot. * export by name (not the generic export pattern); preparation for more selective export of functions in the future. * new functions: `Rdo_get_argument_names`, `Rdo_get_item_labels` # Rdpack 0.4-5 (not on CRAN) * dependence `bibtex` becomes "Imports". `tools` and `gbRd` remain (for now) "Depends" since functions from them are used in some examples without `require()`'s. * `rebib()`: now `outfile=""` can be used to request overwriting `infile`. (a small convenience; before the change, one could do this by giving the `outfile` and `infile` the same values.) * Bug fix: `predefined.Rd` contained `\tabular` environments with vertical bars, `|`, in the format specification. This is not documented in "Writing R exts" but works for LaTeX and remained unnoticed by me and R CMD check. However, rendering the help page for the objects documented in "predefined.Rd" gave an error in html and text mode. Package installation failed only if html was requested at build time. * small changes in the documentation # Rdpack 0.4-4 # Rdpack 0.4-1 (not on CRAN) * new major feature: processing references from Bibtex files. The top user level function is `rebib()`, which updates section "references" in an Rd file. `promptPackageSexpr()` has been updated to use this feature. `inspect_Rdbib()` can be used in programming. * new auxiliary functions for work with `bibentry` objects. * new convenience programming functions for Rd objects. * some small bug fixes. * some gaps in the documentation filled. # Rdpack 0.3-11 (not on CRAN) * `reprompt()` was not handling properly S4 replacement methods. Changed the parsing of the arguments to rectify this. Some other functions also needed correction to handle this. # Rdpack 0.3-10 * `Depends` field in DESCRIPTION file updated to require R 2.15.0 or later (because of a few uses of `paste0()` in recent code). # Rdpack 0.3-8 * first public version Rdpack/inst/0000755000176200001440000000000015141664153012441 5ustar liggesusersRdpack/inst/REFERENCES.bib0000644000176200001440000000377715134200006014537 0ustar liggesusers@Manual{Rpack:bibtex, author = {Romain Francois}, title = {bibtex: bibtex parser}, year = {2014}, note = {R package version 0.4.0}, } @Manual{Rpackage:rbibutils, title = {rbibutils: Convert Between Bibliography Formats}, author = {Georgi N. Boshnakov and Chris Putman}, year = {2020}, url = {https://CRAN.R-project.org/package=rbibutils}, } @misc{parseRd, author = {Duncan Murdoch}, title = {Parsing Rd files}, year = {2010}, url = {https://developer.r-project.org/parseRd.pdf}, } @Manual{Rdevtools, author = {Hadley Wickham and Jim Hester and Winston Chang}, title = {devtools: Tools to Make Developing R Packages Easier}, year = {2018}, note = {R package version 1.13.5}, url = {https://CRAN.R-project.org/package=devtools}, } @Article{dummyArticle, author = {A. ZZZ}, title = {A non-existent paper with a relation between several fundamental constants: $e^{i\pi}=-1$ in the title and showing that \verb{a\\slash b} converts to a\slash b}, journal = {A non-existent journal with the formula $L_2$ in its name and \# \$ \& \_ \^ \~ an ampersand and other special characters preceded by a backslash in the bib file}, year = {2018}, note = {This reference demonstrates that formulas in BibTeX files are OK. A formula in field 'note': $c^2 = a^2 + b^2$. If you need to, even display math is possible: $$ E = mc^2 ,$$ a famous formula. }, } % The entries below are temporary for testing. % for issue #25 @article{DiaLop2020ejor, author = { Juan Esteban Diaz and Manuel L{\'o}pez-Ib{\'a}{\~n}ez }, title = {Incorporating Decision-Maker's Preferences into the Automatic Configuration of Bi-Objective Optimisation Algorithms}, journal = {European Journal of Operational Research}, year = 2021, volume = 289, number = 3, pages = {1209--1222}, doi = {10.1016/j.ejor.2020.07.059}, } Rdpack/inst/examples/0000755000176200001440000000000015102212001014231 5ustar liggesusersRdpack/inst/examples/tz.Rd0000644000176200001440000000171115102212001015155 0ustar liggesusers\name{dummyfun} \alias{a1} \alias{a2} \alias{a3} #ifdef windows \alias{onlywin} #endif #ifdef unix \alias{onlyunix} #endif \title{Example in Rdpack} \description{Dummy description. Second sentence. } \usage{dummyfun(x, y, type, flag = FALSE)} \arguments{ \item{x}{Description of \code{x}} \item{y}{Description of \code{y}} \item{type}{Description of \code{type}} \item{flag}{Description of \code{flag}} } \details{Dummy details. More dummy details. #ifdef unix These are on unix. #endif #ifdef windows These are on windows. #endif } \value{A list with the following components: \item{res}{result, a number} \item{convergence}{numeric code indicating convergence.} } \section{Further information}{ This is a user defined section. } \examples{ dummyfun(1) #ifdef windows ## example on Windows #endif #ifdef unix \dontrun{ ## need to supply a suitable file path (if any) for your system ## example on unix } #endif } \keyword{kw1} \keyword{kw2} Rdpack/inst/examples/reprompt.Rd0000644000176200001440000003617315102212001016402 0ustar liggesusers\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, aliases, 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...)}. \code{reprompt} understands also subsetting ans subassignment operators. For example, suppose that the \code{\\arguments} section of file "bracket.Rd" contains these directives (or any other wrong signatures): \preformatted{ \method{[}{ts}() \method{[[}{Date}() } Then \code{reprompt("./bracket.Rd")} will change them to \preformatted{ \method{[}{ts}(x, i, j, drop = TRUE) \method{[[}{Date}(x, \dots, drop = TRUE) } This works for the assignment operators and functions, as well. For example, any of these \preformatted{ \method{`[<-`}{POSIXlt}() \method{[}{POSIXlt}(x, j) <- value } will be converted by \code{reprompt} to the standard form \preformatted{ \method{[}{POSIXlt}(x, i, j) <- value } Note that the quotes in \code{`[<-`} above. 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/inst/examples/Rdpack-package.Rd0000644000176200001440000004207115102212001017321 0ustar liggesusers\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{rbibutils} \insertCite{Rpackage:rbibutils}{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. Don't align the backslash with the second 'e' of \code{@references}, since roxygen2 may interpret it as verbatim text, not macro. 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/inst/examples/journal_with_percents.bib0000644000176200001440000000047715102212001021327 0ustar liggesusers@article{journalWithPercents, title = {Dummy example of {Journal} containing text with percents}, volume = {1}, journal = {Example bibtex file, https://github.com/GeoBosh/Rdpack/blob/master/inst/examples/journal%20with%20percents.bib}, author = {Boshnakov, Georgi N.}, year = {2018}, pages = {1--1} } Rdpack/inst/examples/url_with_percents.bib0000644000176200001440000000043415102212001020450 0ustar liggesusers@article{urlWithPercents, title = {Dummy example of {URL} with percents}, volume = {51}, url = {https://github.com/GeoBosh/zzfiles/blob/master/url%20with%20percents.bib}, journal = {Example bibtex file}, author = {Boshnakov, Georgi N.}, year = {2018}, pages = {1--1} } Rdpack/inst/pkgdown.yml0000644000176200001440000000031215134204022014614 0ustar liggesuserspandoc: 3.1.3 pkgdown: 2.2.0 pkgdown_sha: ~ articles: {} last_built: 2026-01-21T17:08Z urls: reference: https://geobosh.github.io/Rdpack/reference article: https://geobosh.github.io/Rdpack/articles Rdpack/inst/doc/0000755000176200001440000000000015141664153013206 5ustar liggesusersRdpack/inst/doc/Inserting_bibtex_references.Rnw0000644000176200001440000004316015134452141021374 0ustar liggesusers% Created 2022-07-20 Wed 17:30 % Intended LaTeX compiler: pdflatex \documentclass[a4paper,twoside,11pt,nojss,article]{jss} \usepackage[T1]{fontenc} \usepackage[left=2cm,right=2cm,bottom=15mm]{geometry} \usepackage{graphicx,color,alltt} \usepackage[authoryear,round,longnamesfirst]{natbib} \usepackage{hyperref} % \usepackage{Sweave} \author{Georgi N. Boshnakov} \Plainauthor{Georgi N. Boshnakov} \Address{ Georgi N. Boshnakov\\ School of Mathematics\\ The University of Manchester\\ Oxford Road, Manchester M13 9PL, UK\\ URL: \url{https://personalpages.manchester.ac.uk/staff/georgi.boshnakov/} } <>= library(Rdpack) pd <- packageDescription("Rdpack") @ \Abstract{ Package \pkg{Rdpack} provides a straightforward way to insert BibTeX references in the documentation of an R package, using the RdMacros feature introduced in R~3.2.0. It works for `roxygen2' documentation, as well. \par This vignette is part of package Rdpack, version~\Sexpr{pd$Version}. } \Keywords{bibliographic references, Rd, bibtex, citations, \proglang{R}} \Plainkeywords{bibliographic references, Rd, bibtex, citations, R} \author{Georgi N. Boshnakov} \date{\today} \title{Inserting references in Rd and roxygen2 documentation} \hypersetup{ pdfauthor={Georgi N. Boshnakov}, pdftitle={Inserting references in Rd and roxygen2 documentation}, pdfkeywords={bibliographic references, Rd, bibtex, citations, R}, pdfsubject={}, pdfcreator={Emacs 26.3 (Org mode 9.1.9)}, pdflang={English}} \begin{document} \maketitle %\SweaveOpts{engine=R,eps=FALSE} %\VignetteIndexEntry{Inserting references in Rd and roxygen2 documentation} %\VignetteDepends{Rdpack} %\VignetteKeywords{bibliographic references, Rd, bibtex, citations, R} %\VignettePackage{Rdpack} \section{Setup} \label{sec:org778a336} To prepare a package for importing BibTeX references it is necessary to tell the package management tools that package \pkg{Rdpack} and its Rd macros are needed. The references should be put in file \texttt{inst/REFERENCES.bib}. These steps are enumerated below in somewhat more detail for convenince: \begin{enumerate} \item Add the following lines to file `DESCRIPTION': \begin{verbatim} Imports: Rdpack RdMacros: Rdpack \end{verbatim} Make sure the capitalisation of \texttt{RdMacros} is as shown. If the field 'RdMacros' is already present, add `Rdpack' to the list on that line. Similarly for field 'Imports'. \item Add the following line to file `NAMESPACE'\footnote{Any function for package \pkg{Rdpack} will do. This is to avoid getting a warning from 'R CMD check'.}: \begin{verbatim} importFrom(Rdpack,reprompt) \end{verbatim} The equivalent line for `roxygen2' is \begin{verbatim} #' @importFrom Rdpack reprompt \end{verbatim} \item Create file \texttt{REFERENCES.bib} in subdirectory \texttt{inst/} of your package and put the bibtex references in it. \end{enumerate} \section{Inserting references in package documentation} \label{sec:orgd4ad0fc} Once the steps outlined in the previous section are done, references can be inserted in the documentation as \texttt{\textbackslash{}insertRef\{key\}\{package\}}, where \texttt{key} is the bibtex key of the reference and \texttt{package} is your package. This works in Rd files and in roxygen documentation chunks. In fact, argument 'package' can be any installed R package\footnote{There is of course the risk that the referenced entry may be removed from the other package. So this is probably only useful for one's own packages. Also, the other package would better be one of the packages mentioned in DESCRIPTION.\}}, not necessarily the current one. This means that you don't need to copy references from other packages to your \texttt{"REFERENCES.bib"} file. This works for packages that have \texttt{"REFERENCES.bib"} in their installation directory and for the default packages. See also the help pages \texttt{?Rdpack::insertRef} and \texttt{?Rdpack::Rdpack-package}. For example, the help page \texttt{?Rdpack::insertRef} contains the following lines in section ``References'' of the Rd file: \begin{verbatim} \insertRef{Rpack:bibtex}{Rdpack} \end{verbatim} The first line above inserts the reference labeled \texttt{Rpack:bibtex} in Rdpack's \texttt{REFERENCES.bib}. The second line inserts the reference labeled \texttt{R} in file \texttt{REFERENCES.bib} in package `bibtex'. A roxygen2 documentation chunk might look like this: \begin{verbatim} #' @references #' \insertRef{Rpack:bibtex}{Rdpack} \end{verbatim} \section{Inserting citations} \label{sec:orgb97375b} From version 0.7 of \pkg{Rdpack}, additional Rd macros are available for citations\footnote{They were introduced in the development version 0.6-1, but 0.7 is the first version with them released on CRAN.}. They can be used in both Rd and roxygen2 documentation. If you are using these, it will be prudent to require at least this version of Rdpack in the ``Imports:'' directive in file DESCRIPTION: \texttt{Rdpack (>= 0.7)}. \subsection{Macros for citations} \label{sec:org3007a43} \label{sec:macros-citations} \texttt{\textbackslash{}insertCite\{key\}\{package\}} cites the key and records it for use by \texttt{\textbackslash{}insertAllCited\{\}}, see below. The style of the citations is author-year. The ''et al'' convention is used when there are more than two authors\footnote{This feature was introduced in Rdpack 0.8-2.}. \code{key} can contain more keys separated by commas. Here are some examples (on the left is the code in the documentation chunk, on the right the rendered citation): \begin{center} \begin{tabular}{ll} Documentation source & rendered\\ \hline \texttt{\textbackslash{}insertCite\{parseRd\}\{Rdpack\}} & (Murdoch 2010)\\ \texttt{\textbackslash{}insertCite\{Rpack:bibtex\}\{Rdpack\}} & (Francois 2014)\\ \texttt{\textbackslash{}insertCite\{parseRd,Rpack:bibtex\}\{Rdpack\}} & (Murdoch 2010; Francois 2014)\\ \end{tabular} \end{center} By default the citations are parenthesised \texttt{\textbackslash{}insertCite\{parseRd\}\{Rdpack\}} produces \Sexpr{ insert_citeOnly("parseRd", "Rdpack") }, as in the examples above. To get textual citations, like \Sexpr{ insert_citeOnly("parseRd;textual", "Rdpack") }, put the string \texttt{;textual} at the end of the key. Here are the examples from the table above, rendered as textual citations: \begin{center} \begin{tabular}{ll} Documentation source & rendered\\ \hline \texttt{\textbackslash{}insertCite\{parseRd;textual\}\{Rdpack\}} & Murdoch (2010)\\ \texttt{\textbackslash{}insertCite\{Rpack:bibtex;textual\}\{Rdpack\}} & Francois (2014)\\ \texttt{\textbackslash{}insertCite\{parseRd,Rpack:bibtex;textual\}\{Rdpack\}} & Murdoch (2010); Francois (2014)\\ \end{tabular} \end{center} The last line in the table demonstrates that this also works with several citations. 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 \texttt{@} and prefixing each key with it. The \texttt{@} symbol will not appear in the output. For example, the following code: \begin{verbatim} \insertCite{@see also @parseRd and @Rpack:bibtex}{Rdpack} \insertCite{@see also @parseRd; @Rpack:bibtex}{Rdpack} \insertCite{@see also @parseRd and @Rpack:bibtex;textual}{Rdpack} \end{verbatim} produces: \qquad \begin{tabular}{l} Rendered\\ \hline \Sexpr{insert_citeOnly("@see also @parseRd and @Rpack:bibtex", "Rdpack")}\\ \Sexpr{insert_citeOnly("@see also @parseRd; @Rpack:bibtex", "Rdpack")}\\ \Sexpr{insert_citeOnly("@see also @parseRd and @Rpack:bibtex;textual", "Rdpack")}\\ \end{tabular} The text of the arguments of the macro in this free form should have no markup. For example, if you want to put the phrase \texttt{see also} in italic, enclosing it with \texttt{\textbackslash{}emph\{...\}} (in Rd) or the equivalent \texttt{\_...\_} (in markdown) will not work\footnote{For details see \href{https://github.com/GeoBosh/Rdpack/issues/23}{Github issue \#23} raised by Martin R. Smith.}. For textual citations a workaround is to invoke \texttt{\textbackslash{}insertCite} for each key and type the markup outside the macro arguments. For parenthetical citations the solutions is to ask \texttt{\textbackslash{}insertCite} to omit the parentheses by putting \texttt{;nobrackets} at the end of the argument\footnote{With \pkg{Rdpack} versions greater than 2.1.3.}. The parentheses can then be put manually where needed. For example, \begin{verbatim} (\emph{see also} \insertCite{@@parseRd and @Rpack:bibtex;nobrackets}{Rdpack}) \end{verbatim} produces: (\emph{see also} \Sexpr{insert_citeOnly("@@parseRd and @Rpack:bibtex;nobrackets", "Rdpack")}). \subsubsection{Further macros for citations} \label{sec:org89632ba} The macro \texttt{\textbackslash{}insertNoCite\{key\}\{package\}} records one or more references for \texttt{\textbackslash{}insertAllCited} but does not cite it. Setting \texttt{key} to \texttt{*} will record all references from the specified package. For example, \texttt{\textbackslash{}insertNoCite\{R\}\{bibtex\}} records the reference whose key is \texttt{R}, while \texttt{\textbackslash{}insertNoCite\{*\}\{utils\}} records all references from package ``utils'' for inclusion by \texttt{\textbackslash{}insertAllCited}. \texttt{\textbackslash{}insertCiteOnly\{key\}\{package\}} is as \texttt{\textbackslash{}insertCite} but does not record the key for the list of references assembled by \texttt{\textbackslash{}insertAllCited}. \subsection{Automatically generating lists of references} \label{sec:orgfdcfa4f} The macro \texttt{\textbackslash{}insertAllCited\{\}} can be used to insert all references cited with \texttt{\textbackslash{}insertCite} or \texttt{\textbackslash{}insertNoCite}. A natural place to put this macro is the references section. The Rd section may look something like: \begin{verbatim} \references{ \insertAllCited{} } \end{verbatim} The analogous documentation chunk in roxygen2 might look like this: \begin{verbatim} #' @references #' insertAllCited{} \end{verbatim} Don't align the backslash with the second 'e' of \texttt{@references}, since roxygen2 may interpret it as verbatim text, not macro. Rd macro \texttt{\textbackslash{}insertCited\{\}} works like \texttt{\textbackslash{}insertAllCited} but empties the references list after finishing its work. This means that the second and subsequent \texttt{\textbackslash{}insertCited} in the same help page will list only citations done since the preceding \texttt{\textbackslash{}insertCited}. Prompted by issue 27 on github to allow separate references lists for each method and the class in R6 documentation. \subsection{Changing the style of references} \label{sec:orgb5b1c57} Package \texttt{Rdpack} supports bibliography styles for lists of references\footnote{Support for styles is available since \texttt{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 \texttt{\textbackslash{}insertAllCited} in a package to appear with full names, add \texttt{.onLoad()} function to your package. If you don't have \texttt{.onLoad()}, just copy the following definition: <<>>= .onLoad <- function(lib, pkg){ Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames") invisible(NULL) } @ %def If you already have \texttt{.onLoad()}, add the line containing the \texttt{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. \section{Possible issues} \label{sec:org98c15ef} \subsection{Warning from 'R CMD build'} \label{sec:org5c929bd} If 'R CMD build' or \texttt{devtools::build()} gives a warning along the lines of: \begin{verbatim} Warning: C:/temp/RtmpqWQqji/.../XXX.Rd:52: unknown macro '\insertRef' \end{verbatim} then check the syntax in file DESCRIPTION --- the most common cause of this is misspelling \texttt{RdMacros:}. Make sure in particular that `M' is uppercase. \subsection{Development using `devtools'} \label{sec:org9e2f214} The described procedure works transparently in `roxygen2' chunks and with Hadley Wickham's `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 \texttt{?xxx} for functions from the package you are working on and their help pages contain references, you may encounter some puzzling warning messages in `developer' mode, something like: \begin{verbatim} 1: In tools::parse_Rd(path) : ~/mypackage/man/abcde.Rd: 67: unknown macro '\insertRef' \end{verbatim} These warnings are again about unknown macros but the reason is completely different: they pop up 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 \texttt{parse\_Rd} where to look for additional macros\footnote{The claims in this sentence can be deduced entirely from the informative message. Indeed, (1)\textasciitilde{}the error is in processing a source Rd file in the development directory of the package, and (2)\textasciitilde{}the call to \texttt{\textbackslash{}parse\_Rd} specifies only the file.}. These warnings are harmless - the help pages are built properly and no warnings appear outside ``developer'' mode, e.g. in a separate R\textasciitilde{}session. You may also consider using the function \texttt{viewRd()}, discussed below, for viewing Rd files. \subsection{Latex markup in BibTeX entries} \label{sec:org83922f5} 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\footnote{Thanks to Michael Dewey for suggesting the discussion of this.}. Only do this for entries that do not render properly or cause errors, since most of the time this should not be necessary. For encoding related issues of REFERENCES.bib see the dedicated subsection below. If mathematics doesn't render properly replace the Latex dollar syntax with Rd's \texttt{\textbackslash{}eqn}, e.g. \texttt{\$x\textasciicircum{}2\$} with \texttt{\textbackslash{}eqn\{x\textasciicircum{}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. \texttt{\textbackslash{}doi}. See also the overview help page, \code{help("Rdpack-package")}, of \pkg{Rdpack}. Among other things, it contains some dummy references which illustrate the above. \subsection{Encoding of file REFERENCES.bib} \label{sec:org663630e} If a package has a declared encoding (in file \texttt{DESCRIPTION}), \texttt{REFERENCES.bib} is read-in with that encoding\footnote{From \texttt{Rdpack (>=0.9-1)} The issue of not handling the encoding was raised by Professor Brian Ripley.}. Otherwise, the encoding of \texttt{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: \begin{verbatim} prepare_Rd: input string 1 is invalid in this locale \end{verbatim} 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 \texttt{tools::showNonASCIIfile()}. Since \pkg{Rdpack} switched to the bibtex parser in package \pkg{rbibutils}, if the bib file contains Latex escape sequences standing for accented Latin characters, such as \texttt{\textbackslash{}'e} and \texttt{\textbackslash{}"o}, they are imported as is. They are converted to UTF-8 only when the text is rendered for output. If R's checking tools complain about non-ASCII characters add the following encoding declaration to file DESCRIPTION\footnote{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.}: \begin{verbatim} Encoding: UTF-8 \end{verbatim} Needless to say, make sure that there are really no characters from encodings like 'latin1'. With the previous bibtex parser (before Rdpack version 1.1.0) the conversion was done earlier, which resulted in confusing messages about non-ASCII characters, even when the file REFERENCES.bib was pure ASCII. This should no longer happen. \section{Viewing Rd files} \label{sec:org54eca5d} A function, \code{viewRd}, to view Rd files in the source directory of a package was introduced in version 0.4-23 of \pkg{Rdpack}. A typical user call would look something like: \begin{verbatim} Rdpack::viewRd("./man/filename.Rd") \end{verbatim} By default the requested help page is shown in text format. To open the page in a browser, set argument \code{type} to \code{"html"}: \begin{verbatim} Rdpack::viewRd("./man/filename.Rd", type = "html") \end{verbatim} Users of 'devtools' can use \code{viewRd()} in place of \code{help()} to view Rd sources\footnote{Yes, your real sources are the \texttt{*.R} files but \code{devtools::document()} transfers the roxygen2 documentation chunks to Rd files (and a few others), which are then rendered by \pkg{R} tools.}. \end{document} Rdpack/inst/doc/Inserting_bibtex_references.R0000644000176200001440000000110215141664152021022 0ustar liggesusers### R code from vignette source 'Inserting_bibtex_references.Rnw' ################################################### ### code chunk number 1: Inserting_bibtex_references.Rnw:19-21 ################################################### library(Rdpack) pd <- packageDescription("Rdpack") ################################################### ### code chunk number 2: Inserting_bibtex_references.Rnw:250-254 ################################################### .onLoad <- function(lib, pkg){ Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames") invisible(NULL) } Rdpack/inst/doc/Inserting_bibtex_references.pdf0000644000176200001440000023336115141664153021411 0ustar liggesusers%PDF-1.5 % 1 0 obj << /Type /ObjStm /Length 4655 /Filter /FlateDecode /N 85 /First 711 >> stream x\[s8~?o'SB~ٚJUblj'DZsߚYmmd+əd@EgKaH @ %0f$JhHQ8c&8%0M9a0c!N) \L." W\n5DpoΖ!`NΈs"ˆT. %QȯnRB%DhPdD0b3'FpBʉ)b)+4\0@2<:O8􈄖t΁:"T*9 #P @j  2v -Fxʸ`Kx JZdx 2CBB Ճ60aVCAmPN %KC2頯A Td ebTEm):1Pf%kP1P ?3A#(ht%ԙA8hhq&Tl)tex2$2Ax %[lX(jILf̈́X>!t3/lv0ߐf1_k@O>\oYA~`>ϻ|jX_ӛe"JCj>xjK* 8<H~,'PӪMAPji0| X,'BX@kA8-Y1Ϳ iZw]|3;Ur5[Wkx} @F V:"iw+zM y.ss%[.`ߏWfZȣǯɋrYOW AFy ٿ)j U`Ͽo^nP2rAy#JΏ@;ȓ'-W2"^OFDj/MQ>ϴ fb-߮(T g+cf~۪ѾڎWŷUd "%kȭBa'E{H) O{#ﱨzi&kPXSooBsqJ]͒RdND,6Kn5v[4؞`kUG:s!i0kPu,XmR{;ćHf&= ذ~f-Dl4&[ Qaxb:]L4kz@'][sV.6Yop\_}J'uQj(cCǃZڶ!@r=okҪkMS plQ_47!H.Au dXϿ;FSʭox,ix w9!q' [XZPlx0ãz`ר>GxgT0#yݜ/޲Ԟhm) o%`!4Ǽܻ8B) FƴIW :J$C1xecSl(z7?AQPHjazWz;&iA w`m5j3b 0t|NR7hcI>oI {pY3"㖁E&M%Slu1I^e,˄w|=_~h'xNQe>hEkN%nk[5z-w*MZ{CU/8x\t1Yn<ѓ݈t;O6M7M Ɣ:jYNiW5ĔV}qWZG]k`j{ Llsȑ5M W}5hĝzQB<]Z\mE[1nʈ`T0b!eJg<Ƌk.s݈-v@4ɁO qx,R:EI}eJ*6/@@;ă ݉ 巷/N>-I;U10IU Z!窆3%?QC[qM2сg d==nNxwcPb1a#ހ;Lu=s3͠ӍĜ hXYHo4gX=ܠdqQho4˨5d{a!|]n6|sys(g2?]O_sMιo-xu~2D)k3ÿRh4~˻1t?O' 㦞ove{Xw%qR\5>v;k(-˘x-b{W GZkopgbͺ F:nk,YoJ w#gӋ?V1پxKwם́hv/r<\qc<@}7㸛!G\h{q+ ;{w >{gEvp#=s{\F= 3Na Cw0ZpU0'bౌu/QPxGG;W{Wo>\Э|1#;URb!9 ׯ;c8ojlfGmg+!N;4neXgG ,ǒzW1dhc3c Άv,A\}13-2c LM/SP !µs(EY{\A#CbNJpڛ/Bvb&Ʀ'tݵ92en2 i;Sг}u,oBdW@/Lz39z,<;+ח[~U7QLdbg`]f.e}Pgcr???/~9^Pd3z?s9S#ʌۧi\/nƅ+*b)i/\GZendstream endobj 87 0 obj << /Subtype /XML /Type /Metadata /Length 1508 >> stream GPL Ghostscript 10.02.1 bibliographic references, Rd, bibtex, citations, R 2026-02-07T16:29:31Z 2026-02-07T16:29:31Z Emacs 26.3 (Org mode 9.1.9) Inserting references in Rd and roxygen2 documentationGeorgi N. Boshnakov endstream endobj 88 0 obj << /Filter /FlateDecode /Length 3147 >> stream xZKoFoȁԳ0wO8JId ֌$e,[UM)ZX r؏z|U?Uɋ ſEU\/>.8Z?⛋BܖkU\\-^^V _V^ůlJy#dk˕*~ՕTJrsUc> 5|Vs#8[1ްzgg}\o"Ml}g.w=Mv^~ϋiytZLR4Zb >_q^7I@{qɾ924f_ҎR }b3Ja뻅0 m L-tiU[ht_w_+|0c ӊHWr~Շ/ſ`FVܚb]\Ń&~Z z՗KaK/g&jTP$ĠU8]I m/Miq,O[>5븛s\Z*V#FZ[źC@{p]*}C7r&NfohcicmGyMb$,%AlÅQ]emo9=?}(: &~ a,[ "fEX 0M C9 ,Y*>2|#3oLp3]ݷi*` ]/{4q6hu,AJxv УءMZ￡ge'd,⯿I5f2rp |6y-ՊGW.nz6+hF*z>"K$ᩧN 4:-e4}fKUr>ѭ4oq3 %Q<'  [_l Bkw~RGO>LkmsnM62 %w;">U*8I|tvn?>4x/ O4 ESG^ z(Jg4b FRʒ1%j0vF)1lJ4J 6rt*pe]U6q־+/a>AamKtri)d ox! 7cu@&62u\KLCgA"%oSg%!3uim .}Lg!M6=xMc^HFM$@a#[v>e/'< A@MYO]L:4q؂[( X!{sWO3_Fs1PJs"W0^*%]Z8Jc(K(̈4'|2(JKVphaA7m NT+Ӂ-a8pW+ ]8kȻJxgwo_+ГWpEt"-Yʸ#%<=sa` DCʯ}ʉG{Xƒt%)u.a~D0j:nqI(6MY*G>.rz`˗ed@r%ȷث z0T7m_f/PHqDdu=;2ZPЖH .M€Z.~|{r9p<.* C1vGH\w41n*ŀNT#xēm]&1G|fcA.t?>F=AIuMk :" @ 'qW]~5I^iX  gc :D:\އ-)LT$R)^#d-Ux;1?_R]{ X:măYd>5&!3sؙ͒cؖFA E=M7bֽn85;fSF:Ěi&Smh9[A2mtU盫o7Y"2^Ri und>U/ ΂`ȬK%tR LI<>tCGʴ"ߡYݿ"M% >SX' Өl4h2QliJ%JiZY-jߦ;4tlm."-GL9q<@Sf iWJopЬ f0[I&Spv&,Y7wRyWջ2/ 5Pv]"XߞxU@m c2R|I: 2_&x' #3%oGދtͤ>`lϑMk2vS*̩B P/~pKnX2f[ҵxb$[A鑅<$WĢigN07߆J$NKv!yPsPٱc7endstream endobj 89 0 obj << /Filter /FlateDecode /Length 4630 >> stream x[sGrA+|Rf*+ qb!Y,(RJ\eٙ{ͪ*/~wVͮ~;c,~7?]tc͔.3Ui] >;W,D ݼ*+% \_͉J٢6Ç/02mAIkA>l8lޯ\G^:͊e bÉa8i97"K0Urs3_ķ31ѤܖLݦߗ~dEPBjNźEѝw.3mU*ꞆH1™*cyܫNׇ5#Q8kpcKuÅzV^).Gf(+s\ZT˳PtXj* !U0,K}XY_eBUjfgkElO/u>nKU2cǴDen#&|qo`˛Pł;Qjg pgxGNA[k soG!ݢwnHAٗe>v ~6=a(8Ӟ'--uh(HɃvOBZ+ԉ eP d.,- __^_oww"wzG٘+˃URE# doh;`^fBI$G@R2Fx OXqS' }HV#iW*"UAeGUQB27i3J؈.vPBvM*e\|׬82 ޴7VPۄ$wIK gEyTDcz@P¡+î8AGGP#b ~vOʔb'ꡱ!YirU =`:.A/s_ӆXUNnxwsԚRU{CҭdןBi_snMTDTCd4Gkֺn4+^ IGj2Qm6m*_!TvY&^FQ66kd\ߤBI- sscvs3vC!͊`W➙]WjȮ~>Wx g{X d @s b].Foc9Z妴S ['T SЇTffo}҄/X;ywHt"W5wJAΧv#g >.TGQhwwufIl[[<><@%ݮ9}B93J#DCZHjhI4 )3i5 ">Ũ˓Ѡ.vdWȨG>i: a <}83$&P˨H&W,c:xWظ3*;U?6 ,`rԫuqoA|kFMZ\$/zFMQ>˹/DK7"3>l^{#2Ç6lx%oMږԾAKQ3wzE!ާM1`o}BQs crS>7ov0lĦi)}{tAN&͇T Қ%zR۟.e: /椐`kWſ3~"|{Ì P9f4% l(RI GObP?Ѐ7rl<1&SzUrw$)%VnW =篎QH>YoC#`ģL53SKGSy+qUD?4*SKa8 *p`ب[d )]hy$à!6m9cq 5~w~nC(tf"zediڅrG YjaL*BUeu[3Έ>E7qKLB(+n) 87q{kShפG]]9v|b%՚TPP HǾDW,d"dzq bA'} k*ƐN09XjFV³xofx o?)'Ҷw,=||3H^ _3gMKmLr6WLG8}G>zU4QUbd#VlTzLr@ãjwŷ^OUy&K I\6ژaY!fh>nq5KmAe(A%HL^?2a.ShjYp=G14=<%|v3H3A3d.TWyzf3/ C P`m؟/x*IfΉxr i]HS4ʐ+Ӭ@.0q7yO͛UA(ZGٱ4/H}fOAdOxԤ͋ӅEX݁:k>&2cnSDN3YbW{9.B?):?tqCd+Ub h%G+h>Rsl4dN ,GgOFl<2th[zYN_!m :dWyRɋ<; XDo;qKfX Sk| oϑ5?ׇ!Pc0c=12/&_~ Wsmi|^OAD[DfT*w8{:/cER\Yi~qgyO&sy' (& `>fMt ڦN%gROذ"]D8%qBg*Ot خ'iϬxЉMiuzt )t+#o]b:FQ|u1I' * *n^8k∦k! 9B]Kh"p: r:x[VGjen|i6nCK]#~nF'?ay 1yվ'J*`gNpOXltoW+\nEz}"Sk'oy'KlTNK/"Y}#d@` SGQ`Epe:6N 2'ߔ:޻O̻Pϴu;sExZ١5}ЖA'mE)x l앂b*o'`w.m`0;]|ˣ5C 0W UaY=jK9eE2V2|I+H!ެb`:F}G?3kØIC3Jd~7B1 n4mG/|endstream endobj 90 0 obj << /Filter /FlateDecode /Length 4034 >> stream x[oSy1߻񋓶 P4iUEIH}$m ( üٙfvflI39ys$z5Og5MίO|6RֈѪ6MW'ӦneV۪nS!D0^\v{;ņ°Unm4LThn\vRD.;V\I%6mq*MSK'BVklXnnr;E+.kt5[nY]7VVu`go/gWD󿟜3x,5Syw2nSj^fŝsUWשID0Rj~ni69e_,YkM, >fN@Ӫ˞v8_O~ylO&'~<1V`N;ѿYzSrDO^i vm\Lyp)q 3/T?SѻL^ Sz=v6*\﫝3(rR'rpD]uYlC6 `\y1⾈@P.ܹ'NBY IrAZ97"4uDx~2PTL;aJYv䡾;|w_e>&@v؎YVLjXC;`r*iD. -ngT^&zl˫Љvdu8RV7=R.UEV?BUKQsAA8w羷wh0 Kh iojQmHEB8Qe M;ToYnVrZ͘>a "R?#lu#_z S9/b.$>~g+b]Jɺ^ GX+D5ICx:95z^vdzTfQFQ=V\/ӄBM-xAvtQde yu{wSCMʹ3gg}-x$3֗D )K*oJøZ˞b ) cVu4;A"Ŭڕ.Zχy3l|@^_q[ IRoHQV4*&h><"H3~hIu NE'Gtf?}uFEڳ f%JZR$yK\d4iqSo>j§$rC̿dГa! uq!bf2$u|wV!J2}6Tb=M ,q)CС.k h2& ۀ_ѶJ}AV>yblkLYfƕAzBP:AP6r"7hˬUp&m;b R;.sk*cҼH'j5Ǡ4M5+w 8N_-݌p( i N%:oԊAC6|zޔxxO@:J OE=}=$3Lbh:$ 1X+{P"_/btŨ|:uНY-#e^$5.f'.KxSD0H/A#^ }ŹpۄC\1`gR~h;6S7g<k*t|J{Ǩ1 EG~!P[O̳"B R{1;fȽwE W6/!?>\I|*Mi؜gV `d5eD8`~_4Z9.stnar-ۛvoT>af a;p*eU^w.Xp+D@,xS*LSo>//j@yDn(‚ s}|gU_? "Ո^\MWltbXο =C#9<[.nINw2ƞ`[_pa.%V8a#?QWϲ˜ĴCr71{P iƇg!xTLqFoЙ7~/Q hwr8P8?o˧%i dGOf+%ADc'xt3 !]V}4ܮi;4en-ͧk>9cOKd nqZ>nc/%q;J)nb6g )M qsv=D:uHOoE5V[Pen O)eۃ)RT1;Pj{(:@LR 'EYtLMbtpF| R"8bДta_V8#HlovG!+X;IrpJX^Wr g& }6CcB^QKZH6"eEIX oY\j\tڳ׀TK.\jH)}gJ p$'Ъg"J6y~t^Hͷ~K+n84-C@df%7^%%lڻu]m'΋2BeL̇oG> stream x[[su~aJ/Iv@+^un$))% gpB.~{Υ@c0\)Nwsq&r?$ܞ||y clcI', Dgyd`I Gs diTx? x Oq^{ b2'vu .]Q-J"YBs9cE[|X 6%ځw-a۾}w:'@$lC TQblQGP얇 DUa6ĕbm6}~gOMdw{pc<+4,'',EÜu94G޼%1tq#xћz_"^C?Za'Ы'~5MrRtܻKͪ6U:HwOїQ@CEZu&od )`{rӈ`T7!=yS4[_X/Vxa(CD6@ccX,?0(E*#(RH 7yN AOqV<]P~yb2IЇk+ ̰$?dڒې)b(6ZcGH;0p{]_)3fJ/Gw;Yd{yV^~:K~H.VدӺ : 4q[MC5JKF"nrCUc,x7iH#U,Hv'lbāJ+_Q u?7o= qz 0{cvZ5azP> pma?J£q}z7D]pC&҆!8,,C5~eDS=^sVFT*7*>7)zݕûY`HJ HQA4 ȭzbXjɬ) #>ZЁnZ fP207XoZ@Bgy#]ꔻH][*%yV#{9y S2/ x!ꔫ -0DӡL)e&2c7̪`}gUmtfI9/Qo&V:c:]i:BuP ibl.Rz cqǦoLK})<ȉ]f'f,;F-7!FjeC_n=;T O:)m ^F8m&>]bހ{"WNW] >KYj|kS*X1cŁ5b"AFL>} *mis°e)BpYR2OxKAE`Oz  !c1T+^d2t UXT|D D#86jeTl0! Cܪ?ƪıdcUNcIVfT}aV +A$|@. E1o@̰4 1籬,+^([D+h73a3E"Ճ/^<<8֫@U`-k Zݷ4FFiZ>Yw}B \iֻ;B@w]?} p/0 ɦ.kg_LEsF?=<3r_Md9Q@ܷ !oBH[Ml,v4 hdp\G9 el /K&߮gy7d5л Z  hV/TNSc)}c~:ȾZՈ^9L|feRΞ7` ULo:Mt2ӇC@#h yAeAbu6(us vv1k172;8r h2T_"6rݞ~%)߉>a6\<Bgnژf$25LTf8zկboiZyFdX TkE_]qi<!bPS$rC@E[aH2[vx6@\i݄6ö벟qÃI$ -Xfr2>Oa}\ˆ-1Uk͈F[ YgTuDj4狟/ǭԢ̕Vn A)IR"TĜo$w)-:*YS]ey$ )3t7ߟnv8CZ<]=$36NL*8WhHf5|2"2fWV-i$q"\]~qp׼{م&4y:<@l:Qٸ>xxP7]]HH_w+ڛIb`HEN4GHpg3O}_qKt{ZI bNl=7TuɇFʶZ,e>iLt{9wW ٟiI]fidrmLfHX\ Mw(nZYI'\7SSjGH _ l@ d",|Bܔ.M_q}.<|Xb ͂N6F LX s,[y&iobϤ%cjs7,b4tݑ/Zk*H5$R! g1mJ@o8bLFqz`6 ?*Rx*FwՆgž7toIA2=r027aRo) r /NF|G<1i߫Mvm%u1O{ Xlm4НR^gTB&-%Yendstream endobj 92 0 obj << /Filter /FlateDecode /Length 5523 >> stream x\mov ,.x9/ w7Hݽq-5%:'({^fX ysEE۳lq{LЯ z_2+挻EjZ"OMQ..gl,r+la+T On YR4˄Jڥ4ܔɧ^ ,EeRd)R\%B !2%Xi+R[.V*OmQ`N,%`L&VgXLɶyYL,g Kʓewld-O$qk̄[E?O 䡫wqMX4KϓvK+Mu' zEZF{׾(DQ&_(&tUεMRunqEY>tU׏AWk9>] .vpOJnbFimuqУE! \>LI24HaoS47Sfr3cx;UA3_@Y;9ZU@RËf.c~TdZj^]9nz@*H7,g(uw@ǽLD(Eۜ\U:E>Ի;uЕǻѺy06&% -^xr/:߼xϯ߅F5og ; :[ ,oKo(,w&1ԍzzrY(kDWk&Gr$"fO& a텋֠ATSJeFaʉ@˛*t M~j\2DOP::o׏1V@JL/Fu0*r$0K )7q2T176F3HlW`S e@? X7s7 SEFxCRCĉ ^&~j5Š?->\UYZDa8]Lk&"FX_B&zwؑ5$𰉑Q\#<)!Wv:7 S흇'+\r6i=1OYֵnخï33+0e=h[B/Fb6jk.2У.GǞ( PGe'8)GNjORE}fkB'> kICSuE.`h hg̠!mT FHY&L Xlo<:nCPΑaqĈKȭ,G6]͡T%s?MΜ\9xE#n Cpt|L/#%\FCs:Ty6lUsmh||#ѧW1Zx)1VBH r >•({&6R~!ɟUI1a^22E@[>wBh8=YbUc51b4yX93U=dZYL. _1mĉy@# ,LF@wKZhCu>)vJPt^"nml1Vx,/6! EXE3v\Ş6_'>͔3?nރKxpA"(t⹱ pCR_^jكںCc@3hRME.%m9U>|!#߅u+c}&à1gW#{DaSݦyx _?0Əs'(d\iEn:Jip )VTlϷ&8@iVt!LGē6U}1I*Q/%NK"Rv,hѯXxz4Gdq-F1w'E"tc#CC^TaLvx~( SD`_w'2씓ϰx,4dLr֋)$'c„|\璄hFT9rɽѾRqڣ@jۻQu$ O].z-[]M xU _^_/l=Q^B7xd[t3 {23U[;bwB)qP@TS$2@(̕mM~h>/$+f:&>٬aFF LTrqv%H5FR_ 囕ů@e=q|&,`Qkt9~GS|ugbls`<6{drZ!ơ<ziĩUt֧TM>,{ERF @&b=of@{ jzeq9E)% J6!k)V29Q? _LFSLBo TSZ32]EfY@p lH,iWr&OyAK17+nb1+;b)%-Gf ӾCk>,Q8 0Cv wnW˓!tq]_!R6~ܺm]̟>%: X?Fr 0[$JdLB>{žyUwnY*V]|l#T=ҫy=OCy/֯Jw!Y%(8SBH@OUSoZI^W*Zrdrxx"HkPPQ|aF /QI>@Hٓ> fx 7==q!e#&WxE|0VQċ;U;o<%k!ǧe} V8ܡBiQ!g3Mi!]OpQ;;տA#G0gg.00$t:f3%RS ܩq52DL%/W&1'/\hIe5<:5d :RxO4(icxD`4%$_si\ %[{ nEo!"`kN^t^&q WJIr5rC32ak& p>  Up6)29֮hM؈8"i ώhp4_bG}#"ohăvnthu1@ȀT8s.#p$>Rp0X5fwmpS58GO'HEmAo bjׯKίDORY561 b|>%ؓO?Kw}dD9еQ\Ģ'O#t^׏(UΣ*&)HUz"7off¬e$1㛻KeD4r0} ^G@A7uk3%Ef](q%!uj[NCer䩘z.|`8swP'. Nfe&1$r).sOC{A2|w3FyW`;6Q]amP73w| >W8N3 :$ůJY|zۏOF踅^y\qfyjfqDYdh1guB3u`{S([t}SX5,I~8UW=O$;#s0SF!2/6LCdNGq6H3q` /T׸l!>b& e6#Uyr ؝ȸNg1m!rg,%=6b^Umgp@ȺHfp'AU"bTSݎ ִDO rc qN"[%rn8c1c:BxEndqL9$HD )NǨcM&oTSsӎ(UG2udڠ݋9QLc3ce\E>骾 'P=v\<ˉL[ *=X a@gGyoØ45w;w~a* |,"}1enVDN EZSfZySUUy MtŷqUa+HvaN.${:ZBK9U\"z8Tn!Qˡ?Cz6`l檟H_`2W1}-Wc?Pǚr_aז|8Lp"0; `%EĦ5r\j-+~CmjoA`V 6Ox_ǘqv_b\v7\xYf ش>\˜C׺DXqH!į"a}ƖrsTL, -^z8nu&Ek^8!.;>UY&OVOznoBHzQ^*ծ5O8z:NYp#9 t1TLjP9]w{1Ele*-L% b+ s{"GTlewE^Iz_]%'U=( xiR6_+f75R>LYXi/Bz1:>რ^W]9xKYc](Q̂>] d_7՝3I )VF=waw պT=Xqhkg ;tZ"ܸt ״ Ȉ#XnǹK?0 o ܇_XS\pX<^-X!|ŽePRϊ ˲}`_`ɨu p>VhTx,R2?endstream endobj 93 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 5233 >> stream xX XWr7 MjQq_5qA5dS\> ;&6"AL4.Io&јELB$FO%߼[ &$ͼG5]?W8;1*j#ç<3aNDh ;Guh:^O!;݁3s"n7?;j1Kb\M> ]7F hTa1133Yx1#_fͬdV1c?f53yL``1$ƛYLa2+4Yf μ`+L3yqaf,$2UN6:u:wv^Sbl7^/:~7Doj?'>5S.O¸ }JA:m WO tef$,UmxuO.5H0&kC].0GGc ۻP 5p *ͼ퀍 6[f;개@&k&ChCTyr SdEӿSCJvT ףMȕ;\%o, x8]4;X+|Mf%i {'xJGp^k`ŅG$xr|UǑ,|ИWigȤHv0 "m+.$ud j> 0Fd)OOOJw4Z"j`+m7 3j/@oLB@tяH9%&cB/_`u\of\%rqDp;S2Mz fq L;?p.%V"Y%N$KF0Ii/`_\Z=BON\ 8=ovh+`'ebER A֒(ob% (#FKS;0F[bݝ&Hx^j 9(wENx^)Ͽ̳%B`c8W ;s}O-zIH&cdco=eY%]楈FjYM(QZ'&>COsByuVp;E <yԓkCP9aЩ#G=?Ct^y=(ȃh6-x@|Į= M#EO[@z Zn)reDKv2LKŒ @3[qlMxԹ +4̡o^ҷb?;;8Zp_)le1A]]OCE2?"& _9m5/{9fdƿu ]-܀* 4|F۳q*wB,`Y]m/iVNPfU~ULmš-dcMڐ#fDܱ mΆ9ݛakq8Sz>ҏ¤:Τ:R~ Ǡ^ ٣KV--N߆rTg͏ָqQ+)fH-S#7em>: OפS299'q1eźx#olzJ >U aVf$H.4cz J\y( Ł"ތ M0zkǣ~,x戀D?)jo7h($vU؏2C~ܢr 8B"#ן^3zt: Rz~,LoUeh{P*4egN_{ifU~ OMF]X1ܐDslyzO GZvs3%glsWq6pT[uAvZ屒J${iTs5@d"yD 3J[!6 rɍV{1rLY]szD{Z8Ls,}~sZ~)$6iIlه1.<7.31#%/ Ru/e2ev:*@}y't=\9`)ݡ^Y٥s!y(8AM7gVy*!k* 0wW8?4/5X3&6VC])*eOs޾ղqMb R&9֢SB_gA[xc|*ĖJ{8޸/}e"8VB3 8Wi ZFt0Dt6]EzdkbJO qOv?\0%h0Yde1T.?^U6s4lmR*=)-%Z  `Wr m4,By \!\qAQaE)#u$HSB45Z'.)O`*v%C4tG(MN=G{dÇ5ᯇ!Ρu^rP\H`^*huДGGHZbC`##w8OntXqy[O̼ζA'y6t Wyu'y!]/(Z oq 89\AՍT;yݝˀ-H(LJ DERdW =-QO^ZNȡo &R Ba,nq-!CMoMbcxN8Lڙn걳qù]Yߖ2eڲn9j3XsV*EC+U[2#cͰ;^$]i xDTn{wVnj!>g5o5]9JbmNg|I&) NpfjCP3Up.ԗ>N^(4MMKֽaXkז$mCN=9FSٴ?f 50ᅹ0 شd߹`0i/l L㶚Ma[bNd:qbmX.O[8B12mR%4 zE$οYW9t-g|7lzҢ> stream x=mL[eB{YgΙKƘmjnc%hUL7[  eO)"A vr& !,Atn&!jfs]}~>?u)2(#J Kw?Vv~mZ b"!Fy5?/đ* l!9$4r.F|*"r"#_qz$Lb K;T Wˠ| u>}ip F>YHX=b{4nPI& &a;x^G 28R+~)f4#TAOdV jU,L_jRy7D:Ã֖,^3!#v9 oiKX^ܬIkx] q``%X{Qpu6{C]v:kZZj*z;Tz``8Qߩ Wlpۿ N=]> stream xYy\WܕQS-jkDq Ȣ4KCw-P}-&jLFcԘh$.97ňyy?ʪ{9;d2E}7gϦ 7b~knrf0` 덚{1ҟ~g0'B.ivEn#6/qwXeN>&N)^#01ow 3q`23Kw!2f( c3ÙƉyYɌdV1Yhf 3yYa0Xf3,`&00$f6YLaTL_&eԌ#g1 la:3]_;Ӄbތ c`LYօYDX13Y}iCVìrZ' ?grWչs?զn{vٓ鹶<{]=wMg>Sd3Ŷs;~|l׆}_k:P5q` A!j aM}pҵuħZkHH[n;Y 4'g%4AqdAr} 郙*@+aFDkAkNF+ ;9\]| ,Y1+Li}+ k5ݨt6tZ8E旫^ȓ?epL8[-n'~pvWd;%r7h 5DA HKdN`H_ڧ= j2$Fnt%4#2)8=8ěI)kRiN;Ѥ% lPsv[(UGkAkpK]x ]Pvo,V1E>0j0-tmRk=VvāL" q÷8\9M{vBTͳXpVK,B*G>&V79XC2D*:gMK[fNU)}I'ۻ4Q %>jb-|t\~"oYTH828i\|ڰeÀ֎'q7'p9؜}K3't =Ͼ}dlm,,JUG(P}ltwi#I_04hȼ?do;?48:;`=pC^+j$2³]' õ8\!o٪ E2̤4fQ %هok*(H1I3 RPh ?Z}җ\$% >쮭rȈU>5.)6.I^ ;pܫ*TSX,S^$݊oɞs)ECBHNMN..M&0tXJ=g^hc m+[16xRee,"86XSwƑ%wKdP:{ˎSS&%Ȋ(* 1C`_q$P&VX˅=PDkr}pAuZ)1蛙)Yh7ԙe.%sRE ^޲mPi(6m0Zt`HK2#6)(f({-M>$GcIbUؔ}7ڐԩQxlԼA3iLJr,3~.:*R aaMut|8Z 0h9,Hݚt ,4{n |K"*J*s6$kdwv}"ߙ[V3Ծ0¥{Yn)U/={LL={ƵGO5Ʃi-!`N-w?832NJzoPed#lZM dcNPlL.ҋ5 =_̷g5q:oJ3 אq kmgHa *,f(}o_GRʋ5 NEbiƝ]="7k;eJd؜[ ](^}@7DJ}28 'F~H&50}z|}ɔ?cXdXdhu7rlij[+%' T3r췇7CB> A\HAXUM~I9]p?Ub%TF|K^ɳmt!͐V^XީSVjk:9PVPPSf}adb8BUS9Y纉WmݦMc}^M#|+xOn+v؍c` %5HHN&@-u:e%{}Ơ2Mî"۶Zt0IZ"rc x20*0z wn"<)Jͯ(/js2ʪhSkWӜ5o {ݍGh4/PvR^dpvE.Cv fP&B_5{.n VZK09^AE}}S~qm݊7 GC?A Ӵ4ߤ1+cK| wyxi9t}?ǿ?Ǐe%? A)zl\\זf_hX:}AGFD1ژbH3P6'{H+R񴼯&V{2IN_/ %1׷q\SzJ.NSNkZCr .ޗz^QO Ui|=U% ױ%3lk,(=M*;,;3u>c =ˈKa= xVx$"? b)B@].xBÃ;e*-]]}E -Zk7C6L :|fIE8v3j H߸O~*j))[FR/k s!8 JέVp#Eu3&L+r?`?ܰg?6SYcS'g2ҩM_h;?\Dii"jNaګu\UQF(-`KMyM932tq(߸R4 |G9! *jL7x27gY{vdŎGKդS SMM"gIϻdbNIoF nh v>NӃ8\hi2U]ElKIJ˺)*?aF08P>֨˷%6qF)vwR»tm..++ъf1j"CuLvՐ4O :'.7G~^ZV6oyNg4BR"rYF;1pFErAR}Q8>0zL(E?Uv\6*)6VϓmVb4$,h3Ro 6$@16 [ 9,KS(X`7P<(}sGNӿ6T8SEu]ЫįЧvʁAKKXl6"YL͋8tb1 5a5B^ ̰dяJJ *1"C3p$oZzv-_잔5.O n4VF?{XR;|=$F"]rPU #,ق[|P8, |:[M0Lsݺ12  endstream endobj 96 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 1524 >> stream xeT{PTu-{Ѹe!vñh& o &(rs}V."쮻)2ԤR ,3m.S1wvq"RⳲW7U0m*[8uZyh-ǭUZTCd뽟ǜG/jxeD֐I.#/4$K*EILD4djSMG<qJL=Y]=D?G݄扸 (ĊpWZ^0/h{Upgf>ju@3rM7XVLǕ%s8gkV q' gC*i"NA4e~F!I{?g("jU(g;`: H ^Uža_XIk=>)ϔgѠJvOӸ/wŝfOvn00|![\kk!lg4z#w|o6l. Jh`tgV:hha{cp@(fEł]5bkjc/!coxu\6wƪЇQ"5F2عR~H0Lot\[PDx59ק"!DXfi.,w>oݯ;ؔ3C'+Ǿ8[Ԡj࿐QK:kln@??1T߶0Pw?п}CR>|x{z3cȻ*cᰁBF䪚b(F`BP_: 4cyV0uEZ!V2;s=)& nNc.úSCYJos~<Ata doKb*?\W--9ۡiZjk2C)TՇ'$wp޵6Aٶ ܟn||Yb:.Y&%{QuW}OV)M#J+lR,a.4--{Rхϡz,y'?hZb.H*0û݁ax!p$ˍ@QQob,8&;1U_帮U[9{amrC@IvfC0oE_ T#p-k881>æ @6dfT7Nwz.-ҥJz _$Xܑv(4cODbO-) 祟u6_5VJQ:"bn}7^(Z|v!IC2ؤNzh\m&}~8ú ,I|b.٤ghmmszZi5;ٷ"%*7tL`F[5 ۅ!vș|2ʀo`~+;ƭuI9{_#j^6Gww::<## ?/endstream endobj 97 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 1444 >> stream x{LSWo)+|NwoD&dlAEe")W-B)嶥Z(!NfNefjKN5q%%fw|> ;ʎHcމV6sp)ӏς0!, )]ks/fV4eGYzFc [b-X6Oc;CA+ƅGf-eggK170`A~xP+vh]R\k r .Xv,pm~OX= ЙtijN~)0ԨHn~m^J5to ~(~.vt,6&Q$"+O8 ܒ RWej7C/ >$uZL3c\m'`5h(уa0eQ7eN;ć wMvk"mLKZgGm<>&dvhě2b!Sߗ8_?l%_e ƻow\- L&;NoR*ZMBCØI({ Vޞ◳6o'ḫKA]cdɽh=?!WPu0DhhQ֔]}gN<`G3;"e˹ؘ5ѫdd\$d}lBӞyRӢAooJz]Ay"Eʼno*{2:{ N!Bdafc7Z0O> stream xcd`ab`dd N+64 JM/I, JtwxӋewS0c1##K5|Z2,(~_?~bܥ;~3>,}}Q\rUl<_s/Mn9.|ͳz00MPendstream endobj 99 0 obj << /Filter /FlateDecode /Length 598 >> stream x]=nP{7?6`n\$\" Z.ř)H$}__^.ӯvNesZwloe7<]I}\wo:N}|opi}4]S>NuזtpT baA4Ƭd|ǪA|dqdqbqflUOUN8T "BUQ5"B"Br## ! ! ! &H#i4j*XTSb &f#ld6j*XES& &H#i4 @tB:Zt5lbv2;x]NfG&M: ep "ArRBAB#@a1! FPu V A!! dPbZ2! e؄FCkȅ`P0Qyd הo7M&\SI߄k7pM&})ߤo5M| הo7!L &lRFIMOusrӑm:/ߝ[/+0p9$endstream endobj 100 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 6265 >> stream xY |SU~ء*BY[ݗ$]  # eDQFIJߤi{˽s|'1VL&9(0hK;槱ǺՌ=8?4n5aІmåZ&D'RJnV@IJa\NrV8 JH zj 4BH~yl݋^P3E({?6W.z`˟ -!Qn>QQohrVBkR$?R;dn>w4h@"M07thYRm3Yή@ζ-ICmƒ Xf]˖ק⋬*N\A&/ubL/5BXPNIu8(C tOMB nӞ71,LLzl0XJ^Q3+b5e2߽h3988y>5] ^/eG x.m{9|K;Y1fڡZDQ^ ) !=cC|u;GԊ1ĉG#b9' 8NRm1 ݢ}iSzijG}<8;EV:\pK\tۗGUvπxAsTb/=W/k{#<>8.LKFKa~¢u 7XMk$. AMVA7x4nޱ*o':jDMnJz(q![`libö7tp/\| ף ԇ2*""GRh+P[%<#[tgXRO$=sGIdyVq.q- 7[~(vZ᠜ܴ"`Nv\]?~K/}{  V=38z\K)VJV<7xTm=jar1 +8w}1^>XcRrQ (jrVf*֖* 11-x0֤ 5EC0M~F-v&} 9OOߙ;6}"Tg 8UrmGu>]GyvWgzQ^ftlzMhoߌ!yCBpKqd=/ޜc8#{<$iOnݾ{|Xc0mg8q- ZkrPwZZv!ѣ᧭ʱhVFlRHjddu"Iwm=Ze.siWA&pO. ,?).--(3`q#ӄd,Ǟן}=j4}α$JmvM#n%#nQE|b=5lJUbjj~?[XH~N4{7bC8^╮ D5DW1$eݺfenKe ] $+#5BrlugtRckރDQ]֋F'^'C6(7c惮]]_v8bI4"OV#d6RjOU'&nvq^Ɂm _܄P)opkzr?c9Fģ?6/F\cJ"(o(nXiݸֹѥ?waD>7gɄ7edצG??kB -k{J38(6O W>/mҾ NJ[6%2XvVslMt d42m !dQv5+pT._Ր>eYxI"tę8G'ɱkk1@ΰ"~S:ĝ;_E *R|@{bKj:9y( ߵ|m).(,%; Q}Wq ?~14 ګumLDN&-Sy^\ߩD?c.,m6nC5IUϣ1 CHJ S?:!)F]?_`=2X +2c *tʃ}X0mjmnBߛ,͉w ?ؠ˩*5(8z*6&g̚I&J ]xmPPxxPPmNW[umpڀ#[_ u,dϑy+T.hܹ3BVxQr,Sb=훊(g[.[4o5_(o͗钿3u;e+>z,2"үW;-m-רn>6EH x- H_(kOa2bb8>8e M|8]f{X(gϺs^-|ά"hUona%d宐FKO,ĀG~!.S͂Ltaa1{8kVz7W K)e@6MJhߣv; hhk`P^7vm4|g+Gܺ}@C1cb<5l6ǩu hPt_!5GV&o Ct4^ͽlB&b_8 o9G P]rW;/.e' TF$_ѐG{W%dĂSo{EEQ8/WWfftO$Q:K,nUeEr*VMq'y2 mvoְ8 [ у-EyNGh !50#NEٽK8onbc6L?$# .ij*q?`3 "Ykƥ^2f*58J;p%~!Y):V{7dRdhyʪ=itht_lqݯZ4 b|#I>eK;5vPTG M2*.,jDTMqXIeb2Nc^^ e\~Jup EHrjVV;iژSo$W]_B>^#%(:B&Lضf_BWR+6Nr=?LZa/b4*p;}ٳw+2XFon+$U&'MDVFR 6œdL/PqI M 9=6?]•s R 4HH<}a"Sw2a]iBBĚ vc HbK5*Nq41\mî|qc'OtU@E\A6bU[p)2JˆVf:4@/&jd P]VE%Cw4i Gy3=8c 'o[4e\Oo>7vPfB>p%eܮ´\rUv)IEbEU9 1`_]VQ)qbdK|ڠ{}oXGSH[n63OP9Pƥ&E@ .Ɯ6qS3 Z#Q7JM=ycwL2{NsjWտ]aoWT\h܎vNQT*"5dZ6Qf$GT敕 կyZ|ߣ 4v_&- VSL{Fl~1$8)NdN8_ɆoxL1Z8_g^1h & d\ʡ!K󱆲6mG8-(G+?l.:ֺDz [!%/Py)T[3NL (3P# n 9\e}8> stream x5{Te1!)`;5*3(LTRZ@^LsH2:` k hYy<8G~9|><сxu?ۦlWmp8,jɨҌ.L[.^A%h•n;!#Ąg8Ha^+ z|?s\p2o\4:,X>?]Q.+;'=㖙޺Hj B#ґ(B' | pBoNܱh Bn ?s&=HY.1._s:Ks Q%fd2:+i1*yNDt[BT q ;,mM!JMY`a>c4tކ>+J) 9>"%nGl|.T֐[ TU45+KSwgnHx ȧCzfexQ1]3*l"h$7+UpF[g91%j*[?xvñI֌1vmt{6 Q{¢S# _ZT9suָ' L>OL3E.J86?by[Xa 4 Ld-:3 2!Ih72"@54CTSD&,l-?&0h8Ӗ^V_CR}me5g ȒZ%S>N. +6ɰC<4R/ C7(5,Oj8";7pA2O%%/f( XhoW]S)sMcndXkF޿LN Ө=Ӝc^Hp&YuܶQДPw5ʓR]+̛#VO0y/CfQp[kZ+OOа֐mտS,N^]T}e4<^PmIU ` yeGș[`ᵎ'_Mcol H#m_|o&U Ueqm?B ŽaH\` X=,ge6"OYus AII=z!{5LBj+Ć?"Ƒ=)Uoj:VK Ѥt *!زR$3'ץ&SRtiS) [ _c vP-$8p*+Z!>I>X(r? Zur"$)OMWf/Y^TYмti2TII<>TnHŪr>9 Ȍ"(glsTDTvG3GkY9`UUNO`="?GaJ?ThN'x,;;o endstream endobj 102 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 1388 >> stream x=iPSW_<$}Q b-KEԪ). ZQ qAC'0R*R_ ,VTFؖQiQƹ0Ù3wc,KyK\}+@ljbtԧ (;n/=Soڒ׏ (bL•NIL)v=v]w2xJ5(Jp}(bu+2sh<&+Ex\Fo!UrCep$00[I#r|F' ᄳ0ڌ")yኤmrMP]plٍВ‘e^>(v=](L41?U%tiHxQ4/4>Fx 2- 6)=E !u9ѧ}!'!""]Gи&hfHEQФlʸCXlveH{ P m:ÐFJ5ΝkI_ew=lDEh~'=fU\YBZ@ HŒv?0(z);T k( >J!p9/R҂=uA^,shˮWB-w"ltɁlyv2Ѐ?f4ǖ% u%Xൢ܎n9Yy*\[}u g;>܏li!nM '{.pHCO)X#OnC"Iӷxxwh0JB׽q>NK=|8Y-F+2qy*´n"ocyڎ7 )1/<S">KF]<<[Sm҈Upvu cqi9W-ȎK\Fb4I-޾oKR6/tu`L-&SU-ـ3i|6zqStXUukk ii 6%k3!SFz܀`kc* n֬ܭX QU3AIlm 7C,RnA|7Í: lc!TC 1G*c6 O|2T Ho㡙/[ .CC"`WL- [^m&øw6/VXeMbeb gyo~iU+8 :^Zeʬ5T57V%O+P@O> stream xx \Hf1;CZ}G u d¾ʖ'y5ӺjrUVVkk =ܯ `_93j%߰9(=af/{Q?Wt'Y4V Pd5hˠVZ={K d `!Gl{nX}ᑶ;1vqvv4"tęF^5:dH6vG Çc M4nZVȉXPb_#kkBb7cPLMfKNtOHT+ .` pR %(_"4ݳ6]#Sc o۲rF22h+ .)Uþ5AꥈRzn.{導ܧCS> '@uVurhg|\kcw/\Q)_Xʖeg#'1<-,1W]=)aU;7SI{+Kpi E#?~KkqxJ5j;84\M| ~ ^iXKD{ٍx2~5IPS "΁ i4Y@X8gWMSP(cP0|y/o]ߊяLc^ c1ڌy4 }1"F3?q8x譫w8\OFaL%\t9aJh}f_4>4yO=)70زG=P5HgK1ZV'PihL:=BĶSh&c{ B=7wٯRdmo{kQjƛlYg;!ↀzM9Տ"%;4?)PW([x4>& X11UUEyֲg0''21AMŽ^&9 O@ן#Rl|27 eWF~K1Hyޔ\DzTS)h<N M"4L 'j#^^֧ʞ2H%.2E/Ӕ Kʤ4i4YMVTE)N'(*cB<'y,0|Hee\FV~AffGBO:5:rBD`4aw:J'ऐvsWHgZ7x*$8`N܇?#7; |Ipo0[̣eьkF> o  wmK}|WGxZD`Bi#\'XkMWo/o5Y fw8&ewxʿ`qob6'uQR謪ȨpL"DOCJ]3o5{(P8Aid>ff(e P::SQyF44#@@Ґ\,HT)cpP"Kv5PFz2\>tEh_Ja,JFcއvfj15e5m̭֜tޏަ\odXk7r :+Ex⌘O^ǭ']iY\_ ]2֓. GmiQ]z06ص_>:_͡u5Ǯj\L4 5?3"gBR4HNeL*fK 08!3{潎甡-|dzT<2!Q55%˫æX$bn.g~Uga4/yp⧖($ҢɿU"Q$@AsUMU`~pit0G&yMؗ"93Z@HO*3!#IvVʲگd܆+m+ЊNp [>VaM?>@e]L`IX~7 uf'Rv".a\{=G֐6YgkV63V8Y륋Dŵ7.w2NvAz+aw0߳ƿJu -At&ZڴMb+2AuyhIW\EvZVR"%]7[6ѯSuZtXT ?l|icld;Thr'8xI}TD},ynvD_><7cݰIBg {ԢWբZ aw.Qw/ز(Si,*+3u"z8^ pا þzzf4 cǽ-MT ̊%.,-HRA A"9 2 ;aJgql54TEE`p {%8I>iyO_`mF4WQ"HxZNᏀ88 t$&%0))<$2zIװ?ϙWxo6(&!B^ qH[ 1ӣ,RJ#IH]x^WsSU M8T0d;q}Xu@@XX@@uX}}u5 0 #l@I7I%bEE?iQ4 CyL&tu"7/5kE'&5.GCQyA:<#OS @.PXˬ]!}) oiL4>'v}eZ;%x!0(RR}MHJASHEBe?࿧{m#rdoIK(w)$3,ɖZPMO[%N3c.fA C1eӻoYX ~- ;:SwJ]g?u|D-Z2~24NʆsE*I pHS+S oY EvcrvU$r+qAF41v1 fE<G%E?ߜP{z$:!9) -6eIВmV&tYIN?~BoF_|}TotfgNOmE&?&Fr>MA=S~U> ;dwltpHiPVZϳj ggfqFks2 {$L⬉fؤen)#7_.3{5#^w†̋x%p!JuMFm@Q(cD~؋4*B.;.n{`[<;ւÓbUJ JIF7uUN sS ccj+ ][O,s?\H[Kwd%x#GNG!-߶H_T ~t%iM߿]G Vn W"s0=}wGB-1\S<&X6MX Nm:< __+cİ%:GbP2cx]pΗ?ZJTsx<дjџБz֫4܆f'[\ SH{+d9 ĠϞ-%_6tKvylp;O,-,x7j ! ,*1JMft;[B]LST]1(YL59yB:ҴgU dNZC,:#+++&uendstream endobj 104 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 3406 >> stream xW TSWKQy͐x6RKw7pjAER3 j%5b(9 L߉>OP\Ч-9|.FS 7"|g#[^p&5-u ^AUCѨ+ c\B˯l fgu5x2 ~EW ZFv vǨ!XI,(y#@ %GfB4K`D -&u&u^7􆢎Gh#˜=ikXT?L__$zx:Z0spL`P/:_+a2 ?UK;R{+@񫒃Z]#pVVRȹɘ1M;GGVKa:8u0-hԅ^x `,cXu4 1.A%1fcb]r]w8:KO{;:GSZFGMdL=ƌ cԦMʭN c"))&+'X[@tr+Δ0o,(wxTYw0xJjHޛPaoWRj)oƠҚ*RZJD/,z(nPКrJiWRcrIOUZv7n|!1hngEr1Awmzb=R򕼵 r9J,ql`29ͤnӷ( X9pt*#q T#ţX-촰:Ed8I倣OŴ^ n6Y\qPXc6;rHE3+Ĝ ,^ x o#bLps|5|]Z &D>kPzV*Y+=yabIn:x`# ye "!$c~8~SJ6L<ꡪثpje)n*2CyČOySI8<eK֮˟ OCo{N4v!iX"Ɣ>BTT|I'>{&n>. &iEKЫJa 턛5U) ' f aj3a0&& .5j8^_%P V$op;LfW\DZ`W[ R[Zn*DE_w2)OZzY[&UGGMVI8dLT!̅ԑĚ\41W@fSk{wy 3h]]nY";o׮ -4WM%y/:E3bm]r\3bag{3goyg;^"[h`40F+TaVGC9iZ,?v8D#ըS!6 Mf|^hT:ݢLf5)5L͋E\&l6Yx*:FcTf1+<o9 2-JOeyרSHdi|}ͽ-P0B+s i7jUxem,`%ɭlߠhjźe"y{[ns͓[Y^O$v$$v\92ߥnSO>O۱_1 ˊ pN35B4;t J|9uP'rL*09,ί2[CIW@Jt%彁)6C|;|DP j{ǁ,H?1$QIoAa Ai?^h֝wh[^Uo}p?YG vu= Yr6͗0مFOEBSOfS51 0 3{=~X *m!АfȨj&[k4E}|A.tOϡk1~ӳ_K遞0&(@8!LZjt-;!bt05~E) vKu+3??}n^kZUKl;֡9(]߽f2d4&5kk1Yum9'|T^4>eݡ6m/ 3Vj-WUC:ǔԐ(+HKGD͂u4s{܇I &aUw)"ǎXȧ%$Al>C_ s z2%bω7{Hc)()7!0j@@j Ì6gi\NlSV \QI$5HБ-k*t*"e钅Cwe(XR yB^mkO8kHiL*<~L F:s–hHǯ"+CH$t?aaL=ɑE!P|'Jt~vh3,zLx,6xa%)fhFkO6'fzQ[oPB&%$b_Cxn`BEf*BHXi.[/Q T-Cd rX959rZ.s C@,M70pq?jNrǙS=εqسC>Ǔ@֔/ 9]OMo"ԸW$: 1i09'%4IQbH#$hT @и+kYH\x ȱf?C$QU<PL( 7?iX-xkl[VHhcH`I-Snwx߈qÃ%2d6J͖#GRendstream endobj 105 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 1745 >> stream xU{L?c\3Pwu7e$[Tm,!@RJtqc~&&^&&0IDHS6 ]nuT)~.Rv$,iu~ח`,륣'$U= +g&KVV 8Ɔԑo/-m[xںzs* ǎaoa۱m;ecCamb`+eLO}0ՐkچhGM; ,*m62Ǧ>F[VsЉoޢwE{|a2_IwdH1AV^(U6gEۉ1V+L&%yN`@V`I忀`N6Nk:Ed&ӗVN'OE) cMaέ4NC޾x(mAۈQ>Ҝd #=(ep/9Alz*?s%)>WN)/ㅺćHM .ADbR w;FU}hzf&nZ7t G ]AƵC/8 ;c0nIAȫfUB v\@^-fԬ!-:m> n! ǫ3ýD(7M.3geh#-J_Aw}rpe3Ŧ^F>i{x,xO^"L*02 &Ύi[KJCr4ڋ5ڽtJI *T7W+b xh!>T(dM6r]Ec$ԕG!+]Ψ\Bs^Z|@6 v*dzF":۸=yE@\+`hcƎ s\hM%9Zg PK7vŝ~SЩ$zLdW@c1 ŀK"@m 'jGO.tkp~'}q V'+@gN]'|@B_`c3=æӏрm ">ƊVVbR!͢7лm{&.Œ//s1@=P8+A$gJUȨGO}nMwժY%EI=54pezⲈ㍷N yσ/ C0я,}ú.y#at PztJgoÓ琋!TrF4{x'1CCjKzݽǦN¿"=,g~&ُ|9Oϔ d6U0r)MuuEL2q,C?k8p:V4¯ DԆ= s|T,! {xZmWVqf4&j"mUV&*:p=3ڣ7Pwt2ѫMG3ӳ̸>Fk2OQ#)r\db2(9+}a?b+?"ZUzPNp|OOfl:%nU୎=*w Յߊ' i8*N?v(-x7 +O@Qs~#y5`dLqQqy7E@7o7BL :m6gﱥaA!@endstream endobj 106 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 3692 >> stream xW TW"h8U֟ںq"b%jXU eŵj n32]j۩vvoRN9;'<^?xcZ*qoi3gL]O=ų"N< ?cЪ.<&&nV1b(I`k'y"e ZCQPj# PoPS-ԛRj:ZNVRP![j?QRPèHj@S[m$7ORyCroe?;,bZY6l󰟇?FYA+`} >`5w2HDPe~$z.z6kFKl'ŧ(1gM NEk!i]s$:P{<7I4<{0 ig.8"S\h }1۝>ָ"68%?<-a&+G )"ΟN\mqxQO7HDXKp ʠa/wA"onpFHB8|sȷguO~_SP8Iuk ((&*c:S)aLJW1l iNC("RXO5P :n{Cs=7+%&tQn((OJ9-1{$H'k7<$ A`R#͛x$'6-"ǨJN:́5ۅǺP$&= &.BQuP[ambJ|+x/!g0ꁎ_[$xrBٞF$<+)< 0ԩ)Bk/,>] vI֨xWbmk- ߼  8A3~7/ _&zgT ho|^N\"?CA\aA9}H?;'qҁ`dڐy:a W :I; lU<8g0l;$#\hWW?NٔJ! $r/z zk_H4_sV$X^#Z=p1~-so"e]7]疞69Rh*b ͰD(O9=%ٲ}m\qJr6rJ1h x e_'60蚙,s!4r2u<*b)3sc~kq )V쬵f}RT) p^'T 4~<[՛c 5&DX~]s@[ucy\%R$;|v yJl)[aZOSY~tZJdgDW^vWh=J"iM0weA"q/js2ʒ+MβVa$.}}DDg!"jHi.R;UBS*mt0au3y{ ~Eֵ݁v_X7u!xc,{E}.r_#4B}M9%Gx;(b5F>8t0W< ڄƣKU-V*|x-roAo:oa DGhڣZIO5k|VMl 郢4N23zЍTOz^|.8, 6SI"Zzh.OAjp#~mR?R%u{*g=Ɛ^|{%G/gp*= H'2Wd=  *;.ZݚR!^ao6!S?`(R@nlFE^Nq-dBB1ן8`%lXn.}$,/& J)ő"JKϠ@򸱜=>b Ahv'hn!ٌ=}Ho Uœ\VP7"o%{*RU*5L25?S26U1|yR.G~mhm6 .`kci(ɦJڽGr`;Xۼsu>bD"C Kԧ2Jr5nROPFݒg/(STl+#xL# (̷k-RUPg*z IxHkoGcPI>ATY}Sr 5 4"KcѭM,q՗eh$"is{2n6O0"qkfvl(?l?Wo3JU½Q^+Юa8♎r[ZmAQ]2endstream endobj 107 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 2620 >> stream x}V PgqfzZ`錂l]2YnE% 0 p)s v5&V,!uwGP^}_F0 v[HpȜkwsLaRůjQm2iw;mˏG"wxZgLym׷xa<Of Yl`62%2f9ɬfwƁ82cgF1EƎ|8:bň&%Q&ԪTsEEs[er7FN=򪕿UUZ[qT "iǷJ` Q>:kkt.wf$   m>|7Zh|)l,_c_S[[q'ၚ`ٮb7 #%*Λ¬1HQ5UOBmmTTm<K,ϻ]vs&&C8#>*~8ROL7p/~}gC@? :dϝO5 Jgggݝ+g SeRi+[g]a ݍI UARK>olq "S%ZAd&pY`(]%h#a9Kv*fhCwe$3_m AwJ&0"5>UK 3B6% "kSs4vMs>ܩ'ɦ|!B/ 86\O)hN3OƀڦO [u-jpy;lTSy51ha.5z}LxXJ.S}|FF zA7٧~I, "޵fSK hO 4R҈j)T)lA!Ԋ}.D*NDQ}" cqW[@qױ%;âGf)yI yQwknyܢn +U~Dj p t^:8>aa@Ql3nFjh"dzo޽ =w6=>6nƠ/* uqK$Ɇˁ{sEWʊ3 [03Y5K1jz']NgQ?N8Qdm a3?8sbuUey*Mc>~0eǏ˙Ad": ]|mszuҹM+Q-,SJ>CiY _$p9簕5U \Z:i?MWp|ja!N'/585o7>%rnREX$ $%}! >l$1*-I͂HBWP9Z‡O8-5bpe:n/_;ǃ;r/u1M\>-Pvdt[< JFRʖ/;%A,kUa(:cX,uhqV '-'1,-SԁrA6OF"0t }& ُ}c_8{gTR:#_S r޿Iҳn,N]9 :&ktC` d'.mwOm1u#4Zh#q ب/΁27TEWlmDqq]o m{v:~ceD@Ɛ#-+6և647zQw򗸾fYڨw %t]ǡP@-<j Jlnu"$~#R+.H3vj{0)@D#OoJ,Hggځr+%(Ak^ eٮڨyN$+[[N}X{ Sh˚Yΰ .v©mm#5>;`VءU{_ \H.) `NQ`an;RRC"YSueấʑ޿vR@K)YTiŪ"(\ C>1TBw2Eqȇ&??K 5fg&__yݟFT̕ WuH&hʯӏ r0VK!9f3_Wڧ&˜D"?+ "1}g/&쒩o",Lw+;˅qjB J *(*C$GUT=t|3U?Jj$7:r|7‰8==W҉WDqLIksXu,:)1.->`ХN__r򰩊<&fxœP(--YFV2[+'J lcYf i-endstream endobj 108 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 3257 >> stream xW{\w N3VEk[TT*UAHx$߿[gC)ZVA5Zv>jco$L||cDB$9҂ykwE$džb99{3ߐJ矝=e~I)a;wGD Y5k_2w|xxxM#<@b="6Rb3XN+*eŸxXM,"5!& F8Nty2aCdDơ,'Fe?E}]Id1UcoeO?tXݴi=n;qpq NaNNN_B#EF2? B L )P?o1}w.L)w)Wxx\^pa.X53B|Ÿ+x<6uz ?"#Bt! D?{zrK"o`%فZK6Bu.c-_>fDҌQ(%HIRDf=E] x3_;:T&vTFUqh9#)ݕ]ܤ<Mo.^36%__Jpbj+#' %L9LcՉ:Di5 ƝE_L0SWg`g+QU >3BQ̇3VԢT{WݯJYuNDLK,T!-!( Q?F~K~6P *c keNDduo-1Ptr`^(ľLj.IIgKf'!MtJAxIEW,uh9"/_;2b 6МL)<]h%_1+(iqfVo-9ι}^nAMdujL팢6t6"Y SГX`\[(X(0 k45VT j37)NE ||9cHDrKHy5s&|Ҷ,l0O~&e yJ.ہT dS! qNHYR}>*n2nJ,SrkӛP-E eAq5XQ B 2 ./e!Vri7!߸E[W͢*ZNU#S8;mBs(:/CY;V{䐻^+KΠ$SN#\ƥuFI*qhR:XN3i6Ja^y` =?~)ϗź9-y͞{:Ie"!݁ WhoIGB \k8Zb)a$p1(_]gmAԢ?drpfUZ;a̗Ý@ a0 k.ќR<yz^T=5Yeo_?_h)m4 ʬYYYu%Z4+WZ|(Q?Ȑӑom+ۯӚQ^ڐX3G-X 0fB{xx9Tեau hQ#`^|&3P('oH U]&& VBMIo3](K8q%lnqxzB,u׍q$~6Hl{&IV{Iϵ8? |tOW3EW=vxk?eK_Ny/~Az揬Ϭ en߀cO>3A\>ZkV6Ϟ֙k Sz<*Civg!jeiPy^-̄ 8V6Lo\{.Yll!됮l~EE|:/ez…i'C"#Q-ݨsmzQ&%3{l#z{|}tpG(/{â {4IJ5bPN~Z7rHAUum4 nf>VgP}^Of+!A3o,CTU&a7ގ]q5Mu`o/TqI ~wm>(Y~j&/,ǯ m#s}2;)܊T]lW6ÃTUpkdD*e٥|UZ䦩ol,ԛi-{:ƸpȎ]JJVEY]$/@>뗏aXmH3H3 Țԡt CI٘gS &Oh+WC5BUnY5XRSVCLM`C j\SV@ Pendstream endobj 109 0 obj << /Filter /FlateDecode /Length 1488 >> stream xWIoF7K5}CAt#ZZ"7T-|y{ϟSiJ_] gO̓ w_%UT*,OX+ Rot O99Η'sL$הXĽYNAu P 5ʠU'$0 b}]@VE`exeʘ/ofAp&cOfL4ѨmճȺO,ńQNF)}/fmtCWxj+|_]k81N(#Zy&BJLBU~ܵPt;pjwpb2e54sQtE"46@h[ ROA u ө@ځ_B@*z83]Mt= U .dN~!0_@ )4 u@Zdt_5t|٪`C1ցLEaTe+Eڴ՘*.0W<0iP<q?D$\J%!P\l5ۑՁˆVYgZz!jw#Q^u# yټ*v̋X])昲q~C6v%{Umi g6-51ѾK'm p&i=_<OC⧲LoOcARV0TCS%\nS" Zp7Й*nS}L)(Y׮\YH'` vݶQd zpF7?,/kƢ3mY-\tBZqζX5j粲άF" ݖcR u0݁5 *ǟ|dby {a*:aT:dy_Bh"X%nuۛUhwk@tTXJ |o̦CQ7Um0bS4mQ|ӦWpfSANMz9}DMRn1Vb~&e||@~ S13E hVJ8y9CxpAwgf@ad4]mc])5lձ {y o08[M<"25JN#9;P؎酥7*]0`fjqe{;hOCfU/ƁTvɼS0F2l.a`mZ1[@mV+\.̥cpBXjN\ Kv 3\RhȖ6&錺(*wBus]s6@q| rYEu9> /W [ 1 3 1 ] /Info 3 0 R /Root 2 0 R /Size 111 /ID [<7f4ae4224a268a8e02fbcef882041169>] >> stream xcb&F~0 $8J8?В5@6( NB RD H; R4darr L y" A+ Ȼ,"UJ12 endstream endobj startxref 79210 %%EOF Rdpack/inst/doc/Inserting_figures_and_evaluated_examples.Rnw0000644000176200001440000001656215134450641024145 0ustar liggesusers% Created 2026-01-22 Thu 16:34 % Intended LaTeX compiler: pdflatex \documentclass[a4paper,twoside,11pt,nojss,article]{jss} \usepackage[T1]{fontenc} \usepackage[left=2cm,right=2cm,bottom=15mm]{geometry} \usepackage{graphicx,color,alltt} \usepackage[authoryear,round,longnamesfirst]{natbib} \usepackage{hyperref} % \usepackage{Sweave} \author{Georgi N. Boshnakov} \Plainauthor{Georgi N. Boshnakov} \Address{ Georgi N. Boshnakov\\ School of Mathematics\\ The University of Manchester\\ Oxford Road, Manchester M13 9PL, UK\\ URL: \url{https://personalpages.manchester.ac.uk/staff/georgi.boshnakov/} } <>= library(Rdpack) pd <- packageDescription("Rdpack") @ \Abstract{ This vignette discusses Rd macros provided by package \pkg{Rdpack} for inserting evaluated examples and programmatically created figures. These macros are convenience wrappers around the native capabilities provided by the Rd parser. The macros work in Rd files and roxygen2 comments. \par This vignette is part of package Rdpack, version~\Sexpr{pd$Version}. } \Keywords{examples, graphics, figures, Rd, R} \Plainkeywords{examples, graphics, figures, Rd, R} \author{Georgi N. Boshnakov} \date{\today} \title{Inserting figures and evaluated examples} \hypersetup{ pdfauthor={Georgi N. Boshnakov}, pdftitle={Inserting figures and evaluated examples}, pdfkeywords={examples, graphics, figures, Rd, R}, pdfsubject={}, pdfcreator={Emacs 30.2 (Org mode 9.7.11)}, pdflang={English}} \begin{document} \maketitle %\SweaveOpts{engine=R,eps=FALSE} %\VignetteIndexEntry{Inserting figures and evaluated examples} %\VignetteDepends{Rdpack} %\VignetteKeywords{examples, graphics, figures, Rd, R} %\VignettePackage{Rdpack} \section{Evaluated examples} \label{sec:orgc1085d5} Sometimes the documentation of an object becomes more clear if accompanied by snippets of R code and their results. The standard Rd macro \texttt{\textbackslash{}Sexpr} caters for a number of possibilities to evaluate R code and insert the results and the code in the documentation. The Rd macro \texttt{\textbackslash{}printExample} provided by package \texttt{"Rdpack"} builds on it to print a snippet of R code and the results of its evaluation. For example, \begin{verbatim} \printExample{2+2; a <- 2*3; a} \end{verbatim} gives \begin{verbatim} 2 + 2 ##: 4 a <- 2 * 3 a ##: 6 \end{verbatim} Note that each command is printed on a separate line even though in this example the source code is on a single line, separated by semicolons\footnote{The argument of \texttt{\textbackslash{}printExample} needed to be on a single line with versions of R before \texttt{R-3.6.0}, since the lines after the first were silently ignored, with no errors and no warnings. This should not be a concern if your package requires \texttt{R >= 3.6.0} anyway or if you can live with somewhat inferior documentation in older versions or \texttt{R}.}. Similarly to \texttt{knitr}, the results are prefixed with comment symbols but the code is not prefixed with anything. The help page of \texttt{?Rdpack::promptUsage} contains a number of examples created with \texttt{\textbackslash{}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}. \section{Section examples with results} \label{sec:org26259f1} The macro \texttt{\textbackslash{}printExample} can be used as many times as needed and is typically placed in section \emph{Details} of an object's documentation. In contrast, the macro \texttt{\textbackslash{}runExamples} can be used as a replacement of the whole \texttt{\textbackslash{}examples} section in the Rd file. The code and its results are printed just as by \texttt{\textbackslash{}printExample}. For example, if the following code is put at the top level in an Rd file (i.e. not in a section): \begin{verbatim} \runExamples{2+2; a <- 2*3; a} \end{verbatim} then it will be evaluated and replaced by a normal section examples: \begin{verbatim} \examples{ 2 + 2 ##: 4 a <- 2 * 3 a ##: 6 } \end{verbatim} 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\footnote{In versions of R before 3.6.0, \texttt{R CMD check} used to give warnings about unknown \texttt{\textbackslash{}Sexpr} section at top level. See also the note about multiline argument for \texttt{\textbackslash{}printExample}.}. A small example package using this feature is at \href{https://github.com/GeoBosh/reprexes/tree/master/runExamplesCheck}{runExamplesCheck}. \section{Creating and including graphs} \label{sec:orgebef252} Figures can be inserted with the help of the standard Rd markup command \texttt{\textbackslash{}figure}. The Rd macro \texttt{\textbackslash{}insertFig} provided by package \pkg{Rdpack} takes a snipped of R code, evaluates it and inserts the plot produced by it (using \texttt{\textbackslash{}figure}). \texttt{\textbackslash{}insertFig} takes three arguments: a filename, the package name and the code to evaluate to produce the figure. For example, \begin{verbatim} \insertFig{cars.png}{mypackage}{x <- cars$speed; y <- cars$dist; plot(x,y)} \end{verbatim} will evaluate the code\footnote{See also the remark about using miltiline code in \texttt{\textbackslash{}printExample}. For figures this is not a problem at all even in older versions of R, since all preparatory code can be put in a separate \texttt{\textbackslash{}Sexpr}, and then \texttt{\textbackslash{}insertFig} can be given only the final command producing the graph.}, save the graph in file \texttt{"man/figures/cars.png"} subdirectory of package \texttt{"mypackage"}, and include the figure using \texttt{\textbackslash{}figure}. Subdirectory \texttt{"figures"} is created if it doesn't exist. Currently the graphs are saved in \texttt{"png"} format only. The sister macro \texttt{\textbackslash{}makeFig} creates the graph in exactly the same way as \texttt{\textbackslash{}insertFig} but does not insert it. This can be done with a separate \texttt{\textbackslash{}figure} command. This can be used if additional options are desired for different output formats, see the description of \texttt{\textbackslash{}figure} in "Writing R extensions". \subsection{A technical note} \label{sec:org8441c26} The above description should just work. This note is for users who wonder about technicalities. The R documentation can be built in many ways and as a result the directory \texttt{"man/figures/"} does not necessarily refer to the developers source package. Indeed, when a package is built, R works on a modified and cleaned-up temporary copy of the source directory, so the figures are created in that copy and then included in the package tarball. Similarly during the package check. On the other hand, \texttt{R CMD Rd2pdf} and some other tools and R functions work directly on the source tree of the package and they will create the figures there. The net effect is that a package tarball always contains freshly generated up-to-date graphs. Developers who never generate the documentation by other means may not even have the directory \texttt{man/figures} in the source tree of their package (but it will be present in the package tarball). \newpage \end{document} Rdpack/inst/doc/Inserting_figures_and_evaluated_examples.pdf0000644000176200001440000012751715141664153024156 0ustar liggesusers%PDF-1.5 % 1 0 obj << /Type /ObjStm /Length 3117 /Filter /FlateDecode /N 50 /First 396 >> stream xZ[s6~_Mg'ĕ dƗqllv@KZj{RHɌ8߹ HyDbABbTL4L$ "$&\E!TAP(` ^$J) ""R&@&cDa(94&JB?&BKx$1tHC93Dhc!ZG10'$ .940 Hh$L3&!#H4$F~X(FaYK1DaXjX7X1 K0U83FqC0KXKWLIPdƄˣIfKHǕҒ|uHqdf%}aJW\x_WP#,y z.YN~ww1XY! H=f LYH O#!%Pb֗W0Rnd4)-yq,ZĒ;Oǟd5)!?ǃUUW,smLj.mE>#b~ӢfE3Eė#3?PT0]i_oW(*7γzbsͳ,&y*`vR9-Y鸒g,RYZC`~uڗO6nD.'zY)քW˧kl/Y-@JV 6'ٲK +PigІ/lQ<016NrjllO`@cyvSWQ|G^ClrcK^_UΔGi^wq(׶67ڢ 4h^!\/8wȀ͇{$03ȣ(00XOwQw<沢s/kAޭoͬAXE+Ѧd mJ=m/y#>*`JnS!64^Y>dͺ65=-4]S8%htEW6O)iAKZski%kBsu"au\ Wקr.,̥]`"tranWiQZ> ۈiͯK6橃_xapv1h\-tSAh׻hah=8Bxa:ӷ"}nDZ^[K-! ]KhwI60ZI= آ~R\u@5 !غ+}ӱu|CzV+RMt0>;đ2o{~Ӛ5$mѰ5ְ*A5'E5aݸ=ӵ?qhqStS¸X;X]1ᶁ { )ȑ3^^1̟{2!'~οv fƐ.!XS {WVyMgyvz2U%S>_uKŪZﱛECu-䇍FN^NCګbLaZ1P`q@T[naSmO訅sSͪ-U*Jk:2 252=C 96xtrT5PW x1p-&ZOLUɢzDT A]k$6d`*[Q|0eGY)Xi0 %E^a vIVwoNF?W2f# U$ph?r]-kmQM?a^;6 €ʹi m2/I1y2G\w4[8*m狮wa[ 4=j.–;o\0X̊t.y!xBTUmkHv5rf y yͻ&6ߨ**(K<V;îFJ[i6L4-+4T:bht݇z$dwO2X <\g)]۳Lb dzokX+c0ىVo y<&+l/{Ǐ8/)G`Q| z=ֵX>5eՈ`[ή;{vwa+ͷA̚ݍ"Sn{=m{><40#/ٍӇvÝݴ@OJtꞾ-d*\JZk?@vߤm o}֙XEWE>GB,r'Hp\?[M^(h;Rƒ(-@ty_3쾪5vn}?>o ż,Wr 3g t>f=E2xBֿ րw楄 p+ G( +)BûG6%5dYyHxD❡s&t:oP[:/n+Nϻ@U?mA$o1ȯ?zloɲz0ΈowκS؁m(ۇud1(۟!dsű棈1Duf㶉Gt:_͞}_zA麶q@<UM xo%=԰endstream endobj 52 0 obj << /Subtype /XML /Type /Metadata /Length 1480 >> stream GPL Ghostscript 10.02.1 examples, graphics, figures, Rd, R 2026-02-07T16:29:31Z 2026-02-07T16:29:31Z Emacs 30.2 (Org mode 9.7.11) Inserting figures and evaluated examplesGeorgi N. Boshnakov endstream endobj 53 0 obj << /Filter /FlateDecode /Length 4009 >> stream xZKs7a*>c[yT\q\NRrs4#ޙC*~$I 4VU)VjuӅvP+J)^]]Rȕ\]//=UYJim7r*Q' K(& b~mR,co!Sl?/2E? _"8B&8ԲFPpm&q;ڑ,ʠ,Zz BG$rwȆYݟ.T c-,]Y[(oJ?]}^v` ^N^wmWɪKlRRJ$Ѓ4,7-u8jL8P],|Pc6ȥ@o6ž.a.]9 mjU Z9O,@V:QR6YM#A8, &-נwh\S*Si]Ž+ÒxޯU?H,{9 ҇RUsng< o2MԻ)H m.SksT mA;H̅GY4VwiE6=" _s־ǵ($UNF<0>dQn iBgMkf.KyӢD 'J60&JiБ!!m-|5e CR{AC-+ im.NXU#ά WxIEǧ 5eP*0[id! < '<3OgNB5E+ ښM<*0 "&%2TAP€)$:%ȧڀ(/B qBX/61PNHh+E؉ǠO bw`Gl4)Cx`DQ0]s/!!5 rX2ңs$ǧ7/x.T , Ҭt0x] U>5% ŌEM!9kodP:(#B%] @*2Uv!~1%!Lƌt Pm[Cf:|C<%T`?  Pŏo?z^qc81c=? !!gvvٚ 7yD/zS,b%a">A^hB|:N>4Ղ,Qڟ"3`@,Uf|̹LyȩJcRjma!3 X(I ] Ce{jWw@hUd5ZY'O=uY(1?v |2P\14fG["N2dI2 =ŞӚdՈJ\ȕMtπM63LvMNW@_ٞu1&a"٦j[%Z2PyDv()N*4/IHcij^XD{h/2Of'Plk">s0žbr0Kg*_iٳ͸XSr&a_,)SA8bCCW&ɛ} 9L0RZg9v͡:3 kpb5~RhHƢuUZ(vX1>²XD ̆:ķ oP|%u\ Te4\6#m0;E+PhRh,Mc7n rċ|0i:zP%Gcqâ>uX&% \IA:x OI^{[0,Ke7b9 H|$y_s%" u|K| ?S__!^Xh:>\"~rQSnHO^'}i%)GE`ͧ$=[JRP>g;yB?*P'2jT᳡9n掙=p<ƫr?͖BXg\cd+I!3O \Lc~h;rG^7UciAv<`J4޻ܿvvzThT3gT`b.(,%g&E`ē2C*Gcp@p ܆Q~^&%o4ͥ@)wͪ{/ qN]Pm2("2SCKU,u4imovuGF,ŻC/jpA 2e^R t;v,19WQPDI A6im3^}LcGCo+"dvW,^=45Ʊxh9F@kA%x;D@ʐΎUqDdJ~ tqB )+^lSku3OȿZCzlX¿P A~ upu\w &Nyϵ:\ AH-6?%*z8r/#7RryAŕbB/bc ngCtZMF>66iM!BϴHo@n&6133qt1v??nn&LC}QwӍ.v}&BLS /e2ɚD.WW`-7m"+CU7pxukovp5qs`r"d!bn;Q=B1ش}]KǠ~+ˣcX'Mp:-?M޿e`ǻ=H)ס5TtZKڼJ e  dl;`0)'ꓦؔ~͙; oH5^l cs14V"UwOհrBO{ _Q]5"̎,M{IɒuWZK Cxf ?s.tKB!E,u y'Ѧs kDfq9!$|{]iC[ #"?;}RK^1.*lV4P@+1O>)Q!GCє/Jc'ndaig\/ mzm+œ˾ȃ%+WR[1Mިj4O'u)Ƞү|*2BB8 EJ87QjzB7PC> stream x[Iu_P-ur{Pi6 ô̬*sff/["YmdoދǟU)]xNE/{MYWX<<0Z8kJgˇ@-.!UYDUrO^xҦO˕R,^CMp*U4L|/"aitY{fdzZ%t8\|fJVٍ:JH[#+eJo-z N۞Z4pY4'P_Ww, SxMV9/V0.qN[UjYH@[|lwUnHbg1DLlаl&ۄ5LLJmʍz59kMJH?>)n¡ܘ4[a>DlO8+S$`$Tit MyOUa)irjbQB|vcVT·OE3o[nھL[xE07(00k/ *7RDzvYk\Y.s5"EyLC-:Y#Ⱦ-ciU 5Jh/-&>TF\غvŦ"a`{|Ț*l]w[P12,&lEWlxwH[i3o jlҡ=v= &` 1ۜ˕ӎo0fevIưl]ӽN莳 fw2B|oD.~&mv@dxvWvPqif/`Yp nfĉIidV;f6}2НE+phN7 jQ8(ɆtaY0UpJ }v&}itjG n.1<_~,ېHL Z dzbDa֯EXv.=R}]Wr[^n\yq&b["6 s%N  2o#k/e˵Q;]x"5 f0 5` 1YtN)L1` dTJE+f ]|mAHzgrֻ&i]gBV>]E#ä NߣQQ$M&GM8a HTog)jzps6 58Ǹ۬oS>Hq߯A0sG&#@Bl G=E PUM9=Ux}FB C@H{8o 0xn/*uLfaMmb3%Aӣ 1B~ʸ)ڿfK + P(ܱ 붧{#4,3 ᭷#Ab)P *+~C@*]5fYmJ5Gx`>p_tl]z D;_I&]-$uo8 WBuY1(ij[,Sg& 17f"H{@_iVb&/&:|@*v2{=#k׍kא3 0?>8^> <)2;ِ:OvJoA,Ny9RLUk\α{OΩu HEo8 4c1-n+34dXaiB̦$)@6d1$e*&w?;sf<C8szh8vz6. %8UPXXǻ~@ӽKvXcowM'B&R₶#6=h=c.3xB){;0#%Q$茠 >P׉R>q?~_7yE`(KuD)\CIԤv ·8S8xOv8;cʮLhIɰ+Vʿ$$8Ař/ 9<^'ֆ.y327jEJ9o9}CM 7}z<[/]Q-Ƃ>5&`-QZ]ҎnߡqI LvCONCe=MSS34/WI[*p?Q*jjf I{ :UMpIQOc~K{w=uA45͆.Նҫ-sgЀs"y9Pg>%+is?fh{JŨq3W0r_*E4sֿaFXh4sG!΂C[ư6\qߴ72ʞo:e$WWཷr-inVH vh&4plvK2a9 QEfƂW| g}LUrpJvLZdeȬ~l"$>wWendstream endobj 55 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 3653 >> stream xW XTe>0sHF@P0ϥL14\fd}Qm晁D!%_j_~o=_򫾍sq]y羟~^ck(aK ⤹A֯܀lx{%}ϝp]pd?ύs~T؅qA˶l2$4l/L~q0hƏ`V0c*f,YÌg\f3b|י"f*Y,cܘ0f3zHƖIc((:m؜WSھl{G5IeR]VOP_b!tٵ=n{/CGpqhu[4;\g@BoI.MdIQCzhp}fz"1䒾 QY \V}':zNbca Dɔۉ]R}x&iMnh&j35d`ʡWECImR p /yK Q_YTZR>C_-[mG3p_ f|yhelv MWť?ZuGn)޴Toa_V^F$f~<2D N oI`^TJ4E)ܵ*ϊ+) 3<[f5G^ Ukdo z&W7Xs>N!ž$HIr0~ wu)q(jt9<98oup{KDe(`L.V 9lCn!+;%=3;lk6x GclcXiȅciǢ@ǽ qkuG $ ;F$,&(;$8=(׳t Ҳ+c| d'ɉ;3/vaFbA?=YQɡ:xXz#DᇃC"?{Tiigr>:(*QrZpeYp(eElN?0,+UE[U%uޏ𠇸{+97-'(2&+U1tU@}E'=^ŔbCRVkӵ r˩t?r?z:QNivZ9!Vi*`ePa({o%⾒eN5%5WV' } q3K^$S67r>9c9~Hn ?Lfߐi-a*(7KY2 ȡk‚;*^pBUVTRL2zq긱8Tey\0XMWpڏX&oPkx~@|m7%Ľ`/{PJi5Tkl}E+5h3@.aou/i'hDgtο^owCkNl6aVԓX}/|'7")d;35V/~i 'Tldc+6أL!ϑ߽gOUDɖ[[͍8Pj]̫v8hdecD%3.S۽Δ1YAW ְdg S x*"T߯!`JѪMGQ k0B'Yy_{Zyբ|*pn鐱Tvpe=jvZ{pϙD] !r¸ZO=5UDY S 6AQvNxsPJ[8ɇ-{܃L:4&sq>PQ)-5w0Sɓp] Rqپ}qR˶sW.CjŁyLۯ:|F1ofuoG 82Q1}_I|-6 XP9 o"pm .%\h~ Zb:])=9Y9)Nߗ^J_>B$oL&{_VF?QZ7(TM WAFe%q(v}A6SR#WPX٢g=m("Kg1#[|4xShμɦ_gKlǬ_Ka/ /, K*n{hU?AɂC 2i#40fnlHhGh)}fm1*߾ ,d]ѱoBS!E7 |Huٍ5Lch?&~[R# >`ÀQ8s+ ܃*OT"YLiB6tUQjp7tlzIȎK۝/}륦} w:W{#BTO\#nlP}t:<ӿP 6F&Xi "11^^Z_e, OӷM;Pq ) a&}bషD+MJԒ*lWE1MƂ _endstream endobj 56 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 940 >> stream x=mL[eB{YgΙKƘmjnc%hUL7[  eO)"A vr& !,Atn&!jfs]}~>?u)2(#J Kw?Vv~mZ b"!Fy5?/đ* l!9$4r.F|*"r"#_qz$Lb K;T Wˠ| u>}ip F>YHX=b{4nPI& &a;x^G 28R+~)f4#TAOdV jU,L_jRy7D:Ã֖,^3!#v9 oiKX^ܬIkx] q``%X{Qpu6{C]v:kZZj*z;Tz``8Qߩ Wlpۿ N=]> stream xYw\Tg־kC:2{Ǩ7&c%+ &203gfEй ]c dD5_֒51璗Cqwc~?}9ye #/Yya[OxoږX;.{cϞ{1֟wg 8/! B .K.\{vq[;ew 1`&gA2f0¬`fV2CU0f53qa0#:f3Ye0yXf3,`"f"!3,f0K4Ƒ3 ta2~Lƞ80ؿ蹾^{qqp|K\e_ʾ:UCTTNvNN~+;RKھ%D\/Je-[2LT;U|>e6>xX3#%fcѤ>v3d1'U(p8Ӕ$LxmF%;Qcq@yݑZC%Xxomd06,~a-/{#5n5vf^hq1W|+.+oYϾBkP}/>‘?ڢƏpD4U{8.++n4b[yO(Ptz_j +?06զRLY.&N"ފj5r}8v^iJY='|p {Ez#&ʟGa3iJ0װͮ \ KP pHٱㅇ+u+uxoNcĖ1K)R2#mAGNd-%idh 倹P1l.h z~WS,#DF

:ó!P,#p}NW8K&{Z(CB޲Gg2Q p8.W Dk+7A/zyM֔l }d=̹.eG(҅0s|TwiA#I_Pn4ɂeQOD@XHTOF,mFݸ7X㫰v6DJЌJpTD23`26tyS O3|K0/X1Y;RpƸ*8V5W0֦)|+K_k8%F꭬p-R@kϪԳ !8tNNv>VcY~濤`th ZJ2q|98uүʶe\s7cq_9jhx53Scv&cў  %r@*31)_z+ߡ=OV죄3~љ;nI]0 .r5 &$c3˂|Om](A,w4 Wm ( SWk_Zo6S/|Kec5Q!.#hL&0rPH=).低HQz4[B0<` x|Gf#>6CW7ؙ + TN!L!'oJ?= ;\fq[,{FS>;|VoR^^ZsqH[|R0o.H!fͫB;h,񄈇E3öjD?LI/35'c j2 q#+g{N,} vV*C.P**f'lw|5;tuDNi(˗"R4&ToIf/[g]OHмMRUYTZyLF?/{Y8*9i舷UiE;=R&fUmC`Z%A $M52 &Hr*z`Y9$m_ʮ$^5 3ߥK=Lt "w3%' kU#u#,0[Uj}x1 C-%Jެ<]H8$F޻nk>"ݥy՛겚Uuڋ]@k5< rء?#l&Vso^s\=L&; RD#d…8;5oN"@:Wv!9baOL̾8r|›l)Pll Ox :?M# (tV!{m9Emp)LMh'N]uC ĶCdtuR2"LVUn~ 5(#6?PxTvL̟bi ;;YҌn'l4Zaq˞j2o\@TjNE?,՗aTMؽˠPwKYtMTL#L{k&oڸ+p F%xo8k3xQ`<YcFNspj=K+o &txL6d5oGR6OoP-*:+0?+v^i3߆#[eaNx'&Z +ݕ巹ԕ '*rژ4AVҮ~R&g>K2=tz^x'ԻgҮk:DqAy_̪Gҋy>b_vO6UT1c& t+Ƕ7 0E&.Zt4'2ױqUbt1cRE$E%Q:e951 -=T֛F3A>6,E*m!_0!tLMG Ńg3v"6N=@^t ř,vG!}7퟉XԮ؛8`ĽW^xN<Ԛo6҉ddxj_XG'ǟn8;nIC!:2Ps { m>%|Q_ߡV@(!^-YhgiZlۘkFīVK?)BKU((/P| ,_*.*p^,;UKK] 9Y0jAapS3m+*&PjOִ3sn3NG]WWUvpϝ?+aYUC!}:6b4e39uڨ۩縷x<9"kRҰd5%ҬnQ|(d ى+(Z{>ח>>-lߔ"i5S1:.E.fW؏qA) @Ev$x*c(N_pm);O4-uhMK7&|?-6dKG=#==7SlMaL kEBui54 vP#kVw$EV^R7u h PޖTD:L437~א[[TXsLSJbNTNkrC? WI.NT҅K=>Tg? xȷJЍ %^>YʙjO7j[ٷx%24҇"- 75?)| w{-D{15i#7&ܮz(,,inӁ@HjE/v³ߡND9mH*5{`^SpºSj(To铸xSnxd^qd) /(.m?p 8{b,̥$1 \XGl k"=|\r9Eo=hVm Xv˰b&$huϏP?~LB;ˋJ^!ĄG_ pm2QG͵)} (k3"gC7!jN>premLhnGiT~QQN姫g%@XfoXJ#QYCo"ZWjHGgq'gK]7j$U$dYಋ ̓c.S^$y+N#BNQ'^J.M+κ:t-S䣉c]I)ךM"YJp~-n=It8˳_#ssodYxǣt^8bOfsk2J#JӃA'}v"p3]ﮟz YMv4ZNb[&5COKd8 Џv,%]|{pݲ7wwQCg-òB,T{䵬Z΅9GW>ޮ 63`!1&r#u F]t&^A6?'uPͪ"tLLL-56Z/׭J n4FP<+RrlGHtr.ܪXb',َvӻ,}Ez7],FRL&Hoendstream endobj 58 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 945 >> stream xM}L[eK˽V)oqll.K11R˭EF[qh0K@;(J+-3N!/?Ęn˜`Fx.$999O~ Qa+*:Kmw,27wMvrV;SA~ڼIžSVcU !ɫݤpJ&tT);VKdLfXY!SD>=U7s-H5qk oWfPE3U*Rn=9<0ҬlZPSf]c"NpBV84Z,j{ú0Ƙ)LUi=:C3w݋p2s9qa}]<"ٳmkEʺ0}#X~ÃiIY@ XUB(?qh4\mknZDgܜ^!Q9 QHc!s+(!ðSοn,4+Uuc[tu ~1p9eڮ6ƪxZhn$ۦՍ&6꽣K:y÷´9 ptU}?3sv}'" MVyDIFJ: kn!95$H ”MU|uC؆z<.o>s?6:JI/NkXb ω! d"t.*M8mo|̴Ƌ)~R9gE?Ss+;;7>VJ-twx3<421NŚendstream endobj 59 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 1764 >> stream x{PSgO ƣe69ZmSێC^^(-vpn!r$N@I"B[wvtp׶iknKt=HݝΞs9{^xveɶ>J\R'K! VWb Ϗ*_ .cX6Kl{ {{{2L, Kf` [<7$̟H/X_v &]i -گc?x]l21彬h%"P2z̈p.EG|%̇>K N D?yl*)n&cxo㝱Lmx,A* ([\`BhVb݈Nbн{IK! "d=(A9؜v9- BvU?y?ȋmS&NgzXW"5gāP eQn\b + ӨJΞi5F0 5c.+y- D|B;2Y F٭f:$іi-3hy~gh+uwQxoаV%&~b0 \V5 -K)u9S*9f`ҫJ\+m!U!ryK|C-@7Ȇ7\}Nt饟 h?**]06užFZh2b#.Ɏ& ¼_B%Hm|:vϊ%C-٩w*P$Mn,˕<ЯA :L/׵{YVp4ig5k̟Hg>}9dXFЭ {\-Pr$5 sa7p_2"`lt\m3r zr*u,z8LiRyB)+'؍&3>:>sr+`zLw$I[ Z=FNN>ޗ+Zjcaz7!lau#hJ=;{eX wzEj2(q ͠Ըi;AA Mf#CWz=nB3"(/zAQ3C}WM Dewذ ZfIfyY>nPa;ΎK 9 6YKfrРj<1ekf59ls#@èzYAw'\p<2P6MɃ(dcewΫ3ѴVGH}xj4p`` ̇28ɒ속l֩m"~> IJ|\S̢S~yܺ5O7Z\}a}[1+\q_Ilw X[TEZ&uIBqocm䚟beDOSB*-u*L[^]'N>B0I}ucRT +7vwzh~d*r8#:TkgP\1"aeҶp]mD pendstream endobj 60 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 4955 >> stream xXX@}3>k5 6DPP KݥC}RE b Œ5IT5E$h0o~d1@H M  4 " !Qp١ $+ dv|(8UuGIYJf3~vO7}^Xwr: ~Ya^-9k~˷/,&:, sΚOzV/;UWhGlia=19IT}OI"L7hࠅ#?Ĥ\\!0_A4r'k:{aN<@G=`8GW>6ǍO+RשLh_cfv' pt;M pcs~Ɩ? gV$hBZR}> B=c]~AUkwo~H]#Q-r=5S)ta-#b1RWDC9;3$369WeI|͆H`އ3UF\++V;K٪<& \nݾ u[=̱Э)R̮׻mՍf[ X deY@̶$Xqy-<ȳdҡ5G_8! #ln}،^~#hwV[v]1F*azB9dF49Bn8axŸLv#472ęf^c.Sxf':~nn֢V&iZĮh\vfA(TS&Ud]ZqּUpn`/%n꽱!1VIt\iTYLz=iM~K+;jxۺ$*HEU!% =/4wenS&} [:0ذĠ>Vl9K{Fو%$*,+5Ȣșdqhv}ц#? BL7I,bgco2^廊8XDyz3ItdLK̈T ֳ NCd6]Ӯ};4u輘<ȇԌ1#,K0F>}}G_uPuA:M6m l*_ێٵ.:wkplF/Fׯ^ҺѶKp֜'EHtBp uS,E2x.+f?AL@ it4!:E ^#" a8&oɭ;cEՆ֔U'g쫈"V q˦]-gyj'Μ;fGq ?QР᫊0hyYJ~׾F`TҰ/m1Ck.Fҧ\J+N YQ|x*a_^k.pbʓRթR^ވ+TeaQj*( ;k2O㗢MxrbWu st{DR0}gBɠ>Iv-s5>>>>555:3WWZt(\`=EOcNGeW2rWޞ&haN=3ԀXMOb`ŅzENM6Z`ΪPτ-2h-;-K,$8ģ"fޘ4dy_viuo)iTi}v/n2%']v!aDb^wi3z-W?ɥG ns=ţ'h:yOuL`ѣ*i^9m* qr =IۇW)qR0 ehH%;w,-"J9qhEAj=)wwdJVK oѸ%~"QjH =;tBIU!A^dI=G4*gֽ_;KemEM3;H-[BEIXaJ4u.&Jdq h9~R3zջ[A|deJ%0N}~" ▥N$2YXU^\̐gHk;qu$Uh5B8oMxt^4=tӛr` IJ2rkGߧ]յ O2Įw0F  )-OKp/es ֜~!ǡhCehCh5{U{Qxzm8TU_ϓpiQvE߃-9SqfU5ߵILsfFy"#',A(\!é\y:#-' *cꅩCr\z!\gqr6p` z˯;Vs5FJeYYEqM^\N\PUӒy{xG d|nP8ˡӵE͵p!v~uF/rv|zjEm~(b1 %B2[J&:#w%f f$ڣ;ىɊ╍H]τR& jy2diJu5ʆFwwpNN uY1`Q([Gu1X#<d VQٵIy^]R M~I!2etH |33cfs^~5Ӝm33@TkJ?A<GKsܴ\Zk (#YIפe HQendstream endobj 61 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 503 >> stream xcd`ab`dd M̳ JM/I, JtòGG@ȘAAAl C UƊk3 ;0tzr`阾A~e=rIa:Y˺v]g*{ZG\Fۖ;QawvЁ/|{%.Gwwfnnlߥ͞u왒';;߂ryl 6\jFyr+[nse'\y cTY$C ↲W3);sR>G}೸Ï<.: (+Xڧ-^jgm=ton7ЁכU\kssJ:+8jtϑvkoA߂.ia!dȭ_h!% u>~g.{9?g}ϟ:yr\,!<{@`„Gxx3endstream endobj 62 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 492 >> stream xLMRoman6-Regularv-  O123Qjcw`$mIK%gd͋ǧj~$`dًËËً‡cOf}I|:}O˪16-X~_ȱЋ=:D\BEKmlGcvjs-AS ڥˋ- 2U9`up拔s8Tl+'ညyp|{R%I[Bp$^sjpmza(S(vCo  To Kendstream endobj 63 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 3922 >> stream xW TS׺>!sT=jZR[*"*N s @œOd C$$D&+ DKV{muZZWv@޻{0m5ʎVFx Kl8 Q/8:# wS18Uv X%~YΙGQkuNRQ˩-Ի j%EGQ_jj WʕQNʅBHlv vwzQUgb(HtC_a♫},szlZƽ8':~)z,`A,ig4jr,42PYKU0KL!Uر2Mʨ~fHoO hH0Ku z G0Q@2x2&%h_segX[D_l؜Gx|swOΡ(؃o 7'u`do4X ,|"*+yk=ݮ,  0}Y?Ô 9DYps:̈4vY_֗@ THhfAJ/ܰb(q7Cgw(T1F ҽPP4 #ԽR(ohS۪zZqp`"! nUU,$A2W.p* ܍ݮTQ@*O+W"/'BZMo dyD&UVD 1~VQ-G-n?BܵPPVXF['z34$0kp>}-ߚ{C|RKasXrxbghVf`|_O16E7GKދZ Vc٫O8vY`9{2%Z|674̀7tPhyd >f^c9ta=m;>_T-m$B;yjM`UWU'9o 4ЬUnq}+k @olQB=hJY+?) b8]ѨZv9 O1߇ƕt^% eZ 6w/we'Y;if78+?5I`1pwn}->Π(2P{v1l; 1+[1c:-Ǡ j H$<,۱Ѣ!87rLEN:WBPSBkdj_T_@)xι!.tVqy%0.&>\SYg퇦Ex<_=GV|'#^q9_P r`^oqux~jT&T\C,WlSEO%]|Q @ ;C*_gJs<ϺpHWj">ú77FGGG777766۬ $ m49yx=ʺR2F 78_w[;|GgN yHϣ fT9\M)MGfFsӻ(?PJ$*["h YeɜEg6BqpJ,9@'AvEZ]QUf=RfBW>G2&Mc_8DҢ$hoU!OyY`&ʬWg] #`dnD^NPIOm-Q]+,4A-b1bq# &˪'DB:0nÓц\'Y!]֪*rHHNM/n8!푰 O >sGZ73LTnV?# Z6ٓ-uIzjT}6l O/aOW6Mś~``X]'.-ҍ/eӮ'k] uڝ+Lֿ-KG|;w ݷn'_9Cnm}˕}[oDbľvۯV򁦣ξ@= a ;~|hjrl\mTW̳I'!C%x܈c0Hx6rl$2lI@ND0'R]j}9kAԝ>X -O&|l v4~.+UTT)Id#=manۙ+ &1I_g=p:v02g ;OOa^ m@y(X#`fʼ`1xk<}bj| CbX 2¢2U>cF9TqBwLm+Iu;W\Bl3!)$AX$8}ߕu,C3~ 32u#f̱/RmUۢsBx2Fɰ׏)eJȞVI 5\W_Gѐ?ߞg2@+"Ȣν1h9zS^\/93W0Q!O!6|@Q x> stream xWy\SW~1)%Q;9*u,jhjAAv$, \}_ ֕0mjXZRk:"$|<e66;8(ey#EB,̎2W&>52~X5kCׅFz:xmWd;RjfSRR)gjZC-Q-eO-6S#5b)ZNSIG¢̨X X=jV GfsZDKE2D+eRGyu\jbc1"٢ױɹ-0'xn9xyM;⹏#(` Ia),\f_=_ݫ*C(1-N\%WUsB B ހ7(7_=6ġz.Siį 20_R'b/_ҍAB < ggUkg/t_`ͫ;7})EabO:fz)Wկ^' _a1b:7^<*k #_|>qAHv-.%H(ňشb 좥'@LG"-qs|??z8~bxstTs^n`qmG69biπ1l6,z `NK?|(6GP2ɏ'$S!kd/b@GfMj  ^`IO,WUz5=lq 6x ͚_7{cja7=W:#?K):x !xE~Qh +玄>>t;b~s="؄ʤ%bEp6TRe?UUqn @Bf!dI;Lv4i#Rl1vHqޥٳ~^*^Cϼn [^rjƕ/m5pɂ-_g}X]F9C3~;[fEӛx'+]_ۉjQ3W%C*H|iNmO! x-Qzx<,%u$+/`«Zt۰`]o״s0B'bʚ0o )Ì($= '}@ SGj-w-b9L*+NE\eJZj6ÿ.1uu7+sl^0nH"t?~-sHa(cFoP\|\`Ȥ҉qf{p"f`qբ_- 3U=x&y+*@nHj@3 /B5׳j~_6 c|7 F ¶mBy$1j Xͳ&O5SO?V,Χ+]<1NYu:uҹKDopԁp'ԍ;Tn VY_vl}a6:.U{Q cy7#G(>#%!M6/LTWӨmDw\uaIzqZvHU|1QZc}N'OvttwfüsW8t#-5і(` ¦A{B-%Xep5eGHK HeS|cBK([[6+j2:9;_,^?\50AעFWM4c*rDrF\^Q}tڧuOrMIezoۜ Ug Dyw'3=3>-;^^-CS+Jj@Ս|"kAX|x[P!V  Hp%N(i njkl^< 5p f!;'Tg d^Ɛw+_ve5h ^roS1=x{V]?cn wPU䂃9lse#ieW(/5+%"1F:RSkwn8dE9?.=#;OAi"BT1m`#j)W4Z?`Ύ1ۮZVkaAQendstream endobj 65 0 obj << /Filter /FlateDecode /Subtype /Type1C /Length 3047 >> stream xW PgflQQi'L/V+D15N@sr0\ ^Q]c\c5jȵf*VNuM/|(DЄUIo14&VL[zIa/ k D#~?3w.LQ-JL^mʸ)j95ZAVQTOQ7TZL->Qq`%X(?J#qsW7.Ie~4E%=3pk :(uk\hr1N%{-$y?[Vgu'70"?GktV݌VD2,@Qv?Z*e~{K` ي':XK saP;5?@(Z 降w_pKJrܼ\{_K>2ROv@һOkf8\Ƥ ~H/@_5KNþ@Wdom0ځECd̙|;o wMCl6o6E B=:@4U.hF;N4lc<P$Ua71B66/,~s\uQc_6ZN4;l#ЪrD8"rWjc'khKdU,:r'"FJy!Ynsģ`FW5RfNy,V,~&$}ZQYUf a_, Z9Kixдis! Uu`hA;:Nu586%K @: u/!-Iu)CT`B) ' ~6hV2f\ks5?<%FUj]>ao BMދO4.C鐠MoaSsKc ,.+p ȝWy%eaz\iHvYj^vn,>$wv[iB6F{%ۥQd,A9]7B.V( , #tD址?~A0iTn_!Dv3;ɭn\"D qFS^P~9[Е["K1ZRVV}p#]L%u[2IK:` Qa;dmoѺѾ썚EjgX z8Yiֵ8vk 6ӌfFɗ=pfDqN{mO3 YmM'ΜfXfd\ oЫ @,VYQh-G $I%q֘#0#* C&jR,{_,+kS^T!Lō%\*lF߲ʆ\nH%]z9/9&]qp)L^穳>k$1~}ntƅzΟGk}HY5DQ:+ScH5婘=2t4,R0s(˹]!'fڨ 1UquƁs֖ Gk܇NCeUfE^&֊ZODaа7{^P l\ ~7_ 9/#ϖD)hOaU4/=2~쩽/LE`wS/kvUvHN'IjU8CI}FOs[,$ζ OBި &̷/^8ltzE)ˁel(9B!G+Sq▘B͌ Igڙ#VqX.}>/!Su^y^CnR+?ob}Qy3F?$=4l?y1]ͮZ2څ%X)cQDoo> stream xSK0GTT㱱sJU6}l(!!M,Шha{Yq To']: YIo#PncEcylMJσB[ƲR 3Ν5ncdiXc.J;"I +Nk+n](ͭ1}WCj9aB dE7Cqd̐zlh&(3݁:rrdߑv8O띟Gk٧ B5Dtczh6♅f-9-*F@>gء^3` UBi3hp'd S/'=nLbt{3D#H/ "0&fm֫eK\> /W [ 1 2 1 ] /Info 3 0 R /Root 2 0 R /Size 68 /ID [<6b6b0d2a64479e444851eb2a02a893fb><7f4ae4224a268a8e02fbcef882041169>] >> stream xcb&F~ cqEؤ.$XXG H @)H0ԭ [![CRANStatusBadge](http://www.r-pkg.org/badges/version/Rdpack)](https://cran.r-project.org/package=Rdpack) [![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/Rdpack)](https://www.r-pkg.org/pkg/Rdpack) [![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/grand-total/Rdpack?color=blue)](https://r-pkg.org/pkg/Rdpack) [![R-CMD-check](https://github.com/GeoBosh/Rdpack/workflows/R-CMD-check/badge.svg)](https://github.com/GeoBosh/Rdpack/actions) [![DOI](https://zenodo.org/badge/100482670.svg)](https://zenodo.org/badge/latestdoi/100482670) 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](#org8a647c9) 2. [Inserting Bibtex references and citations](#org4e77937) 1. [Preparation](#org766760b) 2. [Inserting references](#orgf0b8e07) 3. [Inserting citations](#orgbff7de3) 4. [Changing the style of references](#orge63a829) 5. [Troubleshooting](#org35439dc) 1. [A puzzling message in devtools development mode](#orgc0ddf98) 2. [Typical errors](#orge94900c) 6. [Latex markup in BibTeX entries](#org7490870) 7. [Encoding of file REFERENCES.bib](#org5fd3efd) 3. [Viewing Rd files](#orgb41e139) 4. [Using Rdpack::reprompt()](#orgcdf91db) 1. [What it does](#orge44c86a) 2. [Reprompt and open in an editor](#org975854d) 5. [Inserting evaluated examples](#orgb77362a) 1. [Evaluating the examples in section Examples](#org3bee793) 6. [Inserting figures/graphs/plots](#org9b84bd5) # 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{Rpackage:rbibutils}{Rdpack} #' #' \insertRef{R}{bibtex} The first line above inserts the reference with key `Rpackage:rbibutils` 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 Additional Rd macros are available for citations. They also can be used in both Rd and roxygen2 documentation. `\insertCite{key}{package}` cites `key` and records it for use by `\insertAllCited` and `\insertCited`, see below. `key` can contain more keys separated by commas. `\insertCite{parseRd,Rpackage:rbibutils}{Rdpack}` produces (Murdoch 2010; Boshnakov and Putman 2020) and `\insertCite{Rpackage:rbibutils}{Rdpack}` gives (Boshnakov and Putman 2020). 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,Rpackage:rbibutils;textual}{Rdpack}` produces: Murdoch (2010); Boshnakov and Putman (2020). 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{} Don't align the backslash with the second 'e' of `@references`, since roxygen2 may interpret it as verbatim text, not macro. `\insertCited{}` works like `\insertAllCited` but empties the reference list after finishing its work. This means that the second and subsequent `\insertCited` in the same help page will list only citations done since the preceding `\insertCited`. Prompted by issue 27 on github to allow separate reference lists for each method and the class in R6 documentation. 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 @Rpackage:rbibutils}{Rdpack} \insertCite{@see also @parseRd; @Rpackage:rbibutils}{Rdpack} \insertCite{@see also @parseRd and @Rpackage:rbibutils;textual}{Rdpack} produces: (see also Murdoch 2010 and Boshnakov and Putman 2020) (see also Murdoch 2010; Boshnakov and Putman 2020) see also Murdoch (2010) and Boshnakov and Putman (2020) With the parenthesised citations, if you need markup for the text before or after the citations, say `see also` in italic, put `;nobrackets`1 at the end of the first argument of the Rd macro, take out the part containing markup, and put the parentheses were suitable. For example, (\emph{see also} \insertCite{@@parseRd and @Rpackage:rbibutils;nobrackets}{Rdpack}) (in markdown, use `_see also_` in place of `\emph{see also})`. This gives: (*see also* Murdoch 2010 and Boshnakov and Putman 2020) — `\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 session2. 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.bib3. 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 encoding4. 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 DESCRIPTION5: Encoding: UTF-8 Needless to say, make sure that there are really no characters from encodings like 'latin1'. # Viewing Rd files The function `viewRd()` can be used to view Rd files in the source directory of a package6. A typical user call would look something like: Rdpack::viewRd("./man/filename.Rd") The requested help page is shown in the default format for the current R session (taken from `getOption("help_type")`). To request a specific format set `type` to `"html"` or `"text"`, as in: Rdpack::viewRd("./man/filename.Rd", type = "html") # open in a browser Rdpack::viewRd("./man/filename.Rd", type = "text") # text `viewRd()` renders references and citations correctly, since it processes 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)7. # 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 files8. 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. # Footnotes 1 From `Rdpack (> 2.1.3)` (prompted by Martin R. Smith, issue #23). 2 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. 3 Thanks to Michael Dewey for suggesting the discussion of this. 4 From `Rdpack (>=0.9-1)` The issue of not handling the encoding was raised by Professor Brian Ripley. 5 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. 6 From `Rdpack (>= 0.4-23)`. 7 In recent versions of Rstudio this function is no longer needed, since `?fun` now handles the macros. 8 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. Rdpack/build/0000755000176200001440000000000015141664153012563 5ustar liggesusersRdpack/build/vignette.rds0000644000176200001440000000052415141664153015123 0ustar liggesusersQOO0g ,11ŋGc x1ă76B!ɇx1qJ=eٖږ=B3\v}'QT\$ᚯ4$J?5X̓JBRBiE[C"EApAFyI@<GUBQsہ{NoL)s,>yglqtib/LPaFv9.~ҁR'<:X;~ftXyoH7a3Nɱ&p6æ)+W}1}Y%ZBQaSRc#Oo.vѶ8Q$29|]m'.URdpack/build/partial.rdb0000644000176200001440000022054115141664151014712 0ustar liggesusers x\I&HLU"X "Y {P;ȼn33o7 b8hfz4f4Fe[ɶ_Se[e^wwv]{wdzk{z'3#yAɌF8qod2}2}$۝2y ǽf8/l>zo,r$ifwy_ۿՒWvG3jm={;j/y嶷mUm?c  DSqFܙ,ݟnb _K^OQ:*Qx,ÕkձźW.M,^zmbRq;6_9cl|RۯǔCRs}'miֶþoSn"}om-:eg Og4~ hxX U?K}o){NRT1n*x iy5Q7!~mR$cIN:_bw\>B1 '<EuiڊF!<D?)!K tSismf!gy~5-vslm{3 j'M[(JEh;CgSwN jL 1*"4]O]w¼5BH]fwjJd%cX+})؅ٕiGLY| b@IV'֑n B>jm@ڶEn%~1Ǻߏ;`Y 8;3=wCmhFgj&A<]J"C7Մ F)=:YT\?dv:/PuC[g~VIs `V9<q|0>t myER k"x VhEU}F(YggɶgHCT!ȇr=]BVzU&Zq"?i0òEWSΪ> mm_ߵtda/+lb 68բp+#꒗^)J61 yԘ~+q*oCu̎9^ӞڞL.Z~WiTlY8 %gex4M%P{~{S.?_ʭl5P[/PW¨9].Y*vUޑyEHc̉SL?%/WeҏikoW +Z3}=lVi,]_|WxJa<;I)-]ؽzv֯}y=SΆBku?괥9"J yԐΰ %%۵CEx&eOf H{VCDOBSx{qE- YoiAgҸwT >GApxS}'ym^E;.,Q$K1zdIr;q$Ur%-Lb&1tZYےѽ'z o1'VxEO~= =A5Q#Uup0nx|nu5BvK?g됯g/G^;▕ҩʮЏi_իPCCV*&Cze3J^-{ZƌZ+KX ,Ib$ģblKu OCN.ZdswmJ)%cfkg2 T =:~ -e&}"}}?m~EQW(2i{x Rbכu9͒ vBɯF.}qG;$TFufԚ}i/t~Gnw/,y@ꁶGR(ƾ/m[v>m_*߭2HzBX_ͯw'UwW*N$ ~YĊ|`oYoZjuuKZC'5n[@HE\Z-PCX>Rq_FߢEwՖNrc;~>qYm: \Z7&"U ޿d8W^8~%Ԯ;m5íP2B=,nZ'jk7-Ȥt#\ཅ2-3-Pwhb[ TC?0xy0u7׽j{OOKrȖ{ղRwxQh([=:ʋ7V-7PqKk-wnmBiIn]&jԫp۳PþTRi/c:զg2tk7ME-!~Ø ;l7Pm Iڍ8"F6NvhoVtE6mY\0ʧ|h'se'*p^|C VܹoX;hyJ0mߓÏ ,kUzm6s;wi~emo׷/n4lXU|hL37|h?BoW__RєaܪL|&R{:&K@4+OhMy>mwH=k0*-ӿ3#O|0; 0Vp ܱKcjt,\ _4fN鼖_y}K5Bk|ԈޥHj?qߐ^ZU2ɜz*.ׯb;]Ikca[,wRWm£B$P #Zޱ-\zu5דۥWkD6ucu6u%CV􎅻ӏ b{U\N]o+orzE;B:0^!VT!guC=uz+x1m-POEVnވ%[a#9d VCIUKLmmHvIoY̓s>{N]h:Ú`RųQԫ DL3xc Ví %߳ޣoaroFxm6NUҽZj\iPHٛd}tm$^<q}C %kK޲|;{XIT M\,j)+fK?.  :P?61Zkl?oBM}? `ô}w/j n5nXwv46♄x,љODff}E[3|996G t%ģZ}mt>Z`r -ɏ{Vk/dDA3{'"sAa2vokjo䓐Ov_h*V{dI-qf s^Jy{80}7Ryȫo>3Mkw#BZR}&dNif2ncX+`Ɋ՟l܃>'1EHhIeA1ǬfLLKnu$B[7WsXAl Lcj652ET*[\,8S(l`xFWɏ@Fs/eHxIB۷?g/樋_ mIx8yƘ K8_'&x0J%I6zg>|j6pHs]=IDծR 3kq3\rc =dq#]9}5'kr2:g!O~Ía%;tYnexkBӐPTa lP' .F\uƥS.:?1CqIF`\2 $J.nRq@{Ys9tz;YVg'&7!N}{23p|J:ۿh]փ_\aG4DmKژ`1cKJUϤ 5q: YRTyHM%g`C;p?-FK#,dc(7p>>oK:8;2| k9Y Tu t(F͟J1֕LJog3'!^S:cBNEΏ 8Vkhy zELg k֩),deKǐ-FGIFD&}^/q 2ZҺaV#)MGZ%(-ȷz0MlB3,QNJMox+Xhᅵ=uó?ȋ!9آcY1D8pq%Ɩ*<Y+KR;h`@@< ˔4%cX+L,ZN(4$9")p YHF^vDid{RS < YOs[ۜs 8ܑd- KoCmNۙj&U'8 S5p=7=%΢/]ՒC4::yrnʪʢ+Vk㾬Aڻ5+W~ YZlFF =۶PNcZS}ُ[MЙN R_SC˼ k*nx4ӵ*hAY9;Bץ:)#v/ 㨰tGB<$Ss 9Zm79POnH_=2S~Up *e>^I5Nk,F&\`^QL JmeSkFT*82^AH+BO'RzB1[xK{ :'\߱~SޑG`(rRJ_w^ lN)Ϩ<DQ-+Q$M`"~,*BVZJ#r ujndӔ_/e9-> CߖN\&ޥO4J&\ #R?Inlek.$kzꕯoAeAprR4KI~OA>y=3'(;A;;ϞeȶEѰѯe u:C0$.=`-Wz>/“͏.}௲S]k Fq7[d /;)&ŅcN޵Tcq&z} `y:ZyQqH{yNUyoՖ0yH"6"8k>Qf %-ӡ2=┍g`H8ym9NN3iYמ2ͯ!̌i^ްqg \=K6f[Bÿ (;M0=΍8Jq( (;A;~47)wCG+BBU%8^|}u5Yտ7iswj}Lc 2e-K}۪b*/> ͖;bL"wA4aG+)%o&&(7GB;4Q H=(hJRf_ etʤoo mtuM~fj,Õkձy0x굉KX6cD!ЏҏF8Z?2f ƿ:4I9(Nr |xIg~/m릊ϞΎ"v{FMpeZKb<L,_.N_E's(F&?F^-֑>vU{/_ykBnY4tHВ. PT! hаh.<Y:^l% N14Ta XjCA5I?p=]h*MBIRlC7I!ESN^{Ɏ_|V4mEKvEVPl=t_$HV}mH3Ia<%7oPzHGk5bj?OkPbcVs tPkVkY$6%Щzz8_bH.c V+>cfVH4 TɅҶەil^%; i?5(!wig^w?&?X%%6J-"NwR8|ZW`WjQn$(Y$$G|ߧ4~,*nŲnxCSN@UBW+u1;J9ů_?/זEI+!~' I ymH1\){IH!!eT?8Haſ\*?#|66jACR-пzKdLzAB< qtZFEޡ!npfC/ҡ!mmw5cć.^0AnV:C~^1ZpQ%lhKzE%$ڛ&˟;GYY\~Jey/TKtkTA}oLƕp?R`tzݸRè: ݪF*# ҸW#mL ijo!^lWC*C (KqoPE|5ӪbݮG*x=}.ҷtQ:q.%hG1,~]nA-jOz8,BOHΰ.kNirjķ0poatt鉸c䛺V jjpDk,!Cۨ5*(*0J9چxz\L\.P}Y.楏F?4i/5YFu5Dx ZB<4vQiZr_NWòUC!"]ŲxN\#T|mQo5iX4|re5KA^[B^.ʋV_L|r#xtN-tW#y}5tkSlj0 J̙߂[o+*IiTB=N$hg^ЩJHGP ک-# CMuJ@dA>CsiAߨ]ÐOY-_x%:blP*[Q(b{x}cևl=SO Fe3~E[O)0#r, 8.G+~}y-R9 ӫ+7DeU% g`ĚހxjJh@܎o54T.}h8/ܶ0>nٍnvGӐosf3o|[PE{?WT_C(h͗X EjyC$mYW'R} Nx -㗘>*~[8KJ;9&16L$Hb5's@8y̗\0w.+N9b^œzӽȩHNeRũ֝HQ,]Ɗ+NO^:u.Y/_Y=j\n۹/y$r]?֙R}$EOXI ׇ̤yJ^"Q XgXȆ#Oo78_ld#RN>JfT5a+{97tV[=vNba&ф\#KM, 3~3->u8u~cW,W*3 < \NsIȓn28, |! 8S|͉ٯ״%4(M7ԸT-mȷ{,! 3T%ch B˒`[GJ@Z t.u|9]O<:mrLB<4ow/<|=w©K<ԓa"(o?Z1>;<2ԡ0imKͥK OA6\zQ=18iδdx"8ZOn9ULIΥ=љ5RrՍ"WVZSL}{>B&m!`r^jڔDcLB<Ƌ)yUmko<"Oc3^^F򮰧:g֋Iw$7)5MA+JR]F@ZrE]B1M>ln(OXb.N NBQ %oGJ;,|N646^|}՗%y՗: JeUU&. [3t4Ǎ$n"%Z _nmUeӥz-T_%lJ!լͺeWyKBmM{eIL9(塤6QqÐA@6R]z5{D(.dͫq&C_WN@9}į=Wެ5'ذ[k!*G]NA2t ZtUpx@hg8'֍z^fix*BA[I^50֚gWBZQtDCD:1RqSypҪ#7H gcGF\ 7xdU%G7 ]f^yBMyD\:l:/vHխ iMv2;@chF .1Ejaq &:'g!kyH*s uĭ>54&Dzj$jgI5o#Dzoݺ3ޖ[ 佒;VpI( G1t޲b~\,ž_>%BAlSBp=ƔǀZ{j;4| U8`=}SU8pv4e冋 pN~gߩ< ca59IkeڟWxFT',b3eɪ> y5A005q~@' WyGޅl7;%37*>9 Ǣߨ]q_JeWK^]OQSk\rO )}ަ`\( _|LWL7 sϡC7|>9w@Wq#C/36, C)Tuhށ|ǘ&*"15*JQ8rY tBMDd US;*C]Vn%j1|b w|_dnA'K]N.+~3i[R߀fڻxEkaV8gN$viNH'@4'T.B:}ߜK|hj!Gu_`/_^_m#BYP/D!|'5D h?Qq@{!8Y-0U%Nǀc[r~ !k}AVW|@;d?%x)Fգ4-0Y&ۼ^/#6!k-KݾPZݏ:)<ds Cy1KIǐnﳽ/+| r': kQ=6ÒP LqEhae&ETO%CC,9בM"wYYc8GTjK!kEhQJ[4Q$Lh'XSqG0_RɟU ![T@T %ȗ;Sj>4a0[jXuKtXl4\om2^;EWsobv]kv#n5Tܝt'vQ%_aB{Y*&3/YDj)+뾸U)&o#&BȫyVգ@ҳTz^aa9Ez>4غ"kOՓiDĉ󐵂T1(d2m-Vv5]擦SU(UB6_fc ZSIn8PP^>wY<q-tk7fWbux]y ]4Jv`WXkB8p& I#/L%4\?ƷxQ׮")7Y@#:k„}o)sy 13t5|7+Xx5ExG(վe_-@<4a ėeZNr7s Zr_*jpnj9|=bzF4TK&A{ (-Kh&֜H=XꮅfӰGODJNoR زѩ̑n8ROeb)s:ۦG4.Jǰ 5_^7¾:3zqSkz-zei4\uW 74_f x.@-iJ;MO,Y6.i j ߳Mç&3؃lRU 1qO?Z,hSRy&J.(:b&߇6?c3kKm,IzdeSJ8yC5-ɉ$$ BɤŲK{z 5}s޺Dd'f GVd? vc6t܊{|+D2d`j27 rSqSi]_# 7w 15*A9 L;)襄V.;'Tq+"r_>k eA%V al/E& yvdR6/r+)o@.~i]1lzG]˼K/njR!8Pm!AJWA6H|Tu tƯ3k"?%FKCaN #ubxj$eIOB>i':msJBr'F)ҟPAZ#߳_M^;ߏ"dWR< ǐ(}9ry/\J)_BP1G ]hv+D'6!t J; %K;jƤ5PQ]>lq0(BֽN<P!Hn wK VǁYMW'*,ʹr,F<G!r2Eho˒n7g27.LŪqB6#y/Beij 2i1XhgWۨ{( *v|a3`.Dcv6|WҊrW2ÐM{=>Z1h kOQwl*n?pqkpUU">p1-g6`t{kǔ<q\jw9&ߐo@݃桕%'CV?u"әQNؽZ#vnmhgV kYVKݹUPO?o>n KpP 1.[/ɵOUAp򐵉h›DEDAf?"qY<ԯ>se5dN2QRD2 |JjK")B#MN2zWհZExikvax-~U]ބu$oԛ[M8Q7mut+SOBOBsOs T;<)D;zKOӪDr6Mš[<0sNqYl$wFl-GKkP2›F3B 2? I<:y?^+l'nNK#)$}̣43{Ng%cHW r…\?$d1L(gpֆ]0x*&FCcmPO C6OOnXh܊υ#<)偟އl~<,fDq~P{˂AC: \ҶղqAmI8*cq%wzEL Dz[E*ZB l30~u @6T0+|\#t+h^|8lyh m瑯?ix+)C OB[ɟ^\79*Bj<1=Fy/@@}[_D j/lB%F3tL]%(8ZZG!5nJ mb^OOo@2xڷ(t q'E2tO mnQq-f{DCqǠzAh 2C%T\?0d-uH$zXc d]UUW{?:76Ev7B ^ k9kt,uBkua߀,:g_qBsWo^ O ҶZb݋i]%D..[$d7e w8܇OZ"? J$8qsZqh&r#q2l&zܗHD*O4[3yKO6hYQ*oIL( ktN$V}}uyU\.kӼ߅^D+H$$_C۠`dlff,we=*;~Ru/DL,:!Prz9ۋT}9NC CKѯnVCj=n +523_?jT?߭!w=zF oY=Sqlo3U9A"ץ*'<Y_}?Ky% J3០\|A6ߛ/!LA%FC".%QAͶyc}Q9 mog(MAZm(?c4^5ĉBU%nb+CU>}FD, p>_Z\4Fƽa'w7֎K! '!nIN n'-9v/@@ {´FAB<%؜|d Vn[nyyYm \S2t8YkSm󋊻 ">uނ|XuXFfK4njj1)dʮIz(.^VV0B B6_J^_sW\q(MIR{@^ݨWG+BHA0~EL>O{^UwAw[2&Q뷿D_eb;A<5h|yP3 3{BM ٮvOp<:_pIܝMA迶JN%poţ3,yK/W(15OmU*OB;Ue6c{dC/ @rT3~ A&LWC1K-xܬO!O "ψC$-\6K;<8F>,t˪okiuqKGC0u &Wz-%2 򚠸T0;Fa};IJ貪K'Nwj _ aE02qA_P@ېo`lwe ..T\?ތ^|NYFe7|bO?i /tu/Bwe7>hdҒ[Ě>ej&n9ų(#%蕽HLHDbx ]-1gmdeK}*}"< Y/, N9`J)S#+GCsI?6CVtY#sR?8 4>S=/P*x {t Mс܉9$_8p_:ŭxf0z`i)v;nE;n O(Wqγ*bmuZA;EcT84`Xj57=X \.QgA/`ppT߂=>GA1CtFtmCvȚ^Ʃre^e!l~ķVW݀懡H)i249gLلSX&4,z]x|2!k3.v( 1Sls T w+hA޲-AIk[!%f-L<+ eRF akIJ|'eGڋgYX֌q,O>N wŲ^JΥvv܂>WRKH|K* ƻ4xSLhXKWl75K^5œI |:q \eBCj]#q< wI ~µʢ7H Bii_5LEOK[WL}Q6e.V'bYMT˱`Nt0Ij\\c9Ȓ_."` Lik ԌpjAh  t.i[}~R7ԫϒw)tKG2j\}|7YG%۸FEuFuV.ƺ[y*}[b$n3M Τ`:/~Qu$җʻgW}v ԗ~7 ug|:&DzMrska'sOBŵtရᴓ|#Vr-b-B31wq3R> 9I Xi(p$p)N3C`زgRkbX\^ii9lsl5 ^J#ED2O0Qncj LEQyK60/,_&gLr˙Ek|{%j2Wb>-ޱŲ8Vq 8TǤ(ef? L,yɤlՃrJ[PYs;Kyʿ|b'D-M{E6`\FUdS;{jow4%JF'jj;T>X&4l+R#1fU%rbl%t΂y7bА<\ZWwphoOP2qԘv, 0!rucB~T]XJYOBAdbkBk,|]Se)S<RȟJHG9q;@a2+: -: ےtMS0h,빥ix, >Qǁ'bYF[n 7ϧGr.qbߒȯ2Em r^-[TP9Nt3Ch><ٌ'g'1}*ѳ7BPxE26ce\ Z3QTF/lLO va*7TK ,g3PP`mQӺћQ.dߣkeJOq516 /LJ$R|1$jrJ{&ɤuʼ ˄wH,iiD[3rVA6p!-\ \Di_B7*P\ҚD^^v8i1I{_ wJ@^_[ ǡo vN$͊O!s%%(іL/m QNyUTVX $zy2Ƈ:X\wtgwc7S|JGcY/6 wXe O;pEVo 9|SUm I,[~^}^Wt-B\$AzW(fPq@m==1shk+R!`>5#q˟*O B]tw3aܢiŒ3)Ыt|;_ʧ>y魮vrGMLC_grrq5UC_h'Yew)~s"; bÇZ#%n_~eSjb<\Bq4zLE $N|ḽ_>H/"bU"Z=[PP˄?~-S_ob Ҏl FȬR_{h54iRCD(G'ú0%)ۣFG,#:k5H4MLn7hȏR\A|@O(˂I5O^w5`CGY N}aIJ =l5h}A[%F!6CSLhvH灅X[7iX,k(ʟZBƁbYӷ^\[v/.-$B{qQygqPJhŲG}/* 0zڢŐGq'?ul ,p6-E\Ιz:-`pZ&u;nO9 )#"w8Gl), ƲA!{Se6h0%ǣj&3l!h%pIݪSq-,oZIU_f:V2ӉAwNP%Ofk+io=DK~8 ?F|UtP.~UY~\>sauK7Z/J^`4=^F}  ?E%ji$~V=5$AK;ck44y:/?:gQwc;={Ӝq(KW%jMӮ2 $7$-kca}n15nCy2-l7Hf E6?nەm`ZCGc٪{Pqclt^RGeL[Ʋ޲GN&-X3ꁁ@WbАȞ'pH {c7Q69<VEm*nx2-\d&vDtՋ7{iIV,[ޭ_fךvG|GsEze׶A\Fl'EB,[pw5e 28 92\rXԾ!4 eHeeKͥy˥1Hv ܗrY)G_Ʋcr(0Jah[B ǿ3P3oPqCl,[غ0QYXN?U^j ZZ񋘅G i%ph;*sW}!8itӛT0Ųa([K%SQX}m5Ug.7(y5"DBKjO|cYoSS$*nH,[1Ix& qZMo f5@J~Kj6= eBC[sATPkJO!CQTNX`}8LhG{NHzDZ |Or%%35JcK0r% a1jzJ| M$6KHdz{/jH~5vOc-J0y is'"U*D!4s80y۝K} Ĵp:+ާVkcRZhʼnr` cR,~#;boЛ/󥥴'm،Ʋ^*Q/e{x--dS/D6OAKNV^i8٠Q&A5cH=&|Ny .EZϗqqWUx =<n^*t՞N9bK|9!Ie_qEnaU"lc[\Rڔɂn l"_[:^PW@QסpEFKۧAzȦD%ZCñlu$%Z.7<z%j<_AVB&ڀѝOJm9k7p:-$fF+~)3b4)b+EQi-"Ԇk|=x-V^c!{VWln$/ܲ7RjB8w12ڔu>7^J6Ey4=w7n->KO!p,nK Dzհ)C.<.fuKZɳ8E: .^){+AЫ挩_cJ8b+;2'i4(f3?M۩ջhj]芄m(to+FW4?PEgfk4X&|ibtx5n;mkqՕ"X&4TAq~k0qe -&r-qXܩ'O*/ܪGJN2 PaNoŲ/Gel4=ˊAyy1jPecO Or7~X-[evD?֡mLLObق]6Cˋ e6i.pQe_q GSB(uXyxŕu*EEOɏs^(. onv[ `e 3/B7zr ;hlz6Re 4G0И{H]l`!uv#F&SK$oŲY" jlKTiSV T ˄4( ˚-Ab¦pA78QVO[ma _JK3+uBhBt6۟Y$&.Fٴ;c\_rraKŤdh}D=jiKR X̧!{T`Q<_/M/Yݹ{"I&r?(zwcQ\W~HU|>EQjL۝vZ$&UU`Dh/׵Nb7+N"_w8BVz˱&&AզZ7RP5& 9cj M鄙؍u.*Ʋ*ǘ[ªe͜2~ZrU/1 JR.ܥ)]Dt^|Di4hrBR#Q}]KCݕf֣Sujh'm1N27Zu] ({Vftj"߱m nҵUmOܝ~TJaVMRZDm ܵvRieRJ_(p ?=''ciߧBڸN vJ_w̷IjѮp~ Aې'tj`wygk^Sɳx@ij󿬆_喡Gx>YO h y{qNjNfswjCdʟox;p;rֲKK *HݚHOk0xiVb_Žnv8 "!8~Q"ZSTP9D/{EAsX)ںףT-ci}[rav!6LG:6;~=YDˠR/;}&E'&ޱADL JUn K,;.g[{"Q!}@Hš[\L2iE׸lx Ce[;TC)HܸJn8;aæ_-)}cs%v]|G CoM)_*%Y4yUVZY'~zem]l7h5N涅R7sKNůI{{D#}βk#֯Q}˽R?Oߩ^_Z?NYP]_#xȾcGdr_L_ʧ9`>{w)?g֝u5(Ϫ8#X." Y܈!_s٣O?ܓ3ՓwrnOS~oy )B*\41y,U߮fɸocLc&tRL|k<}Y %b-H]]V6XI(R@Bs2~ |^h2k]ͣm!&(TT N1<' γaYbgHT ߼&_hM3 T$ڷM%Sݖ˲z5 nm=$iB{F9S`Nx̯3?&bk?cg)4р01ah-[V24u4h}asulcHL?@ju5, X7my/5hN+[ Nx//8Uw'SN=lFYm }VĎX((W;WPӝQ&uk^bSETNk17bixp8RT󹻶%n f]L3:*Ih?~4]N6v!^o[cQ667^͋H`׮^TİҘggonfyxekYzf΃㪤3ݶucgOgGqB?ܾT~ɣ؞Ie f⭧LftnoDl/CVlŮykՕuk~|"+oLBR7yv51iޟp$-! &]*c-8e0oˑvP{$cA(]UK_ !V܆[G^|bc)n XTx,5BES `v/ܰx5qI)} p Xیf.U2mcX-;i c*dZ ܙi v]EFO©[=n-c)ROAzc@i6-U2Sɏ:ҳt2c_IFg.ŝHRm n\Um|. {({N߾FW/^;'d^y[Ii~|=Q[%cw.8rbue;2+ ɻ3M|H>jJgDm2Ä~9XYaeT\:,SrLw^*hT3Ư%D9k\/(QzV^:o37 |vnٍۆ7E XQoEr9z5^kaX2뫟}!A;&ag^A.&V?nXtҧi*D+u p6fX%!Mhmn܈jo#&]m[6*pThҌZRO?\V8*CUuA6 g",ηSU/tc T_0pƦsq "h\7^Aw!Bf{tȶ#H!9YX&v,r*ﰕwyT4o=z)KZOb4lnl^MnlsjnZvSHvʰ6r*ZF2> ͌oK'L|H`[SMu9h*'Ϗ >[wQ.{^le{DK;,6;)t9%b,nhPnwIr 81uƣ`9/E5JcξƄ _ۼ0Nj!|_.Iɝn{j;X*qP#d1M Օ[^/MNΗgnF|!x˷q}qtQ/5aX]op\}Ǫ/9+u+e F켞2&9td]mE!M4 ʈzKa2g_Jm^&Ϝ \u)N:'KoK/!Hv^+rԉ]aö4IEb{)j{Nf>uIM~N٫"R[v3ҥwUs=W2_ _J@8yOke"S(ޚȬ3D ++nUiޠ>o.i<_7gqt1Scgn㯣!?sd %t>ls"kY\/<iB{_=!XI -)׹W 6|X}Sj1.UKsNkо#F O'!ͭuЩ"+Zlo'w@WȢ,T~ 8z>yWa> Tvgub(Ɠ]QT1 iZD`ht]ƏuD0S;2)`C+ ~RJj= MFi?p:,AK+_£AzO> vV u,BIU햡IR %ŦUEM#;YNw ci8aj/,ih㐏w_z@TI zݵ]ڔ"aR!ĜZ-kG(B9z9j~WC\KMBꎇjy*\E Xi1kIПەiM`^%d`vcvw6^-Sȟk'kv{TK'$WQ0Y7ŋLNQDKu/:m7>/vY-ZKHiQcT5{g^)ZaSڄ:A#<@d4Eul He5u<*-@jyMR#U! YYmɤ= qMk}[O&Afz:w$4vهI->laphdRրx4ݦ5JNkM\k NEzrj7b{ d1dU5AJs7epDw2m3Q WSz`OGoFTJs='$9[F6UB<]o(imbKC@>q eQ*K┱BWWu l k/j|(<<}u/I,Ǧ} մC6nIu"QYmRbu}qƍ'?1o;}״[+o{ſ?'] V_x_%X6<ԫϒRlܫ^S=Jm=owו[F#/O̼#zQ n92udk LcIJ.94369NG};_Sk %ӛL|ek._1Z__s;;CA4nP{Zft"*JGZj*ػX*LM XW o^ lx!<4 Yggl)+_4T[bU膡YX+5֮ԿNN-@)V<`-poUENbB'Cg8v"dbu$NmvFTGH(W@hvS_٧1u A4xzT*(EMܭAل}iٝ4<٦o`RqC:H:=G7ړhdZn1 tyg3Hm‰NKo7'B f3:Y߸pRN!1<%Ryu׻X'-k2$Kz&.7 GUgFJCOW.?2vˮ0>^D-J!6~!FG5NsGOΞ4y8$! ̺c$CY kRTȔA$=1>A:ɷa]jm,փg%Fzhh#aDZ X Q-!<Yo\t05T'uD!n~U:d{ٳ:E8I<-J L Ӑ탥j~SJ-?+R2[y_+sl|Opr2^/ΗrEGu_@e@PZJ=03Z"7ۂj$#K{Kr!K~W_h.ԣ<.ХN17rκ,^`U6|zTo66 G#jV{qx\KZ/gxm58.CoQH2kZ2REZTsIڌ.]Y~LUf[U}Y+| :k#.(y/R)n(3l M[CyΜ.U7VRE?q-WO1APr,3t*)4_C ʣL"H-"vF:#Q' URC)!Cv;){TT7'!CG/IGF>HODAgMw$R07 _B<4;g C(%v%Q$ģ%%b+3[xLFc|o;. mt~Õkձymbk㗊ݱ8XũXs^@*&[ۨW^N62 ࢷeqƤ N2,$uﶭq?{:;8~5Ɯj/Y;x߹3Y?ݦ;I>~2bcRk*mϮymUua; WR:y:Pԥ=$a@~_ h d*X{ Ns:Y}ֺvP%lKӣIQ6Mܣaz(f>`~,k^-16Q7!~mR$cIߧrj0j;bdhDy+t09oQ#/*w;tŨx,؅j4}O- !_dJnX Y)oJn8*C h66͢wlY-Cs[NUbAҮLQ;&bێ/J3X(ȫz<;vVA]wY_k;g~vͳφAg8|.ܯխqAY%cH#nT5LfEQ 528ӷ`DJݮG*x4Gtox kE:nLubj_=3nh:{td@z7l+ WR/JW;ݍ0ں=yf݈Bpٷŗr/_^a)55+L?BG‹z7DZ 7etu$U%<[-Dza-ȷ6_҄!zSzKf7f rPMP--;jA o@=u&Wm*~JB<]WP罛;Օ$k?MVޒX_a^1b57(cM!] ݲr}h]Bh?ɪ.Mw,)W٨w!(lQ{ԏbg }r}*x} >]Ē))a[n4HvG{EG36;=_ԑH A>#9oTmNķlna-z|_V܏fGKőK3KY=${I4ЫuJt6:EIjϗ_-=7 gchc~+5< PW$<;n!ϝg ^5t._͋hW4qa1vXiѕ#K =h$>iPwD\鄸 NզPQBȰI>`N'z&ݵF\ ˒l%:tCxuc99Zˬ%f2FT5ѭITViﳒ//d|-^6•¸Fyx F;M"ӉhG`RƢyl-G @ū+N0Dk(جr/6-m"u!*>E4% E-ԎdiCZm^|ո 05s[Ÿu-#glgF(t{)E j7,&4V -/mŸ]JRY3Ԏ}N-Z. bv^$RӐOo{I 39LJ["&~Ba(l!1<Y˟¬WKnJ'.uSSۀ+#6A@Zi7"Y\99kMڌz'pQQ(ř5Gf:>,OT!Ygm dT9yZ76c RIu7m.d 3-kn>kl B^MLng!3uJ]Jq'^-'jv|-EG݊AلFVtRwND%끊*׃Q jU%g6_U)^Hp(cp/BmjAL%V ۥbqBN@U>lk}'cw9e2șۥ{ƔG|jەi&Nߕ\yJB̯SBeOI9$Yq6>3 SG]0yQdpٰ}v'j&"73gT#*X%v4%+d&ҔFc(F0|stKnkV|t[UÈdMٲ㟪L/@(0|AW m)a 2-F<>Q&-@M+T>Zς&:|ZC(ja5zWZ9-Kh)Be[[CP937&Kl~*sYsyIi(0rD#9^U=C0>ln ng6" ?M+ F#*F |vCۍ?]`4K=GovyV gUag~M>l~~ FPxJT#N %v9ݾR}˱zgXe oT`|7,seK J'ݲdsq=ϲSm/a}Q!.dk;9sq^͇h!B)kWFnE2C5QqfLK~Ge+O|˜n#;+mΖH!:eaβr_meLfl,_ϷTqek,+"e?v(OT~HTu* A8yΘ)<\k6L %.&J@] od[O) CƵ^KBYՏ ӥqawbMSP0>mϿMw<%6@)fTnQZfS5X2)oDx~59(1;L,-Ę[X.v{YVP&JQW6[u/*/tI,R|h1cKFpXRSnQi ZJ|uگ9iY+9+ɖnʶ͸|-[h;kIBTeWA8yZ2K RY!Yn\X*W(bxx _;)--xL"ovwQEn!U}CLX/V墽{)hj :'!q_$<|M4G]NF1 D FBN E}C${7nʓ&LDjx(ӵ{T\?޽SR|xe'T1#nGB6_ ; ڨRdT)o#VU!+yW^4jI:<*+n+̠A6_$HdZ?o]+xr6Ϩ7oaK6+.dQn(Gk^$N;A|'gK LE'mt,u.t(0J3-٬> hv>S:_ l8F:a(1 0 nyW%U41kJ \4L}e}[j gJa&'usZQ\?'Z'L|9 +o)w}Q(\fGFX_GY]-gqgN)oF^TgOfNߝR}=ۿ1(2,_*S1U[򉗏 (o< Ko6fSۥ2[#b@pM".bs=y }%3oTI:HRZhvɔ鎾'X Ql lw`c T EfE9qǭ5WAJ[Rxn+.RB<4vg U?r_Kz䯡.nkЅ8|?DxJ =jG&+&AjHh''PyfKmP%OP fqu*0+)*!-> Yѕy"wƉYud'w٫o_*^3jrR%5`sVvlyR ZkLf_Guy^U [B;'?{@GO\M󪢻6qW}%_5:7PqunW"UB<=~@é*TGŷz*Mtyʟ j=E%S,eG~#| ,p>CQq i UJT)kTԗDxSTB ڙ=KSN3曷hKt$^L_;] 3'|_6(yÁN#*[Y}zun+"#.5ma|2畻@FNjtE$> #_\Ki Y1SO^(;A;8ƹw=++7*bKC7R]Hu˺/f-Bm\gԃZƫ~ S׺P0( l  zNЎ U'!](Ջ|~]\܈p̕SRR k͆OsTwju:_ ]u9|ږW7Dh;_콯VRAC3ԙ: Dxh^^w?|{r=?)^'!E )xnoc"dVWjsy~b}@o=n&Mb'z+O@O|iDPV,{|r+wqR#wiqG.t]vawD Ex yĖcW< UJPo@ [Wds;~=:MU%LR[FF3i x!BpΦk Hhpds['к-+"nK}Ж)"nK}ܖz N6 l=[j{COY ckLwz>HMXHE csFT>g$ģAҶ"f .;k~PJ)y pp/!KͲˁSp{HϠ5@獹Q Z dw-C^t]Wf3J7H5ѽ~5'\﷿ͭRWfUkWM_*_vbKxTZBR?E R:n[~FC¤cKF!K#JRߋnۺ볧|ۈn_כfiVb&~wdON_27QIQv6:I6fWκ8lW]Ni44i*馸aDqWqqOebkQFɕxwzU셫%񣐏SeJs!GCHڼyQݒV0]h42 )'a~2A xkOB{ڱaM98v 4앻JnX qKi-cJRָ{ C $h4i1CB;EV^䂒/Q2]ni9*nɴ)4Za#F ף=RP{Ҟ/y*ڢ("^K bG:p׭zK4Ftvn uCtP?5%]wHhCGF 32-x[I)xw$*xyAmmyKdыH,[\qA6ϖnWa%tca[z+&(2|_HͶVlT;OU8yx!7))IvF%R^C !1$Ԇj1(t{>`ۥd÷߹t~rx5h1q `P YætNgƞ4В_X]$Nt"W"K(:Qmȷ7".!O{F;7fJSQVy.:!ԭ! р(YH4cȱ./:ρiȧ57ˉ?^~09o`1UU"Ff.!aȓ[X k@cQU3 *8 |}_`O9r$r|w"!{?Ua:0'!]{V_x_%cZ <ԫw~^z$~)Ff7KGW(rKّT[Ri+*p4QkJ_`Aɗdaٍ=K7 +Sʵ%6}c]= Bg؟.{hF^}v7zJoC7^h#)nIť/YqCf)~ ّ,߻io/}-:\~7< K.[yQ|P?KKopޠEzKY9wW[ oG cBb&6J ;Q3ɍ2%$&;mH$m-;%%/4:nv165 'W]g.&vz\坺P _IHy64j<8i(j FEzKc EؤxgCNAڎqaj *xMj A3=i߈P3 $ǰV?"%FŊ_ J-07BWbϰ鐮:Qslbs6?:QtͱĢǼ-r]^d+uD_+-y˼zj_"WD(BNcIn_i#Ţod\g)tQj)UˡC2u׍0R tsë.,hkkȞ (m(d6ɠ5LJ} )eC6?SF*pyzx8k4U}N>:S]c+R <&IS{Sqy-4oɩR&-REI#x5`jaƽd/@x)?#!nӘB $# oᥭ[د6<&ճgYSU>9JN6bkH)owFJY h~n.N}pE'4v!$J*;(;A;]lɍ+Qn*i)nuaHz›򊯛nymR4vIhLA /-B#٥)1?Ms=VCdZqj磐5O ]f)X٭.G+42OCHM'ҧ{u-hv dLrK;O `K(2ʙ+S ?$-!6 ?WB{z!{R5LC9nPǘ[w '@p;&[|iN7T]{VdYY{<1ӞCB e'h=)X%^Nng)6|ژgq[}!C8b\.tpe[͒Ӹ1^ Qb- ?w/ժzYa 0/Ѩݩf)@О?|M[a=cPvvƘ}iHY^?r}~TT~&(+ƋW)ȧI>y5'g%- ;`E!n?\iLLξ~(gYg8ub6NNZtť-jSN*5QvvZ8 7pfCWCCB{Э0qYNZ{J#"s[om[${3BNooyͶh lޢuoa=Y芹U$e}7"9;e a/D ѳ]*ej29?jA;cL:|Ne(Q}6רƭlTW NPbH<Nů{r6R~ܿʐVTm tOӪ'γFxs8@\)]+7AШP 7YK+~i&a$(ډf"h$w=}|d@3F#D46`kԂTx iܧtXʼn% kn[Z#_hZs LrJvBxW!@tJ2e:%dE§)hx ~/L\ΘlϴP$w~/eq>G5u/n-[SZa5?h N?ۄ1Am ̧=i8S:EoQjO,/Bj<%Au_ t]CƻurA?2Tn7qHB-4{yaEv[g>lFu7 ثSЗv3 ){ ߀>Ψ{SzAmhLPG=4&jK80G htL`x]+cQ)Y(%u'RCBw!:ğ\+~R䓸ϗZ"B#YȳHUx\Qy$-=ŁHy u3F 錻Nb+ur46rLDeXұsԾHlnDE\T vUIz=Uu:U"1绌k>ɑB"'lfT&"GzR`=* FZxGNn-rׯTN[(wU_^CGi嵼WhEd6Eҕ'YJfB~'?^agavTi!WEak 9|N?,diR#)N!P (3i =+~-dzőI4QܼD9:=|1&R1[1 Vn!] 7%B!* H!~fm->,3ӱrE'ث%eڸAS,s܎K9q$):,ҍ^RD|2(^A!wǝG jn0ud $ģMЩ 8&zpqD'm⋽T"IHxm㷸dSu/r(Һ84$f KM?x}t:Ð)r"#!l[ 7C6 @N ̯Y=/i}}os3w9W}B{f.V.Օ7 AhcpB\.㫴;li00 9k+Ŕbwq3eߩsDZ=+ڤZޡ˪Dg!>̈Xu'tW"~VWjJHܔSAƬv{ǐ6/+Дq(En)o-^SMdӌ4DMo\V/iȧ{1Op^[ɩ(V?}Y V]SA)FSM+y_rgܗ^l!WKavdD^ˍ܈?loF܁Ϟ?;86˃W }cw7OQF:*$39ia͆u,uk{TG9^ȟ`?:ܓ) n79_H O۵)Dd VUB$4[iS`߆ Ao)H+R\*x i8DZWi~*03RЅ8|?TDD{S&9MqO2#15nϳ4[j*ڳo*[(z\G-ڳRKhǣwVݝDMsDʨ|_B<39rt+A;z:| Ҳ2Zrn۶7j+9v,'{;CIGkHa&Jx!kQhQG$ލ&fIFG-? l)]f'~, yo钊q{Cm?51i_DKG>@WwdXBytɶ1ԎX;敕c+b+02[QI٭$jA=;Ðj',|XRJN<4%=Ű]ދw9mGCAJHAo4 $ma51itR눑XA{\[vda5IxmPZ{9(VH4dlp%ZIV ӌ}ںWZ ^XK4LRӸ?;VU&8`:]SErU[5Ao1ur1uw7zfƠe,7Abhj\2 ^q+N +"NC;%­6o]z֗' -%+qZ'c"&StIz0 g:|0.#̆񎥾)5K?i$mrdGsCc)u]׬&ݵ|ptQ:HЬ_F!vK5sQgn./t2Al .b ]!r]"|X&7NgknJo*xrT] t](1jAHbSZj8ށjj~Z}joE{ޓO5\rZI1{uzi+cJ(1HrMV :WOA>ݎ^z:xn{C>NBgƦPq7 0n]qdZ^Ӊ@1p#vnpn2M)Tdy D2uWsFME(!* `d|FC[r刷N14dcKٙGwgxke`$͑hQhǭCNj+X)AR?|UBjnt(R׀Ah%f5яb;v Jo`Z!Ϛ†8 ~fpPFiSw#:%cl4dUC(KkHc[toJ (ljK}a1pJUi,9F!;fZc"wq"G=ǽVR71=OOWcAol[t(N ֊F:+E}H5'ђsu?u)GFS>ڃ-^bˈ6)˞8+^R މ|3ˈ!ȒT(tzP7C(f;:Ѳ@cwRYtK%>WUr/aEmi.grm邿 pAw+~at.9T0{^Wו3=L}|*lwj|"Bfl.OT\?>B6_b(cP[;|Pr%9TK]=_N)uC-~Ucz֦˰Nېocm˒0fWGieI`9s1CE?kj)jEY+" Ph}KgGraC5M77MHϭ&v{@H𶕎q=[q^}Ԣ 77:9q.C.g6Rݜ 3{eT5<5EO5j~QG[bx`!Vs%/pNcs iL_,!NFt~MdejUL.Ǩb|vK\EW7K~MMBVb&>p4RR/3Q(.Sq"@lmc;3ZIi->wKqFKtuBoJB#9̸ȾCq&',*~C7|6% OA>e3Tй`  xr/\Cq[Sb[FW4CqxE:+"pXsJޒXD5$ $YH!ducCUr־Hğ̎S_AMdo<kV"W|}"U9to #7$./A?=VıPk+ dy{3O}t<ۏkT:]$XFn<:oLAߝL8|=(&䲺NsMrJhz9KNGϚkP8<YkVS*xQ'|m@ɐ㥩N3$0Vǡ_Ƞ)Ҽ#}-[#@Jm_V竞z?6:fe)"x%<YϺ?DqUM\/@`n(ki x8S:dk{Co}7=6퀯xB{vQ2 hڽAi>ۖ 0޵,]9ѧOkU>Z#Ǫhg ł"Tz"|*Z]GFpAwQ,r_Qy#84|։]\3)[Jد nMhaŌ1'.cM8,z+_>UIz#<ɓB xB{¹W;_ҮoO@TOc:¥ׯڧ`I8 |z1$(h Xꞅp׉)c6V~ma!csNTSl5x+Q*=we<;~ ʄ!_--Sّhx8^dҪU3ʐ܄Dnsfo+x $]ykt_A\OE7ֹl%%ز!ufs`6mlag%4Rl%*Oŝ $BWvr\7,d޷xݐk8 }U*,d[(N\}g| غ]6(Bz@e!ZScuxkox PqC͗ɲN;]]w\~ Ys) )/S疘A6ק_7'Փ .4NGӄBB*f)_,vtUeБ@&i @K;Ѡ؀N0Mum{s?sXB~xn!Qh(HpyKz\7Bq8Y"7r#lr10~\-hrʞͣ?LdzwG^'L=8}wqJ Cȡj 7vcׂ^ #WT |U11>1>3FQHBl  "5Sͩh!B=EV8/Bw-ؗؑ6kbH ~^u~ 5JhC+P26ξ]ް[ w>?fZf6W)+x¯AP)L8J'4[[W#"gz!C{}~Ahק]5E'ػ2TU7E}n'3l^Dcx KOd>1ݮ~'mk@[NM]r:Gq+L#w*8[~=xA1ށ3Ltd,(W+]W0‡vcnOMCyzG=y? 2ǐdпߍtFU?Նvv.B&736./S*iܲGx}a׍ύTQ`Sq_AUuW!/3ĉEˁ}ѩVe?$j}EVsKԝ tpܡe-5Vp8e'x^p~45~*FYp'N>ْ%l=T[ExޛɱeA*JRi׫JJYIzSzoQQUȎ,Lیlxg<1 ˀ0c6cl4fm ئE%JKDBF5|$wU]$1vrGjVU& f&޶::yZmD: Z}4Gm8׃/zi5W,ɌgW *k%/8zN\AzZ(0cm%s+W]$K߀TPݻwΡh{RM{#DWY9 Ӽy+*VO~9!dܶ%Ao#-t'ϭm_m{`5w{JF9$6,9УXᘌrŗSt;ߙ$?1źd='79'=j>iw]h UQ[?3uj?DŽ) Ơ[jTΏ?LbOypVXTtQMXѱZRj*d۹v)~E3_5t{L.Yu )6/L{zbu AO+` |r~EjX.&&@_Ѷvp-\׀O@?8Y!vOA?UorI@) Ih[m^h9LYFDtˏ!i?$KseƫfͺK/Vg=Wg/^xvLq9v3:9Q~r}5*glV:7,VC %fޞ*z47uU<mzӗ}}8іU`U$ e ?6٣oȎ_ogvCL7Uφzm0(+AvEG&F)'bC<bo W-UE]-efqcn7böeI1N~)‹J&;O?كnڤUQ~x4:#h0]=`po3 Ds@(3:&T23` ӏ&3'."MxqeY'ࢀsrdpԍ$>!mmϳr=:@.ӋWIԣF8$nAޣE#[2+0.@S6m3{>؀;z6X(nѱj18Lpi|bCBOޖizohkn#3+1loڈ-n\M_Y\bzK7R큡>PYӧe_I3E_6˘/q-zFcep0ӠOKE1,Q'O~</`JB%W@_ѦꂌNnU=uY $}CZ܃ GɝeݏAү/4捻ފ~(>!Y\Tš |=mG%kD5dtg:U,܈% 'W!P%}8 ޝ`7me!mc _l]KfLIVRHa9g3-g-!uˠOU'*k[7 \Ee jb04{Vpj:Uew&S- w* 7΅;_EGN{6aI]93Ul2NK]~kVcVe4%FO_~C 65WY2O@@*DI&'Jhѧ"5ϛ/k7\ -0G1A@C`>w&ו+ʦZXMR/v=Ng`%^7ryh4.Fdc.yГ,h]-r Y]t,CԊH+$YQOĊra/[AoMvࠢZY>XMd8P û$xum !9q' >[+9ٰ0ISAafBd[;. ɵ xMح}XYG'+.,0ܤA x?ӑ4Y~ՒU\ ռ1+Xhh{vيIF.<{? #_a5..Щr3yTL2RDьOs@r›o> ބwm$psFX&vY[r*8`z/ v v^&Aַ)}ճ6>h)g#݂pMrGQKl(XGoManH@%n.Gu2L\B)9 mJ:LLg@ϤYг:Ӹġ.n.!V.PnV[Ck߈jU1,? -1&ӓYSuF߬:4!aT.Y/g3p7hb؍Êl6 gA|Kth$hl]nd8F3m :h7q]}CYW|h&!nVhyku NhYbܥ-Wh95ZjTnWT8/ 8#9T:qB,8.(55:5V;{ @Ebcmb7 Zt }1 /ž0BAߒ33LCRA_FC,ÕYx&Oָ6&S\x&v2z΢m[jINx rn{/Ӥ>{ul 31h \caw3pl*π>=Iݞ? =KI ;ɔ'HmQYy=Zgú"ӯA99mPN8H#A'AK#b]>; <Z]Z`UÉp{-ix xAż05,'!#=PcTcU5RDъmLW {x hI]9-u$BC㠏+NED< hec Z=!׀AKv̓оL\uH";+ۋ VPO>{ 4cN9=A;"< :xOĞxڴihۼ(H"Moy\=\Z&9ēyx9I1HcC<8Ҫ|W!KR3Q[7Q~$̃ (/Zn1菕:iQ"a.ōt? Lq8I-) =\v&hyaʟ3Uch=|FE+ŷ W=Qd#YbC ߫gZ-J"6n,ZIݶݥ^y& .-u0^6'V?!I0ދP}sh󌎸xMn9v='g'!f^{5ve2p,p?h}c(͚'́8<66O4&iNπZ',ʺYuӢ.8 Z<|#TmɹE[\Vo301؍2)rj!M_WFٵc:Vofz~!Bxp3lb\$V/-B}) !w/X}Bro 4BpD$x-4te;VR4`bLOP8w\ɾMs22p+h}[^+l~ z[j1`JVp~g3bgd,h?NDtˏ3%MY~HﵗƌWu__p9s&L4S13Q>nF,\GcZcjƶTQ-4UU|7ÿt8??nw܇m^Տ\bJבdAoL?f8Q­ѯ?}E/WEۙ]M:zSv FV@*P#Cѳ@J x$v=Ƌ^ CZvޘA:!Їdum([F^/dZnLHKGĞqG6:̢}Eu>wޕnnл !M XU0A3 e#}I[ nm` hC⬅!DؖyGVn3%) 4}t\855WWE]ßfܞ啻Q%OW0¶q^VEmbQ*0RB.&X(nѱj$~L5 5 0ՌK}rt# =B=>kOLh*,^44&Z.PM lnljX=|&,7E:Z?둣!C9ЗmGZsw}R,{tײedvB@.%_޻2n܂rd鯼#0y|m;2nnj櫼Y][UtE3)KsŽ;z&7_Y(.ݔ}o#h0}9WtuUS4@ O)7E&}Z\bggNIXaN2bwZS 4vlu5O>%#SwGӠ5g*a8SsD7ATcˆcÖ0ڟ,Kc FYn+fWI#n;M5Uu$0Z֢P!4 AJ5^hHԢH#( {5/5csVCrsF9K . ҎuzDVɹZ{NĶhAK-hrά(kDm$#Џt=^jdfw7XWɺ06B}cvx#U;< އi#O~vﲄHAoF naa4'ٌIK4v~#Jtt +yk%#x][A?T\ ݚY,us= х[$}.y#"g]7 įEGǮ/.`F ᎶҚj׮D;=h 4!I|DU C= )dB}ʵL&-94VwݠL׸Q1ǔulEׅ;bMTԤN V3 f9rN 4 #4}\v31E.ڽRHSǠ'o|P#OU:0/ja$S?WgR̆ YQ8 CnH8 DY$ASM4"9Zme :̗25D"-V7gˆMr68}>0؅uڊ:yl7r>پxѮQvT" !S3s"\8}#`KbJծolaZW~k~XU=$Ҳ0gҮS*Ҭ0wvmTᰴD=ٵIY-}WV$a9," fԈ$Yε`׽lcl%$HL?=yzZ]Xm:f6l`iJ j12ToYEd E'z^Jel_cλ99 , \wRbF}m3jb༣OG.37MtF{{ZUAuvќvﳊpէ/1pӊXܳ3/=2XLuw׊k`T``r;"6p1pk钁^%N *cu){M"87/=Xx׎uA] v`{6@ bm'~{c*bgP_{49)UO9U1p} =pqϘ8/=XuQA] v`{㦹lڃuXӕRF ւYvͤkcբ]NJ|\[yp<|84&*Ǎ@ihR27?]͏߄ޯc/#v(+@EM$;RQ-XL6xZԐy/|gh-jd{޾yӛ]#owK8!kp k[Ǖ7!זmC1vY7z¾k{M}"Xۭ}Sc[kN)r\isL[(뻺Qd;ɶdz{LC$]-]m*s~fuZ㦗~vGXv3<Ը~j[3Q3En;~~8oBm*鷸tSSݎY5_JŨguV(sM\c9U=E eOm,s?0vzҬ[O+-kAi_R٭e]OH#@#;@'rҩmԃdB%T2?l9 420;3 b@/lb.ZKkr׿~koH)cmm5v 3IdmK L#Fzp@%7?.}yRϴ1\m(e`}j=~6W_K lw83I?>P̚>0?=rԗX.ڃ=HO6t}cۈ6:%g^xƢ#YUD$8p=l=*"b7 zvW]@D}*}$^]@M&=$#Gp}C7ItJ"fЛeD D*tDSm2IQ&#ljVc]A.@'ɱ w+U?}h2u! %IK&@#ɱ r$[LFcn*K|hNqF/bbVS1  z;U+o{;1T}[:\ޖ2}HC' 0!yL/# RO eZ;8n1}Có36eMKlʚuyeƫfͺK/Vg悘 @8{Μ CQL%T5KRO_Ə['csԼ竝G[As}BT 6#?R8ѐ5NF$ e ?6"?}E/2WEۙ]UL>SVF6@a*Bs3]Eg[#-! 14)(~_ ZI[/~m^MŪ'c&x]eR-1d #ߘV0P8@xkeft d0|`eF*d\QG?YгROUE+ʑnVȝ7>:idF{\SP5Z qYNd~*7%,6HFxH^?ȍ'EE1L&8p+hnnl: -ep}ynҩwj ណq(^8*ʼ<';T‰ (߸?w: uGx !VuXUݙqG'ahdOFu=2-z'4' ƀ@K 3EC1X; g%1XUsyST$V=ռajWW*vm#q  ;\&:R<S'Y=u"vRoPmyn-壺Jtf &O(j$f yLplLp'usޟ9ojJ8z6>lVXٶ_Ҧy?Q&!/~2%=ۈʇmjf}| Qpc͠7k3䨟cԅw]7#e?Q 'oU}'} 'w9ēUL7g$nMȇ#k$$ Z.ZD1HƖ}Tل妙czu'\X O70=hc# ~,ChiܺWҾʟۍէ}mgj0j097LK6-UE]IjZTUohP\VwΕX(:=;ajs05X6Ԧ:1MF;@m?u'phј $ŝnR_j.O.a.0Xm E:G~2/Ftːۏ=AK] 26! ;c%jC u ƀA6yV in,\YgMU]t!ʚ>M<8&b}p,clbƮQXziQiЧEC5+ƭr HЖ@_PVHZB%W@n*>.6.hq\f?N>ޮ=P*yp~Yl'~s'u-DF&Tz(sC4 pWs 5Mv7}F4&{Ӡ /ir-],U+A < L7AA=*:fcb?̡X+׎.;v,ep?I(>!Y|/C`=xҮi($B=o\#Xk$p;[ntٌ,&?06ػnT;AWcD4% %~~8<klKl].,zKfU83(#ЏQ[UϤM5ֲl,D!JL \ m홎\{U7; IpI>v>  O,i:'bOVxK#Ԛ,5w" Vws7}7gVh7-hh_\vѴrخLAzWRA# r)36X#f]2XU:t:[ȌZ45rFhCckeH^yTT _rHpM؎Vt;.Y=Ws(CнXB9ބjqٖ_;OGYM)mV-Ǯsy/; P7GϼfehٵF~jJQ4p({$72 Țb2٩@n\荎u K(vۥRcq{̨ǹ)M!>z2+W&I1J߭ϻ2%ϥywt|ƞT5*S;ryqVw ./M@q9C셅@7ZD̨+Wj6Ze KǛb=n`&@e>Pi|׈ym9ѐ Z蘐m#"N۹PӭEkH3 >hV,z/)Ÿu.*f ix]p}fw!.q ځPͭW*٨ʲ@]r!Pl\ф\*M+U^TsX!4j$+ڎcքbJeGOy_Bmő !M8ZH! ʳLVsiׄ ڮ;) s[NҙS%f7@3?̻VRnr)S;ν۵Eη'S®1ZH|q{J滛2߮˙Щr5 ǢbG$>`t."< ZDZváׂa92%5)!h,E/9 (bCeA@kkAEKrvGxԩ%\&8lTJJa8vZ /ھEGA haUHUkI1fL#\79czV14޲-uYA|{l`=LPP;)fph%1?E6ޫ-?B  ,N)X༬dI}=&UtD  tn7W{sqN#{+#,!ha3?/p +#-M } a{a߾)Wަ7V0qP2*#@VUʣ0,h ~VQkkFYYc;0%S)NwV)~ l:OKmHKRv{JUuvxtt1utkkQh'I~,f`h\Cnv@㽆ߜ{@k%*\V_,(ziNDqf+rFn[?^a۸r, Gľ!~JU \lJT1<n v=^}hckOp'u=(k[?s]M-QS"ǀ8N,߈uw2ݧCv׸&ɮ{c_%UgMNt'-Bs{7+ 6|Z݃Is Bz?&hSܭdSW,WWb*vUe,39~j]c<\\ֻB/|rvgs!oitXFHQ{Iɂ.®\߹|LwB |7z<n#i'xV/ͤ5R?o¯vxܮ7O@z}>V޹d/PpHg|/97gi?^vΉnN*UMOlb P ~0vZ(5yNjn}]ITJ(*¡&oAҪ5ؒlyӬrU̇7e%Q .lQӪjPY5jOHskSj,5č©0 M7~6+uV9*qzc߰VGHCl4Њ:( Kqp?"cG'G?B\A% C<yA!3g9QC sx!b7 Zյξ!:&ʂ S^ RQ;Zt35ȄbHxQ&S/c؎>|HFn g~߸Y {k $ZF~ZO@%({$}眘E #-Ą?+߯ZpC"C>j B=qwbc #iJsé840>{훼t\w)!Y@jܰ8b/NTZn V^D#S 75n xTl)6 %vY!Їo/0x4~LJ4 W]BG]F Dv8d&l;Bvbl+? q σ>,,xz,WG /8~r6{!*,Ye/6Ŏ[&"ĄAytM<[vtvo4~;ڷEyOK%Ϡ ƴxϏ&롪u;Vj,\%"l*KҔY~Ji8v4hZѮz ]yjaQ#<Zjթ5[T kH]y獨4s얏ʔ_FǧVA?V.Tv;Fj$AF)S&_Mq_$Ð=hd#ecQϧKG!aR)sfG;KTZ#́Ωk[Ϳ! k& D$=m>a-% YRG~C= 7&حRU+?r=Z2{i]$g ;{g'RSUUHx&+`jKV%|tIx] aɉAՖgw[KP_ʄ߄@b8;}=Ѥ < %n-5'_7ޘB8x*㭆BZxF?d$(z}k0mm8-?|d,\k/R7.ݿX Mx3sLxcbTg#VO߹Ə ~Ѳ\~}Ch!?p_̕n)_FQܿjޚ$T?_6~x \e\h~0Zu{%sګ.U5N7 Rdpack/man/0000755000176200001440000000000015141073053012230 5ustar liggesusersRdpack/man/Rdo_modify.Rd0000644000176200001440000000704215102212001014576 0ustar liggesusers\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/c_Rd.Rd0000644000176200001440000000417415102212001013355 0ustar liggesusers\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') if(requireNamespace("gbRd")){ 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/Rdo_fetch.Rd0000644000176200001440000000633015102212001014377 0ustar liggesusers\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/predefined.Rd0000644000176200001440000000603115102212001014605 0ustar liggesusers\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 providing the types of the top level sections in 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"]} results in \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}", 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]{ tmp_rdo_top_tags <- rdo_top_tags tmp_incomplete <- length(tmp_rdo_top_tags) \%\% 5 if(tmp_incomplete != 0) tmp_rdo_top_tags <- c(tmp_rdo_top_tags, rep("''", 5 - tmp_incomplete)) paste("\\\\tabular{lllll}{", paste(sub("^[#]", "\\\\\\\\verb{#}", sub("^([\\\\])", "\\\\\\\\\\\\1", tmp_rdo_top_tags)), c(rep("\\\\tab ",4),"\\\\cr"), sep="", collapse="\n"), "}")} Note that most, but not all, are prefixed with a backslash. } \references{ \insertAllCited{} } \keyword{Rd} Rdpack/man/format_funusage.Rd0000644000176200001440000000517215102212001015672 0ustar liggesusers\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/Rdo_macro.Rd0000644000176200001440000000504415102212001014410 0ustar liggesusers\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_get_argument_names.Rd0000644000176200001440000000245415102212001017155 0ustar liggesusers\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/inspect_signatures.Rd0000644000176200001440000000334115102212001016412 0ustar liggesusers\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.Rd0000644000176200001440000000171215102212001015441 0ustar liggesusers\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/Rdreplace_section.Rd0000644000176200001440000000366115102212001016133 0ustar liggesusers\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/promptUsage.Rd0000644000176200001440000001505715102212001015016 0ustar liggesusers\name{promptUsage} \alias{promptUsage} \alias{get_usage} \title{ Generate usage text for functions and methods \Sexpr[stage=build,results=hide]{require(Rdpack)} } \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/S4formals.Rd0000644000176200001440000000276715102212001014366 0ustar liggesusers\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/get_sig_text.Rd0000644000176200001440000000653215102212001015173 0ustar liggesusers\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 \Sexpr[stage=build,results=hide]{require(Rdpack)} } \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/Rdo_flatinsert.Rd0000644000176200001440000000162615102212001015464 0ustar liggesusers\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_tags.Rd0000644000176200001440000000265415102212001014251 0ustar liggesusers\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/inspect_usage.Rd0000644000176200001440000000261115102212001015331 0ustar liggesusers\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/parse_pairlist.Rd0000644000176200001440000000710515102212001015524 0ustar liggesusers\name{parse_pairlist} \alias{parse_pairlist} %\alias{pairlist2f_usage} \alias{pairlist2f_usage1} \title{ Parse formal arguments of functions \Sexpr[stage=build,results=hide]{require(Rdpack)} } \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/inspect_Rd.Rd0000644000176200001440000000510115102212001014567 0ustar liggesusers\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/Rdo_locate_leaves.Rd0000644000176200001440000000301315102212001016107 0ustar liggesusers\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/zzbsdup.Rd0000644000176200001440000000160715102212001014205 0ustar liggesusers\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/parse_Rdtext.Rd0000644000176200001440000000362715102212001015154 0ustar liggesusers\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_remove_srcref.Rd0000644000176200001440000000162415102212001016150 0ustar liggesusers\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_show.Rd0000644000176200001440000000170515102212001014267 0ustar liggesusers\name{Rdo_show} \alias{Rdo_show} \title{Convert an Rd object to text and show it} \description{Render an Rd object as text and show it.} \usage{ Rdo_show(rdo) } \arguments{ \item{rdo}{an Rd object} } \details{ \code{Rdo_show} renders the help page represented by \code{rdo} as text and shows it with \code{file.show()}. \code{Rdo_show} is a simplified front end to \code{utils::Rd2txt}. See \code{\link{viewRd}} for more complete rendering, including of references and citations. } \value{ Invisible \code{NULL}. The function is used for the side effect of showing the text representation of \code{rdo}. } \author{Georgi N. Boshnakov} \seealso{ \code{\link{viewRd}} } \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) } } \keyword{Rd} Rdpack/man/append_to_Rd_list.Rd0000644000176200001440000000433415102212001016135 0ustar liggesusers\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/get_usage_text.Rd0000644000176200001440000000274215102212001015514 0ustar liggesusers\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/Rdo_insert.Rd0000644000176200001440000000245515102212001014616 0ustar liggesusers\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/Rdo_set_section.Rd0000644000176200001440000000405115102212001015623 0ustar liggesusers\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/reprompt.Rd0000644000176200001440000003617315102212001014362 0ustar liggesusers\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, aliases, 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...)}. \code{reprompt} understands also subsetting ans subassignment operators. For example, suppose that the \code{\\arguments} section of file "bracket.Rd" contains these directives (or any other wrong signatures): \preformatted{ \method{[}{ts}() \method{[[}{Date}() } Then \code{reprompt("./bracket.Rd")} will change them to \preformatted{ \method{[}{ts}(x, i, j, drop = TRUE) \method{[[}{Date}(x, \dots, drop = TRUE) } This works for the assignment operators and functions, as well. For example, any of these \preformatted{ \method{`[<-`}{POSIXlt}() \method{[}{POSIXlt}(x, j) <- value } will be converted by \code{reprompt} to the standard form \preformatted{ \method{[}{POSIXlt}(x, i, j) <- value } Note that the quotes in \code{`[<-`} above. 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/parse_Rdpiece.Rd0000644000176200001440000000530615102212001015251 0ustar liggesusers\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 dots <- paste0("\\\\", "dots") 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_collect_metadata.Rd0000644000176200001440000000404315102212001016572 0ustar liggesusers\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/zzcapture_promptany.Rd0000644000176200001440000000510215102212001016636 0ustar liggesusers\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/promptPackageSexpr.Rd0000644000176200001440000000665515102212001016333 0ustar liggesusers\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/Rdpack_bibstyles.Rd0000644000176200001440000000412415104674756016024 0ustar liggesusers\name{Rdpack_bibstyles} \alias{Rdpack_bibstyles} \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) } \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 \code{authors} to \code{"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{ if called with no arguments, a list of the names of all styles. if called with one argument (\code{package}) only, the name of the bib style, a character string, requested by that package. The style is created if hadn't been set up before. As a special case \code{package = ""} will return the default Rdpack style. if called with two arguments, the function set up a bibstyle as discussed in section \sQuote{Details}. It returns the name of that style. } %\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/macros/0000755000176200001440000000000015102212001013475 5ustar liggesusersRdpack/man/macros/refmacros.Rd0000644000176200001440000000437215102212001015753 0ustar liggesusers% insert reference #1 - key, #2 - package %% changing to cache bib as insertCite does \newcommand{\insertRef}{\Sexpr[results=rd,stage=build]{Rdpack::insert_ref(key="#1",package="#2")}} %\newcommand{\insertRef}{\Sexpr[results=rd,stage=install]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env(); Rdpack::insert_ref(key="#1",package="#2", cached_env=.Rdpack.currefs)}} % insert reference #1 - keys, #2 - package \newcommand{\insertCiteOnly}{\Sexpr[results=rd,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(keys="#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(keys="#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(keys="#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)}} \newcommand{\insertCited}{\Sexpr[results=rd,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_all_ref(.Rdpack.currefs, empty_cited = TRUE)}} % 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/Rd_combo.Rd0000644000176200001440000000261415102212001014227 0ustar liggesusers\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) ## which Rd files don't have a value section? counts <- unlist(Rd_combo(rdnames, function(x) length(Rdo_locate_core_section(x, "\\value")))) rdnames[counts == 0] ## reprompt all files Rd_combo(rdnames, reprompt) for(nam in rdnames) try(reprompt(nam)) for(nam in rdnames) try(reprompt(nam, sec_copy=FALSE)) } } \keyword{Rd} %\keyword{Rdprocessing} Rdpack/man/Rdo_reparse.Rd0000644000176200001440000000304215102212001014744 0ustar liggesusers\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." dots <- paste0("\\\\", "dots") 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/Rdo2Rdf.Rd0000644000176200001440000001022415102212001013741 0ustar liggesusers\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 outputs "author" preceded by one backslash only. # reprompt(infile="./man/Rdo2Rdf.Rd", sec_copy = FALSE) } \keyword{Rd} Rdpack/man/Rdo_insert_element.Rd0000644000176200001440000000251615102212001016325 0ustar liggesusers\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/rdo_text_restore.Rd0000644000176200001440000000327715102212001016104 0ustar liggesusers\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/Rdpack-package.Rd0000644000176200001440000004240615134177532015333 0ustar liggesusers\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{ % 2025-11-15 commented out % % \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{rbibutils} \insertCite{Rpackage:rbibutils}{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{} } Don't align the backslash with the second 'e' of \code{@references}, since roxygen2 may interpret it as verbatim text, not macro. 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 a number 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 1:} Reference \insertCite{dummyArticle;textual}{Rdpack} (see below) does not exist. It is a test that simple math in BibTeX entries works. \strong{Note 2:} Reference \insertCite{unpublished-full;textual}{rbibutils} is included to show that some more and less usual accents are handled. --- \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/Rdo_locate.Rd0000644000176200001440000000660615102212001014563 0ustar liggesusers\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/insert_ref.Rd0000644000176200001440000002072015102212001014641 0ustar liggesusers\name{insert_ref} \alias{insert_ref} \alias{insertRef} \concept{Rd macros} \concept{bibtex} \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 \code{insert_ref()} is the workhorse behind this mechanism. The description given on this page should be sufficient, for more details see the vignette. } \usage{ insert_ref(key, package = NULL, \dots, cached_env = NULL) } \arguments{ \item{key}{the bibtex key of the reference, a character string.} \item{package}{the package in which to look for the bibtex file.} \item{\dots}{ further arguments to pass on to \code{get_bibentries()}. The only one of interest to users is \code{bibfile}, whose default is "REFERENCES.bib", see \code{\link{get_bibentries}}. } \item{cached_env}{ environment, used to avoid repeatedly passing the bib file from scratch, mainly used by the Rd macros. } } \details{ \code{insert_ref} extracts a bibliograhic 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}. Package \pkg{Rdpack} provides several Rd macros for inserting references and citations in the documentation of a package. All macros work in both, manually written Rd files and in \pkg{roxygen2} documentation chunks. The macros look for references in file \code{"REFERENCES.bib"} in the root of the installation directory of the package. When a package is in development mode under \pkg{devtools}, \code{"inst/REFERENCES.bib"} in the development directory of the package is checked first. See also \code{\link{get_bibentries}} but note that while direct calls to \code{insert_ref()} can specify a different file, the filename and the places where it is looked for are fixed for the Rd macros. The description below assumes that \pkg{Rdpack} has been added to file DESCRIPTION, as described in \code{\link{Rdpack-package}} and vignette \code{"Inserting_bibtex_references"}. The Rd macros are put in the text of documentation sources (\sQuote{Rd} files or \sQuote{roxygen2} chunks). \subsection{Rd macro insertRef}{ \verb{\\insertRef{key}{package}} inserts the reference with bibtex key \verb{key} from file \code{"REFERENCES.bib"} in package \verb{package}. Argument \sQuote{package} can be any installed \R package, not necessarily the one of the documentation object, as long as it contains file \code{"REFERENCES.bib"} in the root of its installation directory. The references are partially processed when the package is built. References inserted with \verb{\\insertRef} 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). For example, section \sQuote{References} of this help page shows (among other things)) the rendered results of the following lines in the Rd source file: \preformatted{ \\insertRef{Rpackage:rbibutils}{Rdpack} \\insertRef{parseRd}{Rdpack} \\insertRef{bibutils6.10}{rbibutils} } A roxygen2 documentation chunk might look like this: \preformatted{ #' @references #' \\insertRef{Rpackage:rbibutils}{Rdpack} #' #' \\insertRef{parseRd}{Rdpack} #' #' \\insertRef{bibutils6.10}{rbibutils} } The first reference has label \verb{Rpackage:rbibutils} and is taken from file \code{"REFERENCES.bib"} in package \pkg{Rdpack}. The third reference is from the file \code{"REFERENCES.bib"} in package \pkg{rbibutils}. For more details see vignette \code{"Inserting_bibtex_references"}. } \subsection{Rd macro insertCite}{ \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,Rpackage:rbibutils}{Rdpack}} \tab \insertCite{parseRd,Rpackage:rbibutils}{Rdpack} \cr \code{\\insertCite{Rpackage:rbibutils}{Rdpack}} \tab \insertCite{Rpackage:rbibutils}{Rdpack} \cr \code{\\insertCite{bibutils6.10}{rbibutils}} \tab \insertCite{bibutils6.10}{rbibutils} } 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,Rpackage:rbibutils;textual}{Rdpack}} produces: \insertCite{parseRd,Rpackage:rbibutils;textual}{Rdpack}. To mix the citations with other text, such as \sQuote{see also} and \sQuote{chapter 3}, write the list of keys as 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 @Rpackage:rbibutils}{Rdpack}, \insertCite{@see also @parseRd; @Rpackage:rbibutils}{Rdpack}, \insertCite{@see also @parseRd and @Rpackage:rbibutils;textual}{Rdpack}. } produces: \tabular{l}{ \insertCite{@see also @parseRd and @Rpackage:rbibutils}{Rdpack}, \cr \insertCite{@see also @parseRd; @Rpackage:rbibutils}{Rdpack}, \cr \insertCite{@see also @parseRd and @Rpackage:rbibutils;textual}{Rdpack}. } In the parenthesised form, adding \verb{;nobrackets} at the end of the list of keys causes the enclosing parentheses to be dropped. This is useful if you wish to use markup for the text surrounding the references. For example, \preformatted{ (\emph{see also} \insertCite{@@parseRd; @Rpackage:rbibutils;nobrackets}{Rdpack}). } gives: (\emph{see also} \insertCite{@@parseRd; @Rpackage:rbibutils;nobrackets}{Rdpack}). Without \sQuote{\verb{;nobrackets}} the result would be (\emph{see also} \insertCite{@@parseRd; @Rpackage:rbibutils}{Rdpack}). } \subsection{Rd macro insertNoCite}{ 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{parseRd}{Rdpack}} and \code{\\insertNoCite{*}{rbibutils}} record the specified references for inclusion by \code{\\insertAllCited}. } \subsection{Rd macro insertAllCited}{ \code{\\insertAllCited} inserts all references cited with \code{\\insertCite} and \code{\\insertNoCite}. Putting this macro in the references section will keep the references up to date automatically. The Rd section may look something like: \preformatted{ \\references{ \\insertAllCited{} } } or in roxygen2, the references chunk might look like this: \preformatted{ #' @references #' \\insertAllCited{} } } \subsection{Rd macro insertCiteOnly}{ \code{\\insertCiteOnly{key}{package}} is as \code{\\insertCite} but does not include the key in the list of references for \code{\\insertAllCited}. } } \value{ for \code{insert_ref}, a character string } \references{ For illustrative purposes there are two sets of citations below The first set of references is obtained with \code{\\insertRef} for each reference: \insertRef{parseRd}{Rdpack} \insertRef{Rpackage:rbibutils}{Rdpack} \insertRef{bibutils6.10}{rbibutils} ---- The following references are obtained with a single \code{\\insertAllCited{}}. The references are sorted automatically by the surnames of the authors: \insertAllCited{} } \author{Georgi N. Boshnakov} \seealso{ \code{\link{Rdpack-package}} for overview, \code{vignette("Inserting_bibtex_references", package = "Rdpack")} for further details on the citation macros \code{\link{insert_citeOnly}} for the function generating citations } \examples{ cat(insert_ref("Rpackage:rbibutils", "Rdpack"), "\n") } \keyword{documentation} \keyword{Rd} Rdpack/man/viewRd.Rd0000644000176200001440000000256515102212001013750 0ustar liggesusers\name{viewRd} \alias{viewRd} \title{View Rd files in a source package} \description{View Rd files in a source package.} \usage{ viewRd(infile, type = getOption("help_type"), 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 \code{getOption("help_type")}. } \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/parse_usage_text.Rd0000644000176200001440000000265415102212001016051 0ustar liggesusers\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/get_bibentries.Rd0000644000176200001440000001106115102212001015464 0ustar liggesusers\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") ## Bib from base R packages are disabled in Rdpack v2 (notify the ## maintainer of Rdpack or raise an issue on github if you wish this back). ## ## 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/list_Rd.Rd0000644000176200001440000000350515102212001014103 0ustar liggesusers\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/inspect_args.Rd0000644000176200001440000000321615102212001015163 0ustar liggesusers\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/Rdo_empty_sections.Rd0000644000176200001440000000306115102212001016351 0ustar liggesusers\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/Rdo_get_item_labels.Rd0000644000176200001440000000223215102212001016422 0ustar liggesusers\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/Rdo_sections.Rd0000644000176200001440000000632615102212001015142 0ustar liggesusers\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_get_insert_pos.Rd0000644000176200001440000000300315102212001016324 0ustar liggesusers\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_modify_simple.Rd0000644000176200001440000000206715102212001016151 0ustar liggesusers\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/makeVignetteReference.Rd0000644000176200001440000001030615102212001016742 0ustar liggesusers\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{ ## NOTE (2020-01-21): the following examples work fine, but are not ## rendered correctly by pkgdown::build_site(), so there may be errors ## on the site produced by it, https://geobosh.github.io/Rdpack/. 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/inspect_slots.Rd0000644000176200001440000000107115102212001015370 0ustar liggesusers\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/parse_text.Rd0000644000176200001440000000327615102212001014666 0ustar liggesusers\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{parse_text} in package gbutils } \keyword{programming} \keyword{internal} Rdpack/man/update_aliases_tmp.Rd0000644000176200001440000000135515102212001016347 0ustar liggesusers\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/insert_citeOnly.Rd0000644000176200001440000000410415102212001015651 0ustar liggesusers\name{insert_citeOnly} \alias{insert_citeOnly} \title{Generate citations from bibtex keys} \description{Generate citations from bibtex keys.} \usage{ insert_citeOnly(keys, package = NULL, before = NULL, after = NULL, bibpunct = NULL, ..., cached_env = NULL, cite_only = FALSE, dont_cite = FALSE) } \arguments{ \item{keys}{ a character string containing bibtex key(s) prefixed with the symbol \code{@}, intermixed with free text. The format is the same as for Rd macro \verb{\\insertCite}. Put \verb{;textual} at the end of the string to get a textual citation. Similarly, \verb{;nobrackets} requests parenthesised citation without the enclosing parentheses. Alternatively, \code{keys} can contain one or more keys, separated by commas. } \item{package}{name of an R package.} \item{before}{see \code{\link{citeNatbib}}.} \item{after}{see \code{\link{citeNatbib}}.} \item{bibpunct}{see \code{\link{citeNatbib}}.} \item{\dots}{further arguments; for internal use.} \item{cached_env}{for internal use.} \item{cite_only}{for internal use.} \item{dont_cite}{for internal use.} } \details{ This is the function behind \verb{\\insertCite} and related macros. Argument \code{"keys"} has the syntax of the first argument of \verb{\\insertCite}, see \code{\link{insertRef}} for full details. } \value{ a character vector containing the references with Rd markup } %\references{ %%% ~put references to the literature/web site here ~ %} \author{Georgi N. Boshnakov} \seealso{ \code{\link{insert_ref}} for description of all available Rd macros } \examples{ insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd", package = "Rdpack") ## (see also Boshnakov and Putman 2020 and Murdoch 2010) insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd;nobrackets", package = "Rdpack") ## see also Boshnakov and Putman 2020 and Murdoch 2010 insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd;textual", package = "Rdpack") ## see also Boshnakov and Putman (2020) and Murdoch (2010) } \keyword{documentation} Rdpack/man/ereprompt.Rd0000644000176200001440000000262515102212001014522 0ustar liggesusers\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/man/compare_usage1.Rd0000644000176200001440000000457315102212001015404 0ustar liggesusers\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/insert_all_ref.Rd0000644000176200001440000000467415102212001015503 0ustar liggesusers\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 = "", empty_cited = FALSE) } \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.} \item{empty_cited}{ if \code{TRUE}, empty the list of currently cited items. } } \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{ a character string containing a textual representation of the references, suitable for inclusion in an Rd file } \references{ Currently there are no citations on this help page. Nevetheless, 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{ ## 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") ## all references from package Rdpack and rbibutils m <- matrix(c("*", "Rdpack", "*", "rbibutils"), ncol = 2, byrow = TRUE) cat(insert_all_ref(m), "\n") } \keyword{documentation} Rdpack/man/RStudio_reprompt.Rd0000644000176200001440000000251315102212001016022 0ustar liggesusers\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{ereprompt}}, \code{\link{prompt}} } Rdpack/man/parse_Rdname.Rd0000644000176200001440000000264415102212001015106 0ustar liggesusers\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_tag.Rd0000644000176200001440000000266415102212001014067 0ustar liggesusers\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/Rdapply.Rd0000644000176200001440000001074115102212001014116 0ustar liggesusers\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/char2Rdpiece.Rd0000644000176200001440000000370615102212001015001 0ustar liggesusers\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/Rdo_append_argument.Rd0000644000176200001440000000323115102212001016454 0ustar liggesusers\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." dots <- paste0("\\\\", "dots") 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/Rdo_which.Rd0000644000176200001440000000425615102212001014415 0ustar liggesusers\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/rebib.Rd0000644000176200001440000001125415102212001013566 0ustar liggesusers\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/deparse_usage.Rd0000644000176200001440000000574615102212001015323 0ustar liggesusers\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 \Sexpr[stage=build,results=hide]{require(Rdpack)} } \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/zzasym_compare.Rd0000644000176200001440000000326715102212001015553 0ustar liggesusers\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/Rdo_piecetag.Rd0000644000176200001440000000254515102212001015073 0ustar liggesusers\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/DESCRIPTION0000644000176200001440000000324615142024311013162 0ustar liggesusersPackage: Rdpack Type: Package Title: Update and Manipulate Rd Documentation Objects Version: 2.6.6 Authors@R: c( person(given = c("Georgi", "N."), family = "Boshnakov", role = c("aut", "cre"), email = "georgi.boshnakov@manchester.ac.uk", comment = c(ORCID = "0000-0003-2839-346X")), 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://geobosh.github.io/Rdpack/ (doc), https://CRAN.R-project.org/package=Rdpack BugReports: https://github.com/GeoBosh/Rdpack/issues Depends: R (>= 2.15.0), methods Imports: tools, utils, rbibutils (> 2.4) Suggests: grDevices, testthat, rstudioapi, rprojroot, gbRd License: GPL (>= 2) LazyLoad: yes Encoding: UTF-8 RoxygenNote: 7.1.1 NeedsCompilation: no Packaged: 2026-02-07 16:29:31 UTC; georgi Author: Georgi N. Boshnakov [aut, cre] (ORCID: ), Duncan Murdoch [ctb] Maintainer: Georgi N. Boshnakov Repository: CRAN Date/Publication: 2026-02-08 06:10:17 UTC