├── inst ├── examples │ ├── RdpackTester │ │ ├── NAMESPACE │ │ ├── R │ │ │ └── RdpackTester-internal.R │ │ ├── inst │ │ │ ├── REFERENCES.bib │ │ │ └── auto │ │ │ │ └── REFERENCES.el │ │ ├── DESCRIPTION │ │ └── man │ │ │ └── RdpackTester-package.Rd │ ├── RdpackTester.pdf │ ├── url_with_percents.bib │ ├── journal_with_percents.bib │ └── tz.Rd ├── RStudio │ └── addins.dcf ├── CITATION └── REFERENCES.bib ├── tests ├── testthat │ ├── dummyArticle.rds │ ├── char2Rdpiece_a.RDS │ ├── char2Rdpiece_b.RDS │ ├── char2Rdpiece_c.RDS │ ├── get_sig_text_f1.RDS │ ├── get_sig_text_f4.RDS │ ├── myshow-methods.Rd │ ├── as.character.f_usage.Rd │ ├── show.Rd │ ├── test-char2Rdpiece.R │ └── classRepresentation-class.Rd └── testthat.R ├── vignettes ├── Inserting_bibtex_references.pdf └── Inserting_figures_and_evaluated_examples.pdf ├── .Rbuildignore ├── TODO ├── man ├── inspect_slots.Rd ├── update_aliases_tmp.Rd ├── Rdo_remove_srcref.Rd ├── Rdo_flatinsert.Rd ├── set_Rdpack_bibstyle.Rd ├── Rdo_show.Rd ├── zzbsdup.Rd ├── Rdo_is_newline.Rd ├── Rdo_modify_simple.Rd ├── Rdo_get_item_labels.Rd ├── RStudio_reprompt.Rd ├── Rdo_get_argument_names.Rd ├── viewRd.Rd ├── Rdo_insert.Rd ├── Rdo_insert_element.Rd ├── ereprompt.Rd ├── Rd_combo.Rd ├── parse_usage_text.Rd ├── Rdo_tags.Rd ├── Rdo_piecetag.Rd ├── inspect_usage.Rd ├── S4formals.Rd ├── parse_Rdname.Rd ├── Rdo_get_insert_pos.Rd ├── Rdo_locate_leaves.Rd ├── Rdo_tag.Rd ├── get_usage_text.Rd ├── Rdo_reparse.Rd ├── Rdo_empty_sections.Rd ├── Rdo_append_argument.Rd ├── parse_text.Rd ├── rdo_text_restore.Rd ├── inspect_args.Rd ├── zzasym_compare.Rd ├── inspect_signatures.Rd ├── list_Rd.Rd ├── Rdreplace_section.Rd ├── parse_Rdtext.Rd ├── Rdpack_bibstyles.Rd ├── char2Rdpiece.Rd ├── Rdo_collect_metadata.Rd ├── macros │ └── refmacros.Rd ├── insert_citeOnly.Rd ├── Rdo_set_section.Rd ├── c_Rd.Rd ├── Rdo_which.Rd ├── append_to_Rd_list.Rd ├── compare_usage1.Rd ├── insert_all_ref.Rd ├── format_funusage.Rd ├── zzcapture_promptany.Rd ├── Rdo_macro.Rd ├── inspect_Rd.Rd ├── parse_Rdpiece.Rd ├── deparse_usage.Rd ├── Rdo_fetch.Rd ├── predefined.Rd ├── Rdo_sections.Rd ├── Rdo_locate.Rd ├── promptPackageSexpr.Rd ├── parse_pairlist.Rd ├── get_sig_text.Rd ├── Rdo_modify.Rd ├── Rdo2Rdf.Rd ├── makeVignetteReference.Rd ├── Rdapply.Rd └── get_bibentries.Rd ├── R ├── alias.R ├── RStudio.R ├── slots.R ├── parse.R ├── threedots.R ├── promptSexpr.R ├── predefined.R └── yytransient.R ├── .github └── workflows │ ├── pkgdown.yaml │ └── check-standard-tex.yaml ├── DESCRIPTION ├── .gitignore ├── NAMESPACE └── _pkgdown.yml /inst/examples/RdpackTester/NAMESPACE: -------------------------------------------------------------------------------- 1 | exportPattern("^[[:alpha:]]+") 2 | -------------------------------------------------------------------------------- /inst/examples/RdpackTester.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/inst/examples/RdpackTester.pdf -------------------------------------------------------------------------------- /tests/testthat/dummyArticle.rds: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/tests/testthat/dummyArticle.rds -------------------------------------------------------------------------------- /tests/testthat/char2Rdpiece_a.RDS: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/tests/testthat/char2Rdpiece_a.RDS -------------------------------------------------------------------------------- /tests/testthat/char2Rdpiece_b.RDS: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/tests/testthat/char2Rdpiece_b.RDS -------------------------------------------------------------------------------- /tests/testthat/char2Rdpiece_c.RDS: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/tests/testthat/char2Rdpiece_c.RDS -------------------------------------------------------------------------------- /tests/testthat/get_sig_text_f1.RDS: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/tests/testthat/get_sig_text_f1.RDS -------------------------------------------------------------------------------- /tests/testthat/get_sig_text_f4.RDS: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/tests/testthat/get_sig_text_f4.RDS -------------------------------------------------------------------------------- /inst/examples/RdpackTester/R/RdpackTester-internal.R: -------------------------------------------------------------------------------- 1 | test_1 <- function(x,y){ 2 | "This function does nothing." 3 | } 4 | -------------------------------------------------------------------------------- /vignettes/Inserting_bibtex_references.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/vignettes/Inserting_bibtex_references.pdf -------------------------------------------------------------------------------- /inst/examples/RdpackTester/inst/REFERENCES.bib: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/inst/examples/RdpackTester/inst/REFERENCES.bib -------------------------------------------------------------------------------- /inst/RStudio/addins.dcf: -------------------------------------------------------------------------------- 1 | Name: Reprompt 2 | Description: Updates Rd file based on editor contents 3 | Binding: RStudio_reprompt 4 | Interactive: false 5 | -------------------------------------------------------------------------------- /vignettes/Inserting_figures_and_evaluated_examples.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GeoBosh/Rdpack/HEAD/vignettes/Inserting_figures_and_evaluated_examples.pdf -------------------------------------------------------------------------------- /tests/testthat.R: -------------------------------------------------------------------------------- 1 | if(require("testthat")) { 2 | library(testthat) 3 | library(Rdpack) 4 | test_check("Rdpack") 5 | } else 6 | warning("package 'testthat' required for 'Rdpack\'s' tests") 7 | -------------------------------------------------------------------------------- /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^bug_* 2 | .rsync_exclude 3 | ^docs/ 4 | ^vignettes/.RData 5 | ^_pkgdown.yml$ 6 | ^revdep$ 7 | ^README.org 8 | ^Org$ 9 | ^TODO 10 | [.]emacs[.]desktop.* 11 | ^TAGS$ 12 | ^auto$ 13 | [^/]*[.]Rout$ 14 | ^TechnicalDoc 15 | ^sav[0-9]*[.]Rhistory 16 | ^NAMESPACEsav$ 17 | ^_pkgdown\.yml$ 18 | ^docs$ 19 | ^\.github$ 20 | ^\.git$ 21 | -------------------------------------------------------------------------------- /inst/examples/url_with_percents.bib: -------------------------------------------------------------------------------- 1 | @article{urlWithPercents, 2 | title = {Dummy example of {URL} with percents}, 3 | volume = {51}, 4 | url = {https://github.com/GeoBosh/zzfiles/blob/master/url%20with%20percents.bib}, 5 | journal = {Example bibtex file}, 6 | author = {Boshnakov, Georgi N.}, 7 | year = {2018}, 8 | pages = {1--1} 9 | } 10 | -------------------------------------------------------------------------------- /inst/examples/journal_with_percents.bib: -------------------------------------------------------------------------------- 1 | @article{journalWithPercents, 2 | title = {Dummy example of {Journal} containing text with percents}, 3 | volume = {1}, 4 | journal = {Example bibtex file, 5 | https://github.com/GeoBosh/Rdpack/blob/master/inst/examples/journal%20with%20percents.bib}, 6 | author = {Boshnakov, Georgi N.}, 7 | year = {2018}, 8 | pages = {1--1} 9 | } 10 | -------------------------------------------------------------------------------- /inst/examples/RdpackTester/inst/auto/REFERENCES.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "REFERENCES" 3 | (lambda () 4 | (LaTeX-add-bibitems 5 | "Rpack:bibtex" 6 | "parseRd" 7 | "Rdevtools" 8 | "dummyArticle" 9 | "nadler_diffusion_2005" 10 | "cayton_robust_2006" 11 | "fukunaga_introduction_1990" 12 | "fukunaga_introduction_1990_fake_vol" 13 | "fukunaga_introduction_1990_fake_number" 14 | "fukunaga_introduction_1990_fake_vol_number")) 15 | :bibtex) 16 | 17 | -------------------------------------------------------------------------------- /inst/examples/RdpackTester/DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: RdpackTester 2 | Type: Package 3 | Title: Testbed for Rdpack 4 | Version: 1.0 5 | Date: 2018-09-22 6 | Author: Georgi N. Boshnakov 7 | Maintainer: 8 | Description: A lot of the functionality of package 'Rdpack' is best tested on a 9 | package. This package is part of 'Rdpack' and is used for that purpose. 10 | License: GPL (>=2) 11 | RdMacros: Rdpack 12 | NeedsCompilation: no 13 | Packaged: 2018-09-22 13:55:28 UTC; mcbssgb2 14 | -------------------------------------------------------------------------------- /tests/testthat/myshow-methods.Rd: -------------------------------------------------------------------------------- 1 | \name{myshow-methods} 2 | \docType{methods} 3 | \alias{myshow-methods} 4 | \alias{myshow,ANY-method} 5 | \alias{myshow,Seq-method} 6 | \title{~~ Dummy title ~~} 7 | \description{~~ Dummy description ~~} 8 | \section{Methods}{ 9 | \describe{ 10 | 11 | \item{\code{signature(object = "ANY")}}{ 12 | %% ~~describe this method here~~ 13 | } 14 | 15 | \item{\code{signature(object = "Seq")}}{ 16 | %% ~~describe this method here~~ 17 | } 18 | }} 19 | \keyword{methods} 20 | \keyword{ ~~ other possible keyword(s) ~~ } 21 | -------------------------------------------------------------------------------- /inst/CITATION: -------------------------------------------------------------------------------- 1 | citHeader("To cite the 'Rdpack' package in publications use:") 2 | 3 | 4 | year <- sub("-.*", "", meta$Date) 5 | vers = paste('R package version', meta$Version) 6 | 7 | bibentry(bibtype = "Misc", 8 | title = "{Rdpack}: Update and Manipulate Rd Documentation Objects", 9 | author = person(given = c("Georgi", "N."), family = "Boshnakov"), 10 | year = year, 11 | note = vers, 12 | doi = "10.5281/zenodo.3925612" 13 | #, url = "https://CRAN.R-project.org/package=Rdpack" 14 | ) 15 | -------------------------------------------------------------------------------- /TODO: -------------------------------------------------------------------------------- 1 | * (2024-11-09) do something with 'RdpackTester' (under inst/examples). 2 | I had forgotten about it but could add examples about issues and their fixing. 3 | Also, indicate somewhere to users how to use it to report bugs. 4 | Alternatively, make a repo where they can contribute. 5 | 6 | * vignette for reprompt/ereprompt/RStudio_reprompt 7 | 8 | * pcDst.Rd gives an error, it was produced by Roxygen. 9 | 10 | * escape percents in strings in usage sections, e.g. usage for f(dateformat = "%Y-%m-%d"), 11 | see also a related question on R-devel 12 | 13 | * reprompt("xxx-methods",...) to set the "doctype" field to "methods" 14 | -------------------------------------------------------------------------------- /man/inspect_slots.Rd: -------------------------------------------------------------------------------- 1 | \name{inspect_slots} 2 | 3 | \alias{inspect_slots} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Inspect the slots of an S4 class 9 | } 10 | 11 | \description{ 12 | Inspect the slots of an S4 class. 13 | } 14 | \usage{ 15 | inspect_slots(rdo, final = TRUE) 16 | } 17 | 18 | %- maybe also 'usage' for other objects documented here. 19 | \arguments{ 20 | \item{rdo}{an Rd object.} 21 | \item{final}{if not TRUE insert text with suggestions, otherwise 22 | comment the suggestions out. 23 | } 24 | } 25 | \author{Georgi N. Boshnakov} 26 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 27 | \keyword{RdoS4} 28 | 29 | -------------------------------------------------------------------------------- /man/update_aliases_tmp.Rd: -------------------------------------------------------------------------------- 1 | \name{update_aliases_tmp} 2 | 3 | \alias{update_aliases_tmp} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{Update aliases for methods in Rd objects} 8 | 9 | \description{Update aliases for methods in Rd objects} 10 | 11 | \usage{ 12 | update_aliases_tmp(rdo, package = NULL) 13 | } 14 | 15 | %- maybe also 'usage' for other objects documented here. 16 | 17 | \arguments{ 18 | \item{rdo}{an Rd object} 19 | \item{package}{the name of a package, a character string.} 20 | } 21 | 22 | \details{ 23 | This is a quick fix. todo: complete it! 24 | } 25 | 26 | \value{ 27 | the updated Rd object 28 | } 29 | 30 | 31 | 32 | \author{Georgi N. Boshnakov} 33 | 34 | 35 | 36 | 37 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 38 | 39 | 40 | 41 | 42 | 43 | 44 | % Add one or more standard keywords, see file 'KEYWORDS' in the 45 | 46 | % R documentation directory. 47 | 48 | \keyword{RdoS4} 49 | 50 | -------------------------------------------------------------------------------- /man/Rdo_remove_srcref.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_remove_srcref} 2 | \alias{Rdo_remove_srcref} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Remove srcref attributes from Rd objects} 5 | \description{Removes srcref attributes from Rd objects.} 6 | \usage{ 7 | Rdo_remove_srcref(rdo) 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{rdo}{an Rd object} 12 | } 13 | \details{ 14 | \code{srcref} attrbutes (set by \code{parse_Rd}) may be getting in the 15 | way during manipulation of Rd objects, such as comparisons, addition 16 | and replacement of elements. This function traverses the 17 | argument and removes the \code{srcref} attribute from all of its elements. 18 | } 19 | \value{ 20 | an Rd object with no srcref attributes. 21 | } 22 | 23 | \author{Georgi N. Boshnakov} 24 | 25 | 26 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 27 | 28 | 29 | % Add one or more standard keywords, see file 'KEYWORDS' in the 30 | % R documentation directory. 31 | \keyword{RdoProgramming} 32 | -------------------------------------------------------------------------------- /man/Rdo_flatinsert.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_flatinsert} 2 | \alias{Rdo_flatinsert} 3 | \alias{Rdo_flatremove} 4 | \title{Insert or remove content in an Rd fragment} 5 | \description{Insert or remove content in an Rd fragment.} 6 | \usage{ 7 | Rdo_flatinsert(rdo, val, pos, before = TRUE) 8 | 9 | Rdo_flatremove(rdo, from, to) 10 | } 11 | \arguments{ 12 | \item{rdo}{an Rd object.} 13 | \item{val}{the value to insert.} 14 | \item{pos}{position.} 15 | \item{before}{if TRUE, insert the new content at pos, pushing the 16 | element at pos forward. 17 | } 18 | \item{from}{beginning of the region to remove.} 19 | \item{to}{end of the region to remove.} 20 | } 21 | \details{ 22 | \code{Rdo_flatinsert} inserts \code{val} at position \code{pos}, 23 | effectively by concatenation. 24 | 25 | \code{Rdo_flatremove} removes elements from \code{from} to \code{to}. 26 | } 27 | \value{ 28 | the modified \code{rdo} 29 | } 30 | \author{Georgi N. Boshnakov} 31 | % \seealso{ 32 | % %% ~~objects to See Also as \code{\link{help}}, ~~~ 33 | % } 34 | %\examples{ 35 | %} 36 | \keyword{ RdoProgramming } 37 | -------------------------------------------------------------------------------- /R/alias.R: -------------------------------------------------------------------------------- 1 | # todo: are aliases updated for classes? 2 | 3 | update_aliases_tmp <- function(rdo, package = NULL){#only for methods, currently; only appends 4 | fname <- .get.name_content(rdo)$short # name of the generic 5 | 6 | rdoaliases <- toolsdotdotdot.Rd_get_metadata(rdo, "alias") # aliases currently in rdo 7 | 8 | curtxt <- get_sig_text(rdo, package = package) # process signatures described in rdo 9 | ucur <- parse_usage_text(curtxt) 10 | 11 | methaliases <- sapply(ucur, function(x) .methsig2alias(fname, x$defaults)) 12 | 13 | new_aliases <- methaliases[ !(methaliases %in% rdoaliases) ] 14 | if(length(new_aliases) > 0) # update the aliases 15 | for(alias in new_aliases){ 16 | rdo <- Rdo_insert(rdo, char2Rdpiece(alias, "alias")) 17 | } 18 | rdo 19 | } 20 | 21 | .methsig2alias <- function(name, sig){ 22 | res <- gsub("\"", "", paste(c(name, sig), collapse=",")) 23 | paste(res, "-method", sep="") # no comma after the last arg 24 | } 25 | -------------------------------------------------------------------------------- /man/set_Rdpack_bibstyle.Rd: -------------------------------------------------------------------------------- 1 | \name{set_Rdpack_bibstyle} 2 | \alias{set_Rdpack_bibstyle} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Set up a bibstyle defined in Rdpack} 5 | \description{Set up a bibstyle defined in Rdpack} 6 | \usage{ 7 | set_Rdpack_bibstyle(bibstyle = "JSSRd") 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{bibstyle}{a character string} 12 | } 13 | %\details{ 14 | %%% ~~ If necessary, more details than the description above ~~ 15 | %} 16 | %\value{ 17 | %%% ~Describe the value returned 18 | %%% If it is a LIST, use 19 | %%% \item{comp1 }{Description of 'comp1'} 20 | %%% \item{comp2 }{Description of 'comp2'} 21 | %%% ... 22 | %} 23 | %\references{ 24 | %%% ~put references to the literature/web site here ~ 25 | %} 26 | %\author{ 27 | %%% ~~who you are~~ 28 | %} 29 | %\note{ 30 | %%% ~~further notes~~ 31 | %} 32 | % 33 | %%% ~Make other sections like Warning with \section{Warning }{....} ~ 34 | % 35 | %\seealso{ 36 | %%% ~~objects to See Also as \code{\link{help}}, ~~~ 37 | %} 38 | %\examples{ 39 | %} 40 | \keyword{internal} 41 | -------------------------------------------------------------------------------- /man/Rdo_show.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_show} 2 | \alias{Rdo_show} 3 | \title{Convert an Rd object to text and show it} 4 | \description{Render an Rd object as text and show it.} 5 | \usage{ 6 | Rdo_show(rdo) 7 | } 8 | \arguments{ 9 | \item{rdo}{an Rd object} 10 | } 11 | \details{ 12 | 13 | \code{Rdo_show} renders the help page represented by \code{rdo} as 14 | text and shows it with \code{file.show()}. 15 | 16 | \code{Rdo_show} is a simplified front end to \code{utils::Rd2txt}. 17 | See \code{\link{viewRd}} for more complete rendering, including of 18 | references and citations. 19 | 20 | } 21 | \value{ 22 | Invisible \code{NULL}. 23 | The function is used for the side effect of showing the text 24 | representation of \code{rdo}. 25 | } 26 | \author{Georgi N. Boshnakov} 27 | \seealso{ 28 | \code{\link{viewRd}} 29 | } 30 | \examples{ 31 | ## create a minimal Rd object 32 | u1 <- list_Rd(name = "Dummyname", alias = "Dummyallias1", 33 | title = "Dummy title", description = "Dummy description", 34 | Rd_class = TRUE ) 35 | \dontrun{ 36 | ## run this interactively: 37 | Rdo_show(u1) 38 | } 39 | } 40 | \keyword{Rd} 41 | -------------------------------------------------------------------------------- /man/zzbsdup.Rd: -------------------------------------------------------------------------------- 1 | \name{.bsdup} 2 | 3 | \alias{.bsdup} 4 | \alias{.bspercent} 5 | \alias{.anypercent} 6 | 7 | %- Also NEED an '\alias' for EACH other topic documented here. 8 | 9 | \title{Escape backslashes and percent in Rd code} 10 | 11 | \description{Escape backslashes and percent in Rd code.} 12 | 13 | \usage{ 14 | 15 | .bspercent(x) 16 | 17 | .anypercent(x) 18 | } 19 | 20 | %- maybe also 'usage' for other objects documented here. 21 | 22 | \arguments{ 23 | \item{x}{a character string} 24 | } 25 | 26 | \details{ 27 | \code{.bsdup(x)} duplicates backslashes. 28 | 29 | \code{.bspercent(x)} escapes percent signs. 30 | 31 | \code{.anypercent(x)} also escapes percent signs but but only if the 32 | \code{Rd_tag} attribute of \code{x} is not COMMENT. 33 | 34 | } 35 | 36 | 37 | 38 | 39 | 40 | \author{Georgi N. Boshnakov} 41 | 42 | 43 | 44 | 45 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 46 | 47 | 48 | 49 | 50 | \examples{ 51 | ##---- Should be DIRECTLY executable !! ---- 52 | } 53 | 54 | % Add one or more standard keywords, see file 'KEYWORDS' in the 55 | 56 | % R documentation directory. 57 | 58 | \keyword{internal} 59 | -------------------------------------------------------------------------------- /inst/examples/tz.Rd: -------------------------------------------------------------------------------- 1 | \name{dummyfun} 2 | \alias{a1} 3 | \alias{a2} 4 | \alias{a3} 5 | #ifdef windows 6 | \alias{onlywin} 7 | #endif 8 | #ifdef unix 9 | \alias{onlyunix} 10 | #endif 11 | \title{Example in Rdpack} 12 | \description{Dummy description. 13 | Second sentence. 14 | } 15 | \usage{dummyfun(x, y, type, flag = FALSE)} 16 | \arguments{ 17 | \item{x}{Description of \code{x}} 18 | \item{y}{Description of \code{y}} 19 | \item{type}{Description of \code{type}} 20 | \item{flag}{Description of \code{flag}} 21 | } 22 | \details{Dummy details. 23 | More dummy details. 24 | 25 | #ifdef unix 26 | These are on unix. 27 | #endif 28 | #ifdef windows 29 | These are on windows. 30 | #endif 31 | } 32 | \value{A list with the following components: 33 | \item{res}{result, a number} 34 | \item{convergence}{numeric code indicating convergence.} 35 | } 36 | \section{Further information}{ 37 | This is a user defined section. 38 | } 39 | \examples{ 40 | dummyfun(1) 41 | #ifdef windows 42 | ## example on Windows 43 | #endif 44 | #ifdef unix 45 | \dontrun{ 46 | ## need to supply a suitable file path (if any) for your system 47 | ## example on unix 48 | } 49 | #endif 50 | } 51 | \keyword{kw1} 52 | \keyword{kw2} 53 | 54 | 55 | -------------------------------------------------------------------------------- /man/Rdo_is_newline.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_is_newline} 2 | 3 | \alias{Rdo_is_newline} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Check if an Rd fragment represents a newline character 9 | } 10 | 11 | \description{ 12 | Check if an Rd fragment represents a newline character 13 | } 14 | 15 | \usage{ 16 | Rdo_is_newline(rdo) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{rdo}{an Rd object} 23 | } 24 | 25 | \details{ 26 | This is a utility function that may be used to tidy up Rd objects. 27 | 28 | It returns TRUE if the Rd object represents a newline 29 | character, i.e. it is a character vector of length one containing the 30 | string \verb{"\n"}. Attributes are ignored. 31 | 32 | Otherwise it returns FALSE. 33 | } 34 | 35 | \value{ 36 | TRUE or FALSE 37 | } 38 | 39 | 40 | 41 | \author{Georgi N. Boshnakov} 42 | 43 | 44 | 45 | 46 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 47 | 48 | 49 | 50 | 51 | % Add one or more standard keywords, see file 'KEYWORDS' in the 52 | 53 | % R documentation directory. 54 | 55 | %\keyword{RdoProgramming} 56 | %\keyword{RdoElements} 57 | \keyword{RdoBuild} 58 | -------------------------------------------------------------------------------- /man/Rdo_modify_simple.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_modify_simple} 2 | 3 | \alias{Rdo_modify_simple} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{Simple modification of Rd objects} 8 | 9 | \description{Simple modification of Rd objects.} 10 | 11 | \usage{ 12 | Rdo_modify_simple(rdo, text, section, ...) 13 | } 14 | 15 | %- maybe also 'usage' for other objects documented here. 16 | 17 | \arguments{ 18 | \item{rdo}{an Rd object.} 19 | \item{text}{a character vector} 20 | \item{section}{name of an Rd section, a string.} 21 | \item{\dots}{additional arguments to be passed to \code{Rdo_modify}.} 22 | } 23 | 24 | \details{ 25 | 26 | Argument \code{text} is used to modify (as a replacement of or 27 | addition to) the content of section \code{section} of \code{rdo}. 28 | 29 | This function can be used for simple modifications of an Rd object 30 | using character content without converting it separately to Rd. 31 | 32 | \code{text} is converted to Rd with \code{char2Rdpiece(text, section)}. 33 | The result is passed to \code{Rdo_modify}, together with 34 | the remaining arguments. 35 | } 36 | 37 | \value{ 38 | an Rd object 39 | } 40 | \author{Georgi N. Boshnakov} 41 | \seealso{ 42 | \code{\link{Rdo_modify}} 43 | } 44 | 45 | \keyword{RdoBuild} 46 | -------------------------------------------------------------------------------- /man/Rdo_get_item_labels.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_get_item_labels} 2 | \alias{Rdo_get_item_labels} 3 | \title{Get the labels of items in an Rd object} 4 | \description{Get the labels of items in an Rd object.} 5 | \usage{ 6 | Rdo_get_item_labels(rdo) 7 | } 8 | \arguments{ 9 | \item{rdo}{an Rd object.} 10 | } 11 | \details{ 12 | 13 | \code{Rdo_get_item_labels(rdo)} gives the labels of all 14 | \code{"\item"}s in \code{rdo}. Argument \code{rdo} is often a section 15 | or other Rd object fragment, see the examples. 16 | 17 | } 18 | \value{ 19 | a character vector 20 | } 21 | \author{Georgi N. Boshnakov} 22 | \examples{ 23 | infile <- system.file("examples", "tz.Rd", package = "Rdpack") 24 | rd <- tools::parse_Rd(infile) 25 | 26 | ## get item labels found anywhere in the Rd object 27 | (items <- Rdo_get_item_labels(rd)) 28 | 29 | ## search only in section "arguments" (i.e., get argument names) 30 | ## (note [[1]] - there is only one arguments section) 31 | pos.args <- Rdo_locate_core_section(rd, "\\\\arguments")[[1]] 32 | (args <- Rdo_get_item_labels(rd[[pos.args$pos]])) 33 | 34 | ## search only in section "value" 35 | pos.val <- Rdo_locate_core_section(rd, "\\\\value")[[1]] 36 | (vals <- Rdo_get_item_labels(rd[[pos.val$pos]])) 37 | 38 | ## There are no other items in 'rd', so this gives TRUE: 39 | all.equal(items, c(args, vals)) # TRUE 40 | } 41 | \keyword{RdoProgramming} 42 | -------------------------------------------------------------------------------- /inst/examples/RdpackTester/man/RdpackTester-package.Rd: -------------------------------------------------------------------------------- 1 | \name{RdpackTester-package} 2 | \alias{RdpackTester-package} 3 | \alias{RdpackTester} 4 | \docType{package} 5 | \title{ 6 | \packageTitle{RdpackTester} 7 | } 8 | \description{ 9 | \packageDescription{RdpackTester} 10 | } 11 | \details{ 12 | 13 | The DESCRIPTION file: 14 | \packageDESCRIPTION{RdpackTester} 15 | %\packageIndices{RdpackTester} 16 | 17 | Some of the references here are non-existent or a modified to 18 | test/demonstrate features of the citation macros. 19 | 20 | \strong{Note:} Reference \insertCite{dummyArticle;textual}{Rdpack} 21 | does not exist. It is a test that simple math in BibTeX entries works. 22 | 23 | 24 | \insertCite{nadler_diffusion_2005}{Rdpack} 25 | \insertCite{cayton_robust_2006}{Rdpack} 26 | 27 | \insertCite{fukunaga_introduction_1990}{Rdpack} 28 | \insertCite{fukunaga_introduction_1990_fake_vol}{Rdpack} 29 | \insertCite{fukunaga_introduction_1990_fake_number}{Rdpack} 30 | \insertCite{fukunaga_introduction_1990_fake_vol_number}{Rdpack} 31 | 32 | } 33 | \author{ 34 | \packageAuthor{RdpackTester} 35 | 36 | Maintainer: \packageMaintainer{RdpackTester} 37 | } 38 | \references{ 39 | \insertAllCited{} 40 | 41 | --- 42 | 43 | Formulas are handled in fields were they make sense, here title, 44 | journal, note: 45 | 46 | \insertRef{dummyArticle}{Rdpack} 47 | 48 | 49 | } 50 | \keyword{ package } 51 | %\seealso{ 52 | %~~ \code{\link[:-package]{}} ~~ 53 | %} 54 | \examples{ 55 | test_1() 56 | } 57 | -------------------------------------------------------------------------------- /.github/workflows/pkgdown.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | release: 9 | types: [published] 10 | workflow_dispatch: 11 | 12 | name: pkgdown 13 | 14 | jobs: 15 | pkgdown: 16 | runs-on: ubuntu-latest 17 | # Only restrict concurrency for non-PR jobs 18 | concurrency: 19 | group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} 20 | env: 21 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 22 | permissions: 23 | contents: write 24 | steps: 25 | - uses: actions/checkout@v3 26 | 27 | - uses: r-lib/actions/setup-pandoc@v2 28 | 29 | - uses: r-lib/actions/setup-r@v2 30 | with: 31 | use-public-rspm: true 32 | 33 | - uses: r-lib/actions/setup-r-dependencies@v2 34 | with: 35 | extra-packages: any::pkgdown, local::. 36 | needs: website 37 | 38 | - name: Build site 39 | run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) 40 | shell: Rscript {0} 41 | 42 | - name: Deploy to GitHub pages 🚀 43 | if: github.event_name != 'pull_request' 44 | uses: JamesIves/github-pages-deploy-action@v4.4.1 45 | with: 46 | clean: false 47 | branch: gh-pages 48 | folder: docs 49 | -------------------------------------------------------------------------------- /man/RStudio_reprompt.Rd: -------------------------------------------------------------------------------- 1 | \name{RStudio_reprompt} 2 | \alias{RStudio_reprompt} 3 | \title{Call reprompt based on RStudio editor contents} 4 | \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 5 | is highlighted in a \file{.R} file, on that object.} 6 | \usage{ 7 | RStudio_reprompt(verbose = TRUE) 8 | } 9 | \arguments{ 10 | \item{verbose}{ 11 | If \code{TRUE} print progress to console. 12 | } 13 | } 14 | \details{ 15 | This function depends on being run in RStudio; it will generate 16 | an error if run in other contexts. 17 | 18 | It depends on code being in a package that has already been 19 | built, installed, and attached. In RStudio, this means you 20 | should run \dQuote{Install and Restart} before running this 21 | function. 22 | 23 | It is automatically installed into RStudio as an add-in called 24 | \dQuote{Reprompt}. Whether invoked directly or through the 25 | add-in, it looks at the file currently being edited in the 26 | code editor. If it is an \file{.Rd} file, it will run 27 | \code{\link{reprompt}} on that file. 28 | 29 | If it is an \R source file, it will look for a selected object 30 | name. It queries the help system to find if there is already 31 | a help page for that name, and if so, works on that. If not, 32 | it will try to create one. 33 | } 34 | \value{ 35 | \code{NULL}, invisibly. 36 | } 37 | \author{ 38 | Duncan Murdoch 39 | } 40 | \seealso{ 41 | \code{\link{reprompt}}, \code{\link{ereprompt}}, \code{\link{prompt}} 42 | } 43 | -------------------------------------------------------------------------------- /man/Rdo_get_argument_names.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_get_argument_names} 2 | \alias{Rdo_get_argument_names} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Get the names of arguments in usage sections of Rd objects} 5 | \description{Get the names of arguments in usage sections of Rd objects.} 6 | \usage{ 7 | Rdo_get_argument_names(rdo) 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{rdo}{an Rdo object.} 12 | } 13 | \details{ 14 | 15 | All arguments names in the "arguments" section of \code{rdo} are 16 | extracted. If there is no such section, the results is a character 17 | vector of length zero. 18 | 19 | Arguments which have different descriptions for different OS'es 20 | are included and not duplicated. 21 | 22 | Arguments which have descriptions for a particular OS are included, 23 | irrespectively of the OS of the running R process. 24 | (\strong{todo:} introduce argument to control this?) 25 | 26 | } 27 | \value{ 28 | a character vector 29 | } 30 | % \references{ 31 | % %% ~put references to the literature/web site here ~ 32 | % } 33 | \author{Georgi N. Boshnakov} 34 | % \note{ 35 | % %% ~~further notes~~ 36 | % } 37 | % 38 | % %% ~Make other sections like Warning with \section{Warning }{....} ~ 39 | % 40 | \seealso{ 41 | \code{\link{Rdo_get_item_labels}} 42 | } 43 | \examples{ 44 | ##---- Should be DIRECTLY executable !! ---- 45 | } 46 | % Add one or more standard keywords, see file 'KEYWORDS' in the 47 | % R documentation directory. 48 | %\keyword{ ~kwd1 } 49 | 50 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: Rdpack 2 | Type: Package 3 | Title: Update and Manipulate Rd Documentation Objects 4 | Version: 2.6.4.9000 5 | Authors@R: c( person(given = c("Georgi", "N."), 6 | family = "Boshnakov", 7 | role = c("aut", "cre"), 8 | email = "georgi.boshnakov@manchester.ac.uk", 9 | comment = c(ORCID = "0000-0003-2839-346X")), 10 | person(given = "Duncan", 11 | family = "Murdoch", 12 | role = "ctb", email = "murdoch.duncan@gmail.com") ) 13 | Description: Functions for manipulation of R documentation objects, 14 | including functions reprompt() and ereprompt() for updating 'Rd' 15 | documentation for functions, methods and classes; 'Rd' macros for 16 | citations and import of references from 'bibtex' files for use in 17 | 'Rd' files and 'roxygen2' comments; 'Rd' macros for evaluating and 18 | inserting snippets of 'R' code and the results of its evaluation or 19 | creating graphics on the fly; and many functions for manipulation of 20 | references and Rd files. 21 | URL: https://geobosh.github.io/Rdpack/ (doc), https://github.com/GeoBosh/Rdpack (devel) 22 | BugReports: https://github.com/GeoBosh/Rdpack/issues 23 | Depends: 24 | R (>= 2.15.0), 25 | methods 26 | Imports: 27 | tools, 28 | utils, 29 | rbibutils (>= 1.3) 30 | Suggests: 31 | grDevices, 32 | testthat, 33 | rstudioapi, 34 | rprojroot, 35 | gbRd 36 | License: GPL (>= 2) 37 | LazyLoad: yes 38 | RoxygenNote: 7.1.1 39 | -------------------------------------------------------------------------------- /man/viewRd.Rd: -------------------------------------------------------------------------------- 1 | \name{viewRd} 2 | \alias{viewRd} 3 | \title{View Rd files in a source package} 4 | \description{View Rd files in a source package.} 5 | \usage{ 6 | viewRd(infile, type = getOption("help_type"), stages = NULL) 7 | } 8 | \arguments{ 9 | \item{infile}{name of an Rd file, a character string.} 10 | \item{type}{one of \code{"text"} or \code{"html"}} 11 | \item{stages}{ 12 | a character vector specifying which stages of the R installation 13 | process to immitate. The default, 14 | \code{c("build", "install", "render")}, should be fine in most cases. 15 | } 16 | } 17 | \details{ 18 | 19 | This function can be used to view Rd files from the source directory 20 | of a package. The page is presented in text format or in html browser, 21 | according to the setting of argument \code{type}. The default is 22 | \code{getOption("help_type")}. 23 | 24 | } 25 | \value{ 26 | the function is used for the side effect of showing the help page in a 27 | text help window or a web browser. 28 | } 29 | %\references{ 30 | %%% ~put references to the literature/web site here ~ 31 | %} 32 | \author{Georgi N. Boshnakov} 33 | \note{ 34 | 35 | Developers with \code{"devtools"} can use \code{viewRd()} instead of 36 | \code{help()} for documentation objects that contain Rd macros, such 37 | as \code{insertRef}, see vignette: 38 | 39 | \code{vignette("Inserting_bibtex_references", package = "Rdpack")}. 40 | 41 | } 42 | %\seealso{ 43 | %%% ~~objects to See Also as \code{\link{help}}, ~~~ 44 | %} 45 | %\examples{ 46 | %} 47 | \keyword{documentation} 48 | % use one of RShowDoc("KEYWORDS") 49 | -------------------------------------------------------------------------------- /man/Rdo_insert.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_insert} 2 | 3 | \alias{Rdo_insert} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Insert a new element in an Rd object possibly surrounding it with new 9 | lines 10 | } 11 | 12 | \description{ 13 | Insert a new element in an Rd object possibly surrounding it with new 14 | lines. 15 | } 16 | 17 | \usage{ 18 | Rdo_insert(rdo, val, newline = TRUE) 19 | } 20 | 21 | %- maybe also 'usage' for other objects documented here. 22 | 23 | \arguments{ 24 | \item{rdo}{an Rd object} 25 | \item{val}{the content to insert, an Rd object.} 26 | \item{newline}{a logical value, controls the insertion of new lines 27 | before and after \code{val}, see `Details'. 28 | } 29 | } 30 | 31 | \details{ 32 | 33 | Argument \code{val} is inserted in \code{rdo} at an appropriate 34 | position, see \code{\link{Rdo_get_insert_pos}} for detailed 35 | explanation. 36 | 37 | If \code{newline} is TRUE, newline elements are inserted before and 38 | after \code{val} but only if they are not already there. 39 | 40 | Typically, \code{val} is a section of an Rd object and \code{rdo} is 41 | an Rd object which is being constructed or modified. 42 | 43 | } 44 | 45 | \value{ 46 | an Rd object 47 | } 48 | 49 | 50 | 51 | \author{Georgi N. Boshnakov} 52 | 53 | 54 | 55 | 56 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 57 | 58 | 59 | 60 | 61 | % Add one or more standard keywords, see file 'KEYWORDS' in the 62 | 63 | % R documentation directory. 64 | 65 | %\keyword{RdoProgramming} 66 | %\keyword{RdoElements} 67 | \keyword{RdoBuild} 68 | -------------------------------------------------------------------------------- /man/Rdo_insert_element.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_insert_element} 2 | 3 | \alias{Rdo_insert_element} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Insert a new element in an Rd object 9 | } 10 | 11 | \description{ 12 | Insert a new element at a given position in an Rd object. 13 | } 14 | 15 | \usage{ 16 | Rdo_insert_element(rdo, val, pos) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{rdo}{an Rd object} 23 | \item{val}{the content to insert.} 24 | \item{pos}{position at which to insert \code{val}, typically an integer 25 | but may be anything accepted by the operator "[[". 26 | } 27 | } 28 | 29 | \details{ 30 | \code{val} is inserted at position \code{pos}, between the elements at 31 | positions \code{pos-1} and \code{pos}. If \code{pos} is equal to 1, 32 | \code{val} is prepended to \code{rdo}. If \code{pos} is missing or 33 | equal to the length of \code{rdo}, \code{val} is appended to 34 | \code{rdo}. 35 | 36 | todo: allow vector \code{pos} to insert deeper into the object. 37 | 38 | todo: character \code{pos} to insert at a position specified by "tag" for example? 39 | 40 | todo: more guarded copying of attributes? 41 | } 42 | 43 | \value{ 44 | an Rd object 45 | } 46 | 47 | 48 | 49 | \author{Georgi N. Boshnakov} 50 | 51 | 52 | 53 | 54 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 55 | 56 | 57 | 58 | 59 | % Add one or more standard keywords, see file 'KEYWORDS' in the 60 | 61 | % R documentation directory. 62 | 63 | %\keyword{RdoProgramming} 64 | %\keyword{RdoElements} 65 | \keyword{RdoBuild} 66 | -------------------------------------------------------------------------------- /man/ereprompt.Rd: -------------------------------------------------------------------------------- 1 | \name{ereprompt} 2 | \alias{ereprompt} 3 | \title{Update an Rd file and open it in an editor} 4 | \description{ 5 | Update an Rd file and open it in an editor. This is a wrapper for 6 | reprompt with different defaults for some parameters. 7 | } 8 | \usage{ 9 | ereprompt(..., edit = TRUE, filename = TRUE) 10 | } 11 | \arguments{ 12 | 13 | \item{\dots}{ 14 | passed on to \code{\link{reprompt}}, see its documentation for 15 | details.} 16 | \item{edit}{if \code{TRUE}, the default, open an editor when finished.} 17 | \item{filename}{if \code{TRUE}, the default, replace and/or edit the 18 | original Rd file.} 19 | } 20 | \details{ 21 | 22 | \code{ereprompt} calls \code{reprompt} to do the actual job but has 23 | different defaults for the arguments described on this page. By 24 | default, it replaces the original Rd file with the updated 25 | documentation and opens it in an editor. 26 | 27 | } 28 | \value{ 29 | called for the side effect of updating Rd documentation file and 30 | opening it in an editor 31 | } 32 | %\references{ 33 | %%% ~put references to the literature/web site here ~ 34 | %} 35 | \author{Georgi N. Boshnakov} 36 | %\note{ 37 | %%% ~~further notes~~ 38 | %} 39 | % 40 | %%% ~Make other sections like Warning with \section{Warning }{....} ~ 41 | % 42 | \seealso{ 43 | \code{\link{reprompt}} which does the actual work 44 | } 45 | \examples{ 46 | ## this assumes that the current working directory is 47 | ## in any subdirectory of the development directory of Rdpack 48 | \dontrun{ 49 | ereprompt(infile = "reprompt.Rd") 50 | } 51 | } 52 | \keyword{documentation} 53 | % use one of RShowDoc("KEYWORDS") 54 | -------------------------------------------------------------------------------- /man/Rd_combo.Rd: -------------------------------------------------------------------------------- 1 | \name{Rd_combo} 2 | 3 | \alias{Rd_combo} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{Manipulate a number of Rd files} 8 | 9 | \description{Manipulate a number of Rd files.} 10 | 11 | \usage{ 12 | Rd_combo(rd, f, ..., .MORE) 13 | } 14 | 15 | %- maybe also 'usage' for other objects documented here. 16 | 17 | \arguments{ 18 | \item{rd}{names of Rd files, a character vector.} 19 | \item{f}{function to apply, see Details.} 20 | \item{\dots}{further arguments to pass on to \code{f}.} 21 | \item{.MORE}{another function to be applied for each file to the 22 | result of \code{f}.} 23 | } 24 | 25 | \details{ 26 | 27 | \code{Rd_combo} parses each file in \code{rd}, applies \code{f} to the 28 | Rd object, and applies the function \code{.MORE} (if supplied) on the 29 | results of \code{f}. 30 | 31 | A typical value for \code{.MORE} is \code{reprompt} or another 32 | function that saves the resulting Rd object. 33 | 34 | todo: \code{Rd_combo} is already useful but needs further work. 35 | } 36 | 37 | 38 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 39 | 40 | 41 | 42 | 43 | \examples{ 44 | \dontrun{ 45 | rdnames <- dir(path = "./man", pattern=".*[.]Rd$", full.names=TRUE) 46 | 47 | ## which Rd files don't have a value section? 48 | counts <- unlist(Rd_combo(rdnames, function(x) length(Rdo_locate_core_section(x, "\\value")))) 49 | rdnames[counts == 0] 50 | 51 | ## reprompt all files 52 | Rd_combo(rdnames, reprompt) 53 | for(nam in rdnames) try(reprompt(nam)) 54 | for(nam in rdnames) try(reprompt(nam, sec_copy=FALSE)) 55 | } 56 | } 57 | \keyword{Rd} 58 | %\keyword{Rdprocessing} 59 | -------------------------------------------------------------------------------- /man/parse_usage_text.Rd: -------------------------------------------------------------------------------- 1 | \name{parse_usage_text} 2 | \alias{parse_usage_text} 3 | \alias{parse_1usage_text} 4 | \title{ 5 | Parse usage text 6 | } 7 | \description{ 8 | Parse usage text. 9 | } 10 | \usage{ 11 | parse_1usage_text(text) 12 | parse_usage_text(text) 13 | } 14 | \arguments{ 15 | \item{text}{ 16 | conceptually, the content of the usage section of one or more Rd objects, a 17 | character vector, see Details. 18 | } 19 | } 20 | \details{ 21 | 22 | For \code{parse_usage_text}, \code{text} is a character vector 23 | representing the contents of the usage section of an Rdo object. 24 | \code{parse_usage_text} does some preprocessing of \code{text} then 25 | calls \code{parse_1usage_text} for each usage statement. 26 | 27 | The preprocessing changes "\verb{\\}\verb{dots}" to "\verb{...}" and 28 | converts S3- and S4-method descriptions to a form suitable for 29 | \code{parse()}. The text is then parsed (with \code{parse}) and 30 | "\verb{srcref}" attribute removed from the parsed object. 31 | 32 | todo: currently no checks is made for Rd comments in \code{text}. 33 | 34 | \code{parse_1usage_text} processes the usage statement of one object 35 | and calls \code{\link{pairlist2f_usage1}} to convert it to an object 36 | from S3 class \code{"f_usage"}. 37 | 38 | } 39 | 40 | \value{ 41 | 42 | for \code{parse_1usage_text}, an object from S3 class 43 | \code{"f_usage"}, see \code{\link{pairlist2f_usage1}} for its 44 | structure. 45 | 46 | for \code{parse_usage_text}, a list containing one element for each 47 | usage entry, as prepared by \code{parse_1usage_text} 48 | 49 | } 50 | \author{Georgi N. Boshnakov} 51 | \keyword{RdoUsage} 52 | -------------------------------------------------------------------------------- /man/Rdo_tags.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_tags} 2 | \alias{Rdo_tags} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Give the Rd tags at the top level of an Rd object} 5 | \description{Give the Rd tags at the top level of an Rd object.} 6 | \usage{ 7 | Rdo_tags(rdo, nulltag = "") 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{rdo}{an Rd object.} 12 | \item{nulltag}{a value to use when \code{Rd_tag} is missing or NULL.} 13 | } 14 | \details{ 15 | 16 | The \verb{"Rd_tag"} attributes of the top level elements of \code{rdo} are 17 | collected in a character vector. Argument \code{nulltag} is used for 18 | elements without that attribute. This guarantees that the result is a 19 | character vector. 20 | 21 | \code{Rdo_tags} is similar to the internal function 22 | \code{tools:::RdTags}. Note that \code{tools:::RdTags} may return a 23 | list in the rare cases when attribute \code{Rd_tags} is not present in 24 | all elements of \code{rdo}. 25 | 26 | %% ~~ If necessary, more details than the description above ~~ 27 | } 28 | \value{ 29 | a character vector 30 | } 31 | % \references{ 32 | % %% ~put references to the literature/web site here ~ 33 | % } 34 | \author{Georgi N. Boshnakov} 35 | % \note{ 36 | % %% ~~further notes~~ 37 | % } 38 | 39 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 40 | 41 | \seealso{ 42 | \code{\link{Rdo_which}}, 43 | \code{\link{Rdo_which_tag_eq}}, 44 | \code{\link{Rdo_which_tag_in}} 45 | %% ~~objects to See Also as \code{\link{help}}, ~~~ 46 | } 47 | \examples{ 48 | ##---- Should be DIRECTLY executable !! ---- 49 | } 50 | \keyword{Rd} 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | -------------------------------------------------------------------------------- /man/Rdo_piecetag.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_piecetag} 2 | 3 | \alias{Rdo_piecetag} 4 | \alias{Rdo_sectype} 5 | \alias{is_Rdsecname} 6 | 7 | %- Also NEED an '\alias' for EACH other topic documented here. 8 | 9 | \title{ 10 | Give information about Rd elements 11 | } 12 | 13 | \description{ 14 | Give information about Rd elements. 15 | } 16 | 17 | \usage{ 18 | Rdo_piecetag(name) 19 | 20 | Rdo_sectype(x) 21 | 22 | is_Rdsecname(name) 23 | } 24 | 25 | %- maybe also 'usage' for other objects documented here. 26 | 27 | \arguments{ 28 | \item{name}{the name of an Rd macro, a string.} 29 | \item{x}{the name of an Rd macro, a string.} 30 | } 31 | 32 | \details{ 33 | \code{Rdo_piecetag} gives the "Rd_tag" of the Rd macro \code{name}. 34 | 35 | \code{Rdo_sectype} gives the "Rd_tag" of the Rd section \code{x}. 36 | 37 | \code{is_Rdsecname(name)} returns TRUE if \code{name} is the name of a 38 | top level Rd section. 39 | 40 | The information returned by these functions is obtained from the 41 | charater vectors \code{Rdo_piece_types} and 42 | \code{Rdo_predefined_sections}. 43 | } 44 | 45 | 46 | 47 | 48 | 49 | \author{Georgi N. Boshnakov} 50 | 51 | 52 | 53 | 54 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 55 | 56 | 57 | \seealso{ 58 | \code{\link{Rdo_piece_types}} and 59 | \code{\link{Rdo_predefined_sections}} 60 | } 61 | 62 | \examples{ 63 | Rdo_piecetag("eqn") # ==> "VERB" 64 | Rdo_piecetag("code") # ==> "RCODE" 65 | 66 | Rdo_sectype("usage") # ==> "RCODE" 67 | Rdo_sectype("title") # ==> "TEXT" 68 | 69 | Rdo_sectype("arguments") 70 | } 71 | 72 | % Add one or more standard keywords, see file 'KEYWORDS' in the 73 | 74 | % R documentation directory. 75 | 76 | \keyword{RdoProgramming} 77 | -------------------------------------------------------------------------------- /man/inspect_usage.Rd: -------------------------------------------------------------------------------- 1 | \name{inspect_usage} 2 | 3 | \alias{inspect_usage} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Inspect the usage section in an Rd object 9 | } 10 | 11 | \description{ 12 | Inspect the usage section in an Rd object. 13 | } 14 | 15 | \usage{ 16 | inspect_usage(rdo) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{rdo}{an Rd object.} 23 | } 24 | 25 | \details{ 26 | The usage section in the Rd object, \code{rdo}, is extracted and 27 | parsed. The usage of each function described in \code{rdo} is 28 | obtained also from the actual installed function and compared to the 29 | one from \code{rdo}. 30 | 31 | The return value is a list, with one element for each function usage 32 | as returned by \code{compare_usage1}. 33 | 34 | One of the consequences of this is that an easy way to add a usage 35 | description of a function, say \code{fu} to an existing Rd file is to 36 | simply add a line \code{fu()} to the usage section of that file and 37 | run \code{reprompt} on it. 38 | } 39 | 40 | \value{ 41 | a list of comparison results as described in `Details' 42 | (todo: give more details here) 43 | } 44 | 45 | 46 | 47 | \author{Georgi N. Boshnakov} 48 | 49 | 50 | 51 | 52 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 53 | 54 | \seealso{ 55 | \code{\link{inspect_args}} 56 | } 57 | 58 | 59 | % \examples{ 60 | % ##---- Should be DIRECTLY executable !! ---- 61 | % } 62 | 63 | % Add one or more standard keywords, see file 'KEYWORDS' in the 64 | 65 | % R documentation directory. 66 | 67 | %\keyword{ ~kwd1 } 68 | \keyword{RdoUsage} 69 | %\keyword{RdFunction} 70 | -------------------------------------------------------------------------------- /man/S4formals.Rd: -------------------------------------------------------------------------------- 1 | \name{S4formals} 2 | \alias{S4formals} 3 | \title{Give the formal arguments of an S4 method} 4 | \description{Give the formal arguments of an S4 method.} 5 | \usage{ 6 | S4formals(fun, \dots) 7 | } 8 | \arguments{ 9 | \item{fun}{name of an S4 generic, a string, or the method, see Details.} 10 | \item{\dots}{further arguments to be passed to \code{getMethod}, see 11 | Details.} 12 | } 13 | \details{ 14 | \code{S4formals} gives the formal arguments of the requested method. 15 | If \code{fun} is not of class \code{methodDefinition}, it calls 16 | \code{getMethods}, passing on all arguments. 17 | 18 | Typically, \code{fun} is the name of a generic function and the 19 | second argument is the signature of the method as a character 20 | vector. Alternatively, \code{fun} may be the method itself (e.g. obtained 21 | previously from \code{getMethod}) and in that case the \verb{"\dots"} 22 | arguments are ignored. See \code{\link{getMethod}} for full details 23 | and other acceptable arguments. 24 | 25 | } 26 | \value{ 27 | a pairlist, like \code{\link{formals}} 28 | } 29 | \note{ 30 | Arguments of a method after those used for dispatch may be different from 31 | the arguments of the generic. The latter may simply have a \verb{"\dots"} 32 | argument there. 33 | 34 | todo: there should be a similar function in the "methods" package, or 35 | at least use a documented feature to extract it. 36 | } 37 | \author{ 38 | Georgi N. Boshnakov 39 | } 40 | \examples{ 41 | require(stats4) # makes plot() S4 generic 42 | 43 | S4formals("plot", c(x = "profile.mle", y = "missing")) 44 | 45 | m1 <- getMethod("plot", c(x = "profile.mle", y = "missing")) 46 | S4formals(m1) 47 | } 48 | \keyword{methods} 49 | -------------------------------------------------------------------------------- /tests/testthat/as.character.f_usage.Rd: -------------------------------------------------------------------------------- 1 | \name{as.character.f_usage} 2 | \alias{as.character.f_usage} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{~~ Dummy title ~~} 5 | \description{~~ Dummy description ~~} 6 | \usage{ 7 | as.character.f_usage(x, ...) 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{x}{ 12 | %% ~~Describe \code{x} here~~ 13 | } 14 | \item{\dots}{ 15 | %% ~~Describe \code{\dots} here~~ 16 | } 17 | } 18 | \details{ 19 | %% ~~ If necessary, more details than the description above ~~ 20 | } 21 | \value{ 22 | %% ~Describe the value returned 23 | %% If it is a LIST, use 24 | %% \item{comp1 }{Description of 'comp1'} 25 | %% \item{comp2 }{Description of 'comp2'} 26 | %% ... 27 | } 28 | \references{ 29 | %% ~put references to the literature/web site here ~ 30 | } 31 | \author{ 32 | %% ~~who you are~~ 33 | } 34 | \note{ 35 | %% ~~further notes~~ 36 | } 37 | 38 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 39 | 40 | \seealso{ 41 | %% ~~objects to See Also as \code{\link{help}}, ~~~ 42 | } 43 | \examples{ 44 | ##---- Should be DIRECTLY executable !! ---- 45 | ##-- ==> Define data, use random, 46 | ##-- or standard data sets, see data(). 47 | 48 | ## The function is currently defined as 49 | function (x, ...) 50 | { 51 | deparse_usage1(x) 52 | } 53 | } 54 | % Add one or more standard keywords, see file 'KEYWORDS' in the 55 | % R documentation directory (show via RShowDoc("KEYWORDS")): 56 | % \keyword{ ~kwd1 } 57 | % \keyword{ ~kwd2 } 58 | % Use only one keyword per line. 59 | % For non-standard keywords, use \concept instead of \keyword: 60 | % \concept{ ~cpt1 } 61 | % \concept{ ~cpt2 } 62 | % Use only one concept per line. 63 | -------------------------------------------------------------------------------- /man/parse_Rdname.Rd: -------------------------------------------------------------------------------- 1 | \name{parse_Rdname} 2 | 3 | \alias{parse_Rdname} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Parse the name section of an Rd object 9 | } 10 | \description{ 11 | Parse the name section of an Rd object. 12 | } 13 | 14 | \usage{ 15 | parse_Rdname(rdo) 16 | } 17 | 18 | %- maybe also 'usage' for other objects documented here. 19 | 20 | \arguments{ 21 | \item{rdo}{an Rd object} 22 | } 23 | 24 | \details{ 25 | The content of section "\verb{\name}" is extracted. If it contains a 26 | hyphen, `-', the part before the hyphen is taken to be the topic 27 | (usually a function name), while the part after the hyphen is the 28 | type. If the name does not contain hyphens, the type is set to the 29 | empty string. } 30 | 31 | \value{ 32 | a list with two components: 33 | \item{fname}{name of the topic, usually a function} 34 | \item{type}{type of the topic, such as \verb{"method"}} 35 | } 36 | 37 | 38 | 39 | \author{Georgi N. Boshnakov} 40 | 41 | 42 | 43 | 44 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 45 | 46 | 47 | 48 | 49 | \examples{ 50 | u1 <- list_Rd(name = "Dummyname", alias = "Dummyallias1", 51 | title = "Dummy title", description = "Dummy description", 52 | Rd_class=TRUE ) 53 | 54 | parse_Rdname(u1) 55 | 56 | u2 <- list_Rd(name = "dummyclass-class", alias = "Dummyclass", 57 | title = "Class dummyclass", 58 | description = "Objects and methods for something.", 59 | Rd_class=TRUE ) 60 | 61 | parse_Rdname(u2) 62 | } 63 | 64 | % Add one or more standard keywords, see file 'KEYWORDS' in the 65 | 66 | % R documentation directory. 67 | 68 | \keyword{RdoProgramming} 69 | -------------------------------------------------------------------------------- /man/Rdo_get_insert_pos.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_get_insert_pos} 2 | \alias{Rdo_get_insert_pos} 3 | \title{ 4 | Find the position of an "Rd_tag" 5 | } 6 | \description{ 7 | Find the position of an "Rd_tag". 8 | } 9 | \usage{ 10 | Rdo_get_insert_pos(rdo, tag) 11 | } 12 | \arguments{ 13 | \item{rdo}{an Rd object} 14 | \item{tag}{the "Rd_tag" to search for, a string} 15 | } 16 | \details{ 17 | 18 | This function returns a position in \code{rdo}, where the next element 19 | carrying "Rd_tag" \code{tag} should be inserted. The position is 20 | determined as follows. 21 | 22 | If one or more elements of \code{rdo} have "Rd_tag" \code{tag}, then 23 | the position is one plus the position of the last such element. 24 | 25 | If there are no elements with "Rd_tag" \code{tag}, the position is one 26 | plus the length of \code{rdo}, unless \code{tag} is a known top level 27 | Rd section. In that case, the position is such that the standard 28 | ordering of sections in an Rd object is followed. This is set in the 29 | internal variable \code{.rd_sections}. 30 | } 31 | \value{ 32 | an integer 33 | } 34 | \author{Georgi N. Boshnakov} 35 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 36 | \examples{ 37 | #h <- help("Rdo_macro") 38 | #rdo <- utils:::.getHelpFile(h) 39 | rdo <- Rdo_fetch("Rdo_macro", "Rdpack") 40 | 41 | ialias <- which(tools:::RdTags(rdo) == "\\\\alias") 42 | ialias 43 | next_pos <- Rdo_get_insert_pos(rdo, "\\\\alias") # 1 + max(ialias) 44 | next_pos 45 | stopifnot(next_pos == max(ialias) + 1) 46 | 47 | ikeyword <- which(tools:::RdTags(rdo) == "\\\\keyword") 48 | ikeyword 49 | next_pos <- Rdo_get_insert_pos(rdo, "\\\\keyword") # 1 + max(ikeyword) 50 | next_pos 51 | stopifnot(next_pos == max(ikeyword) + 1) 52 | } 53 | \keyword{RdoProgramming} 54 | -------------------------------------------------------------------------------- /man/Rdo_locate_leaves.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_locate_leaves} 2 | \alias{Rdo_locate_leaves} 3 | \title{Find leaves of an Rd object using a predicate} 4 | \description{Apply a function to the character leaves of an Rd object 5 | and return the indices of those for which the result is TRUE.} 6 | \usage{ 7 | Rdo_locate_leaves(object, f = function(x) TRUE) 8 | } 9 | \arguments{ 10 | \item{object}{the object to be examined, usually a list.} 11 | \item{f}{a function (predicate) returning TRUE for elements with the 12 | desired property. 13 | } 14 | } 15 | \details{ 16 | \code{object} can be any list whose elements are character strings or 17 | lists. The structure is examined recursively. If \code{object} is a 18 | character vector, it is enclosed in a list. 19 | 20 | This function provides a convenient way to locate leaves of an Rd 21 | object with a particular content. The function is not limited to Rd 22 | objects but it assumes that the elements of \code{object} are either 23 | lists or charater vectors and currently does not check if this is the 24 | case. 25 | 26 | \strong{todo:} describe the case of \code{list()} (\code{Rd_tag}'ed.) 27 | } 28 | \value{ 29 | a list of the positions of the leaves for which the predicate gives 30 | \code{TRUE}. Each position is an integer vector suitable for the 31 | \code{"[["} operator. 32 | } 33 | 34 | \author{Georgi N. Boshnakov} 35 | 36 | \examples{ 37 | dummyfun <- function(x) x 38 | 39 | fn <- tempfile("dummyfun", fileext = "Rd") 40 | reprompt(dummyfun, filename = fn) 41 | rdo <- tools::parse_Rd(fn) 42 | 43 | f <- function(x) Rdo_is_newline(x) 44 | 45 | nl <- Rdo_locate_leaves(rdo, f ) 46 | 47 | length(nl) # there are quite a few newline leaves! 48 | 49 | unlink(fn) 50 | } 51 | %\keyword{Rdlookup} 52 | \keyword{Rd} 53 | -------------------------------------------------------------------------------- /man/Rdo_tag.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_tag} 2 | 3 | \alias{Rdo_comment} 4 | \alias{Rdo_verb} 5 | \alias{Rdo_Rcode} 6 | \alias{Rdo_text} 7 | \alias{Rdo_tag} 8 | \alias{Rdo_newline} 9 | 10 | %- Also NEED an '\alias' for EACH other topic documented here. 11 | 12 | \title{ 13 | Set the Rd_tag of an object 14 | } 15 | \description{ 16 | Set the Rd_tag of an object. 17 | } 18 | \usage{ 19 | Rdo_comment(x = "\%\%") 20 | 21 | Rdo_tag(x, name) 22 | 23 | Rdo_verb(x) 24 | 25 | Rdo_Rcode(x) 26 | 27 | Rdo_text(x) 28 | 29 | Rdo_newline() 30 | } 31 | 32 | %- maybe also 'usage' for other objects documented here. 33 | 34 | \arguments{ 35 | \item{x}{an object, appropriate for the requested Rd_tag.} 36 | \item{name}{the tag name, a string.} 37 | } 38 | 39 | \details{ 40 | These functions simply set attribute "\verb{Rd_tag}" of \code{x}, effectively 41 | assuming that the caller has prepared it as needed. 42 | 43 | \code{Rdo_tag} sets the "\verb{Rd_tag}" attribute of \code{x} to \code{name}. 44 | The other functions are shorthands with a fixed name and no second 45 | argument. 46 | 47 | \code{Rdo_comment} tags an Rd element as comment. 48 | 49 | \code{Rdo_newline} gives an Rd element representing an empty line. 50 | } 51 | 52 | \value{ 53 | \code{x} with its "\verb{Rd_tag}" set to 54 | \code{name} (\code{Rdo_tag}), 55 | "TEXT" (\code{Rdo_text}), 56 | "VERB" (\code{Rdo_verb}) or 57 | "RCODE" (\code{Rdo_Rcode}). 58 | } 59 | 60 | 61 | 62 | \author{Georgi N. Boshnakov} 63 | 64 | 65 | 66 | 67 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 68 | 69 | 70 | 71 | 72 | % Add one or more standard keywords, see file 'KEYWORDS' in the 73 | 74 | % R documentation directory. 75 | 76 | %\keyword{RdoProgramming} 77 | %\keyword{RdoElements} 78 | \keyword{RdoBuild} 79 | -------------------------------------------------------------------------------- /man/get_usage_text.Rd: -------------------------------------------------------------------------------- 1 | \name{get_usage_text} 2 | 3 | \alias{get_usage_text} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Get the text of the usage section of Rd documentation 9 | } 10 | 11 | \description{ 12 | Get the text of the usage section of Rd documentation. 13 | } 14 | 15 | \usage{ 16 | get_usage_text(rdo) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{rdo}{an Rd object or a character string} 23 | } 24 | 25 | \details{ 26 | If \code{rdo} is a string, it is parsed to obtain an Rd object. 27 | 28 | The content of section "\verb{\usage}" is extracted and converted to string. 29 | } 30 | 31 | \value{ 32 | a string 33 | } 34 | 35 | 36 | 37 | \author{Georgi N. Boshnakov} 38 | 39 | \note{ 40 | todo: \code{get_usage_text} can be generalised to any Rd section but it is 41 | better to use a different approach since \code{print.Rd()} does not 42 | take care for some details (escaping \%, for example). Also, the 43 | functions that use this one assume that it returns \R code, which 44 | may not be the case if the usage section contains Rd comments. 45 | } 46 | 47 | 48 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 49 | 50 | 51 | 52 | 53 | \examples{ 54 | ## get the Rd object documenting Rdo_macro 55 | #h <- utils::help("Rdo_macro", lib.loc = .libPaths()) 56 | #rdo <- utils:::.getHelpFile(h) 57 | rdo <- Rdo_fetch("Rdo_macro", "Rdpack") 58 | # extract the usage section and print it: 59 | ut <- get_usage_text(rdo) 60 | cat(ut, sep = "\n") 61 | } 62 | 63 | % Add one or more standard keywords, see file 'KEYWORDS' in the 64 | 65 | % R documentation directory. 66 | 67 | %\keyword{RdoProgramming} 68 | \keyword{RdoUsage} 69 | %\keyword{RdFunction} 70 | -------------------------------------------------------------------------------- /man/Rdo_reparse.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_reparse} 2 | \alias{Rdo_reparse} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Reparse an Rd object} 5 | \description{Reparse an Rd object.} 6 | \usage{ 7 | Rdo_reparse(rdo) 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{rdo}{an Rd object} 12 | } 13 | \details{ 14 | \code{Rdo_reparse} saves \code{rdo} to a temporary file and parses it 15 | with \code{parse_Rd}. This ensures that the Rd object is a "canonical" 16 | one, since one and the same Rd file can be produced by different (but 17 | equivalent) Rd objects. 18 | 19 | Also, the functions in this package do not attend to attribute 20 | "srcref" (and do not use it) and reparsing takes care of this. 21 | (todo: check if there is a problem if the tempfile disappears.) 22 | 23 | %insertCite{@see @parseRd,@Rpack:bibtex}{Rdpack} % only for testing! 24 | 25 | \insertCite{parseRd,Rpack:bibtex}{Rdpack} % only for testing! 26 | } 27 | \references{ 28 | \insertAllCited{} % only for testing 29 | } 30 | 31 | 32 | 33 | 34 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 35 | 36 | 37 | \examples{ 38 | # the following creates Rd object rdo 39 | dummyfun <- function(x) x 40 | fn <- tempfile("dummyfun", fileext = "Rd") 41 | 42 | reprompt(dummyfun, filename = fn) 43 | rdo <- tools::parse_Rd(fn) 44 | 45 | dottext <- "further arguments to be passed on." 46 | 47 | dots <- paste0("\\\\", "dots") 48 | rdo2 <- Rdo_append_argument(rdo, dots, dottext, create = TRUE) 49 | rdo2 <- Rdo_append_argument(rdo2, "z", "a numeric vector") 50 | 51 | Rdo_show(Rdo_reparse(rdo2)) 52 | 53 | # the following does ot show the arguments. (todo: why?) 54 | # (see also examples in Rdo_append_argument) 55 | Rdo_show(rdo2) 56 | 57 | unlink(fn) 58 | } 59 | \keyword{Rd} 60 | -------------------------------------------------------------------------------- /man/Rdo_empty_sections.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_empty_sections} 2 | 3 | \alias{Rdo_empty_sections} 4 | \alias{Rdo_drop_empty} 5 | 6 | %- Also NEED an '\alias' for EACH other topic documented here. 7 | 8 | \title{Find or remove empty sections in Rd objects} 9 | 10 | \description{Find or remove empty sections in Rd objects} 11 | 12 | \usage{ 13 | Rdo_empty_sections(rdo, with_bs = FALSE) 14 | 15 | Rdo_drop_empty(rdo, sec = TRUE) 16 | } 17 | 18 | %- maybe also 'usage' for other objects documented here. 19 | 20 | \arguments{ 21 | \item{rdo}{an Rd object or Rd source text.} 22 | \item{with_bs}{if \code{TRUE} return the section names with the 23 | leading backslash.} 24 | \item{sec}{not used} 25 | } 26 | \details{ 27 | The function \code{checkRd} is used to determine which sections are 28 | empty. 29 | } 30 | 31 | \value{ 32 | For \code{Rdo_empty_sections}, the names of the empty sections as a 33 | character vector. 34 | 35 | For \code{Rdo_drop_empty}, the Rd object stripped from empty 36 | sections. 37 | } 38 | 39 | 40 | 41 | \author{Georgi N. Boshnakov} 42 | 43 | 44 | 45 | 46 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 47 | 48 | 49 | 50 | 51 | \examples{ 52 | dummyfun <- function(x) x 53 | rdo8 <- list_Rd(name = "Dummyname", alias = "dummyfun", 54 | title = "Dummy title", description = "Dummy description", 55 | usage = "dummyfun(x,y)", 56 | value = "numeric vector", 57 | author = "", 58 | details = "", 59 | note = "", 60 | Rd_class=TRUE ) 61 | 62 | Rdo_empty_sections(rdo8) # "details" "note" "author" 63 | 64 | rdo8a <- Rdo_drop_empty(rdo8) 65 | Rdo_empty_sections(rdo8a) # character(0) 66 | } 67 | 68 | % Add one or more standard keywords, see file 'KEYWORDS' in the 69 | 70 | % R documentation directory. 71 | 72 | %\keyword{Rdprocessing} 73 | \keyword{RdoBuild} 74 | 75 | -------------------------------------------------------------------------------- /man/Rdo_append_argument.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_append_argument} 2 | \alias{Rdo_append_argument} 3 | \title{ 4 | Append an item for a new argument to an Rd object 5 | } 6 | \description{ 7 | Append an item for a new argument to an Rd object. 8 | } 9 | \usage{ 10 | Rdo_append_argument(rdo, argname, description = NA, indent = " ", create = FALSE) 11 | } 12 | \arguments{ 13 | \item{rdo}{an Rd object.} 14 | \item{argname}{name of the argument, a character vector.} 15 | \item{description}{description of the argument, a character vector.} 16 | \item{indent}{a string, typically whitespace.} 17 | \item{create}{not used (todo: remove?)} 18 | } 19 | \details{ 20 | Appends one or more items to the section describing arguments of 21 | functions in an Rd object. The section is created if not present. 22 | 23 | If \code{description} is missing or NA, a "todo" text is inserted. 24 | 25 | The inserted text is indented using the string \code{indent}. 26 | 27 | The lengths of \code{argname} and \code{description} should normally 28 | be equal but if \code{description} is of length one, it is repeated to 29 | achieve this when needed. 30 | } 31 | \value{ 32 | an Rd object 33 | } 34 | \author{Georgi N. Boshnakov} 35 | \examples{ 36 | ## the following creates Rd object rdo 37 | dummyfun <- function(x) x 38 | fn <- tempfile("dummyfun", fileext = ".Rd") 39 | reprompt(dummyfun, filename = fn) 40 | rdo <- tools::parse_Rd(fn) 41 | 42 | ## add documentation for arguments 43 | ## that are not in the signature of 'dummyfun()' 44 | dottext <- "further arguments to be passed on." 45 | dots <- paste0("\\\\", "dots") 46 | rdo2 <- Rdo_append_argument(rdo, dots, dottext, create = TRUE) 47 | rdo2 <- Rdo_append_argument(rdo2, "z", "a numeric vector") 48 | 49 | ## reprompt() warns to remove documentation for non-existing arguments: 50 | Rdo_show(reprompt(rdo2, filename = fn)) 51 | 52 | unlink(fn) 53 | } 54 | \keyword{RdoBuild} 55 | %\keyword{RdoElements} 56 | 57 | -------------------------------------------------------------------------------- /man/parse_text.Rd: -------------------------------------------------------------------------------- 1 | \name{parse_text} 2 | \alias{parse_text} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Parse expressions residing in character vectors} 5 | \description{Parse expressions residing in character vectors.} 6 | \usage{ 7 | parse_text(text, ..., keep = TRUE) 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{text}{the text to parse, normally a character vector but can be 12 | anything that \code{parse} accepts for this artgument.} 13 | \item{\dots}{additional arguments to be passed on to \code{parse}.} 14 | \item{keep}{required setting for option \verb{keep.source}, see 15 | details.} 16 | } 17 | \details{ 18 | This is like \code{parse(text=text,\dots)} with the additional feature 19 | that if the setting of option "keep.source" is not as requested by 20 | argument \code{keep}, it is set to \code{keep} before calling 21 | \code{parse} and restored afterwards. 22 | 23 | This function is no longer exported by \pkg{Rdpack} since it is here 24 | for historical reasons and to avoid unnecessary dependence on 25 | \pkg{gbutils}. Use the equivalent \code{gbutils::parse_text} instead. 26 | 27 | } 28 | \value{ 29 | an expression representing the parsed text, see \code{link{parse}} for 30 | details 31 | } 32 | \author{Georgi N. Boshnakov} 33 | \note{ 34 | The usual setting of option "keep.source" in interactive sessions is 35 | TRUE. However, in `R CMD check' it is FALSE. 36 | 37 | As a consequence, examples from the documentation may run fine when 38 | copied and pasted in an R session but (rightly) fail `R CMD check', 39 | when they depend on option "keep.source" being \code{TRUE}. 40 | 41 | } 42 | 43 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 44 | 45 | \seealso{ 46 | \code{\link{parse}}, 47 | \code{parse_text} in package gbutils 48 | } 49 | \keyword{programming} 50 | \keyword{internal} 51 | -------------------------------------------------------------------------------- /man/rdo_text_restore.Rd: -------------------------------------------------------------------------------- 1 | \name{rdo_text_restore} 2 | \alias{rdo_text_restore} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Ensure exported fragments of Rd are as the original} 5 | \description{ 6 | 7 | For an Rd object imported from a file, this function ensures that 8 | fragments that were not not changed during the editing of the object 9 | remain unchanged in the exported file. This function is used by 10 | reprompt() to ensure exactly that. 11 | 12 | } 13 | \usage{ 14 | rdo_text_restore(cur, orig, pos_list, file) 15 | } 16 | %- maybe also 'usage' for other objects documented here. 17 | \arguments{ 18 | \item{cur}{an Rd object} 19 | \item{orig}{an Rd object} 20 | \item{pos_list}{a list of srcref objects specifying portions of files 21 | to replace, see 'Details'.} 22 | \item{file}{a file name, essentially a text representation of 23 | \verb{cur}.} 24 | } 25 | \details{ 26 | 27 | This is essentially internal function. It exists because, in general, 28 | it is not possible to restore the original Rd file from the Rd object 29 | due to the specifications of the Rd format. The file exported from 30 | the parsed Rd file is functionally equivalent to the original but 31 | equivalent things for the computer are not necessarily equally 32 | pleasant for humans. 33 | 34 | This function is used by \code{reprompt} when the source is from a 35 | file and the option to keep the source of unchanged sections as in the 36 | original. 37 | 38 | \strong{todo:} needs clean up, there are unnecessary arguments in 39 | particular. 40 | 41 | } 42 | \value{ 43 | the main result is the side effect of replacing sections in 44 | \code{file} not changed by \code{reprompt} with the original ones. 45 | } 46 | \author{ 47 | Georgi N. Boshnakov 48 | } 49 | 50 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 51 | 52 | \seealso{ 53 | \code{\link{reprompt}} 54 | } 55 | \keyword{RdoProgramming} 56 | -------------------------------------------------------------------------------- /man/inspect_args.Rd: -------------------------------------------------------------------------------- 1 | \name{inspect_args} 2 | 3 | \alias{inspect_args} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Inspect the argument section of an Rd object 9 | } 10 | 11 | \description{ 12 | Inspect the argument section of an Rd object. 13 | } 14 | 15 | \usage{ 16 | inspect_args(rdo, i_usage) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{rdo}{an Rd object describing functions.} 23 | \item{i_usage}{see Details.} 24 | } 25 | 26 | \details{ 27 | \code{inspect_args} checks if the arguments in the documentation 28 | object \code{rdo} match the (union of) the actual arguments of the 29 | functions it describes. 30 | 31 | If \code{i_usage} is missing, it is computed by inspecting the current 32 | definitions of the functions described in \code{rdo}, see 33 | \code{inspect_usage}. This argument is likely to be supplied if the 34 | function calling \code{inspect_args} has already computed it for other 35 | purposes. 36 | } 37 | 38 | 39 | \value{ 40 | TRUE if the arguments in the documentation match the (union of) the 41 | actual arguments of the described functions, FALSE otherwise. 42 | 43 | The returned logical value has attribute `details' which is a list 44 | with the following components. 45 | 46 | \item{rdo_argnames}{arguments described in the documentation object, \code{rdo}.} 47 | \item{cur_argnames}{arguments in the current definitions of the 48 | described functions.} 49 | \item{added_argnames}{new arguments} 50 | \item{removed_argnames}{removed (dropped) arguments.} 51 | } 52 | 53 | 54 | 55 | \author{Georgi N. Boshnakov} 56 | 57 | 58 | 59 | 60 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 61 | 62 | 63 | 64 | 65 | 66 | 67 | % Add one or more standard keywords, see file 'KEYWORDS' in the 68 | 69 | % R documentation directory. 70 | 71 | %\keyword{RdoProgramming} 72 | \keyword{RdoUsage} 73 | %\keyword{RdFunction} 74 | -------------------------------------------------------------------------------- /man/zzasym_compare.Rd: -------------------------------------------------------------------------------- 1 | \name{.asym_compare} 2 | 3 | \alias{.asym_compare} 4 | \alias{.ocompare} 5 | 6 | %- Also NEED an '\alias' for EACH other topic documented here. 7 | 8 | \title{Tensor comparison and asymmetric comparison between two vectors} 9 | 10 | \description{Tensor comparison and asymmetric comparison between two 11 | vectors.} 12 | 13 | \usage{ 14 | .ocompare(x, y) 15 | 16 | .asym_compare(x, y) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{x}{ 23 | %% ~~Describe \code{x} here~~ 24 | } 25 | \item{y}{ 26 | %% ~~Describe \code{y} here~~ 27 | } 28 | } 29 | 30 | \details{ 31 | \code{.ocompare} (for "outer compare") returns a matrix whose (i,j)th 32 | element is TRUE if x[i] is identical to y[j], and FALSE otherwise. 33 | 34 | \code{.asym_compare} calls \code{.ocompare} and iterprets its result 35 | asymmetrically. Elements of \code{x} that are not in \code{y} ae 36 | considered "new". Similarly, Elements of \code{y} that are not in 37 | \code{x} ae considered "removed". Elements that are in both are 38 | "common". 39 | 40 | Todo: check if the above is correct or the other way round! !!! 41 | 42 | } 43 | 44 | \value{ 45 | For \code{.ocompare}, a matrix as described in Details. 46 | 47 | For \code{.asym_compare} a list with indices as follows. 48 | \item{i_new}{new elements, indices in \code{x} of elements that are not 49 | in \code{y}.} 50 | \item{i_removed}{removed elements, indices in \code{y} of elements that are not 51 | in \code{x}.} 52 | \item{i_common}{common elements, indices in \code{x} of elements that 53 | are in both, \code{x} and \code{y}.} 54 | } 55 | 56 | 57 | 58 | \author{Georgi N. Boshnakov} 59 | 60 | 61 | 62 | 63 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 64 | 65 | 66 | 67 | 68 | \examples{ 69 | ##---- Should be DIRECTLY executable !! ---- 70 | } 71 | 72 | % Add one or more standard keywords, see file 'KEYWORDS' in the 73 | 74 | % R documentation directory. 75 | 76 | \keyword{internal} 77 | -------------------------------------------------------------------------------- /man/inspect_signatures.Rd: -------------------------------------------------------------------------------- 1 | \name{inspect_signatures} 2 | 3 | \alias{inspect_signatures} 4 | \alias{inspect_clmethods} 5 | 6 | %- Also NEED an '\alias' for EACH other topic documented here. 7 | 8 | \title{ 9 | Inspect signatures of S4 methods 10 | } 11 | 12 | \description{ 13 | Inspect signatures of S4 methods. 14 | } 15 | \usage{ 16 | inspect_clmethods(rdo, final = TRUE) 17 | 18 | inspect_signatures(rdo, package = NULL, sec = "Methods") 19 | } 20 | 21 | %- maybe also 'usage' for other objects documented here. 22 | 23 | \arguments{ 24 | \item{rdo}{an Rd object.} 25 | \item{package}{the name of a package, a character string or NULL.} 26 | \item{sec}{the name of a section to look into, a character string.} 27 | \item{final}{If not TRUE insert text with suggestions, otherwise 28 | comment the suggestions out. 29 | } 30 | } 31 | 32 | \details{ 33 | 34 | Signatures in documentation of S4 classes and methods are stored 35 | somewhat differently. \code{inspect_signatures} inspects signatures in 36 | documentation of methods of a function. \code{inspect_clmethods} 37 | inspects signatures in documentation of a class. 38 | 39 | \code{inspect_signatures} was written before 40 | \code{inspect_clmethods()} and was geared towards using existing code 41 | for ordinary functions (mainly \code{parse_usage_text()}. 42 | 43 | If new methods are found, the functions add entries for them in the Rd 44 | object \code{rdo}. 45 | 46 | If \code{rdo} documents methods that do not exist, a message inviting 47 | the user to remove them manually is printed but the offending entries 48 | remain in the object. 49 | At the time of writing, \verb{R CMD check} does not warn about this. 50 | 51 | } 52 | 53 | \value{ 54 | an Rd object 55 | } 56 | 57 | \note{todo: need consolidation.} 58 | 59 | \author{Georgi N. Boshnakov} 60 | 61 | 62 | 63 | 64 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 65 | 66 | 67 | 68 | 69 | 70 | 71 | % Add one or more standard keywords, see file 'KEYWORDS' in the 72 | 73 | % R documentation directory. 74 | 75 | \keyword{RdoS4} 76 | -------------------------------------------------------------------------------- /R/RStudio.R: -------------------------------------------------------------------------------- 1 | # In RStudio, call reprompt on function that cursor is pointing to. 2 | 3 | RStudio_reprompt <- function(verbose = TRUE) { 4 | 5 | if (!requireNamespace("rstudioapi") || !requireNamespace("rprojroot")) 6 | stop("RStudio support requires you to install the 'rprojroot' and 'rstudioapi' packages") 7 | 8 | sourceContext <- rstudioapi::getSourceEditorContext() 9 | infile <- sourceContext$path 10 | 11 | if(length(infile) == 0) 12 | stop("Nothing to do. See ?Rdpack::RStudio_reprompt for information about this add-in.") 13 | 14 | if (grepl("[.][rR]d$", infile)) # editing a help file 15 | reprompt(infile = infile, filename = infile, verbose = verbose) 16 | 17 | else if (grepl("[.][rRsSq]$", infile)) { # editing R source 18 | pkgdir <- rprojroot::find_package_root_file(path = dirname(infile)) 19 | pkg <- basename(pkgdir) 20 | 21 | if (length(sourceContext$selection) == 1) { 22 | fnname <- sourceContext$selection[[1]]$text 23 | } else 24 | fnname <- "" 25 | if (!nchar(fnname)) 26 | stop("Select a function name") 27 | 28 | if (!exists(fnname)) 29 | stop("Object ", sQuote(fnname), " not found. Run 'Install and Restart'?") 30 | 31 | existing <- help(fnname) 32 | ## Subset to the ones in the current package 33 | existing <- existing[basename(dirname(dirname(existing))) == pkg] 34 | 35 | if (length(existing) == 1) { 36 | infile <- file.path(pkgdir, "man", paste0(basename(existing), ".Rd")) 37 | reprompt(infile = infile, filename = infile, verbose = verbose) 38 | } else if (!length(existing)) 39 | infile <- reprompt(fnname, 40 | filename = file.path(pkgdir, "man", paste0(fnname, ".Rd")), 41 | verbose = verbose) 42 | else 43 | stop("Multiple matches to ", sQuote(fnname), ". Open one help file manually.") 44 | } else 45 | stop("This tool only works on .Rd or .R files.") 46 | 47 | rstudioapi::navigateToFile(infile) 48 | } 49 | -------------------------------------------------------------------------------- /man/list_Rd.Rd: -------------------------------------------------------------------------------- 1 | \name{list_Rd} 2 | \alias{list_Rd} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Combine Rd fragments} 5 | \description{Combine Rd fragments and strings into one object.} 6 | \usage{ 7 | list_Rd(..., Rd_tag = NULL, Rd_class = FALSE) 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{\dots}{named list of objects to combine, see `Details'.} 12 | \item{Rd_tag}{if non-null, a value for the \verb{Rd_tag} of the result.} 13 | \item{Rd_class}{logical; if TRUE, the result will be of class "Rd".} 14 | } 15 | \details{ 16 | 17 | The names of named arguments specify tags for the corresponding 18 | elements (not arbitrary tags, ones that are converted to macro names 19 | by prepending backslash to them). This is a convenient way to specify 20 | sections, items, etc, in cases when the arguments have not being 21 | tagged by previous processing. Character string arguments are 22 | converted to the appropriate Rd pieces. 23 | 24 | Argument \code{...} may contain a mixture of character vactors and Rd 25 | pieces. 26 | } 27 | \value{ 28 | an Rd object or list with \verb{Rd_tag} attribute, as specified by the 29 | arguments. 30 | } 31 | 32 | \author{Georgi N. Boshnakov} 33 | 34 | 35 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 36 | 37 | \seealso{ 38 | \code{\link{c_Rd}} 39 | } 40 | \examples{ 41 | ## see also the examples for c_Rd 42 | 43 | dummyfun <- function(x, ...) x 44 | 45 | u1 <- list_Rd(name = "Dummyname", alias = "dummyfun", 46 | title = "Dummy title", description = "Dummy description", 47 | usage = "dummyfun(x)", 48 | value = "numeric vector", 49 | author = "A. Author", 50 | Rd_class=TRUE ) 51 | Rdo_show(u1) 52 | 53 | # call reprompt to fill the arguments section (and correct the usage) 54 | fn <- tempfile("dummyfun", fileext = "Rd") 55 | reprompt(dummyfun, filename = fn) 56 | 57 | # check that the result can be parsed and show it. 58 | Rdo_show(tools::parse_Rd(fn)) 59 | 60 | unlink(fn) 61 | } 62 | \keyword{RdoBuild} 63 | 64 | -------------------------------------------------------------------------------- /inst/REFERENCES.bib: -------------------------------------------------------------------------------- 1 | @Manual{Rpack:bibtex, 2 | author = {Romain Francois}, 3 | title = {bibtex: bibtex parser}, 4 | year = {2014}, 5 | note = {R package version 0.4.0}, 6 | } 7 | 8 | @Manual{Rpackage:rbibutils, 9 | title = {rbibutils: Convert Between Bibliography Formats}, 10 | author = {Georgi N. Boshnakov and Chris Putman}, 11 | year = {2020}, 12 | url = {https://CRAN.R-project.org/package=rbibutils}, 13 | } 14 | 15 | @misc{parseRd, 16 | author = {Duncan Murdoch}, 17 | title = {Parsing Rd files}, 18 | year = {2010}, 19 | url = {https://developer.r-project.org/parseRd.pdf}, 20 | } 21 | 22 | 23 | @Manual{Rdevtools, 24 | author = {Hadley Wickham and Jim Hester and Winston Chang}, 25 | title = {devtools: Tools to Make Developing R Packages Easier}, 26 | year = {2018}, 27 | note = {R package version 1.13.5}, 28 | url = {https://CRAN.R-project.org/package=devtools}, 29 | } 30 | 31 | @Article{dummyArticle, 32 | author = {A. ZZZ}, 33 | title = {A relation between several fundamental constants: $e^{i\pi}=-1$; 34 | Also, a test that slash is fine: Something\slash Something}, 35 | journal = {A non-existent journal with the formula $L_2$ in its name \& an ampersand 36 | which is preceded by a backslash in the bib file.}, 37 | year = {2018}, 38 | note = {This reference does not exist. It is a test/demo that simple formulas in BibTeX 39 | files are OK. A formula in field 'note': $c^2 = a^2 + b^2$. 40 | }, 41 | } 42 | 43 | 44 | 45 | 46 | % The entries below are temporary for testing. 47 | 48 | % for issue #25 49 | @article{DiaLop2020ejor, 50 | author = { Juan Esteban Diaz and Manuel L{\'o}pez-Ib{\'a}{\~n}ez }, 51 | title = {Incorporating Decision-Maker's Preferences into the Automatic 52 | Configuration of Bi-Objective Optimisation Algorithms}, 53 | journal = {European Journal of Operational Research}, 54 | year = 2021, 55 | volume = 289, 56 | number = 3, 57 | pages = {1209--1222}, 58 | doi = {10.1016/j.ejor.2020.07.059}, 59 | } 60 | -------------------------------------------------------------------------------- /.github/workflows/check-standard-tex.yaml: -------------------------------------------------------------------------------- 1 | ## Georgi: 2 | ## (1) amended with instructions to setup tinytex, 3 | ## see https://github.com/r-lib/actions/tree/v2/run-rchk 4 | ## 5 | ## (2) build with --compact-vignettes=gs+qpdf, syntax copied from 6 | ## https://github.com/aursiber/nlstools/commit/869cc47fa43a2ded10a079c3af0edf5694bd6a95 7 | 8 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 9 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 10 | on: 11 | push: 12 | branches: [main, master] 13 | pull_request: 14 | branches: [main, master] 15 | 16 | name: R-CMD-check 17 | 18 | jobs: 19 | R-CMD-check: 20 | runs-on: ${{ matrix.config.os }} 21 | 22 | name: ${{ matrix.config.os }} (${{ matrix.config.r }}) 23 | 24 | strategy: 25 | fail-fast: false 26 | matrix: 27 | config: 28 | - {os: macos-latest, r: 'release'} 29 | - {os: windows-latest, r: 'release'} 30 | - {os: ubuntu-latest, r: 'devel', http-user-agent: 'release'} 31 | - {os: ubuntu-latest, r: 'release'} 32 | # - {os: ubuntu-latest, r: 'oldrel-1'} 33 | 34 | env: 35 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 36 | R_KEEP_PKG_SOURCE: yes 37 | 38 | steps: 39 | - uses: actions/checkout@v3 40 | 41 | 42 | - uses: r-lib/actions/setup-tinytex@v2 43 | - run: tlmgr --version 44 | 45 | - name: Install additional LaTeX packages 46 | run: | 47 | tlmgr install titlesec 48 | tlmgr list --only-installed 49 | 50 | 51 | - uses: r-lib/actions/setup-pandoc@v2 52 | 53 | - uses: r-lib/actions/setup-r@v2 54 | with: 55 | r-version: ${{ matrix.config.r }} 56 | http-user-agent: ${{ matrix.config.http-user-agent }} 57 | use-public-rspm: true 58 | 59 | - uses: r-lib/actions/setup-r-dependencies@v2 60 | with: 61 | extra-packages: any::rcmdcheck 62 | needs: check 63 | 64 | - uses: r-lib/actions/check-r-package@v2 65 | with: 66 | build_args: 'c("--compact-vignettes=gs+qpdf")' 67 | upload-snapshots: true 68 | -------------------------------------------------------------------------------- /man/Rdreplace_section.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdreplace_section} 2 | \alias{Rdreplace_section} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{ Replace the contents of a section in one or more Rd files} 5 | \description{Replace the contents of a section in one or more Rd files.} 6 | \usage{ 7 | Rdreplace_section(text, sec, pattern, path = "./man", exclude = NULL, ...) 8 | } 9 | %- maybe also 'usage' for other objects documented here. 10 | \arguments{ 11 | \item{text}{the replacement text, a character string.} 12 | \item{sec}{the name of the section without the leading backslash, as 13 | for \code{Rdo_set_section}.} 14 | \item{pattern}{regular expression for R files to process, see 15 | Details.} 16 | \item{path}{the directory were to look for the Rd files.} 17 | \item{exclude}{regular expression for R files to exclude, see 18 | Details.} 19 | \item{\dots}{not used.} 20 | } 21 | \details{ 22 | 23 | \code{Rdreplace_section} looks in the directory specified by 24 | \code{path} for files whose names match \code{pat} and drops those 25 | whose names match \code{exclude}. Then it replaces section \code{sec} 26 | in the files selected in this way. 27 | 28 | \code{Rdreplace_section} is a convenience function to replace a 29 | section (such as a keyword or author) in several files in one go. 30 | It calls \code{\link{Rdo_set_section}} to do the work. 31 | } 32 | \value{ 33 | A vector giving the full names of the processed Rd files, but the 34 | function is used for the side effect of modifying them as described in 35 | section Details. 36 | } 37 | % \references{ 38 | % %% ~put references to the literature/web site here ~ 39 | % } 40 | \author{ 41 | Georgi N. Boshnakov 42 | } 43 | % \note{ 44 | % %% ~~further notes~~ 45 | % } 46 | % 47 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 48 | 49 | \seealso{ 50 | \code{\link{Rdo_set_section}} 51 | } 52 | \examples{ 53 | \dontrun{ 54 | # replace the author in all Rd files except pkgname-package 55 | Rdreplace_section("A. Author", "author", ".*[.]Rd$", exclude = "-package[.]Rd$") 56 | } 57 | } 58 | % Add one or more standard keywords, see file 'KEYWORDS' in the 59 | % R documentation directory. 60 | \keyword{RdoBuild} 61 | 62 | 63 | -------------------------------------------------------------------------------- /man/parse_Rdtext.Rd: -------------------------------------------------------------------------------- 1 | \name{parse_Rdtext} 2 | 3 | \alias{parse_Rdtext} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Parse Rd source text as the contents of a section 9 | } 10 | 11 | \description{ 12 | Parse Rd source text as the contents of a given section. 13 | } 14 | 15 | \usage{ 16 | parse_Rdtext(text, section = NA) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{text}{Rd source text, a character vector.} 23 | \item{section}{the section name, a string.} 24 | } 25 | 26 | \details{ 27 | 28 | If \code{section} is given, then \code{parse_Rdtext} parses 29 | \code{text} as appropriate for the content of section \code{section}. 30 | This is achieved by inserting \code{text} as an argument to the TeX 31 | macro \code{section}. For example, if \code{section} is 32 | "\verb{\usage}", then a line "\verb{\usage\{}" is inserted at the 33 | begiinning of \code{text} and a closing "\verb{\}}" at its end. 34 | 35 | If \code{section} is NA then \code{parse_Rdtext} parses it without 36 | preprocessing. In this case \code{text} itself will normally be 37 | a complete section fragment. 38 | } 39 | 40 | \value{ 41 | an Rd fragment 42 | } 43 | 44 | 45 | 46 | \author{Georgi N. Boshnakov} 47 | 48 | \note{ 49 | The text is saved to a temporary file and parsed using 50 | \code{parse_Rd}. This is done for at least two reasons. Firstly, 51 | \code{parse_Rd} works most reliably (at the time of writing this) 52 | from a file. Secondly, the saved file may be slightly different 53 | (escaped backslashes being the primary example). 54 | It would be a nightmare to ensure that all concerned functions know 55 | if some Rd text is read from a file or not. 56 | 57 | The (currently internal) function \code{.parse_Rdlines} takes a 58 | character vector, writes it to a file (using \code{cat}) and calls 59 | \code{parse_Rd} to parse it. 60 | } 61 | 62 | 63 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 64 | 65 | 66 | \seealso{ 67 | \code{\link{parse_Rdpiece}} 68 | } 69 | 70 | % Add one or more standard keywords, see file 'KEYWORDS' in the 71 | 72 | % R documentation directory. 73 | 74 | \keyword{RdoProgramming} 75 | -------------------------------------------------------------------------------- /man/Rdpack_bibstyles.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdpack_bibstyles} 2 | \alias{Rdpack_bibstyles} 3 | 4 | \title{Set up a custom style for references in help pages} 5 | 6 | \description{Set up a custom style for references in help pages.} 7 | 8 | \usage{ 9 | Rdpack_bibstyles(package, authors) 10 | } 11 | 12 | \arguments{ 13 | \item{package}{the name of a package, a character string.} 14 | \item{authors}{if equal to "LongNames", use full names of authors in 15 | reference lists, see Details.} 16 | } 17 | 18 | \details{ 19 | 20 | This is the initial implementation of support for styles for lists of 21 | bibliography references. 22 | 23 | Currently setting \code{authors} to \code{"LongNames"} will cause the 24 | references to appear with full names, eg John Smith rather than in the 25 | default Smith J style. 26 | 27 | Package authors can request this feature by adding the following line 28 | to their \code{.onLoad} function (if their package has one): 29 | \preformatted{ 30 | Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames") 31 | } 32 | of just copy the following definition in a package that does not have 33 | \code{.onLoad} : 34 | \preformatted{ 35 | .onLoad <- function(lib, pkg){ 36 | Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames") 37 | invisible(NULL) 38 | } 39 | } 40 | After building and installing the package the references should be 41 | using long names. 42 | } 43 | \value{ 44 | in .onLoad(), the function is used purely to set up a bibstyle as 45 | discussed in Details. 46 | 47 | Internally, \pkg{Rdpack} uses it to extract styles set up by packages: 48 | 49 | - if called with argument \code{package} only, the style requested 50 | by that package; 51 | 52 | - if called with no arguments, a list of all styles. 53 | } 54 | %\references{ 55 | %} 56 | \author{Georgi N. Boshnakov} 57 | %\note{ 58 | %%% ~~further notes~~ 59 | %} 60 | 61 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 62 | 63 | %\seealso{ 64 | %%% ~~objects to See Also as \code{\link{help}}, ~~~ 65 | %} 66 | %\examples{ 67 | %} 68 | % Add one or more standard keywords, see file 'KEYWORDS' in the 69 | % R documentation directory. 70 | \keyword{documentation} 71 | \keyword{bibtex} 72 | % use one of RShowDoc("KEYWORDS") 73 | -------------------------------------------------------------------------------- /man/char2Rdpiece.Rd: -------------------------------------------------------------------------------- 1 | \name{char2Rdpiece} 2 | 3 | \alias{char2Rdpiece} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Convert a character vector to Rd piece 9 | } 10 | 11 | \description{ 12 | Convert a character vector to Rd piece. 13 | } 14 | 15 | \usage{ 16 | char2Rdpiece(content, name, force.sec = FALSE) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{content}{a character vector.} 23 | \item{name}{name of an Rd macro, a string.} 24 | \item{force.sec}{TRUE or FALSE, see `Details'.} 25 | } 26 | 27 | \details{ 28 | 29 | Argument \code{content} is converted to an Rd piece using 30 | \code{name} to determine the format of the result. 31 | 32 | The \verb{Rd tag} of \code{content} is set as appropriate for \code{name}. 33 | More specifically, if \code{name} is the name of a macro (without the 34 | leading `\verb{\\}') whose content has a known "Rdtag", that tag is 35 | used. Otherwise the tag is set to "TEXT". 36 | 37 | If \code{force.sec} is TRUE, \code{name} is treated as the name of a 38 | top level section of an Rd object. A top level section is exported as 39 | one argument macro if it is a standard section (detected with 40 | \code{\link{is_Rdsecname}}) and as the two argument macro 41 | "\verb{\section}" otherwise. 42 | 43 | If \code{force.sec} is FALSE, the content is exported as one argument 44 | macro without further checks. 45 | } 46 | 47 | 48 | 49 | 50 | 51 | \author{Georgi N. Boshnakov} 52 | 53 | \note{ 54 | This function does not attempt to escape special symbols like `\%'. 55 | } 56 | 57 | 58 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 59 | 60 | 61 | 62 | 63 | \examples{ 64 | ## add a keyword section 65 | a1 <- char2Rdpiece("graphics", "keyword") 66 | a1 67 | ## "keyword" is a standard Rd top level section, so 'force.sec' is irrelevant 68 | a2 <- char2Rdpiece("graphics", "keyword", force.sec = TRUE) 69 | identical(a1, a2) 70 | 71 | ## an element suitable to be put in a "usage" section 72 | char2Rdpiece("log(x, base = exp(1))", "usage") 73 | 74 | ## a user defined section "Todo" 75 | char2Rdpiece("Give more examples for this function.", "Todo", force.sec = TRUE) 76 | } 77 | %\keyword{RdoProgramming} 78 | %\keyword{RdoElements} 79 | \keyword{RdoBuild} 80 | 81 | -------------------------------------------------------------------------------- /man/Rdo_collect_metadata.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_collect_aliases} 2 | \alias{Rdo_collect_aliases} 3 | \alias{Rdo_collect_metadata} 4 | \title{Collect aliases or other metadata from an Rd object} 5 | \description{Collect aliases or other metadata from an Rd object.} 6 | \usage{ 7 | Rdo_collect_aliases(rdo) 8 | 9 | Rdo_collect_metadata(rdo, sec) 10 | } 11 | \arguments{ 12 | \item{rdo}{an Rd object} 13 | \item{sec}{the kind of metadata to collect, a character string, such 14 | as "alias" and "keyword".} 15 | } 16 | \details{ 17 | \code{Rdo_collect_aliases} finds all aliases in \code{rdo} and returns 18 | them as a named character vector. The name of an alias is usually the 19 | empty string, \code{""}, but it may also be "windows" or "unix" if 20 | the alias is wrapped in a \verb{#ifdef} directive with the 21 | corresponding first argument. 22 | 23 | \code{Rdo_collect_metadata} is a generalisation of the above. It 24 | collects the metadata from section(s) \code{sec}, where \code{sec} is 25 | the name of a section without the leading backslash. 26 | \code{sec} is assumed to be a section containing a single word, such 27 | as "keyword", "alias", "name". 28 | 29 | Currently \code{Rdo_collect_metadata} is not exported. 30 | 31 | } 32 | \value{ 33 | a named character vector, as described in Details. 34 | } 35 | \author{Georgi N. Boshnakov} 36 | \seealso{ 37 | \code{tools:::.Rd_get_metadata} 38 | } 39 | \examples{ 40 | ## this example originally (circa 2012) was: 41 | ## infile <- file.path(R.home(), "src/library/base/man/timezones.Rd") 42 | ## but the OS conditional alias in that file has been removed. 43 | ## So, create an artificial example: 44 | infile <- system.file("examples", "tz.Rd", package = "Rdpack") 45 | 46 | ## file.show(infile) 47 | rd <- tools::parse_Rd(infile) 48 | 49 | ## The functions described here handle "ifdef" and similar directives. 50 | ## This detects OS specific aliases (windows = "onlywin" and unix = "onlyunix"): 51 | Rdo_collect_aliases(rd) 52 | Rdpack:::Rdo_collect_metadata(rd, "alias") # same 53 | 54 | ## In contrast, the following do not find "onlywin" and "onlyunix": 55 | sapply(rd[which(tools:::RdTags(rd)=="\\alias")], as.character) 56 | tools:::.Rd_get_metadata(rd, "alias") 57 | 58 | Rdpack:::Rdo_collect_metadata(rd, "name") 59 | Rdpack:::Rdo_collect_metadata(rd, "keyword") 60 | } 61 | \keyword{Rd} 62 | -------------------------------------------------------------------------------- /man/macros/refmacros.Rd: -------------------------------------------------------------------------------- 1 | % insert reference #1 - key, #2 - package 2 | %% changing to cache bib as insertCite does 3 | \newcommand{\insertRef}{\Sexpr[results=rd,stage=build]{Rdpack::insert_ref(key="#1",package="#2")}} 4 | %\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)}} 5 | 6 | % insert reference #1 - keys, #2 - package 7 | \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)}} 8 | \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)}} 9 | \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)}} 10 | 11 | \newcommand{\insertAllCited}{\Sexpr[results=rd,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_all_ref(.Rdpack.currefs)}} 12 | 13 | \newcommand{\insertCited}{\Sexpr[results=rd,stage=build]{if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_all_ref(.Rdpack.currefs, empty_cited = TRUE)}} 14 | 15 | % insert reference #1 - key, #2 - package 16 | %\newcommand{\runExamples}{\Sexpr[results=rd,stage=build]{deparse({#1})}} 17 | \newcommand{\runExamples}{\Sexpr[results=rd,stage=build]{Rdpack:::run_examples(quote({#1}))}} 18 | %\newcommand{\printExample}{\Sexpr[results=rd,stage=build]{Rdpack:::run_examples(quote({#1}), Rdsection = "\\\\\\\\preformatted")}} 19 | 20 | \newcommand{\printExample}{\Sexpr[results=rd,stage=build]{.Rdpack.e <- environment();Rdpack:::run_examples(quote({#1}), local = .Rdpack.e, Rdsection = "preformatted")}} 21 | %\newcommand{\printExample}{\Sexpr[results=rd,stage=build]{Rdpack:::run_examples(quote({#1}), local = parent.frame(), Rdsection = "preformatted")}} 22 | 23 | % insert reference #1 - filename, #2 - package 24 | \newcommand{\insertFig}{\Sexpr[results=rd,stage=build]{Rdpack:::insert_fig("#1","#2", { #3 })}} 25 | \newcommand{\makeFig}{\Sexpr[results=hide,stage=build]{Rdpack:::insert_fig("#1","#2", { #3 }, insert=FALSE)}} 26 | -------------------------------------------------------------------------------- /R/slots.R: -------------------------------------------------------------------------------- 1 | inspect_slots <- function(rdo, final=TRUE){ 2 | fullname <- .get.name_content(rdo)$name # name of the class with '-class' suffix 3 | cur <- .capture_promptAny(fullname, final=final) 4 | 5 | ## 2018-08-27 - non-exiting class (TDO: check if it could be something else here 6 | if(inherits(cur, "try-error")){ 7 | return(cur) 8 | } 9 | 10 | curnames <- .get_top_labels(cur, "Slots") # current slots 11 | 12 | rdonames <- .get_top_labels(rdo, "Slots") # slots in rdo 13 | 14 | icmp <- .asym_compare(rdonames, curnames) # compare; get fields $i_new, $i_rem, $i_com 15 | 16 | if(length(icmp$i_new)>0){ 17 | 18 | ## 2014-06-18 the labels contain Rd markup, as in \code{mo.col}, but this seems 19 | ## harmless. 20 | 21 | ## 2014-06-21 new slots were not handled correctly, see the changes below; 22 | ## see also inspect_clmethods - there is a lot of common ground. 23 | ## todo: consolidate? 24 | 25 | ## 2019-05-12 was: newnames <- names(icmp$i_new) # 2014-06-21 new 26 | newnames <- curnames[icmp$i_new] 27 | 28 | cat("Undocumented slots:", newnames # 2014-06-21 was: names(icmp$i_new) 29 | # 2014-06-18 was: icmp$i_new 30 | , "\n") 31 | cat("\tAdding items for them.\n") 32 | # todo: insert in particular order? 33 | cnt_newslots <- .get_top_items(cur, "Slots", newnames) # 2014-06-21 was: icmp$i_new 34 | cnt_newslots <- .nl_and_indent(cnt_newslots) # 2014-06-21 new 35 | 36 | # this ensures that the closing brace for "describe" 37 | # is on new line. todo: this needs to be indented. 38 | cnt_newslots <- c(cnt_newslots, list(Rdo_newline())) # 2014-06-21 new 39 | 40 | dindx <- .locate_top_tag(rdo, "Slots") 41 | 42 | rdo <- append_to_Rd_list(rdo, cnt_newslots, dindx) 43 | } 44 | 45 | if(length(icmp$i_removed)>0){ # todo: maybe put this note in a section in rdo? 46 | ## 2019-05-12 was: cat("Slots:", icmp$i_removed, "\n") 47 | cat("Slots:", rdonames[icmp$i_removed], "\n") 48 | cat("are no longer present. Please remove their descriptions manually.\n") 49 | } 50 | rdo 51 | } 52 | -------------------------------------------------------------------------------- /man/insert_citeOnly.Rd: -------------------------------------------------------------------------------- 1 | \name{insert_citeOnly} 2 | \alias{insert_citeOnly} 3 | 4 | \title{Generate citations from bibtex keys} 5 | 6 | \description{Generate citations from bibtex keys.} 7 | 8 | \usage{ 9 | insert_citeOnly(keys, package = NULL, before = NULL, after = NULL, 10 | bibpunct = NULL, ..., cached_env = NULL, 11 | cite_only = FALSE, dont_cite = FALSE) 12 | } 13 | 14 | \arguments{ 15 | \item{keys}{ 16 | 17 | a character string containing bibtex key(s) prefixed with the symbol 18 | \code{@}, intermixed with free text. The format is the same as for 19 | Rd macro \verb{\\insertCite}. Put \verb{;textual} at the end of the 20 | string to get a textual citation. Similarly, \verb{;nobrackets} 21 | requests parenthesised citation without the enclosing parentheses. 22 | Alternatively, \code{keys} can contain one or more keys, separated 23 | by commas. 24 | } 25 | \item{package}{name of an R package.} 26 | \item{before}{see \code{\link{citeNatbib}}.} 27 | \item{after}{see \code{\link{citeNatbib}}.} 28 | \item{bibpunct}{see \code{\link{citeNatbib}}.} 29 | \item{\dots}{further arguments; for internal use.} 30 | \item{cached_env}{for internal use.} 31 | \item{cite_only}{for internal use.} 32 | \item{dont_cite}{for internal use.} 33 | } 34 | 35 | \details{ 36 | 37 | This is the function behind \verb{\\insertCite} and related macros. 38 | Argument \code{"keys"} has the syntax of the first argument of 39 | \verb{\\insertCite}, see \code{\link{insertRef}} for full details. 40 | 41 | } 42 | 43 | \value{ 44 | a character vector containing the references with Rd markup 45 | } 46 | %\references{ 47 | %%% ~put references to the literature/web site here ~ 48 | %} 49 | \author{Georgi N. Boshnakov} 50 | 51 | \seealso{ 52 | \code{\link{insert_ref}} for description of all available Rd macros 53 | } 54 | 55 | \examples{ 56 | insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd", package = "Rdpack") 57 | ## (see also Boshnakov and Putman 2020 and Murdoch 2010) 58 | 59 | insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd;nobrackets", 60 | package = "Rdpack") 61 | ## see also Boshnakov and Putman 2020 and Murdoch 2010 62 | 63 | insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd;textual", 64 | package = "Rdpack") 65 | ## see also Boshnakov and Putman (2020) and Murdoch (2010) 66 | } 67 | 68 | \keyword{documentation} 69 | 70 | -------------------------------------------------------------------------------- /man/Rdo_set_section.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_set_section} 2 | 3 | \alias{Rdo_set_section} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Replace a section in an Rd file 9 | } 10 | 11 | \description{ 12 | Replace a section in an Rd file. 13 | } 14 | 15 | \usage{ 16 | Rdo_set_section(text, sec, file, \dots) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{text}{the new text of the section, a character vector.} 23 | \item{sec}{name of the section.} 24 | \item{file}{name of the file.} 25 | \item{...}{arguments to be passed on to \code{Rdo_modify}.} 26 | } 27 | 28 | \details{ 29 | Parses the file, replaces the specified section with the new content 30 | and writes the file back. The text is processed as appropriate for the 31 | particular section (\code{sec}). 32 | 33 | For example: 34 | 35 | \code{Rdo_set_section("Georgi N. Boshnakov", "author", "./man/Rdo2Rdf.Rd")} 36 | 37 | (Some care is needed with the author field for "xxx-package.Rd" files, such 38 | as "Rdpack-package.Rd", where the \verb{Author(s)} field has 39 | somewhat different layout.) 40 | 41 | By default \code{Rdo_set_section} does not create the section if it 42 | does not exist, since this may not be desirable for some Rd files. The 43 | "..." arguments can be used to change this, they are passed on to 44 | \code{\link{Rdo_modify}}, see its documentation for details. 45 | 46 | } 47 | 48 | \value{ 49 | This function is used mainly for the side effect of changing \code{file}. 50 | It returns the Rd formatted text as a character vector. 51 | } 52 | 53 | 54 | 55 | \author{Georgi N. Boshnakov} 56 | 57 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 58 | \seealso{ 59 | \code{\link{Rdo_modify}} 60 | } 61 | \examples{ 62 | fnA <- tempfile("dummyfun", fileext = "Rd") 63 | dummyfun <- function(x) x 64 | reprompt(dummyfun, filename = fnA) 65 | Rdo_show(tools::parse_Rd(fnA)) 66 | 67 | ## set the author section, create it if necessary. 68 | Rdo_set_section("A.A. Author", "author", fnA, create = TRUE) 69 | Rdo_show(tools::parse_Rd(fnA)) 70 | 71 | ## replace the author section 72 | Rdo_set_section("Georgi N. Boshnakov", "author", fnA) 73 | Rdo_show(tools::parse_Rd(fnA)) 74 | 75 | unlink(fnA) 76 | } 77 | 78 | % Add one or more standard keywords, see file 'KEYWORDS' in the 79 | 80 | % R documentation directory. 81 | 82 | \keyword{RdoBuild} 83 | -------------------------------------------------------------------------------- /man/c_Rd.Rd: -------------------------------------------------------------------------------- 1 | \name{c_Rd} 2 | \alias{c_Rd} 3 | \title{Concatenate Rd objects or pieces} 4 | \description{Concatenates Rd objects or pieces} 5 | \usage{ 6 | c_Rd(...) 7 | } 8 | \arguments{ 9 | \item{\dots}{objects to be concatenated, Rd objects or character 10 | strings, see `Details'. 11 | } 12 | } 13 | \details{ 14 | The arguments may be a mixture of lists and character strings. The 15 | lists are typically "Rd" objects or pieces. The character strings may 16 | also be elements of "Rd" objects carrying "Rd_tag" attributes. The 17 | "Rd_tag" attribute of character strings for which it is missing is set 18 | to "TEXT". Finally, each character element of \code{"\dots"} is 19 | enclosed in \code{list}. 20 | 21 | Eventually all arguments become lists and they are concatenated using 22 | \code{c()}. If any of the arguments is of class "Rd", the class of the 23 | result is set to "Rd". Otherwise, the "Rd_tag" of the result is set to 24 | the first (if any) non-null "Rd_tag" in the arguments. 25 | 26 | The structure of "Rd" objects is described by 27 | \insertCite{parseRd;textual}{Rdpack}. 28 | 29 | } 30 | \value{ 31 | An Rd object or a list whose attribute "Rd_tag" is set as descibed in 32 | `Details' 33 | } 34 | 35 | \author{Georgi N. Boshnakov} 36 | \seealso{ 37 | \code{\link{list_Rd}} 38 | } 39 | \references{ 40 | \insertAllCited{} 41 | } 42 | \examples{ 43 | a1 <- char2Rdpiece("Dummyname", "name") 44 | a2 <- char2Rdpiece("Dummyallias1", "alias") 45 | a3 <- char2Rdpiece("Dummy title", "title") 46 | a4 <- char2Rdpiece("Dummy description", "description") 47 | 48 | ## The following are equivalent 49 | ## (gbRd::Rdo_empty() creates an empty list of class 'Rd') 50 | if(requireNamespace("gbRd")){ 51 | b1 <- c_Rd(gbRd::Rdo_empty(), list(a1), list(a2), list(a3), list(a4)) 52 | c1 <- c_Rd(gbRd::Rdo_empty(), list(a1, a2, a3, a4)) 53 | d1 <- c_Rd(gbRd::Rdo_empty(), list(a1, a2), list(a3, a4)) 54 | identical(c1, b1) 55 | identical(c1, d1) 56 | Rdo_show(b1) 57 | 58 | ## insert a newline 59 | d1n <- c_Rd(gbRd::Rdo_empty(), list(a1, a2), Rdo_newline(), list(a3, a4)) 60 | str(d1n) 61 | } 62 | 63 | ## When most of the arguments are character strings 64 | ## the function 'list_Rd' may be more convenient. 65 | u1 <- list_Rd(name = "Dummyname", alias = "Dummyallias1", 66 | title = "Dummy title", description = "Dummy description", 67 | Rd_class = TRUE ) 68 | Rdo_show(u1) 69 | } 70 | \keyword{RdoBuild} 71 | %\keyword{RdoProgramming} 72 | -------------------------------------------------------------------------------- /R/parse.R: -------------------------------------------------------------------------------- 1 | ## 2018-01-30 experimenting with processing of Rd macros 2 | ## pkgmacros <- tools::loadPkgRdMacros(system.file(package = package)) 3 | ## rdo <- parse_Rd(infile, macros = pkgmacros) 4 | 5 | ## 2018-01-30 new function 6 | ## as parse_Rd but intercepts warnings about unknown Rd macros 7 | permissive_parse_Rd <- function(file, permissive = TRUE, ...){ 8 | parse_Rd(file, permissive = permissive, ...) 9 | } 10 | 11 | ## 2018-01-30 new argument 'macros' 12 | .parse_Rdlines <- function(lines, macros = NULL){ 13 | tmpfile <- tempfile("Rdlines", fileext = ".Rd") 14 | # unlist is harmless if `lines' is already a character vector 15 | cat(unlist(lines), file = tmpfile, sep = "\n") # todo: catch errors 16 | if(is.null(macros)) 17 | res <- permissive_parse_Rd(tmpfile) # todo: catch errors 18 | else 19 | res <- permissive_parse_Rd(tmpfile, macros = macros) # todo: catch errors 20 | unlink(tmpfile) 21 | res 22 | } 23 | 24 | parse_Rdtext <- function(text, section = NA){ 25 | if(!is.na(section)) 26 | text <- c(paste(section,"{",sep=""), text, "}") 27 | 28 | res <- .parse_Rdlines(text) # write(text, sep="\n", file = file); res <- parse_Rd(file) 29 | 30 | rdtag <- attr(res[[1]], "Rd_tag") 31 | if(!is.na(section) && !is.null(rdtag) && rdtag==section) # todo: tova e krapka! 32 | res <- res[[1]] 33 | if(identical( c(res[[1]]), "\n" )) # c( ) to strip attributes 34 | res[[1]] <- NULL 35 | 36 | res 37 | } 38 | 39 | parse_Rdpiece <- function(x, result=""){ 40 | maket <- list_Rd(title="Dummy title" 41 | , name="dummyname" 42 | , "\\description"="Dummy description" 43 | , note = x 44 | , Rd_class=TRUE 45 | ) 46 | 47 | fn <- tempfile(pattern = "Rdpiece", fileext = "Rd") 48 | cat(as.character(maket), file=fn, sep="") # todo: error processing 49 | wrk <- permissive_parse_Rd(fn) 50 | 51 | unlink(fn) 52 | 53 | if(result=="text"){ # Rd_help2txt is from gbRd 54 | res <- gbRd::Rd_help2txt(wrk, keep_section="\\note", omit_sec_header=TRUE) 55 | }else{ 56 | indx <- Rdo_which_tag_eq(wrk, "\\note") 57 | res <- wrk[[indx]] 58 | if(!is.null(attr(res,"Rd_tag"))) 59 | attr(res,"Rd_tag") <- NULL 60 | } 61 | 62 | res 63 | } 64 | -------------------------------------------------------------------------------- /R/threedots.R: -------------------------------------------------------------------------------- 1 | # > tools:::.strip_whitespace 2 | .strip_whitespace <- 3 | function (x) 4 | { 5 | x <- sub("^[[:space:]]+", "", x) 6 | x <- sub("[[:space:]]+$", "", x) 7 | x 8 | } 9 | 10 | 11 | ## tools:::.Rd_drop_nodes_with_tags, but tools:::RdTags(e) => Rdo_tags(e) 12 | toolsdotdotdot.Rd_drop_nodes_with_tags <- 13 | function (x, tags) 14 | { 15 | recurse <- function(e) { 16 | if (is.list(e)) 17 | structure(lapply(e[is.na(match(Rdo_tags(e), tags))], 18 | recurse), Rd_tag = attr(e, "Rd_tag")) 19 | else e 20 | } 21 | recurse(x) 22 | } 23 | 24 | 25 | ## > tools:::.Rd_get_metadata, but tools:::RdTags() => Rdo_tags() 26 | toolsdotdotdot.Rd_get_metadata <- 27 | function (x, kind) # e.g. kind = "keyword", see help page of Rd_db() 28 | { 29 | x <- x[Rdo_tags(x) == sprintf("\\%s", kind)] 30 | if (!length(x)) 31 | character() 32 | else unique(.strip_whitespace(sapply(x, as.character))) 33 | } 34 | 35 | 36 | ## > utils:::.getHelpFile 37 | utilsdotdotdot.getHelpFile <- 38 | function (file) 39 | { 40 | path <- dirname(file) 41 | dirpath <- dirname(path) 42 | if (!file.exists(dirpath)) 43 | stop(gettextf("invalid %s argument", sQuote("file")), 44 | domain = NA) 45 | pkgname <- basename(dirpath) 46 | RdDB <- file.path(path, pkgname) 47 | if (!file.exists(paste(RdDB, "rdx", sep = "."))) 48 | stop(gettextf("package %s exists but was not installed under R >= 2.10.0 so help cannot be accessed", 49 | sQuote(pkgname)), domain = NA) 50 | toolsdotdotdotfetchRdDB(RdDB, basename(file)) 51 | } 52 | 53 | 54 | ## > tools:::fetchRdDB 55 | toolsdotdotdotfetchRdDB <- 56 | function (filebase, key = NULL) 57 | { 58 | fun <- function(db) { 59 | vals <- db$vals 60 | vars <- db$vars 61 | datafile <- db$datafile 62 | compressed <- db$compressed 63 | envhook <- db$envhook 64 | fetch <- function(key) lazyLoadDBfetch(vals[key][[1L]], 65 | datafile, compressed, envhook) 66 | if (length(key)) { 67 | if (!key %in% vars) 68 | stop(gettextf("No help on %s found in RdDB %s", 69 | sQuote(key), sQuote(filebase)), domain = NA) 70 | fetch(key) 71 | } 72 | else { 73 | res <- lapply(vars, fetch) 74 | names(res) <- vars 75 | res 76 | } 77 | } 78 | res <- lazyLoadDBexec(filebase, fun) 79 | if (length(key)) 80 | res 81 | else invisible(res) 82 | } 83 | -------------------------------------------------------------------------------- /man/Rdo_which.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_which} 2 | \alias{Rdo_which} 3 | \alias{Rdo_which_tag_eq} 4 | \alias{Rdo_which_tag_in} 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | \title{Find elements of Rd objects for which a condition is true} 7 | \description{Find elements of Rd objects for which a condition is true.} 8 | \usage{ 9 | Rdo_which(rdo, fun) 10 | 11 | Rdo_which_tag_eq(rdo, tag) 12 | 13 | Rdo_which_tag_in(rdo, tags) 14 | } 15 | %- maybe also 'usage' for other objects documented here. 16 | \arguments{ 17 | \item{rdo}{an Rd object.} 18 | \item{fun}{a function to evaluate with each element of \code{rdo}.} 19 | \item{tag}{a character string.} 20 | \item{tags}{a character vector.} 21 | } 22 | \details{ 23 | 24 | These functions return the indices of the (top level) elements of 25 | \code{rdo} which satisfy a condition. 26 | 27 | \code{Rdo_which} finds elements of \code{rdo} for which 28 | the function \code{fun} gives TRUE. 29 | 30 | \code{Rdo_which_tag_eq} finds elements with a specific \code{Rd_tag}. 31 | 32 | \code{Rdo_which_tag_in} finds elements whose \code{Rd_tag}'s are among 33 | the ones specified by \code{tags}. 34 | 35 | %% ~~ If necessary, more details than the description above ~~ 36 | } 37 | \value{ 38 | a vector of positive integers 39 | } 40 | % \references{ 41 | % %% ~put references to the literature/web site here ~ 42 | % } 43 | \author{Georgi N. Boshnakov} 44 | % \note{ 45 | % %% ~~further notes~~ 46 | % } 47 | 48 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 49 | 50 | \seealso{ 51 | \code{\link{Rdo_locate}} which searches recursively the Rd object. 52 | } 53 | \examples{ 54 | ## get the help page for topoc seq() 55 | rdo_seq <- tools::Rd_db("base")[["seq.Rd"]] 56 | ## find location of aliases in the topic 57 | ( ind <- Rdo_which_tag_eq(rdo_seq, "\\alias") ) 58 | ## extract the first alias 59 | rdo_seq[[ ind[1] ]] 60 | \dontrun{ 61 | ## extract all aliases 62 | rdo_seq[ind] 63 | } 64 | 65 | ## db_bibtex <- tools::Rd_db("bibtex") 66 | ## names(db_bibtex) 67 | ## ## Rdo object for read.bib() 68 | ## rdo_read.bib <- db_bibtex[["read.bib.Rd"]] 69 | ## Rdo_tags(rdo_read.bib) 70 | ## 71 | ## ## which elements of read.bib are aliases? 72 | ## Rdo_which_tag_eq(rdo_read.bib, "\\alias") 73 | ## rdo_read.bib[[3]] 74 | ## 75 | ## ## which elements of read.bib contain R code? 76 | ## Rdo_which(rdo_read.bib, function(x) any(Rdo_tags(x) == "RCODE") ) 77 | ## rdo_read.bib[[5]] 78 | ## ## which contain prose? 79 | ## Rdo_which(rdo_read.bib, function(x) any(Rdo_tags(x) == "TEXT") ) 80 | } 81 | \keyword{Rd} 82 | -------------------------------------------------------------------------------- /man/append_to_Rd_list.Rd: -------------------------------------------------------------------------------- 1 | \name{append_to_Rd_list} 2 | 3 | \alias{append_to_Rd_list} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Add content to the element of an Rd object or fragment at a given 9 | position 10 | } 11 | 12 | \description{ 13 | Add content to the element of an Rd object or fragment at a given 14 | position. 15 | } 16 | 17 | \usage{ 18 | append_to_Rd_list(rdo, x, pos) 19 | } 20 | 21 | %- maybe also 'usage' for other objects documented here. 22 | 23 | \arguments{ 24 | \item{rdo}{an Rd object} 25 | \item{x}{the content to append, an Rd object or a list of Rd objects.} 26 | \item{pos}{position at which to append \code{x}, typically an integer 27 | but may be anything accepted by the operator "[[". 28 | } 29 | } 30 | 31 | \details{ 32 | The element of \code{rdo} at position \code{pos} is replaced by its 33 | concatenation with \code{x}. The result keeps the "Rd_tag" of 34 | \code{rdo[[pos]]}. 35 | 36 | Argument \code{pos} may specify a position at any depth of the Rd 37 | object. 38 | 39 | This function is relatively low level and is mainly for use by other 40 | functions. 41 | } 42 | 43 | \value{ 44 | the modified \code{rdo} object 45 | } 46 | 47 | 48 | 49 | \author{Georgi N. Boshnakov} 50 | 51 | 52 | 53 | 54 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 55 | 56 | 57 | 58 | 59 | \examples{ 60 | #rdoseq <- utils:::.getHelpFile(help("seq")) 61 | rdoseq <- Rdo_fetch("seq", "base") 62 | iusage <- which(tools:::RdTags(rdoseq) == "\\\\usage") 63 | iusage 64 | attr(rdoseq[[iusage]], "Rd_tag") 65 | 66 | ## append a new line after the last usage line 67 | rdoseq2 <- append_to_Rd_list(rdoseq, list(Rdo_newline()), iusage) 68 | 69 | ## Suppose that we wish to describe the function 'sequence' in the same Rd file. 70 | ## We append an usage statement for 'sequence()', without worrying about its 71 | ## actual signature. 72 | rdoseq2 <- append_to_Rd_list(rdoseq2, list(Rdo_Rcode("sequence()")), iusage) 73 | Rdo_show(rdoseq2) 74 | 75 | ## the two operations can be done in one step 76 | rdoseq3 <- append_to_Rd_list(rdoseq, list(Rdo_newline(), Rdo_Rcode("sequence()")), iusage) 77 | Rdo_show(rdoseq3) 78 | 79 | ## now run reprompt() to update rdoseq3, namely: 80 | ## (1) it corrects the signature of 'sequence' in section \usage. 81 | ## (2) reports new argument "nvec" 82 | ## (3) inserts \item for the new argument(s) in section \arguments. 83 | reprompt(rdoseq3, filename=NA) 84 | } 85 | 86 | % Add one or more standard keywords, see file 'KEYWORDS' in the 87 | 88 | % R documentation directory. 89 | 90 | %\keyword{RdoProgramming} 91 | \keyword{RdoBuild} 92 | -------------------------------------------------------------------------------- /man/compare_usage1.Rd: -------------------------------------------------------------------------------- 1 | \name{compare_usage1} 2 | \alias{compare_usage1} 3 | \title{ 4 | Compare usage entries for a function to its actual arguments 5 | } 6 | \description{ 7 | Compare usage entries for a function to its actual arguments. 8 | } 9 | \usage{ 10 | compare_usage1(urdo, ucur) 11 | } 12 | \arguments{ 13 | \item{urdo}{ 14 | usage text for a function or S3 method from an Rd object or file. 15 | } 16 | \item{ucur}{usage generated from the actual object.} 17 | } 18 | 19 | \details{ 20 | Compares the usage statements for functions in the Rd object or file 21 | \code{urdo} to the usage inferred from the actual definitions of the 22 | functions. The comparison is symmetric but the interpretation assumes 23 | that \code{ucur} may be more recent. 24 | 25 | Note: do not compare the return value to TRUE with \code{identical} or 26 | \code{isTRUE}. The attribute makes the returned value not identical to 27 | TRUE in any case. 28 | } 29 | 30 | \value{ 31 | TRUE if the usages are identical, FALSE otherwise. 32 | The return value has attribute "details", which is a list providing 33 | details of the comparison. The elements of this list should be 34 | referred by name, since if one of \code{urdo} or \code{ucur} is NULL 35 | or NA, the list contains only the fields "obj_removed", "obj_added", 36 | "rdo_usage", "cur_usage", and "alias". 37 | 38 | \item{identical_names}{a logical value, TRUE if the `name' is the same in both objects.} 39 | \item{obj_removed}{names present in \code{urdo} but not in \code{ucur}} 40 | \item{obj_added }{names present in \code{ucur} but not in \code{urdo}} 41 | \item{identical_argnames }{a logical value, 42 | TRUE if the argument names in both objects are the same.} 43 | \item{identical_defaults }{a logical value, 44 | TRUE if the defaults for the arguments in both objects are the same.} 45 | \item{identical_formals }{a logical value, TRUE if the formals 46 | are the same, i.e. fields \code{identical_argnames} and 47 | \code{identical_defaults} are both TRUE.} 48 | \item{added_argnames }{names of arguments in \code{ucur} but not in \code{urdo}.} 49 | \item{removed_argnames}{names of arguments in \code{urdo} but not in \code{ucur}.} 50 | \item{names_unchanged_defaults }{names of arguments whose defaults are the same.} 51 | \item{rdo_usage }{a copy of \code{urdo}.} 52 | \item{cur_usage }{a copy of \code{ucur}.} 53 | \item{alias }{alias of the name of the object, see `Details'.} 54 | } 55 | \author{Georgi N. Boshnakov} 56 | \seealso{ 57 | \code{\link{inspect_usage}} 58 | } 59 | \keyword{RdoUsage} 60 | -------------------------------------------------------------------------------- /man/insert_all_ref.Rd: -------------------------------------------------------------------------------- 1 | \name{insert_all_ref} 2 | \alias{insert_all_ref} 3 | \title{Insert references cited in packages} 4 | \description{Insert references cited in packages. } 5 | \usage{ 6 | insert_all_ref(refs, style = "", empty_cited = FALSE) 7 | } 8 | \arguments{ 9 | \item{refs}{ 10 | % TODO: is this description up-to-date? 11 | a matrix specifying key-package pairs of the references to insert. 12 | Can also be a cached environment, see Details. 13 | } 14 | \item{style}{a bibstyle, see Details.} 15 | \item{empty_cited}{ 16 | if \code{TRUE}, empty the list of currently cited items. 17 | } 18 | } 19 | \details{ 20 | 21 | \code{insert_all_ref} is the workhorse behind several Rd macros for 22 | inclusion of references in Rd documentation. 23 | 24 | Argument \code{refs} is a two-column character matrix. The first 25 | column specifies bibtex keys. To specify more than one key in a 26 | single element, separate them by commas. The second column specifies the 27 | package in which to look for the keys. 28 | 29 | A key equal to "*" requests all keys in the corresponding package. 30 | 31 | \code{insert_all_ref} drops duplicated keys, collects the references, 32 | and converts them to Rd textual representation for inclusion in Rd 33 | documentation files. 34 | 35 | \code{refs} can be a cached environment. This is for internal use and 36 | not documented. 37 | 38 | } 39 | \value{ 40 | a character string containing a textual representation of the 41 | references, suitable for inclusion in an Rd file 42 | } 43 | \references{ 44 | 45 | Currently there are no citations on this help page. Nevetheless, I 46 | have put \verb{\insertAllCited{}} just after this paragraph to show 47 | the message that it prints when there are no citations. This seems 48 | better than printing nothing but it may be argued also that there 49 | should be a warning as well. 50 | 51 | \insertAllCited{} 52 | } 53 | \author{Georgi N. Boshnakov} 54 | % \note{ 55 | % %% ~~further notes~~ 56 | % } 57 | % 58 | % %% ~Make other sections like Warning with \section{Warning }{....} ~ 59 | % 60 | % \seealso{ 61 | % %% ~~objects to See Also as \code{\link{help}}, ~~~ 62 | % } 63 | \examples{ 64 | ## a reference from package Rdpack 65 | cat(insert_all_ref(matrix(c("Rpack:bibtex", "Rdpack"), ncol = 2)), "\n") 66 | 67 | ## more than one reference from package Rdpack, separate the keys with commas 68 | cat(insert_all_ref(matrix(c("parseRd,Rpack:bibtex", "Rdpack"), ncol = 2)), "\n") 69 | 70 | ## all references from package Rdpack 71 | cat(insert_all_ref(matrix(c("*", "Rdpack"), ncol = 2)), "\n") 72 | 73 | ## all references from package Rdpack and rbibutils 74 | m <- matrix(c("*", "Rdpack", "*", "rbibutils"), ncol = 2, byrow = TRUE) 75 | cat(insert_all_ref(m), "\n") 76 | } 77 | \keyword{documentation} 78 | -------------------------------------------------------------------------------- /man/format_funusage.Rd: -------------------------------------------------------------------------------- 1 | \name{format_funusage} 2 | \alias{format_funusage} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Format the usage text of functions} 5 | \description{Formats the usage text of a function so that each line 6 | contains no more than a given number of characters.} 7 | \usage{ 8 | format_funusage(x, name = "", width = 72, realname) 9 | } 10 | %- maybe also 'usage' for other objects documented here. 11 | \arguments{ 12 | \item{x}{a character vector containing one element for each argument 13 | of the function, see `Details'.} 14 | \item{name}{the name of the function whose usage is described, a 15 | string.} 16 | \item{width}{maximal width of each line of output.} 17 | \item{realname}{the printed form of \code{name}, see `Details', a 18 | string.} 19 | } 20 | \details{ 21 | \code{format_funusage} formats the usage text of a function for 22 | inclusion in Rd documentation files. If necessary, it splits the text 23 | into more lines in order to fit it within the requested width. 24 | 25 | Each element of argument \code{x} contains the text for one argument 26 | of function \code{name} in the form \code{arg} or \code{arg = default}. 27 | \code{format_funusage} does not look into the content of 28 | \code{x}, it does the necessary pasting to form the complete usage 29 | text, inserting new lines and indentation to stay within the specified 30 | width. Elements of \code{x} are never split. If an argument (i.e., 31 | element of \code{x}) would cause the width to be exceeded, the entire 32 | argument is moved to the following line. 33 | 34 | The text on the second and subsequent lines of each usage item starts 35 | in the column just after the opening parenthesis which follows the 36 | name of the function on the first line. 37 | 38 | In descriptions of S3 methods and S4 methods, argument \code{name} may 39 | be a TeX macro like \verb{\method{print}{ts}}. In that case the number 40 | of characters in \code{name} has little bearing on the actual number 41 | printed. In this case argument \code{realname} is used for counting 42 | both the number of characters on the first line of the usage message 43 | and the indentation for the subsequent lines. 44 | 45 | } 46 | 47 | \value{ 48 | The formatted text as a length one character vector. 49 | } 50 | 51 | 52 | \author{Georgi N. Boshnakov} 53 | \note{ 54 | Only the width of \code{realname} is used (for counting). The 55 | formatted text contains \code{name}. 56 | 57 | The width of strings is determined by calling \code{nchar} with 58 | argument \code{type} set to "width". 59 | } 60 | 61 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 62 | 63 | \seealso{ 64 | \code{\link{deparse_usage1}} 65 | } 66 | \examples{ 67 | # this function is essentially internal, 68 | # see deparse_usage1 and as.character.f_usage which use it. 69 | } 70 | %\keyword{RdoProgramming} 71 | \keyword{RdoUsage} 72 | %\keyword{RdFunction} 73 | -------------------------------------------------------------------------------- /man/zzcapture_promptany.Rd: -------------------------------------------------------------------------------- 1 | \name{.capture_promptAny} 2 | 3 | \alias{.capture_promptAny} 4 | \alias{.capture_installed_help} 5 | 6 | %- Also NEED an '\alias' for EACH other topic documented here. 7 | 8 | \title{Internal functions used by reprompt} 9 | 10 | \description{Internal functions used by reprompt.} 11 | 12 | \usage{ 13 | .capture_promptAny(fnam, type, package, final, \dots, methods) 14 | 15 | .capture_installed_help(fnam, type = NULL, package = NULL, 16 | suffix = NULL) 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{fnam}{extended name of the object, such as "fun", "gen-methods", 23 | "S4cl-class" or "pkname-package", see details.} 24 | \item{final}{if TRUE, put dummy title and description to make the 25 | file immediately usable.} 26 | \item{\dots}{further arguments to pass on to the prompt function(s).} 27 | \item{methods}{methods to consider, used only when describing S4 methods.} 28 | \item{type}{type of documentation, such as "methods" and "class", see 29 | Details.} 30 | \item{package}{the package where to look for objects or documentation, 31 | useful if more objects of the same name exist.} 32 | \item{suffix}{a character string to be appended to \code{fnam} to 33 | obtain the complete name of the help topic, e.g. "-class", 34 | "-method". 35 | } 36 | } 37 | 38 | \details{ 39 | These functions are used internally by \code{reprompt}. It falls back 40 | to them when only when the user has not supplied an Rd file in the 41 | call. 42 | 43 | Note that for editing it is preferable to use the source Rd files 44 | (when available), since some hard coded information in the installed 45 | help may have been produced by more elaborated code in the Rd sources, 46 | most notably Sweave expressions. 47 | 48 | \code{.capture_promptAny} is used to generate documentation when none 49 | has been supplied by the user or loaded in the session. 50 | \code{.capture_promptAny} parses \code{fnam} to obtain the name of the 51 | object and the type of the required documentation (function, methods, 52 | class), then generates it. Currently this is done with the built in 53 | functions of the \code{promptXXX} family. 54 | 55 | \code{.capture_installed_help} does exactly that --- it captures the 56 | currently installed requested help topic. This function needs clean 57 | up. It was originally written at a time when both the old and new help 58 | formats where co-existing. 59 | } 60 | 61 | \value{ 62 | an Rd object on success or a \code{try-error} object otherwise 63 | } 64 | 65 | 66 | 67 | \author{Georgi N. Boshnakov} 68 | 69 | 70 | 71 | 72 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 73 | 74 | 75 | 76 | 77 | \examples{ 78 | ##---- Should be DIRECTLY executable !! ---- 79 | } 80 | 81 | % Add one or more standard keywords, see file 'KEYWORDS' in the 82 | 83 | % R documentation directory. 84 | 85 | \keyword{internal} 86 | -------------------------------------------------------------------------------- /man/Rdo_macro.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_macro} 2 | 3 | \alias{Rdo_macro} 4 | \alias{Rdo_macro1} 5 | \alias{Rdo_macro2} 6 | \alias{Rdo_item} 7 | \alias{Rdo_sigitem} 8 | 9 | %- Also NEED an '\alias' for EACH other topic documented here. 10 | 11 | \title{ 12 | Format Rd fragments as macros (todo: a baffling title!) 13 | } 14 | 15 | \description{ 16 | Format Rd fragments as macros, generally by putting them in a list and 17 | setting the "Rd_tag" as needed. 18 | } 19 | 20 | \usage{ 21 | Rdo_macro(x, name) 22 | 23 | Rdo_macro1(x, name) 24 | 25 | Rdo_macro2(x, y, name) 26 | 27 | Rdo_item(x, y) 28 | 29 | Rdo_sigitem(x, y, newline = TRUE) 30 | } 31 | 32 | %- maybe also 'usage' for other objects documented here. 33 | 34 | \arguments{ 35 | \item{x}{an object.} 36 | \item{y}{an object.} 37 | \item{name}{the "\verb{Rd_tag}", a string.} 38 | \item{newline}{currently ignored.} 39 | } 40 | 41 | \details{ 42 | \code{Rdo_macro1} wraps \code{x} in a list with "\verb{Rd_tag}" 43 | \code{name}. This is the representation of Rd macros with one argument. 44 | 45 | \code{Rdo_macro2} basically wraps a possibly transformed \code{x} and 46 | \code{y} in a list with "\verb{Rd_tag}" \code{name}. More specifically, 47 | if \code{x} has a non-NULL "\verb{Rd_tag}", \code{x} is wrapped in 48 | \code{list}. Otherwise \code{x} is left as is, unless \code{x} is a 49 | character string, when it is converted to a text Rd element and 50 | wrapped in \code{list}. \code{y} is processed in the same way. 51 | This is the representation of Rd macros with two arguments. 52 | 53 | \code{Rdo_macro} returns an object with "\verb{Rd_tag}" \code{name}, 54 | constructed as follows. If \code{x} is not of class "character", its 55 | attribute "\verb{Rd_tag}" is set to \code{name} and the result 56 | returned without further processing. Otherwise, if it is of class 57 | "character", \code{x} is tagged as an Rd "TEXT" element. It is then 58 | wrapped in a list but only if \code{name} is one of "\verb{\eqn}" or 59 | "\verb{\deqn}". Finally, \code{Rdo_macro1} is called on the 60 | transformed object. 61 | 62 | \code{Rdo_item} is equivalent to \code{Rdo_macro2} with \code{name} 63 | set to "\verb{\item}". 64 | 65 | \code{Rdo_sigitem} is for items which have the syntax used in 66 | description of signatures. In that case the first argument of 67 | "\verb{\item}" is wrapped in "\verb{\code}". If \code{y} is missing, 68 | a text inviting the author to provide a description of the function 69 | for this signature is inserted. 70 | 71 | } 72 | 73 | \value{ 74 | An Rd element with appropriately set \verb{Rd_tag}, as described in 75 | `Details'. 76 | } 77 | 78 | 79 | 80 | \author{Georgi N. Boshnakov} 81 | 82 | 83 | 84 | 85 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 86 | 87 | 88 | 89 | 90 | % Add one or more standard keywords, see file 'KEYWORDS' in the 91 | 92 | % R documentation directory. 93 | 94 | %\keyword{RdoProgramming} 95 | %\keyword{RdoElements} 96 | \keyword{RdoBuild} 97 | -------------------------------------------------------------------------------- /man/inspect_Rd.Rd: -------------------------------------------------------------------------------- 1 | \name{inspect_Rd} 2 | 3 | \alias{inspect_Rd} 4 | \alias{inspect_Rdfun} 5 | \alias{inspect_Rdmethods} 6 | \alias{inspect_Rdclass} 7 | 8 | %- Also NEED an '\alias' for EACH other topic documented here. 9 | 10 | \title{ 11 | Inspect and update an Rd object or file 12 | } 13 | \description{ 14 | Inspect and update an Rd object or file. 15 | } 16 | 17 | \usage{ 18 | inspect_Rd(rdo, package = NULL) 19 | 20 | inspect_Rdfun(rdo, alias_update = TRUE) 21 | 22 | inspect_Rdmethods(rdo, package = NULL) 23 | 24 | inspect_Rdclass(rdo) 25 | } 26 | 27 | %- maybe also 'usage' for other objects documented here. 28 | 29 | \arguments{ 30 | \item{rdo}{an Rd object or file name} 31 | \item{package}{name of a package} 32 | \item{alias_update}{if \code{TRUE}, add missing alias entries for 33 | functions with usage statements.} 34 | } 35 | 36 | \details{ 37 | These functions check if the descriptions of the objects in \code{rdo} 38 | are consistent with their current definitions and update them, if 39 | necessary. The details depend on the type of the documented topic. 40 | In general, the functions update entries that can be produced 41 | programmatically, possibly accompanied with a suggestion to the author 42 | to write some additional text. 43 | 44 | \code{inspect_Rd} checks the \verb{\name} section of \code{rdo} and 45 | dispatches to one of the other \code{inspect_XXX} functions depening 46 | on the type of the topic. 47 | 48 | \code{inspect_Rdfun} processes documentation of functions. It checks 49 | the usage entries of all functions documented in \code{rdo} and 50 | updates them if necessary. It appends "\verb{\alias}" entries for 51 | functions that do not have them. Entries are created for any arguments 52 | that are missing from the "\verb{\arguments}" section. Warning is 53 | given for arguments in the "\verb{\arguments}" section that are not 54 | present in at least one usage entry. \code{inspect_Rdfun} understands 55 | the syntax for S3 methods and S4 methods used in "usage" sections, as 56 | well. The S4 methods may also be in a section as produced by 57 | \code{promptMethods}. 58 | 59 | \code{inspect_Rdmethods} checks and updates documentation of an S4 60 | generic function. 61 | 62 | \code{inspect_Rdclass} checks and updates documentation of an S4 63 | class. 64 | 65 | Since method signatures and descriptions may be present in 66 | documentation of a class, as well as in that of methods, the question 67 | arises where to put "\verb{\alias}" entries to avoid duplication. 68 | Currently, alias entries are put in method descriptions. 69 | } 70 | 71 | 72 | 73 | 74 | 75 | \author{Georgi N. Boshnakov} 76 | 77 | 78 | 79 | 80 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 81 | 82 | 83 | 84 | 85 | % \examples{ 86 | % ##---- Should be DIRECTLY executable !! ---- 87 | % } 88 | 89 | % Add one or more standard keywords, see file 'KEYWORDS' in the 90 | 91 | % R documentation directory. 92 | 93 | \keyword{RdoProgramming} 94 | -------------------------------------------------------------------------------- /tests/testthat/show.Rd: -------------------------------------------------------------------------------- 1 | \name{show} 2 | \alias{show} 3 | \alias{show-methods} 4 | \alias{show,ANY-method} 5 | \alias{show,traceable-method} 6 | \alias{show,ObjectsWithPackage-method} 7 | \alias{show,MethodDefinition-method} 8 | \alias{show,MethodWithNext-method} 9 | \alias{show,genericFunction-method} 10 | \alias{show,classRepresentation-method} 11 | \title{Show an Object} 12 | \description{ 13 | Display the object, by printing, plotting or whatever suits its 14 | class. This function exists to be specialized by methods. The 15 | default method calls \code{\link{showDefault}}. 16 | 17 | Formal methods for \code{show} will 18 | usually be invoked for automatic printing (see the details). 19 | } 20 | \usage{ 21 | show(object) 22 | } 23 | \arguments{ 24 | \item{object}{Any R object} 25 | } 26 | \details{ 27 | Objects from an S4 class (a class defined by a call to 28 | \code{\link{setClass}}) will be displayed automatically is if by a 29 | call to \code{show}. S4 objects that occur as attributes of S3 30 | objects will also be displayed in this form; conversely, S3 objects 31 | encountered as slots in S4 objects will be printed using the S3 32 | convention, as if by a call to \code{\link{print}}. 33 | 34 | Methods defined for \code{show} will only be inherited by simple 35 | inheritance, since otherwise the method would not receive the 36 | complete, original object, with misleading results. See the 37 | \code{simpleInheritanceOnly} argument to \code{\link{setGeneric}} and 38 | the discussion in \code{\link{setIs}} for the general concept. 39 | 40 | } 41 | \value{ 42 | \code{show} returns an invisible \code{NULL}. 43 | } 44 | \seealso{ 45 | \code{\link{showMethods}} prints all the methods for one or more 46 | functions. 47 | } 48 | \examples{ 49 | ## following the example shown in the setMethod documentation ... 50 | setClass("track", slots = c(x="numeric", y="numeric")) 51 | setClass("trackCurve", contains = "track", slots = c(smooth = "numeric")) 52 | 53 | t1 <- new("track", x=1:20, y=(1:20)^2) 54 | 55 | tc1 <- new("trackCurve", t1) 56 | 57 | setMethod("show", "track", 58 | function(object)print(rbind(x = object@x, y=object@y)) 59 | ) 60 | ## The method will now be used for automatic printing of t1 61 | 62 | t1 63 | 64 | \dontrun{ [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12] 65 | x 1 2 3 4 5 6 7 8 9 10 11 12 66 | y 1 4 9 16 25 36 49 64 81 100 121 144 67 | [,13] [,14] [,15] [,16] [,17] [,18] [,19] [,20] 68 | x 13 14 15 16 17 18 19 20 69 | y 169 196 225 256 289 324 361 400 70 | } 71 | ## and also for tc1, an object of a class that extends "track" 72 | tc1 73 | 74 | \dontrun{ [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12] 75 | x 1 2 3 4 5 6 7 8 9 10 11 12 76 | y 1 4 9 16 25 36 49 64 81 100 121 144 77 | [,13] [,14] [,15] [,16] [,17] [,18] [,19] [,20] 78 | x 13 14 15 16 17 18 19 20 79 | y 169 196 225 256 289 324 361 400 80 | } 81 | } 82 | \keyword{programming} -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | auto/ 2 | /vignettes/.RData 3 | /vignettes/Inserting_figures_and_evaluated_examples.tex 4 | /vignettes/Inserting_bibtex_references.tex 5 | /vignettes/auto/ 6 | /auto/ 7 | /R/all.ps 8 | /revdep/ 9 | countr/build/ 10 | /Org/ 11 | /.RData 12 | /.Rhistory 13 | 14 | ## Emacs 15 | .emacs.desktop 16 | .emacs.desktop.lock 17 | *~ 18 | 19 | ## R specific 20 | *.so 21 | *.o 22 | *.dll 23 | .Rproj.user 24 | .Rhistory 25 | .project 26 | .settings/ 27 | inst/doc 28 | 29 | ## Core latex/pdflatex auxiliary files: 30 | *.aux 31 | *.lof 32 | *.log 33 | *.lot 34 | *.fls 35 | *.out 36 | *.toc 37 | *.fmt 38 | *.fot 39 | *.cb 40 | *.cb2 41 | 42 | ## Intermediate documents: 43 | *.dvi 44 | *-converted-to.* 45 | 46 | ## Bibliography auxiliary files (bibtex/biblatex/biber): 47 | *.bbl 48 | *.bcf 49 | *.blg 50 | *-blx.aux 51 | *-blx.bib 52 | *.brf 53 | *.run.xml 54 | 55 | ## Build tool auxiliary files: 56 | *.fdb_latexmk 57 | *.synctex 58 | *.synctex.gz 59 | *.synctex.gz(busy) 60 | *.pdfsync 61 | 62 | ## Auxiliary and intermediate files from other packages: 63 | # algorithms 64 | *.alg 65 | *.loa 66 | 67 | # achemso 68 | acs-*.bib 69 | 70 | # amsthm 71 | *.thm 72 | 73 | # beamer 74 | *.nav 75 | *.snm 76 | *.vrb 77 | 78 | # cprotect 79 | *.cpt 80 | 81 | # fixme 82 | *.lox 83 | 84 | #(r)(e)ledmac/(r)(e)ledpar 85 | *.end 86 | *.?end 87 | *.[1-9] 88 | *.[1-9][0-9] 89 | *.[1-9][0-9][0-9] 90 | *.[1-9]R 91 | *.[1-9][0-9]R 92 | *.[1-9][0-9][0-9]R 93 | *.eledsec[1-9] 94 | *.eledsec[1-9]R 95 | *.eledsec[1-9][0-9] 96 | *.eledsec[1-9][0-9]R 97 | *.eledsec[1-9][0-9][0-9] 98 | *.eledsec[1-9][0-9][0-9]R 99 | 100 | # glossaries 101 | *.acn 102 | *.acr 103 | *.glg 104 | *.glo 105 | *.gls 106 | *.glsdefs 107 | 108 | # gnuplottex 109 | *-gnuplottex-* 110 | 111 | # hyperref 112 | *.brf 113 | 114 | # knitr 115 | *-concordance.tex 116 | # TODO Comment the next line if you want to keep your tikz graphics files 117 | *.tikz 118 | *-tikzDictionary 119 | 120 | # listings 121 | *.lol 122 | 123 | # makeidx 124 | *.idx 125 | *.ilg 126 | *.ind 127 | *.ist 128 | 129 | # minitoc 130 | *.maf 131 | *.mlf 132 | *.mlt 133 | *.mtc 134 | *.mtc[0-9] 135 | *.mtc[1-9][0-9] 136 | 137 | # minted 138 | _minted* 139 | *.pyg 140 | 141 | # morewrites 142 | *.mw 143 | 144 | # mylatexformat 145 | *.fmt 146 | 147 | # nomencl 148 | *.nlo 149 | 150 | # sagetex 151 | *.sagetex.sage 152 | *.sagetex.py 153 | *.sagetex.scmd 154 | 155 | # sympy 156 | *.sout 157 | *.sympy 158 | sympy-plots-for-*.tex/ 159 | 160 | # pdfcomment 161 | *.upa 162 | *.upb 163 | 164 | # pythontex 165 | *.pytxcode 166 | pythontex-files-*/ 167 | 168 | # thmtools 169 | *.loe 170 | 171 | # TikZ & PGF 172 | *.dpth 173 | *.md5 174 | *.auxlock 175 | 176 | # todonotes 177 | *.tdo 178 | 179 | # xindy 180 | *.xdy 181 | 182 | # xypic precompiled matrices 183 | *.xyc 184 | 185 | # endfloat 186 | *.ttt 187 | *.fff 188 | 189 | # Latexian 190 | TSWLatexianTemp* 191 | 192 | ## Editors: 193 | # WinEdt 194 | *.bak 195 | *.sav 196 | 197 | # Texpad 198 | .texpadtmp 199 | 200 | # Kile 201 | *.backup 202 | 203 | # KBibTeX 204 | *~[0-9]* 205 | -------------------------------------------------------------------------------- /man/parse_Rdpiece.Rd: -------------------------------------------------------------------------------- 1 | \name{parse_Rdpiece} 2 | 3 | \alias{parse_Rdpiece} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Parse a piece of Rd source text 9 | } 10 | 11 | \description{ 12 | Parse a piece of Rd source text. 13 | } 14 | 15 | \usage{ 16 | parse_Rdpiece(x, result = "") 17 | } 18 | 19 | %- maybe also 'usage' for other objects documented here. 20 | 21 | \arguments{ 22 | \item{x}{the piece of Rd text, a character vector.} 23 | \item{result}{if "text", converts the result to printable text 24 | (e.g. to be shown to the user), otherwise returns an Rd object.} 25 | } 26 | 27 | \details{ 28 | \code{parse_Rdpiece} parses a piece of source Rd text. The text may be 29 | an almost arbitrary piece that may be inserted in an Rd source file, 30 | except that it should not be a top level section (use 31 | \code{\link{parse_Rdtext}} for sections). Todo: it probably can be 32 | also a parsed piece, check! 33 | 34 | This is somewhat tricky since \code{parse_Rd} does not accept 35 | arbitrary piece of Rd text. It handles either a complete Rd source or 36 | a fragment, defined (as I understand it) as a top level section. To 37 | circumvent this limitation, this function constructs a minimal 38 | complete Rd source putting argument \code{x} in a section (currently 39 | "Note") which does not have special formatting on its own. After 40 | parsing, it extracts only the part corresponding to \code{x}. 41 | 42 | \code{parse_Rdpiece} by default returns the parsed Rd piece. However, 43 | if \code{result="text"}, then the text is formatted as the help system 44 | would do when presenting help pages in text format. 45 | 46 | \strong{TODO:} add an argument for macros? 47 | 48 | } 49 | 50 | \value{ 51 | a parsed Rd piece or its textual representation as described in Details 52 | } 53 | 54 | 55 | 56 | \author{Georgi N. Boshnakov} 57 | 58 | 59 | 60 | 61 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 62 | 63 | 64 | 65 | 66 | \examples{ 67 | # the following creates Rd object rdo 68 | dummyfun <- function(x) x 69 | u1 <- list_Rd(name = "Dummyname", alias = "dummyfun", 70 | title = "Dummy title", description = "Dummy description", 71 | usage = "dummyfun(x,y)", 72 | value = "numeric vector", 73 | author = "A. Author", 74 | Rd_class = TRUE ) 75 | fn <- tempfile("dummyfun", fileext = "Rd") 76 | reprompt(dummyfun, filename = fn) 77 | rdo <- tools::parse_Rd(fn) 78 | 79 | # let's prepare a new item 80 | rd <- "\\\\item{...}{further arguments to be passed on.}" 81 | newarg <- parse_Rdtext(rd, section = "\\\\arguments") 82 | 83 | # now append 'newarg' to the arguments section of rdo 84 | iarg <- which(tools:::RdTags(rdo) == "\\\\arguments") 85 | rdoa <- append_to_Rd_list(rdo, newarg, iarg) 86 | 87 | Rdo_show(rdoa) 88 | 89 | # for arguments and other frequent tasks, there are specialised functions 90 | dots <- paste0("\\\\", "dots") 91 | rdob <- Rdo_append_argument(rdo, dots, "further arguments to be passed on.") 92 | 93 | Rdo_show(reprompt(rdob, filename = fn)) 94 | 95 | unlink(fn) 96 | } 97 | \keyword{RdoProgramming} 98 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | import(methods) 2 | 3 | importFrom(utils, bibentry, browseURL, capture.output, cite, file.edit, 4 | getAnywhere, getS3method, head, help, 5 | packageDescription, packageVersion, person, prompt, vignette) 6 | 7 | importFrom(tools, parse_Rd, toRd, checkRd, Rd2txt, 8 | bibstyle, latexToUtf8, parseLatex, deparseLatex) 9 | #importFrom(grDevices, dev.off, png) 10 | 11 | #importFrom(gbRd, Rd_help2txt) # commented out 2020-11-25 12 | 13 | #importFrom(bibtex, read.bib) 14 | importFrom(rbibutils, readBib) 15 | 16 | S3method(as.character, f_usage) 17 | S3method(print, f_usage) 18 | S3method(print, bibentryRd) 19 | 20 | export( 21 | append_to_Rd_list 22 | , as.character.f_usage 23 | # , bibentry_key 24 | , c_Rd 25 | , char2Rdpiece 26 | , compare_usage1 27 | , deparse_usage 28 | , deparse_usage1 29 | , format_funusage 30 | , get_bibentries 31 | , get_sig_text 32 | , get_usage 33 | , get_usage_text 34 | , insert_ref 35 | , inspect_args 36 | , inspect_clmethods 37 | , inspect_Rd 38 | , inspect_Rdbib 39 | , inspect_Rdclass 40 | , inspect_Rdfun 41 | , inspect_Rdmethods 42 | , inspect_signatures 43 | , inspect_slots 44 | , inspect_usage 45 | , is_Rdsecname 46 | , list_Rd 47 | , pairlist2f_usage1 48 | , parse_1usage_text 49 | , parse_pairlist 50 | , parse_Rdname 51 | , parse_Rdpiece 52 | , parse_Rdtext 53 | # , parse_text 54 | , parse_usage_text 55 | , promptPackageSexpr 56 | , promptUsage 57 | , rattr 58 | , Rd_combo 59 | , Rdapply 60 | , Rdo_append_argument 61 | , Rdo_collect_aliases 62 | , Rdo_comment 63 | , Rdo_drop_empty 64 | , Rdo_empty_sections 65 | , Rdo_flatinsert 66 | , Rdo_flatremove 67 | , Rdo_get_argument_names 68 | , Rdo_get_insert_pos 69 | , Rdo_get_item_labels 70 | , Rdo_insert 71 | , Rdo_insert_element 72 | , Rdo_is_newline 73 | , Rdo_item 74 | , Rdo_locate 75 | , Rdo_locate_core_section 76 | , Rdo_locate_leaves 77 | # , Rdo_locate_leaves2 78 | # , Rdo_locate_predefined_section 79 | , Rdo_macro 80 | , Rdo_macro1 81 | , Rdo_macro2 82 | , Rdo_modify 83 | , Rdo_modify_simple 84 | , Rdo_newline 85 | , Rdo_piece_types 86 | , Rdo_piecetag 87 | , Rdo_predefined_sections 88 | , Rdo_Rcode 89 | , Rdo_remove_srcref 90 | , Rdo_reparse 91 | , Rdo_replace_section 92 | , Rdo_sections 93 | , Rdo_sectype 94 | , Rdo_set_section 95 | , Rdo_show 96 | , Rdo_sigitem 97 | , Rdo_tag 98 | , Rdo_tags 99 | , Rdo_text 100 | , rdo_text_restore 101 | , rdo_top_tags 102 | , Rdo_verb 103 | , Rdo_which 104 | , Rdo_which_tag_eq 105 | , Rdo_which_tag_in 106 | , Rdo2Rdf 107 | , Rdreplace_section 108 | , Rdtagapply 109 | , rebib 110 | , reprompt 111 | , RStudio_reprompt 112 | , S4formals 113 | # , toolsdotdotdot.Rd_drop_nodes_with_tags 114 | # , toolsdotdotdot.Rd_get_metadata 115 | # , toolsdotdotdotfetchRdDB 116 | # , toolsdotdotdotRdTags 117 | , update_aliases_tmp 118 | # , utilsdotdotdot.getHelpFile 119 | , viewRd 120 | , makeVignetteReference 121 | , vigbib 122 | , ereprompt 123 | , insert_citeOnly 124 | , insert_all_ref 125 | , Rdpack_bibstyles 126 | , set_Rdpack_bibstyle 127 | # , run_examples - commenting out until completed 128 | # , insert_fig - commenting out until completed 129 | , Rdo_fetch 130 | ) 131 | -------------------------------------------------------------------------------- /_pkgdown.yml: -------------------------------------------------------------------------------- 1 | url: https://geobosh.github.io/Rdpack 2 | 3 | template: 4 | bootstrap: 5 5 | 6 | search: 7 | exclude: ['news/index.html'] 8 | 9 | reference: 10 | - title: "Rdpack overview" 11 | desc: > 12 | Rdpack overview 13 | contents: 14 | "Rdpack-package" 15 | - title: "Updating and previewing Rd documentation files" 16 | desc: > 17 | Functions for ensuring that the Rd documentation of 18 | functions, methods, classes and other objects is consistent with their 19 | definitions. 20 | contents: 21 | - matches("reprompt") 22 | - viewRd 23 | - promptPackageSexpr 24 | - Rdo_show 25 | - Rdo2Rdf 26 | - title: "Bibtex references and citations" 27 | desc: > 28 | Bibtex references and citations 29 | contents: 30 | - matches("bib") 31 | - insert_all_ref 32 | - insert_ref 33 | - insert_citeOnly 34 | - title: "Replacing parts of Rd objects" 35 | desc: > 36 | Functions to change Rd contents programmatically 37 | contents: 38 | - matches("apply") 39 | - Rdreplace_section 40 | - Rd_combo 41 | - title: "Getting specific parts of Rd objects" 42 | desc: > 43 | Getting specific parts of Rd objects 44 | contents: 45 | - Rdo_tags 46 | - S4formals 47 | - predefined 48 | - title: "Inspecting Rd objects" 49 | desc: > 50 | Functions for inspection of Rd objects 51 | contents: 52 | - inspect_Rd 53 | - inspect_Rdfun 54 | - inspect_Rdmethods 55 | - inspect_Rdclass 56 | - inspect_args 57 | - inspect_clmethods 58 | - inspect_signatures 59 | - inspect_slots 60 | - inspect_usage 61 | - title: "Programming with Rd objects" 62 | desc: > 63 | Functions for use in programmatic manipulation of Rd objects 64 | contents: 65 | - Rdo_get_argument_names 66 | - Rdo_get_insert_pos 67 | - Rdo_get_item_labels 68 | - get_bibentries 69 | - get_sig_text 70 | - get_usage_text 71 | - get_usage 72 | - promptUsage 73 | - title: "Parsing Rd objects" 74 | desc: > 75 | Functions for parsing Rd objects 76 | contents: 77 | - matches("parse") 78 | - title: "Composing Rd objects" 79 | desc: "Functions to put together Rd objects" 80 | contents: 81 | - c_Rd 82 | - list_Rd 83 | - append_to_Rd_list 84 | - char2Rdpiece 85 | - title: "Other" 86 | desc: "Other functions for manipulation of Rd objects" 87 | contents: 88 | - compare_usage1 89 | - format_funusage 90 | - rdo_text_restore 91 | - update_aliases_tmp 92 | - Rdo_append_argument 93 | - Rdo_collect_aliases 94 | - Rdo_empty_sections 95 | - Rdo_fetch 96 | - Rdo_flatinsert 97 | - Rdo_insert 98 | - Rdo_insert_element 99 | - Rdo_is_newline 100 | - Rdo_locate 101 | - Rdo_locate_leaves 102 | - Rdo_macro 103 | - Rdo_modify 104 | - Rdo_modify_simple 105 | - Rdo_piecetag 106 | - Rdo_remove_srcref 107 | - Rdo_sections 108 | - Rdo_set_section 109 | - Rdo_tag 110 | - Rdo_which 111 | -------------------------------------------------------------------------------- /man/deparse_usage.Rd: -------------------------------------------------------------------------------- 1 | \name{deparse_usage} 2 | \alias{deparse_usage} 3 | \alias{deparse_usage1} 4 | \alias{as.character.f_usage} 5 | \title{Convert f_usage objects to text appropriate for usage sections in 6 | Rd files 7 | \Sexpr[stage=build,results=hide]{require(Rdpack)} 8 | } 9 | \description{Converts f_usage objects to text appropriate for usage sections in 10 | Rd files. Handles S3 methods. 11 | } 12 | \usage{ 13 | deparse_usage(x) 14 | deparse_usage1(x, width = 72) 15 | \method{as.character}{f_usage}(x, \dots ) 16 | } 17 | \arguments{ 18 | \item{x}{ 19 | an object from class \code{"f_usage"}. For \code{deparse_usage}, 20 | \code{x} can also be a list of \code{"f_usage"} objects. 21 | } 22 | \item{width}{maximal width of text on a line.} 23 | \item{...}{ignored.} 24 | } 25 | \details{ 26 | 27 | Both, \code{deparse_usage1} and the \code{as.character} method for 28 | class \code{"f_usage"}, convert an \code{"f_usage"} object to a 29 | character string suitable for Rd documentation. The 30 | \code{as.character} method is the user level function (it just calls 31 | \code{deparse_usage1}), \code{deparse_usage1} is internal function for 32 | programming. In the example below the first command creates an 33 | \code{"f_usage"} object, then the second converts it to character string. 34 | 35 | \printExample{(a <- pairlist2f_usage1(formals(cor), "cor"));cat(as.character(a))} 36 | 37 | Each usage entriy is formatted and, if necessary, split over several 38 | lines. The width (number of characters) on a line can be changed with 39 | argument \code{width}. 40 | 41 | \code{deparse_usage} can be used when \code{x} is a list of 42 | \code{"f_usage"} objects. It calls \code{deparse_usage1} with each of 43 | them and returns a character vector with one element for each 44 | component of \code{x}. When \code{x} is an object from class 45 | \code{"f_usage"}, \code{deparse_usage} is equivalent to 46 | \code{deparse_usage1}. 47 | 48 | } 49 | \value{ 50 | For \code{deparse_usage1} and \code{as.character.f_usage}, a named 51 | character vector of length one (the name is the function name). 52 | 53 | For \code{deparse_usage}, a named character vector with one entry for 54 | the usage text for each function. 55 | } 56 | 57 | \author{Georgi N. Boshnakov} 58 | \seealso{ 59 | \code{\link{pairlist2f_usage1}} 60 | } 61 | \examples{ 62 | cur_wd <- getwd() 63 | tmpdir <- tempdir() 64 | setwd(tmpdir) 65 | 66 | ## prepare a list of "f_usage" objects 67 | fnseq <- reprompt(seq) # get and save the help page of "seq" 68 | rdoseq <- tools::parse_Rd(fnseq) # parse the Rd file 69 | ut <- get_usage_text(rdoseq) # get the contents of the usage section 70 | cat(ut, "\n") # of seq() (a character string) 71 | utp <- parse_usage_text(ut) # parse to a list of "f_usage" objects 72 | 73 | ## deparse the "f_usage" list - each statement gets a separate string 74 | cat(deparse_usage(utp), sep = "\n") 75 | 76 | ## explore some of the usage entries individually; 77 | ## the generic seq() has a boring signature 78 | utp[[1]] 79 | as.character(utp[[1]]) 80 | deparse_usage1(utp[[1]]) # same 81 | 82 | ## the default S3 method is more interesting 83 | utp[[2]] 84 | cat(deparse_usage1(utp[[2]])) 85 | cat(as.character(utp[[2]])) # same 86 | 87 | unlink(fnseq) 88 | setwd(cur_wd) 89 | unlink(tmpdir) 90 | } 91 | %\keyword{RdoProgramming} 92 | \keyword{RdoUsage} 93 | %\keyword{RdFunction} 94 | -------------------------------------------------------------------------------- /tests/testthat/test-char2Rdpiece.R: -------------------------------------------------------------------------------- 1 | context("char2Rdpiece") 2 | 3 | test_that("char2Rdpiece works fine", { 4 | ## these two should be identical: 5 | expect_equal_to_reference(char2Rdpiece("graphics", "keyword") 6 | , "char2Rdpiece_a.RDS") 7 | expect_equal_to_reference(char2Rdpiece("graphics", "keyword", force.sec = TRUE) 8 | , "char2Rdpiece_a.RDS") 9 | 10 | expect_equal_to_reference(char2Rdpiece("log(x, base = exp(1))", "usage"), "char2Rdpiece_b.RDS") 11 | expect_equal_to_reference(char2Rdpiece("Give more examples.", "Todo", force.sec = TRUE), "char2Rdpiece_c.RDS") 12 | 13 | }) 14 | 15 | test_that("c_Rd works fine", { 16 | a1 <- char2Rdpiece("Dummyname", "name") 17 | a2 <- char2Rdpiece("Dummyallias1", "alias") 18 | a3 <- char2Rdpiece("Dummy title", "title") 19 | a4 <- char2Rdpiece("Dummy description", "description") 20 | 21 | if(requireNamespace("gbRd")){ 22 | b1 <- c_Rd(gbRd::Rdo_empty(), list(a1), list(a2), list(a3), list(a4)) 23 | b1a <- c_Rd(list(a1), gbRd::Rdo_empty(), list(a2), list(a3), list(a4)) 24 | expect_identical(class(b1), "Rd") 25 | expect_identical(class(b1a), "Rd") 26 | } 27 | 28 | b2 <- c_Rd(list(a1), list(a2), list(a3), list(a4)) 29 | expect_identical(class(b2), "list") 30 | }) 31 | 32 | test_that("get_sig_text works fine", { 33 | setClass("aRdpack") 34 | setClass("bRdpack") 35 | 36 | fn <- tempfile() 37 | on.exit(unlink(fn)) 38 | 39 | ## TODO: the following passes devtools::test() but not 'R CMD check' 40 | ## Why the difference? 41 | 42 | ## only default method defined 43 | #f1 <- function(x, y){NULL} 44 | #setGeneric("f1") 45 | #setGeneric("f1", function(x, y){NULL}) 46 | # 47 | #reprompt("f1", filename = fn) 48 | #rdo <- tools::parse_Rd(fn) 49 | #txt1 <- get_sig_text(rdo) 50 | #expect_equal(class(txt1), "character") 51 | #expect_equal_to_reference(txt1, "get_sig_text_f1.RDS") 52 | 53 | ## several methods defined 54 | #setGeneric("f4", function(x, y){NULL}) 55 | #setMethod("f4", c("numeric", "numeric"), function(x, y){NULL}) 56 | #setMethod("f4", c("aRdpack", "numeric"), function(x, y){NULL}) 57 | #setMethod("f4", c("bRdpack", "numeric"), function(x, y){NULL}) 58 | #setMethod("f4", c("aRdpack", "bRdpack"), function(x, y){NULL}) 59 | # 60 | #reprompt("f4", filename = fn) 61 | #rdo <- tools::parse_Rd(fn) 62 | #txt4 <- get_sig_text(rdo) 63 | #expect_equal(class(txt4), "character") 64 | #expect_equal_to_reference(txt4, "get_sig_text_f4.RDS") 65 | 66 | }) 67 | 68 | test_that("Rdo_fetch works fine", { 69 | somenames <- c("reprompt", "Rdpack-package") 70 | someRdnames <- paste0(somenames, ".Rd") 71 | 72 | ## The no-argument call is mostly for interactive use. 73 | ## (a test here would be artificial) 74 | ## db <- Rdo_fetch() 75 | 76 | db1 <- Rdo_fetch(package = "Rdpack") 77 | expect_equal(class(db1), "list") 78 | expect_true(all(someRdnames %in% names(db1))) 79 | 80 | db2 <- Rdo_fetch(package = "Rdpack", installed = FALSE) 81 | expect_equal(class(db2), "list") 82 | expect_true(all(someRdnames %in% names(db2))) 83 | 84 | db3 <- Rdo_fetch("Rdo_macro", "Rdpack") 85 | expect_equal(class(db3), "Rd") 86 | 87 | db4 <- Rdo_fetch(somenames, "Rdpack", installed = FALSE) 88 | expect_equal(class(db4), "list") 89 | expect_true(setequal(names(db4), someRdnames)) 90 | 91 | }) 92 | 93 | -------------------------------------------------------------------------------- /man/Rdo_fetch.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_fetch} 2 | \alias{Rdo_fetch} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Get help pages as Rd objects} 5 | \description{ 6 | Get a help page as an Rd object from an installed or source package. 7 | } 8 | \usage{ 9 | Rdo_fetch(Rd_name = character(0), package, dir = ".", installed = TRUE) 10 | } 11 | \arguments{ 12 | \item{Rd_name}{ 13 | names of one or more Rd help pages. \code{name} here is the name of 14 | an Rd file stripped from the extension. 15 | } 16 | \item{package}{ 17 | the package from which to get the Rd object, a character string. 18 | } 19 | \item{dir}{ 20 | a character string giving the root directory of a source package. 21 | Used only if \code{package} is missing. 22 | } 23 | \item{installed}{ 24 | if \code{TRUE}, the default, the Rd object is taken unconditionally 25 | from the installed \code{package}. 26 | If \code{FALSE}, the help page may be taken from a source tree, if 27 | appropriate (typically if \code{package} is in `developer's mode 28 | under devtools, see Details). 29 | } 30 | } 31 | \details{ 32 | 33 | If \code{Rd_name} is a character string (typical use case), the 34 | corresponding help page is returned as an object from class 35 | \code{"Rd"}. If the length of \code{Rd_name} is greater than one, the 36 | result is a Rd_named list containing the corresponding \code{"Rd"} 37 | objects. The default \code{Rd_name = character(0)} requests all Rd 38 | pages in the package. 39 | 40 | Note that \code{Rd_name} does not contain the extention \code{".Rd"} 41 | but the names in the returned list do. 42 | 43 | Argument \code{package} names the package from which to fetch the 44 | documentation object. With the default \code{installed = TRUE} the 45 | object is taken unconditionally from the installed package. To get it 46 | from the source tree of a package, use argument \code{"dir"} instead. 47 | The default, \code{""}, for \code{dir} is suitable for workflows where 48 | the working directory is the root of the desired package. 49 | 50 | Argument \code{installed} concerns primarily development under package 51 | \code{"devtools"}. \code{"devtools"} intercepts and modifies several 52 | base \R commands, concerning access to system files and getting help, 53 | with the aim of rerouting them to the source trees of packages under 54 | developer's mode. If argument \code{installed} is \code{TRUE}, the 55 | default, the requested pages are taken from the installed package, 56 | even if it is in development mode. If argument \code{installed} is 57 | \code{FALSE}, the Rd objects are taken from the corresponding source 58 | tree, if the specified package is under developer's mode, and from the 59 | installed package otherwise. 60 | 61 | Argument \code{Rd_name} is the name used in the \code{\\name} section 62 | of Rd files. 63 | 64 | When working off the source tree of a package, \code{Rdo_fetch} 65 | processes the Rd files, so \code{roxygen2} users need to update 66 | them if necessary. 67 | 68 | } 69 | \value{ 70 | if \code{length(Rd_name) = 1}, an object of class \code{"Rd"}, 71 | otherwise a list of \code{"Rd"} objects. 72 | } 73 | \author{Georgi N. Boshnakov} 74 | %\seealso{ 75 | %%% ~~objects to See Also as \code{\link{help}}, ~~~ 76 | %} 77 | \examples{ 78 | ## get a single help page 79 | rdo <- Rdo_fetch("viewRd", package = "Rdpack") 80 | Rdo_show(rdo) 81 | 82 | ## get a list of help pages 83 | rdo <- Rdo_fetch(c("viewRd", "reprompt"), package = "Rdpack") 84 | names(rdo) 85 | } 86 | \keyword{documentation} 87 | % use one of RShowDoc("KEYWORDS") 88 | -------------------------------------------------------------------------------- /man/predefined.Rd: -------------------------------------------------------------------------------- 1 | \name{predefined} 2 | \alias{Rdo_predefined_sections} 3 | \alias{Rdo_piece_types} 4 | \alias{rdo_top_tags} 5 | 6 | \title{ 7 | Tables of predefined sections and types of pieces of Rd objects 8 | } 9 | \description{ 10 | Tables of predefined sections and types of pieces of Rd objects. 11 | } 12 | \usage{ 13 | Rdo_predefined_sections 14 | 15 | Rdo_piece_types 16 | 17 | rdo_top_tags 18 | } 19 | \details{ 20 | 21 | The Rd syntax defines several tables 22 | \insertCite{parseRd}{Rdpack}. \pkg{Rdpack} stores them in the 23 | variables described here. 24 | 25 | \code{Rdo_predefined_sections} is a named character vector providing 26 | the types of the top level sections in an Rd object. 27 | 28 | \code{Rdo_piece_types} is a named character vector giving the types of 29 | the core (all possible?) Rd macros. 30 | 31 | \strong{NOTE:} These objects are hard coded and need to be updated if 32 | the specifications of the Rd format are updated. 33 | 34 | todo: write functions that go through existing Rd documentation to 35 | discover missing or wrong items. 36 | } 37 | \value{ 38 | 39 | for \code{Rdo_predefined_sections}, the name-value pairs are given in 40 | the following table. For example, \code{Rdo_predefined_sections["examples"]} results 41 | in \Sexpr[stage=build,results=rd]{Rdo_predefined_sections["examples"]}. 42 | 43 | \Sexpr[stage=build,results=rd]{require(Rdpack); 44 | paste( 45 | "\\\\ifelse{latex}{\\\\out{", 46 | "\\\\begin{tabular}{ll|lll}", 47 | paste(names(Rdo_predefined_sections)[1:5], Rdo_predefined_sections[1:5], 48 | " ", 49 | names(Rdo_predefined_sections)[-(1:5)], Rdo_predefined_sections[-(1:5)], 50 | sep=" & ", collapse="\\\\\\\\\\\\\\\\ \n"), 51 | "\\\\end{tabular}", 52 | "}}{", 53 | "\\\\tabular{lllll}{", 54 | paste(names(Rdo_predefined_sections)[1:5], Rdo_predefined_sections[1:5], 55 | " | ", 56 | names(Rdo_predefined_sections)[-(1:5)], Rdo_predefined_sections[-(1:5)], 57 | sep=" \\\\tab ", collapse="\\\\cr\n"), 58 | "}", 59 | 60 | "}" 61 | 62 | )} 63 | 64 | for \code{Rdo_piece_types}, the name-value pairs are: 65 | 66 | \Sexpr[stage=build,results=rd]{ 67 | paste( 68 | "\\\\ifelse{latex}{\\\\out{", 69 | "\\\\begin{tabular}{ll|ll|ll}", 70 | paste(names(Rdo_piece_types), " & ", Rdo_piece_types, c(rep(" & ",2),"\\\\\\\\\\\\\\\\"), 71 | sep="", collapse="\n"), 72 | "\\\\end{tabular}", 73 | "}}{", 74 | 75 | "\\\\tabular{llllllllllll}{", 76 | paste(names(Rdo_piece_types), "\\\\tab ", Rdo_piece_types, 77 | c(rep(paste("\\\\tab ", "|", sep=""),2), 78 | "\\\\cr"), 79 | sep="", collapse="\n"), 80 | "}", 81 | 82 | 83 | "}" 84 | 85 | )} 86 | 87 | for \code{rdo_top_tags}, the values are: 88 | 89 | \Sexpr[stage=build,results=rd]{ 90 | tmp_rdo_top_tags <- rdo_top_tags 91 | tmp_incomplete <- length(tmp_rdo_top_tags) \%\% 5 92 | if(tmp_incomplete != 0) 93 | tmp_rdo_top_tags <- c(tmp_rdo_top_tags, rep("''", 5 - tmp_incomplete)) 94 | paste("\\\\tabular{lllll}{", 95 | paste(sub("^[#]", "\\\\\\\\verb{#}", sub("^([\\\\])", "\\\\\\\\\\\\1", tmp_rdo_top_tags)), 96 | c(rep("\\\\tab ",4),"\\\\cr"), 97 | sep="", collapse="\n"), 98 | "}")} 99 | 100 | Note that most, but not all, are prefixed with a backslash. 101 | } 102 | \references{ 103 | \insertAllCited{} 104 | } 105 | \keyword{Rd} 106 | -------------------------------------------------------------------------------- /R/promptSexpr.R: -------------------------------------------------------------------------------- 1 | # like promptPackage but uses \Sexpr{} for automatic information updating 2 | promptPackageSexpr <- function(package, filename= NULL, final = TRUE, overview = FALSE, 3 | bib = TRUE){ # 2013-03-30 neew arg. `bib' 4 | paste0 <- function(...) paste(..., sep="") 5 | 6 | overv <- if(overview | !final) "" else "% " 7 | hide <- "\\Sexpr[stage=build,results=hide]" 8 | pd <- paste0("{pd <- packageDescription(\"", package, "\")}") 9 | lb <- paste0("{lb <- library(help=\"", package, "\", character.only=TRUE)}") 10 | lbflag <- "lbflag <- !is.null(lb$info[[2]])" 11 | 12 | Rdtxt <- 13 | list( paste0("\\name{", package, "-package}") 14 | , paste0("\\alias{", package, "-package}") 15 | , paste0("\\alias{", package, "}") 16 | , paste0("\\docType{", "package", "}") 17 | , "\\title{" 18 | , paste0(" ", hide, c(pd, lb)) # init. commands, cannot be outside sections. 19 | , " \\Sexpr[stage=build]{pd$Title}" 20 | , "}" 21 | , "\\description{" 22 | , " \\Sexpr[stage=build]{pd$Description}" 23 | , "}" 24 | , "\\details{" 25 | , " \\tabular{ll}{" 26 | , " Package: \\tab \\Sexpr[stage=build]{pd$Package}\\cr" 27 | , " Type: \\tab \\Sexpr[stage=build]{pd$Type}\\cr" 28 | , " Version: \\tab \\Sexpr[stage=build]{pd$Version} \\cr" 29 | , " Date: \\tab \\Sexpr[stage=build]{pd$Date}\\cr" 30 | , " License: \\tab \\Sexpr[stage=build]{pd$License}\\cr" 31 | , " LazyLoad: \\tab \\Sexpr[stage=build]{pd$LazyLoad}\\cr" 32 | , " Built: \\tab \\Sexpr[stage=build]{pd$Built}\\cr" 33 | , " }" 34 | , "" 35 | , " Index:" 36 | , paste0(" \\Sexpr[stage=build,results=rd]{paste(\"\\\\\\\\preformatted{\"" 37 | , ", paste(if(!is.null(lb$info[[2]])) lb$info[[2]] else \"No entries\",collapse=\"\\n\"), \"}\", sep=\"\")}") 38 | , "" 39 | , paste0(overv, c("~~ An overview of how to use the package, including the most important ~~" 40 | , "~~ functions ~~")) 41 | , "}" 42 | , "\\author{" 43 | , " \\Sexpr[stage=build]{pd$Author}" 44 | , "" 45 | , paste0("Maintainer: ", "\\Sexpr[stage=build]{pd$Maintainer}") 46 | , "}" 47 | , "\\references{" 48 | , if(bib) "% bibentry:all" 49 | else "% ~~ Literature or other references for background information ~~" 50 | , "}" 51 | , "% ~~ Optionally other standard keywords, one per line, from file KEYWORDS in ~~" 52 | , "% ~~ the R documentation directory ~~" 53 | , "\\keyword{ package }" 54 | , "% \\seealso{" 55 | , "% ~~ Optional links to other man pages, e.g. ~~" 56 | , "% ~~ \\code{\\link[:-package]{}} ~~" 57 | , "% }" 58 | , "% \\examples{" 59 | , "% ~~ simple examples of the most important functions ~~" 60 | , "% }" 61 | ) 62 | if(is.null(filename)) 63 | filename <- paste0(package, "-package.Rd") 64 | 65 | if(is.na(filename)) 66 | return(Rdtxt) 67 | 68 | cat(unlist(Rdtxt), file = filename, sep = "\n") 69 | 70 | message(gettextf("Created file named %s.", sQuote(filename)), 71 | "\n", 72 | gettext("Edit the file and move it to the appropriate directory."), 73 | domain = NA) 74 | 75 | invisible(filename) 76 | } 77 | -------------------------------------------------------------------------------- /man/Rdo_sections.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_sections} 2 | \alias{Rdo_sections} 3 | \alias{Rdo_locate_core_section} 4 | \title{Locate the sections in Rd objects} 5 | \description{Locate the Rd sections in an Rd object and return a list of 6 | their positions and names.} 7 | \usage{ 8 | Rdo_sections(rdo) 9 | 10 | Rdo_locate_core_section(rdo, sec) 11 | } 12 | \arguments{ 13 | \item{rdo}{an Rd object.} 14 | \item{sec}{the name of a section, a character string. For builtin 15 | sections the leading backslash should be included.} 16 | } 17 | \details{ 18 | 19 | \code{Rdo_sections} locates all sections at the top level in an Rd 20 | object. This includes the predefined sections and the user defined 21 | sections. Sections wrapped in \verb{#ifdef} directives are also found. 22 | 23 | \code{Rdo_sections} returns a list with one entry for each section in 24 | \code{rdo}. This entry is a list with components \code{"pos"} and 25 | \code{"title"} giving the position (suitable for use in \verb{"[["}) 26 | and the title of the section. For user defined sections the actual 27 | name is returned, not "section". 28 | 29 | The names of the sections are returned as single strings without 30 | attributes. The titles of predefined sections are single words but 31 | user defined sections may have longer titles and sometimes contain 32 | basic markup. 33 | 34 | \code{Rdo_locate_core_section} works similarly but returns only the 35 | results for section \code{sec}. Currently it simply calls 36 | \code{Rdo_sections} and returns only the results for \code{sec}. 37 | 38 | Note that for consistency \code{Rdo_locate_core_section} does not 39 | attempt to simplify the result in the common case when there is only 40 | one instance of the requested section---it is put in a list of length 41 | one. 42 | 43 | \insertCite{parseRd}{Rdpack} % only for testing! 44 | \insertCite{Rpack:bibtex}{Rdpack} % only for testing! 45 | 46 | } 47 | \value{ 48 | A list giving the positions and titles of the sections in \code{rdo} 49 | as described in 'Details'. The format is essentially that of 50 | \code{\link{Rdo_locate}}, the difference being that field "value" 51 | from that function is renamed to "title" here. 52 | 53 | \item{pos}{the position, a vector of positive integers,} 54 | \item{title}{a standard section name, such as \verb{"\\name"} or, in 55 | the case of "\\section", the actual title of the section. 56 | } 57 | } 58 | \author{Georgi N. Boshnakov} 59 | \note{ 60 | 61 | I wrote \code{Rdo_sections} and \code{Rdo_locate_core_section} after 62 | most of the core functionality was tested. Currently these functions 63 | are underused---they can replace a number of internal and exported 64 | functions. 65 | 66 | } 67 | \seealso{ 68 | \code{\link{Rdo_locate}} 69 | } 70 | \references{ 71 | \insertAllCited{} % only for testing 72 | } 73 | \examples{ 74 | infile <- system.file("examples", "tz.Rd", package = "Rdpack") 75 | rd <- tools::parse_Rd(infile) 76 | 77 | ## Locate all top level sections in rd 78 | sections <- Rdo_sections(rd) 79 | ## How many sections there are in rd? 80 | length(sections) 81 | ## What are their titles? 82 | sapply(sections, function(x) x$title) 83 | 84 | ## The names of builtin sections include the backslash 85 | Rdo_locate_core_section(rd, "\\\\title") 86 | 87 | ## Locate a user defined secion 88 | Rdo_locate_core_section(rd, "Further information") 89 | 90 | ## The names of builtin sections include the backslash 91 | Rdo_locate_core_section(rd, "\\\\details") 92 | 93 | ## All appearances of the requested section are returned 94 | Rdo_locate_core_section(rd, "\\\\alias") 95 | Rdo_locate_core_section(rd, "\\\\keyword") 96 | } 97 | \keyword{Rd} 98 | 99 | 100 | -------------------------------------------------------------------------------- /R/predefined.R: -------------------------------------------------------------------------------- 1 | .rd_sections <- # note: user defined sections are typeset before note, seealso, examples. 2 | c("\\name", "\\Rdversion", "\\docType", "\\alias", "\\encoding", "\\concept", 3 | "\\title", "\\description", "\\usage", "\\format", "\\source", "\\arguments", 4 | "\\details", "\\value", "\\references", "\\section", 5 | "\\note", "\\author", "\\seealso", "\\examples", "\\keyword") 6 | 7 | ## todo: "\\Sexpr", "\\Rdopts", "\\newcommand", "\\renewcommand" 8 | 9 | rdo_top_tags <- unique(c(.rd_sections, 10 | "#ifdef", "#ifndef", 11 | "\\newcommand", "\\renewcommand", 12 | "COMMENT", "TEXT" 13 | )) 14 | 15 | 16 | Rdo_piece_types <- c( name = "VERB" # sections 17 | , alias = "VERB" 18 | , concept = "TEXT" 19 | , docType = "TEXT" 20 | , title = "TEXT" 21 | , description = "TEXT" 22 | , examples = "RCODE" 23 | , usage = "RCODE" 24 | , Rdversion = "VERB" 25 | , synopsis = "VERB" 26 | 27 | , Sexpr = "RCODE" 28 | , RdOpts = "VERB" 29 | 30 | , code = "RCODE" # macros 31 | , dontshow = "RCODE" 32 | , donttest = "RCODE" 33 | , testonly = "RCODE" 34 | 35 | , dontrun = "VERB" 36 | , env = "VERB" 37 | , kbd = "VERB" 38 | , option = "VERB" 39 | , out = "VERB" 40 | , preformatted = "VERB" 41 | , samp = "VERB" 42 | , special = "VERB" 43 | , url = "VERB" 44 | , verb = "VERB" 45 | , deqn = "VERB" 46 | , eqn = "VERB" 47 | , renewcommand = "VERB" 48 | , newcommand = "VERB" 49 | ) 50 | 51 | # todo: not complete. Skaniray instalirana 52 | # dokumentatsiya za tezi raboti! 53 | Rdo_predefined_sections <- c( name = "VERB" 54 | , alias = "VERB" 55 | , concept = "TEXT" 56 | , docType = "TEXT" 57 | , title = "TEXT" 58 | , description = "TEXT" 59 | , examples = "RCODE" 60 | , usage = "RCODE" 61 | , Rdversion = "VERB" 62 | , synopsis = "VERB" 63 | , section = "TEXT" # not clear what to put for this element 64 | # (and the following) 2012-09-23 new entries below. (maybe 65 | # their absence was the reason for some strange behaviour of 66 | # char2Rdpiece). Slagam vsichkite "TEXT", no (todo:) tryabva da 67 | # se proveri. 68 | , arguments = "TEXT" 69 | , keyword = "TEXT" 70 | , note = "TEXT" 71 | 72 | , format = "TEXT" 73 | , source = "TEXT" 74 | , details = "TEXT" 75 | , value = "TEXT" 76 | , references = "TEXT" 77 | , author = "TEXT" 78 | , seealso = "TEXT" 79 | ) 80 | -------------------------------------------------------------------------------- /man/Rdo_locate.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_locate} 2 | \alias{Rdo_locate} 3 | \title{Find positions of elements in an Rd object} 4 | \description{ 5 | Find positions of elements for which a function returns 6 | TRUE. Optionally, apply another function to the selected elements and 7 | return the results along with the positions. 8 | } 9 | \usage{ 10 | Rdo_locate(object, f = function(x) TRUE, pos_only = TRUE, 11 | lists = FALSE, fpos = NULL, nested = TRUE) 12 | } 13 | \arguments{ 14 | \item{object}{an Rd object} 15 | \item{f}{a function returning TRUE if an element is desired and FALSE 16 | otherwise.} 17 | \item{pos_only}{if TRUE, return only the positions; if this argument 18 | is a function, return also the result of applying the function to 19 | the selected element, see Details.} 20 | \item{lists}{if FALSE, examine only leaves, if TRUE, examine also 21 | lists, see Details.} 22 | \item{fpos}{a function with two arguments, \code{object} 23 | and position, it is called and the value is returned along with the 24 | position, see Details.} 25 | 26 | \item{nested}{a logical value, it has effect only when \code{lists} is 27 | TRUE, see `Details'. 28 | } 29 | } 30 | \details{ 31 | 32 | With the default setting of \code{lists = FALSE}, the function 33 | \code{f} is applied to each leave (a character string) of the Rd 34 | object. If \code{lists = TRUE} the function \code{f} is applied also 35 | to each branch (a list). In this case, argument \code{nested} controls 36 | what happens when \code{f} returns TRUE. If \code{nested} is TRUE, 37 | each element of the list is also inspected recursively, otherwise this 38 | is not done and, effectively, the list is considered a leaf. If 39 | \code{f} does not return TRUE, the value of \code{nested} has no 40 | effect and the elements of the list are inspected. 41 | 42 | The position of each object for which \code{f} returns TRUE is 43 | recorded as a numeric vector. 44 | 45 | \code{fpos} and \code{pos_only} provide two ways to do something with 46 | the selected elements. Argument \code{fpos} is more powerful than 47 | \code{pos_only} but the latter should be sufficient and simpler to use 48 | in most cases. 49 | 50 | If \code{fpos} is a function, it is applied to each selected element 51 | with two arguments, \code{object} and the position, and the result 52 | returned along with the position. In this case argument 53 | \code{pos_only} is ignored. If \code{fpos} is NULL the action depends 54 | on \code{pos_only}. 55 | 56 | If \code{pos_only = TRUE}, \code{Rdo_locate} returns a list of such 57 | vectors (not a matrix since the positions of the leaves are, in 58 | general, at different depths). 59 | 60 | If \code{pos_only} is a function, it is applied to each selected 61 | element and the result returned along with the position. 62 | } 63 | \value{ 64 | a list with one entry for each selected element. Each entry is a 65 | numeric vector or a list with two elements: 66 | \item{pos}{the position, a vector of positive integers,} 67 | \item{value}{the result of applying the function to the element at 68 | \code{pos}.} 69 | } 70 | \author{Georgi N. Boshnakov} 71 | \note{ 72 | The following needs additional thought. 73 | 74 | In some circumstances an empty list, tagged with \code{Rd_tag} may 75 | turn up, e.g. \code{list()} with \verb{Rd_tag="\\dots"} in an 76 | \verb{\\arguments} section. 77 | 78 | On the one hand this is a list. On the other hand it may be considered 79 | a leaf. It is not clear if any attempt to recurse into such a list 80 | should be made at all. 81 | } 82 | \seealso{ 83 | \code{\link{Rdo_sections}} and 84 | \code{\link{Rdo_locate_core_section}} 85 | which locate top level sections 86 | } 87 | 88 | \examples{ 89 | # todo: put examples here! 90 | } 91 | \keyword{Rd} 92 | -------------------------------------------------------------------------------- /man/promptPackageSexpr.Rd: -------------------------------------------------------------------------------- 1 | \name{promptPackageSexpr} 2 | \alias{promptPackageSexpr} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Generates a shell of documentation for an installed package} 5 | \description{ 6 | Generates a shell of documentation for an installed package. The 7 | content is similar to `promptPackage' but information that can be 8 | computed is produced with Sexpr's so that it is always up to date. 9 | } 10 | \usage{ 11 | promptPackageSexpr(package, filename = NULL, final = TRUE, 12 | overview = FALSE, bib = TRUE) 13 | } 14 | %- maybe also 'usage' for other objects documented here. 15 | \arguments{ 16 | \item{package}{name of a package, a string} 17 | \item{filename}{name of a file where to write the generated Rd 18 | content, a string. The default should be sufficient in most cases.} 19 | \item{final}{logical; if \code{TRUE} the content should be usable 20 | without manual editing.} 21 | \item{overview}{logical; if \code{TRUE} creates sections with hints 22 | what to put in them, otherwise such sections are written to the file 23 | but are commented out.} 24 | \item{bib}{If TRUE, create a comment line in the references section 25 | that will cause \code{\link{rebib}} to import all references from 26 | the default bib file. 27 | } 28 | } 29 | \details{ 30 | The generated skeleton is functionally (almost) equivalent to that 31 | produced by \code{promptPackage}. The difference is that while 32 | \code{promptPackage} computes some information and inserts it verbatim 33 | in the skeleton, \code{promptPackageSexpr} inserts Sexpr's for the 34 | computation of the same information at package build time. 35 | 36 | In this way there is no need to manually update information like the 37 | version of the package. The index of functions (which contains 38 | their descriptions) does not need manual updating, as well. 39 | 40 | 41 | \code{promptPackageSexpr} needs to be called only once to create the 42 | initial skeleton. Then the Rd file can be edited as needed. 43 | 44 | If the Rd file is generated with the option \code{bib = TRUE} (or the 45 | appropriate lines are added to the refernces section manually) the 46 | references can be updated at any time by a call of \code{rebib}. 47 | 48 | 49 | todo: At the moment \code{final=FALSE} has the effect 50 | described for \code{overview}. At the time of writing this 51 | (2011-11-18) I do not remember if this is intentional or the 52 | corresponding `if' clause contains \code{|} by mistake. 53 | } 54 | \value{ 55 | the name of the file (invisibly) 56 | } 57 | 58 | \author{Georgi N. Boshnakov} 59 | \note{ 60 | The automatically generated information is that of the installed (or 61 | at least built) package. Usually this is not a problem (and this is 62 | the idea of the function) but it means that if a developer is adding 63 | documentation for previously undocumented functions, they will appear 64 | in the 'Index' section only after the package is installed 65 | again. Similarly, if the description file of the package is changed, 66 | the package needs to be installed again for the changes to appear in 67 | the overview. Since the documentation is installed together with the 68 | package this is no surprise, of course. This may only cause a problem 69 | if documentation is produced with \code{R CMD Rd2pdf} before the 70 | updated version is installed. 71 | 72 | This function is not called \code{repromptXXX} since the idea is that 73 | it is called only once and then the Rd file can be edited freely, see 74 | also `Details'. 75 | } 76 | 77 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 78 | 79 | 80 | 81 | % Add one or more standard keywords, see file 'KEYWORDS' in the 82 | % R documentation directory. 83 | \keyword{Rd} 84 | -------------------------------------------------------------------------------- /man/parse_pairlist.Rd: -------------------------------------------------------------------------------- 1 | \name{parse_pairlist} 2 | \alias{parse_pairlist} 3 | %\alias{pairlist2f_usage} 4 | \alias{pairlist2f_usage1} 5 | \title{ 6 | Parse formal arguments of functions 7 | \Sexpr[stage=build,results=hide]{require(Rdpack)} 8 | } 9 | \description{Parse formal arguments of functions and convert them to 10 | f_usage objects.} 11 | \usage{ 12 | parse_pairlist(x) 13 | 14 | pairlist2f_usage1(x, name, S3class = "", S4sig = "", infix = FALSE, 15 | fu = TRUE) 16 | } 17 | \arguments{ 18 | \item{x}{a pairlist representing the arguments of a function.} 19 | \item{name}{function name.} 20 | \item{S3class}{S3 class, see `Details'} 21 | \item{S4sig}{S4 signature, see Details.} 22 | \item{infix}{if \code{TRUE} the function usage is in infix form, see 23 | Details.} 24 | \item{fu}{if TRUE the object is a function, otherwise it is something 25 | else (e.g. a variable or a constant like \code{pi} and \code{Inf}). 26 | } 27 | } 28 | \details{ 29 | These functions are mostly internal. 30 | 31 | % \code{x} is a single pairlist object for \code{parse_pairlist} and 32 | % \code{pairlist2f_usage1}. 33 | % For \code{pairlist2f_usage} it may be a list of pairlist objects. 34 | % (\code{pairlist2f_usage} has been removed) 35 | 36 | \code{parse_pairlist} parses the pairlist object, \code{x}, into a 37 | list with two components. The first component contains the names of 38 | the arguments. The second component is a named list containing the 39 | default values, converted to strings. Only arguments with default 40 | values have entries in the second component (so, it may be of length 41 | zero). If \code{x} is empty or \code{NULL}, both components have 42 | length zero. An example: 43 | \printExample{parse_pairlist(formals(system.file))} 44 | 45 | \code{pairlist2f_usage1()} creates an object of S3 class 46 | \code{"f_usage"}. The object contains the result of parsing \code{x} 47 | with \code{parse_pairlist(x)} and a number of additional components 48 | which are copies of the remaining arguments to the function (without 49 | any processing). The components are listed in section Values. 50 | \code{S3class} is set to an S3 class for for S3 methods, \code{S4sig} 51 | is the signature of an S4 method (as used in Rd macro 52 | \verb{\S4method}). \code{infix} is \code{TRUE} for the rare occations 53 | when the function is primarily used in infix form. 54 | 55 | Class \code{"f_usage"} has a method for \code{as.character()} which 56 | generates a text suitable for inclusion in Rd documentation. 57 | \printExample{pairlist2f_usage1(formals(summary.lm), "summary", S3class = "lm")} 58 | 59 | } 60 | \value{ 61 | For \code{parse_pairlist}, a list with the following components: 62 | \item{argnames}{the names of all arguments, a character vector} 63 | \item{defaults}{ 64 | a named character vector containing the default values, converted to 65 | character strings. Only arguments with defaults have entries in this 66 | vector. 67 | } 68 | 69 | For \code{pairlist2f_usage1}, an object with S3 class 70 | \code{"f_usage"}. This is a list as for \code{parse_pairlist} and 71 | the following additional components: 72 | 73 | \item{name}{function name, a character string.} 74 | \item{S3class}{ 75 | S3 class, a character string; \code{""} if not an S3 method. 76 | } 77 | \item{S4sig}{S4 signature; \code{""} if not an S4 method.} 78 | \item{infix}{a logical value, \code{TRUE} for infix operators.} 79 | \item{fu}{ 80 | indicates the type of the object, usually \code{TRUE}, see Details. 81 | } 82 | 83 | % For \code{pairlist2f_usage}, a list of \code{"f_usage"} objects. 84 | } 85 | \author{Georgi N. Boshnakov} 86 | \seealso{ 87 | \code{\link{promptUsage}} accepts \code{f_usage} objects, 88 | \code{\link{get_usage}} 89 | } 90 | \examples{ 91 | parse_pairlist(formals(lm)) 92 | parse_pairlist(formals(system.file)) 93 | s_lm <- pairlist2f_usage1(formals(summary.lm), "summary", S3class = "lm") 94 | s_lm 95 | as.character(s_lm) 96 | } 97 | \keyword{RdoBuild} 98 | -------------------------------------------------------------------------------- /tests/testthat/classRepresentation-class.Rd: -------------------------------------------------------------------------------- 1 | \name{classRepresentation-class} 2 | \alias{classRepresentation-class} 3 | \title{Class Objects } 4 | \description{ These are the objects that hold the definition of 5 | classes of objects. They are constructed and stored as meta-data by 6 | calls to the function \code{\link{setClass}}. Don't manipulate them 7 | directly, except perhaps to look at individual slots. } 8 | \details{ 9 | Class definitions are stored as metadata in various packages. 10 | Additional metadata supplies information on inheritance (the result of 11 | calls to \code{\link{setIs}}). Inheritance information implied by the 12 | class definition itself (because the class contains one or more other 13 | classes) is also constructed automatically. 14 | 15 | When a class is to be used in an R session, this information is 16 | assembled to complete the class definition. The completion is a 17 | second object of class \code{"classRepresentation"}, cached for the 18 | session or until something happens to change the information. A call 19 | to \code{\link{getClass}} returns the completed definition of a class; 20 | a call to \code{\link{getClassDef}} returns the stored definition 21 | (uncompleted). 22 | 23 | In particular, completion fills in the upward- and downward-pointing 24 | inheritance information for the class, in slots \code{contains} and 25 | \code{subclasses} respectively. It's in principle important to note 26 | that this information can depend on which packages are installed, 27 | since these may define additional subclasses or superclasses. 28 | } 29 | \section{Slots}{ 30 | \describe{ 31 | \item{\code{slots}:}{A named list of the slots in this class; the 32 | elements of the list are the classes to which the slots must 33 | belong (or extend), and the names of the list gives the 34 | corresponding slot names.} 35 | \item{\code{contains}:}{A named list of the classes this class 36 | \sQuote{contains}; the elements of the list are objects of 37 | \code{\linkS4class{SClassExtension}}. The list may be only the 38 | direct extensions or all the currently known extensions (see the 39 | details).} 40 | \item{\code{virtual}:}{Logical flag, set to \code{TRUE} if this is 41 | a virtual class.} 42 | \item{\code{prototype}:}{The object that represents the standard 43 | prototype for this class; i.e., the data and slots returned by a 44 | call to \code{\link{new}} for this class with no special 45 | arguments. Don't mess with the prototype object directly.} 46 | \item{\code{validity}:}{Optionally, a function to be used to test 47 | the validity of objects from this class. 48 | See \code{\link{validObject}}.} 49 | \item{\code{access}:}{Access control information. Not currently used.} 50 | \item{\code{className}:}{The character string name of the class.} 51 | \item{\code{package}:}{The character string name of the package to 52 | which the class belongs. Nearly always the package on which the 53 | metadata for the class is stored, but in operations such as 54 | constructing inheritance information, the internal package name 55 | rules.} 56 | \item{\code{subclasses}:}{A named list of the classes known to 57 | extend this class'; the elements of the list are objects of class 58 | \code{\linkS4class{SClassExtension}}. The list is currently only 59 | filled in when completing the class definition (see the details).} 60 | \item{\code{versionKey}:}{Object of class \code{"externalptr"}; 61 | eventually will perhaps hold some versioning information, but not 62 | currently used. } 63 | \item{\code{sealed}:}{Object of class \code{"logical"}; is this 64 | class sealed? If so, no modifications are allowed. } 65 | } 66 | } 67 | \seealso{ 68 | See function \code{\link{setClass}} to supply the information in the 69 | class definition. 70 | See \link{Classes_Details} for a more basic discussion of class information. 71 | } 72 | \keyword{classes} -------------------------------------------------------------------------------- /man/get_sig_text.Rd: -------------------------------------------------------------------------------- 1 | \name{get_sig_text} 2 | 3 | \alias{get_sig_text} 4 | 5 | %- Also NEED an '\alias' for EACH other topic documented here. 6 | 7 | \title{ 8 | Produce the textual form of the signatures of available methods for 9 | an S4 generic function 10 | \Sexpr[stage=build,results=hide]{require(Rdpack)} 11 | } 12 | 13 | \description{ 14 | Produce the textual form of the signatures of available methods for 15 | an S4 generic function. 16 | } 17 | 18 | \usage{ 19 | get_sig_text(rdo, package = NULL) 20 | } 21 | 22 | %- maybe also 'usage' for other objects documented here. 23 | 24 | \arguments{ 25 | \item{rdo}{an Rd object.} 26 | \item{package}{if of class "character", give only methods defined by 27 | \code{package}, otherwise give all methods. 28 | } 29 | } 30 | 31 | \details{ 32 | Signatures are found using function \code{findMethodSignatures} from 33 | package "methods". 34 | 35 | 36 | Here we find all methods for \code{show()} defined in package 37 | \code{"methods"} and print the first few of them: 38 | \printExample{fn <- utils::help("show-methods", package = "methods"); rdo <- utils:::.getHelpFile(fn); head(get_sig_text(rdo))} 39 | 40 | } 41 | 42 | \value{ 43 | A character vector with one element for each method. 44 | } 45 | 46 | 47 | 48 | \author{Georgi N. Boshnakov} 49 | 50 | \note{ 51 | todo: It would be better to call promptMethods() to get the signatures 52 | but in version R-2.13.x I had trouble with argument `where' (could not 53 | figure out how to use it to restrict to functions from a package; also, 54 | promptMethods() seemed to call the deprecated function 55 | getMethods()). Check how these things stand in current versions of \R, 56 | there may be no problem any more (checked, in 2.14-0 it is the same). 57 | } 58 | 59 | 60 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 61 | 62 | 63 | \examples{ 64 | ## load another package with some S4 methods ("methods" is already loaded) 65 | require("stats4") 66 | 67 | rdo <- Rdo_fetch("show", package = "methods") 68 | ## alternatively: 69 | #fn <- help("show-methods", package = "methods") 70 | #rdo <- utils:::.getHelpFile(fn) 71 | 72 | ## this will find all methods for "show" in currently loaded packages 73 | ## (print only some of them) 74 | head(get_sig_text(rdo)) 75 | 76 | ## this will select only the ones from package "stats4" 77 | get_sig_text(rdo, package = "stats4") 78 | 79 | ## this is also fine (interactively) but need to choose 80 | ## the appropriate element of "fn" if length(fn) > 1 81 | #fn <- help("show-methods") 82 | 83 | ## this finds nothing 84 | #fn <- help("logLik-methods", package = "methods") 85 | #fn 86 | Rdo_fetch("logLik-methods", package = "methods") 87 | 88 | ## this does 89 | #fn <- help("logLik-methods", package = "stats4") 90 | #rdo <- utils:::.getHelpFile(fn) 91 | rdo2 <- Rdo_fetch("logLik-methods", package = "stats4") 92 | 93 | get_sig_text(rdo2) 94 | get_sig_text(rdo2, package = "stats4") 95 | 96 | ## only default method defined 97 | ## using this: 98 | setGeneric("f1", function(x, y){NULL}) 99 | ## since the following gives error in pkgdown: 100 | #f1 <- function(x, y){NULL} 101 | #setGeneric("f1") 102 | 103 | fn <- tempfile() 104 | 105 | reprompt("f1", filename = fn) 106 | rdo <- tools::parse_Rd(fn) 107 | get_sig_text(rdo) 108 | 109 | setClass("aRdpack") 110 | setClass("bRdpack") 111 | 112 | ## several methods defined 113 | setGeneric("f4", function(x, y){NULL}) 114 | setMethod("f4", c("numeric", "numeric"), function(x, y){NULL}) 115 | setMethod("f4", c("aRdpack", "numeric"), function(x, y){NULL}) 116 | setMethod("f4", c("bRdpack", "numeric"), function(x, y){NULL}) 117 | setMethod("f4", c("aRdpack", "bRdpack"), function(x, y){NULL}) 118 | 119 | reprompt("f4", filename = fn) 120 | rdo <- tools::parse_Rd(fn) 121 | get_sig_text(rdo) 122 | 123 | unlink(fn) 124 | } 125 | 126 | % Add one or more standard keywords, see file 'KEYWORDS' in the 127 | 128 | % R documentation directory. 129 | 130 | \keyword{RdoS4} 131 | %\keyword{RdoProgramming} 132 | -------------------------------------------------------------------------------- /man/Rdo_modify.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo_modify} 2 | 3 | \alias{Rdo_replace_section} 4 | \alias{Rdo_modify} 5 | 6 | %- Also NEED an '\alias' for EACH other topic documented here. 7 | 8 | \title{ 9 | Replace or modify parts of Rd objects 10 | } 11 | 12 | \description{ 13 | Replace or modify parts of Rd objects. 14 | } 15 | 16 | \usage{ 17 | Rdo_modify(rdo, val, create = FALSE, replace = FALSE, top = TRUE) 18 | 19 | Rdo_replace_section(rdo, val, create = FALSE, replace = TRUE) 20 | } 21 | 22 | %- maybe also 'usage' for other objects documented here. 23 | 24 | \arguments{ 25 | \item{rdo}{an Rd object.} 26 | \item{val}{an Rd fragment.} 27 | \item{create}{if TRUE, create a new section, see `Details'.} 28 | \item{replace}{a logical, if TRUE \code{val} replaces the old content, 29 | otherwise \code{val} is concatenated with it, see `Details'. 30 | } 31 | \item{top}{a logical, if TRUE examine also the "Rd_tag" of \code{rdo}, 32 | see `Details'. 33 | } 34 | } 35 | 36 | \details{ 37 | 38 | Argument \code{rdo} is an Rd object (complete or a fragment) to be 39 | modified. \code{val} is an Rd fragment to use for modification. 40 | 41 | Basically, \code{val} is appended to (if \code{replace} is FALSE) or 42 | replaces (if \code{replace} is TRUE) the content of an element of 43 | \code{rdo} which has the same "Rd_tag" as \code{val}. 44 | 45 | Argument \code{top} specifies whether to check the "Rd_tag" of 46 | \code{rdo} itself, see below. 47 | 48 | Here are the details. 49 | 50 | If \code{top} is TRUE and \code{rdo} and \code{val} have the same 51 | (non-NULL) "Rd_tag", then the action depends on \code{replace} 52 | (argument \code{create} is ignored in this case). 53 | If \code{replace} is TRUE, \code{val} is returned. Otherwise 54 | \code{rdo} and \code{val} are, effectively, concatenated. For example, 55 | \code{rdo} may be the "arguments" section of an Rd object and 56 | \code{val} may also be an "arguments" section containing new 57 | arguments. 58 | 59 | Otherwise, an element with the "Rd_tag" of \code{val} is searched in 60 | \code{rdo} using \code{tools:::RdTags()}. If such elements are found, 61 | the action again depends on \code{replace}. 62 | 63 | \enumerate{ 64 | \item 65 | If \code{replace} is a character string, then the first element of 66 | \code{rdo} that is a list whose only element is identical to the 67 | value of \code{replace} is replaced by \code{val}. If such an 68 | element is not present and \code{create} is TRUE, \code{val} is 69 | inserted in \code{rdo}. If \code{create} is FALSE, \code{rdo} is not 70 | changed. 71 | 72 | \item 73 | If \code{replace} is TRUE, the first element found is replaced with 74 | \code{val}. 75 | 76 | \item 77 | If \code{replace} is FALSE, \code{val} is appended to the first 78 | element found. 79 | } 80 | 81 | If no element with the "Rd_tag" of \code{val} is found the action 82 | depends on \code{create}. If \code{create} is TRUE, then \code{val} 83 | is inserted in \code{rdo}, effectively creating a new section. If 84 | \code{create} is FALSE, an error is thrown. 85 | 86 | \code{Rdo_replace_section} is like \code{Rdo_modify} with argument 87 | \code{top} fixed to TRUE and the default for argument \code{replace} 88 | set to TRUE. It hardly makes sense to call \code{Rdo_replace_section} 89 | with \code{replace = FALSE} but a character value for it may be 90 | handy in some cases, see the examples. 91 | } 92 | 93 | \value{ 94 | an Rd object or fragment, as described in `Details' 95 | } 96 | 97 | 98 | 99 | \author{Georgi N. Boshnakov} 100 | 101 | 102 | 103 | 104 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 105 | 106 | 107 | 108 | 109 | \examples{ 110 | # a <- tools::parse_Rd("./man/promptUsage.Rd") 111 | # char2Rdpiece("documentation", "keyword") 112 | 113 | # this changes a keyword from Rd to documentation 114 | # Rdo_replace_section(a, char2Rdpiece("documentation", "keyword"), replace = "Rd") 115 | } 116 | 117 | % Add one or more standard keywords, see file 'KEYWORDS' in the 118 | 119 | % R documentation directory. 120 | 121 | \keyword{RdoBuild} 122 | -------------------------------------------------------------------------------- /man/Rdo2Rdf.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdo2Rdf} 2 | \alias{Rdo2Rdf} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{ 5 | Convert an Rd object to Rd file format 6 | } 7 | \description{ 8 | Converts an Rd object to Rd format and saves it to a file or returns 9 | it as a character vector. It escapes percents where necessary and 10 | (optionally) backslashes in the examples section. 11 | } 12 | \usage{ 13 | Rdo2Rdf(rdo, deparse = FALSE, ex_restore = FALSE, file = NULL, 14 | rcode = TRUE, srcfile = NULL) 15 | } 16 | %- maybe also 'usage' for other objects documented here. 17 | \arguments{ 18 | \item{rdo}{an Rd object or a character vector, see `Details'.} 19 | \item{deparse}{logical, passed to the print method for Rd objects, 20 | see `Details'. 21 | } 22 | \item{ex_restore}{logical, if \code{TRUE} escapes backslashes where 23 | necessary. 24 | } 25 | \item{file}{a filename where to store the result. If \code{NULL} or 26 | "missing", the result is returned as a character vector. 27 | } 28 | \item{rcode}{if TRUE, duplicate backslahes in RCODE elements, see 29 | Details. 30 | } 31 | \item{srcfile}{NULL or a file name, see 'Details'.} 32 | } 33 | \details{ 34 | The description here is rather technical and incomplete. In any case 35 | it concerns almost exclusively Rd files which use escape sequences 36 | containing multiple consecutive backslashes or escaped curly braces 37 | (such things appear in regular expressions, for example). 38 | 39 | In principle, this function should be redundant, since the 40 | \code{print} and \code{as.character} methods for objects of class "Rd" 41 | would be expected to do the job. I was not able to get the desired 42 | result that way (the \code{deparse} option to \code{print} did not 43 | work completely for me either). 44 | 45 | Arguments \code{ex_restore} and \code{rcode} were added on an ad-hoc 46 | basis. \code{rcode} is more recent and causes \code{Rdo2Rdf} to 47 | duplicate backslashes found in any element \code{Rd_tag}-ed with 48 | "RCODE". \code{ex_restore} does the same but only for the examples 49 | section. In effect, if \code{rcode} is TRUE, \code{ex_restore} is 50 | ignored. 51 | 52 | The initial intent of this function (and the package Rdpack as a whole 53 | was not to refer to the Rd source file. However, there is some 54 | flexibility in the Rd syntax that does not allow the source file to be 55 | restored identically from the parsed object. This concerns mainly 56 | backslahes (and to some extent curly braces) which in certain contexts 57 | may or may not be escaped and the parsed object is the same. Although 58 | this does not affect functionality, it may be annoying if the escapes 59 | in sections not examined by \code{reprompt} were changed. 60 | 61 | If \code{srcfile} is the name of a file, the file is parsed and the Rd 62 | text of sections of \code{rdo} that are identical to sections from 63 | \code{srcfile} is taken directly from \code{srcfile}, ensuring that 64 | they will be identical to the original. 65 | 66 | 67 | 68 | } 69 | \value{ 70 | \code{NULL}, if \code{file} is not \code{NULL}. Otherwise the Rd 71 | formatted text as a character vector. 72 | } 73 | 74 | \author{Georgi N. Boshnakov} 75 | 76 | \note{ 77 | Here is an example when the author's Rd source cannot be restored 78 | exactly from the parsed object. 79 | 80 | In the Rd source "author" has two backslashes here: \verb{\\author}. 81 | 82 | In the Rd source "author" has one backslash here: \verb{\author}. 83 | 84 | Both sentences are correct and the parsed file contains only one 85 | backslash in both cases. If \code{reprompt} looks only at the parsed 86 | object it will export one backslash in both cases. So, further 87 | reprompt()-ing will not change them again. This is if \code{reprompt} 88 | is called with \code{sec_copy = FALSE}. With the default 89 | \code{sec_copy = TRUE}, \code{reprompt} calls \code{Rdo2Rdf} with 90 | argument \code{srcfile} set to the name of the Rd file and since 91 | \code{reprompt} does not modify section "Note", its text is copied 92 | from the file and the author's original preserved. 93 | 94 | 95 | However, the arguments of \verb{\eqn} are parse_Rd-ed differently (or 96 | so it seems) even though they are also in verbatim. 97 | 98 | 99 | } 100 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 101 | 102 | 103 | \examples{ 104 | # # this keeps the backslashes in "author" (see Note above) 105 | # reprompt(infile="./man/Rdo2Rdf.Rd") 106 | 107 | # # this outputs "author" preceded by one backslash only. 108 | # reprompt(infile="./man/Rdo2Rdf.Rd", sec_copy = FALSE) 109 | } 110 | \keyword{Rd} 111 | -------------------------------------------------------------------------------- /man/makeVignetteReference.Rd: -------------------------------------------------------------------------------- 1 | \name{makeVignetteReference} 2 | \alias{makeVignetteReference} 3 | \alias{vigbib} 4 | \title{Make bibtex references for vignettes} 5 | \description{Make bibtex references for vignettes} 6 | \usage{ 7 | makeVignetteReference(package, vig = 1, verbose = TRUE, title, author, 8 | type = "pdf", bibtype = "Article", key = NULL) 9 | 10 | vigbib(package, verbose = TRUE, \dots, vig = NULL) 11 | } 12 | \arguments{ 13 | \item{package}{ 14 | a character string, the name of an installed package. 15 | } 16 | \item{vig}{ 17 | an integer number or a character string identifying a vignette. 18 | } 19 | \item{verbose}{ 20 | if \code{TRUE}, print the references in Bibtex format. 21 | } 22 | \item{title}{a character string, title of the vignette, see Details.} 23 | \item{author}{a character string, title of the vignette, see Details.} 24 | \item{type}{a character string, type of the vignette, such as 25 | \code{"pdf"} or \code{"html"}. Currently ignored. 26 | } 27 | \item{bibtype}{a character string, Bibtex type for the reference, 28 | defaults to \code{"Article"}. 29 | } 30 | \item{key}{a character string specifying a key for the Bibtex entry. 31 | If missing, suitable key is generated automatically. 32 | } 33 | \item{...}{ 34 | arguments passed by \code{vigbib()} to \code{makeVignetteReference()}. 35 | } 36 | } 37 | \details{ 38 | 39 | \code{vigbib()} generates Bibtex references for all vignettes in a 40 | package. \code{makeVignetteReference()} produces a Bibtex entry for a 41 | particular vignette. 42 | 43 | There seems to be no standard way to cite vignettes in R packages. 44 | For vignettes that are complete journal papers (most notably in the 45 | Journal of Statistical Software), the authors would usually 46 | prefer the papers to be cited, rather than the vignette. In any case, 47 | consulting the output of \code{citation("a_package")} is the best 48 | starting point. If the vignette has been extended substantially after 49 | the paper was published, cite both. 50 | 51 | In many cases it is sufficient to give the command that opens the 52 | vignette, e.g.: 53 | 54 | \code{vignette("Inserting_bibtex_references", package = "Rdpack")}. 55 | 56 | \code{makeVignetteReference()} makes a Bibtex entry for one 57 | vignette. It looks for the available vignettes using 58 | \code{vignette(package=package)}. Argument \code{vig} can be a 59 | character string identifying the vignette by the name that would be 60 | used in a call to \code{vignette()}. It can also be an integer, 61 | identifying the vignette by the index (in the order in which the 62 | vignettes are returned by \code{vignette()}). By default the first 63 | vignette is returned. If \code{vig} is not suitable, a suitable list 64 | of alternatives is printed. 65 | 66 | For \code{vigbib()} it is sufficient to give the name of a package. It 67 | accepts all arguments of \code{makeVignetteReference()} except 68 | \code{vig} (actually, supplying \code{vig} is equivallent to calling 69 | \code{makeVignetteReference()} directly). 70 | 71 | The remaining arguments can be used to overwrite some automatically 72 | generated entries. For example, the vignette authors may not be the 73 | same as the package authors. 74 | 75 | } 76 | \value{ 77 | a bibentry object containing the generated references 78 | (the Bibtex entries are also printed, so that they can be copied to a 79 | bib file) 80 | } 81 | %\references{ 82 | %%% ~put references to the literature/web site here ~ 83 | %} 84 | \author{Georgi N. Boshnakov} 85 | %\note{ 86 | %%% ~~further notes~~ 87 | %} 88 | 89 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 90 | 91 | %\seealso{ 92 | %%% ~~objects to See Also as \code{\link{help}}, ~~~ 93 | %} 94 | \examples{ 95 | ## NOTE (2020-01-21): the following examples work fine, but are not 96 | ## rendered correctly by pkgdown::build_site(), so there may be errors 97 | ## on the site produced by it, https://geobosh.github.io/Rdpack/. 98 | 99 | vigbib("Rdpack") 100 | makeVignetteReference("Rdpack", vig = 1) 101 | makeVignetteReference("Rdpack", vig = "Inserting_bibtex_references") 102 | ## the first few characters of the name suffice: 103 | makeVignetteReference("Rdpack", vig = "Inserting_bib") 104 | 105 | ## this gives an error but also prints the available vignettes: 106 | ## makeVignetteReference("Matrix", vig = "NoSuchVignette") 107 | 108 | vigbib("utils") 109 | makeVignetteReference("utils", vig = 1) 110 | ## commented out since can be slow: 111 | ## high <- installed.packages(priority = "high") 112 | ## highbib <- lapply(rownames(high), function(x) try(Rdpack:::vigbib(x, verbose = FALSE))) 113 | } 114 | \keyword{bibtex} 115 | % use one of RShowDoc("KEYWORDS") 116 | -------------------------------------------------------------------------------- /R/yytransient.R: -------------------------------------------------------------------------------- 1 | # 2013-12-01 new; need testing 2 | .ascharRd <- function(rdo){ 3 | if(is.character(rdo)) # note: applying as.character.Rd, as below gives error in this case 4 | res <- as.vector(rdo) # to drop attributes; 5 | else{ 6 | class(rdo) <- "Rd" 7 | res <- as.character(rdo) 8 | } 9 | 10 | paste(res, collapse="") # todo: argument to make this optional? 11 | } 12 | 13 | .safeRdtag <- function(x, nulltag = ""){ # replaces NULL with nulltag 14 | res <- attr(x, "Rd_tag") 15 | if(is.null(res)) 16 | res <- nulltag 17 | res 18 | } 19 | 20 | # a replacement for tools:RdTags; takes 21 | # 2013-12-08 renamed from .top_RdTags 22 | Rdo_tags <- function(rdo, nulltag = ""){ # note: absent Rd_tag's are returned as "" 23 | locf <- function(x) 24 | .safeRdtag(x, nulltag) 25 | 26 | res <- sapply(rdo, locf) 27 | if (length(res)==0) 28 | res <- character() 29 | res 30 | } 31 | 32 | Rdo_which <- function(rdo, fun){ # fun - predicate 33 | wrk <- sapply(rdo, fun) 34 | which(wrk) 35 | } 36 | 37 | # 2013-12-08 renamed from .whichtageq 38 | Rdo_which_tag_eq <- function(rdo, tag){ 39 | tags <- Rdo_tags(rdo) 40 | pos <- which(tags == tag) 41 | 42 | pos 43 | } 44 | 45 | # 2013-12-08 renamed from .whichtagin 46 | Rdo_which_tag_in <- function(rdo, tags){ # TODO: needs testing! 47 | alltags <- Rdo_tags(rdo) 48 | pos <- which(sapply(alltags, function(x) .tag_in(x,tags) )) 49 | pos 50 | } 51 | 52 | 53 | Rdo_get_item_labels <- function(rdo){ 54 | wrk <- Rdo_locate(rdo, 55 | f = function(x){ # attr(x,"Rd_tag") == "\\item" 56 | .tag_eq(x, "\\item") 57 | }, 58 | lists = TRUE, 59 | nested = FALSE, 60 | pos_only = function(x) if(length(x) > 0) .ascharRd(x[[1]]) 61 | else "" #in \itemize items do not have labels 62 | ) 63 | 64 | sapply(wrk, function(x) x$value) 65 | } 66 | 67 | Rdo_get_argument_names <- function(rdo){ 68 | # 2013-12-08 was: indx <- Rdo_locate_predefined_section(rdo, "\\arguments") 69 | # todo: shouldn't this be using some "locate"-type function? I removed 70 | # Rdo_locate_predefined_section() since it simply checks the tags as 71 | # below but probably should vreate a ne function based on a "locate" 72 | indx <- Rdo_which_tag_eq(rdo, "\\arguments") 73 | 74 | if(length(indx) == 0) 75 | return(character(0)) # no "arguments" section in rdo; initially was: NA_character_ 76 | 77 | txt <- Rdo_get_item_labels(rdo[[indx]]) 78 | 79 | if (length(txt)==0) # this chunk: copied from tools:::.Rd_get_argument_names 80 | return(character()) 81 | txt <- unlist(strsplit(txt, ", *")) 82 | txt <- gsub("\\\\l?dots", "...", txt) 83 | txt <- gsub("\\\\_", "_", txt) 84 | txt <- .strip_whitespace(txt) 85 | 86 | 87 | txt <- unique(txt) # cater for duplication due to #ifdef unix or windows; 88 | # see e.g. system.Rd or system2.Rd in base package 89 | # 90 | # todo: more thought on this? 91 | txt 92 | } 93 | 94 | # 2013-10-23 new 95 | # pattern = ".*[.]Rd$" would be too dangerous. 96 | # but may be exclude could exclude foo-package 97 | Rdreplace_section <- function(text, sec, pattern, path = "./man", exclude = NULL, ...){ 98 | rdnames <- dir(path, pattern, full.names=TRUE) 99 | # todo: allow 'exclude' to have length more than 1 100 | if(!is.null(exclude)){ 101 | rdexcl <- dir(path, exclude, full.names=TRUE) 102 | rdnames <- setdiff(rdnames, rdexcl) 103 | } 104 | 105 | for(nam in rdnames){ 106 | try(Rdo_set_section(text, sec, nam)) 107 | } 108 | 109 | rdnames # todo: return a logical vector of success/failures? 110 | } 111 | 112 | Rdo_locate_core_section <- function(rdo, sec){ # 2013-12-08 113 | # Rdo_which_tag_eq(rdo, sec) 114 | secall <- Rdo_sections(rdo) 115 | sec.names <- sapply(secall, function(x) x$title) 116 | indx <- which(sec.names == sec) 117 | 118 | if(length(indx)==0) 119 | list() 120 | else 121 | ## 2018-04-21 was: secall[[indx]] 122 | secall[indx] 123 | } 124 | -------------------------------------------------------------------------------- /man/Rdapply.Rd: -------------------------------------------------------------------------------- 1 | \name{Rdapply} 2 | \alias{Rdapply} 3 | \alias{rattr} 4 | \alias{Rdtagapply} 5 | \title{Apply a function over an Rd object} 6 | \description{Apply a function recursively over an Rd object, similarly 7 | to rapply but keeping attributes.} 8 | \usage{ 9 | Rdapply(x, \dots) 10 | 11 | Rdtagapply(object, FUN, rdtag, classes = "character", how = "replace", 12 | \dots) 13 | 14 | rattr(x, y) 15 | } 16 | \arguments{ 17 | \item{x}{the Rd object on which to apply a function.} 18 | \item{object}{the Rd object on which to apply a function.} 19 | \item{FUN}{The function to apply, see details} 20 | \item{rdtag}{apply FUN only to elements whose \code{Rd_tag} attribute 21 | is \code{rdtag}.} 22 | \item{y}{an Rd object with the same structure as \code{x}, see `Details'.} 23 | \item{\dots}{arguments to pass to \code{rapply}, see `Details'.} 24 | \item{classes}{a character vector, passed on to \code{\link{rapply}}, 25 | see `Details'. 26 | } 27 | \item{how}{a character string, passed on to \code{\link{rapply}}, 28 | see `Details'. 29 | } 30 | } 31 | \details{ 32 | \code{Rdapply} works like \code{rapply} but preserves the attributes 33 | of \code{x} and (recursively) any sublists of it. \code{Rdapply} 34 | first calls \code{rapply}, passing all arguments to it. Then it 35 | restores recursively the attributes by calling \code{rattr}. 36 | 37 | Note that the object returned by \code{rapply} is assumed to have 38 | identical structure to the original object. This means that argument 39 | \code{how} of \code{rapply} must not be "unlist" and normally will be 40 | "replace". \code{Rdtagapply} gives sensible default values for 41 | \code{classes} and \code{how}. See the documentation of 42 | \code{\link{rapply}} for details and the possible choices for 43 | \code{classes}, \code{how} or other arguments passed to it via 44 | \code{"\dots"}. 45 | 46 | \code{Rdtagapply} is a convenience variant of \code{Rdapply} for the 47 | common task of modifying or examining only elements with a given 48 | \code{Rd_tag} attribute. Since the Rd equation macros \verb{\eqn} and 49 | \verb{\deqn} are assigned Rd tag "VERB" but are processed differently 50 | from other "VERB" pieces, pseudo-tags 51 | "mathVERB" and "nonmathVERB" are provided, such that "mathVERB" is for 52 | actions on the first argument of the mathematical macros \verb{\eqn} and 53 | \verb{\deqn}, while "nonmathVERB" is for actions on "VERB" macros in 54 | all other contexts. There is also a pseudo-tag "nonmath" for anything 55 | that is not math. 56 | 57 | \code{rattr} is an auxilliary function which takes two Rd objects 58 | (with identical structure) and recursively examines them. It makes the 59 | attributes of any lists in the first argument identical to the 60 | corresponding attributes in the second. 61 | } 62 | \value{ 63 | 64 | For \code{Rdapply} and \code{Rdtagapply}, an Rd object with some of 65 | its leaves replaced as specified above. 66 | 67 | For \code{rattr}, the object \code{x} with attributes of any list 68 | elements of it set to the corresponding attributes of \code{y}. 69 | } 70 | \author{Georgi N. Boshnakov} 71 | \note{ 72 | todo: may be it is better to rename the argument FUN of \code{Rdtagapply} to 73 | \code{f}, which is its name in \code{rapply}. 74 | } 75 | 76 | %% ~Make other sections like Warning with \section{Warning }{....} ~ 77 | 78 | \seealso{ 79 | \code{\link{rapply}} 80 | } 81 | \examples{ 82 | # create an Rd object for the sake of example 83 | u1 <- list_Rd(name = "Dummyname", alias = "dummyfun", 84 | title = "Dummy title", description = "Dummy description", 85 | usage = "dummyfun(x)", 86 | value = "numeric vector", 87 | author = "A. Author", 88 | examples = "\na <- matrix(1:6,nrow=2)\na \%*\% t(a)\nt(a) \%*\% a", 89 | Rd_class=TRUE ) 90 | 91 | # correct R code for examples but wrong for saving in Rd files 92 | Rdo_show(u1) 93 | 94 | # escape percents everywhere except in comments 95 | # (actually, .anypercent escapes only unescaped percents) 96 | rdo <- Rdapply(u1, Rdpack:::.anypercent, classes = "character", how = "replace") 97 | 98 | # syntactically wrong R code for examples but ok for saving in Rd files 99 | Rdo_show(rdo) 100 | 101 | 102 | # Rdo2Rdf does this by default for examples and other R code, 103 | # so code can be kept syntactically correct while processing. 104 | # (reprompt() takes care of this too as it uses Rdo2Rdf for saving) 105 | 106 | fn <- tempfile("u1", fileext="Rd") 107 | Rdo2Rdf(u1, file = fn) 108 | 109 | # the saved file contains escaped percents but they disappear in parsing: 110 | file.show(fn) 111 | Rdo_show(tools::parse_Rd(fn)) 112 | 113 | # if you think that sections should start on new lines, 114 | # the following makes the file a little more human-friendly 115 | # (by inserting new lines). 116 | \dontshow{# todo: additional arg. for list_Rd for this? 117 | } 118 | u2 <- Rdpack:::.Rd_tidy(u1) 119 | Rdo2Rdf(u2, file = fn) 120 | file.show(fn) 121 | 122 | unlink(fn) 123 | } 124 | 125 | \keyword{RdoProgramming} 126 | 127 | -------------------------------------------------------------------------------- /man/get_bibentries.Rd: -------------------------------------------------------------------------------- 1 | \name{get_bibentries} 2 | \alias{get_bibentries} 3 | %- Also NEED an '\alias' for EACH other topic documented here. 4 | \title{Get all references from a Bibtex file} 5 | \description{Get all references from a Bibtex file.} 6 | \usage{ 7 | get_bibentries(\dots, package = NULL, bibfile = "REFERENCES.bib", 8 | url_only = FALSE, stop_on_error = TRUE) 9 | } 10 | %- maybe also 'usage' for other objects documented here. 11 | \arguments{ 12 | \item{\dots}{arguments to be passed on to the file getting functions, 13 | character strings, see `Details'.} 14 | \item{package}{name of a package, a character string or NULL.} 15 | \item{bibfile}{name of a Bibtex file, a character string.} 16 | \item{url_only}{ 17 | if TRUE, restrict percent escaping to BibTeX field \code{"URL"}.} 18 | \item{stop_on_error}{ 19 | if \code{TRUE} stop on error, otherwise issue a warning and return 20 | an empty \code{bibentryRd} object. 21 | } 22 | } 23 | \details{ 24 | 25 | \code{get_bibentries} parses the specified file. 26 | % using \code{read.bib} from package \pkg{bibtex} 27 | % \insertCite{Rpack:bibtex}{Rdpack} 28 | and sets its 29 | \code{names} attribute to the keys of the bib elements 30 | (\code{read.bib()} does this since version version 0.4.0 of 31 | \pkg{bibtex}, as well). Here is what 32 | \code{get_bibentries} does on top of \code{read.bib} (the details are 33 | further below): 34 | 35 | \itemize{ 36 | \item \code{get_bibentries} deals with percent signs in URL's. 37 | 38 | \item if the current working directory is in the development 39 | directory of \code{package}, \code{get_bibentries} will first 40 | search for the bib file under that directory. 41 | } 42 | 43 | \code{bibfile} should normally be the base name of the Bibtex file. 44 | Calling \code{get_bibentries} without any \code{"\dots"} arguments 45 | results in looking for the Bibtex file in the current directory if 46 | package is NULL or missing, and in the installation directory of the 47 | specified package, otherwise. 48 | Argument "\dots" may be used to specify directories. 49 | If \code{package} is missing or NULL, the complete path is obtained 50 | with \code{file.path(..., bibfile)}. Otherwise \code{package} must be 51 | a package name and the file is taken from the installation directory 52 | of the package. Again, argument "\dots" can specify subdirectory 53 | as in \code{system.file}. 54 | 55 | If the current working directory is in the development directory of 56 | \code{package}, the bib file is first sought there before resorting to 57 | the installation directory. 58 | 59 | Although the base \R packages do not have files REFERENCES.bib, 60 | argument \code{package} can be set to one of them, 61 | e.g. \code{"base"}. This works since package \pkg{bibtex} provides bib 62 | files for the core packages. 63 | 64 | By default, \code{get_bibentries} escapes unescaped percent signs in 65 | all fields of bibtex objects. To restrict this only to field "url", 66 | set argument \code{url_only} to \code{FALSE}. 67 | 68 | \code{get_bibentries} returns an object from class 69 | \code{"bibentryRd"}, which inherits from bibentry. The printing method 70 | for \code{"bibentryRd"} unescapes percent signs in URLs for some 71 | styles where the escapes are undesirable. 72 | 73 | } 74 | \value{ 75 | a bibentryRd object inheriting from bibentry 76 | } 77 | \references{ 78 | \insertAllCited{} 79 | } 80 | \author{Georgi N. Boshnakov} 81 | % \note{ 82 | % %% ~~further notes~~ 83 | % } 84 | % 85 | % %% ~Make other sections like Warning with \section{Warning }{....} ~ 86 | % 87 | % \seealso{ 88 | % %% ~~objects to See Also as \code{\link{help}}, ~~~ 89 | % } 90 | \examples{ 91 | r <- get_bibentries(package = "Rdpack") 92 | r 93 | print(r, style = "html") 94 | 95 | ## Bib from base R packages are disabled in Rdpack v2 (notify the 96 | ## maintainer of Rdpack or raise an issue on github if you wish this back). 97 | ## 98 | ## b <- get_bibentries(package = "stats") 99 | ## print(b[[1]], style = "R") 100 | ## print(b[[1]], style = "citation") 101 | 102 | ## here the url field contains percent encoding 103 | fn_url <- system.file("examples", "url_with_percents.bib", package = "Rdpack") 104 | u <- get_bibentries(bibfile = fn_url) 105 | 106 | ## the links produced by all of the following are valid 107 | ## and can be put in a browser 108 | print(u, style = "html") 109 | print(u, style = "bibtex") 110 | print(u, style = "R") 111 | print(u, style = "text") 112 | print(u, style = "citation") 113 | 114 | ## The link here contains escapes but when put in a LaTeX document 115 | ## which uses the JSS style it generates correct clickable link, 116 | ## (see Details section) 117 | print(u, style = "latex") 118 | 119 | ## here the journal field contains percent encoding 120 | fn_other <- system.file("examples", "journal_with_percents.bib", package = "Rdpack") 121 | j <- get_bibentries(bibfile = fn_url) 122 | print(j, style = "html") 123 | print(j, style = "bibtex") 124 | print(j, style = "R") 125 | print(j, style = "text") 126 | print(j, style = "citation") 127 | 128 | print(j, style = "latex") 129 | } 130 | \keyword{ bibtex } 131 | \keyword{programming} 132 | --------------------------------------------------------------------------------