{"id":15293000,"url":"https://github.com/geobosh/rdpack","last_synced_at":"2025-04-13T12:20:23.799Z","repository":{"id":41812682,"uuid":"100482670","full_name":"GeoBosh/Rdpack","owner":"GeoBosh","description":"R package Rdpack provides functions and macros facilitating writing and management of R documentation.","archived":false,"fork":false,"pushed_at":"2025-03-16T11:54:46.000Z","size":8566,"stargazers_count":30,"open_issues_count":2,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T02:51:38.776Z","etag":null,"topics":["bibtex","bibtex-references","citations","documentation","r","r-package","rd-format","roxygen2"],"latest_commit_sha":null,"homepage":"https://geobosh.github.io/Rdpack/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GeoBosh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-16T11:38:41.000Z","updated_at":"2025-04-06T02:37:29.000Z","dependencies_parsed_at":"2022-09-01T18:31:48.033Z","dependency_job_id":"52c9dbcd-3b24-4128-8862-3a133d4773ed","html_url":"https://github.com/GeoBosh/Rdpack","commit_stats":{"total_commits":283,"total_committers":5,"mean_commits":56.6,"dds":"0.36042402826855124","last_synced_commit":"1b97d7d52119204b7eef1528e9a7d5f30d4cc57c"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeoBosh%2FRdpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeoBosh%2FRdpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeoBosh%2FRdpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeoBosh%2FRdpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GeoBosh","download_url":"https://codeload.github.com/GeoBosh/Rdpack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248711009,"owners_count":21149281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bibtex","bibtex-references","citations","documentation","r","r-package","rd-format","roxygen2"],"created_at":"2024-09-30T16:37:13.537Z","updated_at":"2025-04-13T12:20:23.770Z","avatar_url":"https://github.com/GeoBosh.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- badges: start --\u003e\n  [![CRANStatusBadge](http://www.r-pkg.org/badges/version/Rdpack)](https://cran.r-project.org/package=Rdpack)\n  [![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/Rdpack)](https://www.r-pkg.org/pkg/Rdpack)\n  [![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/grand-total/Rdpack?color=blue)](https://r-pkg.org/pkg/Rdpack)\n  [![R-CMD-check](https://github.com/GeoBosh/Rdpack/workflows/R-CMD-check/badge.svg)](https://github.com/GeoBosh/Rdpack/actions)\n  [![DOI](https://zenodo.org/badge/100482670.svg)](https://zenodo.org/badge/latestdoi/100482670)\n\u003c!-- badges: end --\u003e\n\nRdpack provides functions for manipulation of R documentation objects, including functions\n`reprompt()` and `ereprompt()` for updating existing Rd documentation for functions, methods\nand classes; Rd macros for citations and import of references from `bibtex` files for use in\n`Rd` files and `roxygen2` comments (`\\insertRef`, `\\insertCite`, `\\insertAllCited`); Rd\nmacros for evaluating and inserting snippets of R code and the results of its evaluation\n(`\\printExample`) or creating graphics on the fly (`\\insertFig`); and many functions for\nmanipulation of references and Rd files.\n\n\n# Table of Contents\n\n1.  [Installing Rdpack](#org8a647c9)\n2.  [Inserting Bibtex references and citations](#org4e77937)\n    1.  [Preparation](#org766760b)\n    2.  [Inserting references](#orgf0b8e07)\n    3.  [Inserting citations](#orgbff7de3)\n    4.  [Changing the style of references](#orge63a829)\n    5.  [Troubleshooting](#org35439dc)\n        1.  [A puzzling message in devtools development mode](#orgc0ddf98)\n        2.  [Typical errors](#orge94900c)\n    6.  [Latex markup in BibTeX entries](#org7490870)\n    7.  [Encoding of file REFERENCES.bib](#org5fd3efd)\n3.  [Viewing Rd files](#orgb41e139)\n4.  [Using Rdpack::reprompt()](#orgcdf91db)\n    1.  [What it does](#orge44c86a)\n    2.  [Reprompt and open in an editor](#org975854d)\n5.  [Inserting evaluated examples](#orgb77362a)\n    1.  [Evaluating the examples in section Examples](#org3bee793)\n6.  [Inserting figures/graphs/plots](#org9b84bd5)\n\n\n\u003ca id=\"org8a647c9\"\u003e\u003c/a\u003e\n\n# Installing Rdpack\n\nInstall the  [latest stable version](https://cran.r-project.org/package=Rdpack) from CRAN:\n\n    install.packages(\"Rdpack\")\n\nYou can also install the [development version](https://github.com/GeoBosh/Rdpack) of `Rdpack` from Github:\n\n    library(devtools)\n    install_github(\"GeoBosh/Rdpack\")\n\n\n\u003ca id=\"org4e77937\"\u003e\u003c/a\u003e\n\n# Inserting Bibtex references and citations\n\nThe simplest way to insert Bibtex references is with the Rd macro `\\insertRef`.\nJust put `\\insertRef{key}{package}` in the documentation to insert item with key\n`key` from file `REFERENCES.bib` in your package `package`. Alternatively, use\none or more `\\insertCite{key}{package}` commands to cite works from\n`REFERENCES.bib`, then issue a single `\\insertAllCited{}` directive to produce a\nlist of all cited references. For this to work\nthe `DESCRIPTION` file of the package needs to be amended, see below the full\ndetails. \n\n\n\u003ca id=\"org766760b\"\u003e\u003c/a\u003e\n\n## Preparation\n\nTo prepare a package for importing BibTeX references it is necessary to tell the\npackage management tools that package Rdpack and its Rd macros are needed. The\nreferences should be put in file `inst/REFERENCES.bib`.  These steps are\nenumerated below in somewhat more detail, see also the vignette\n[`Inserting_bibtex_references`](https://cran.r-project.org/package=Rdpack).\n\n1.  Add the following lines to  file \"DESCRIPTION\":\n    \n        Imports: Rdpack\n        RdMacros: Rdpack\n    \n    Make sure the capitalisation of `RdMacros:` is as shown. If the field\n    `RdMacros:` is already present, add \"Rdpack\" to the list on that\n    line. Similarly for field \"Imports:\".\n\n2.  Add the following line to file \"NAMESPACE\":\n    \n        importFrom(Rdpack,reprompt)\n    \n    The equivalent line for `roxygen2` is \n    \n        #' @importFrom Rdpack reprompt\n\n3.  Create file `REFERENCES.bib` in subdirectory `inst/` of your package and\n    put the BibTeX references in it.\n\n\n\u003ca id=\"orgf0b8e07\"\u003e\u003c/a\u003e\n\n## Inserting references\n\nOnce the steps outlined above are done, references can be inserted in the\ndocumentation as\n\n    \\insertRef{key}{package}\n\nwhere `key` is the bibtex key of the reference and `package` is your package.\nThis works in `Rd` files and in `roxygen` documentation chunks.\n\nUsually references are put in section `references`. In an `Rd` file this might look\nsomething like:\n\n    \\references{\n    \\insertRef{Rdpack:bibtex}{Rdpack}\n    \n    \\insertRef{R}{bibtex}\n    }\n\nThe equivalent `roxygen2` documentation chunk would be:\n\n    #' @references\n    #' \\insertRef{Rpackage:rbibutils}{Rdpack}\n    #'\n    #' \\insertRef{R}{bibtex}\n\nThe first line above inserts the reference with key `Rpackage:rbibutils` in Rdpack's\nREFERENCES.bib. The second line inserts the reference labeled `R` in file\nREFERENCES.bib from package `bibtex`. \n\nThe example above demonstrates that references from other packages can be\ninserted (in this case `bibtex`), as well. This is strongly discouraged for\nreleased versions but is convenient during development. One relatively safe use\nis when the other package is also yours - this allows authors of multiple\npackages to not copy the same refences to each of their own packages.\n\nFor further details see the vignette \n[`Inserting_bibtex_references`](https://cran.r-project.org/package=Rdpack)\nor open it from `R`:\n\n    vignette(\"Inserting_bibtex_references\", package = \"Rdpack\")\n\n(The latest version of the vignette is at\n[`Inserting_bibtex_references (development version on github)`](https://github.com/GeoBosh/Rdpack/blob/master/vignettes/Inserting_bibtex_references.pdf).)\n\n\n\u003ca id=\"orgbff7de3\"\u003e\u003c/a\u003e\n\n## Inserting citations\n\nAdditional Rd macros are available for citations.  They also can be used in both Rd and\nroxygen2 documentation.\n\n`\\insertCite{key}{package}` cites `key` and records it for use by\n`\\insertAllCited` and `\\insertCited`, see below. `key` can contain more keys separated by\ncommas.\n\n`\\insertCite{parseRd,Rpackage:rbibutils}{Rdpack}` produces \n(Murdoch 2010; Boshnakov and Putman 2020)\nand \n`\\insertCite{Rpackage:rbibutils}{Rdpack}`         gives\n(Boshnakov and Putman 2020).\n\nBy default the citations are parenthesised: `\\insertCite{parseRd}{Rdpack}` produces\n(Murdoch 2010).  To get\ntextual citations, like \nMurdoch (2010), \nput the string `;textual` at the end of the key. The references in the last two sentences\nwould be produced with `\\insertCite{parseRd}{Rdpack}` and\n`\\insertCite{parseRd;textual}{Rdpack}`, respectively.  This also works with several\ncitations, e.g.\n\n`\\insertCite{parseRd,Rpackage:rbibutils;textual}{Rdpack}` produces:\nMurdoch (2010); Boshnakov and Putman (2020).\n\nThe macro `\\insertNoCite{key}{package}` records one or more\nreferences for `\\insertAllCited` but does not cite it. Setting\n`key` to `*` will include all references from the\nspecified package. For example, \n`\\insertNoCite{R}{bibtex}`  and  `\\insertNoCite{*}{utils}`\nrecord the specified references for inclusion by `\\insertAllCited`. \n\n`\\insertAllCited` inserts all references cited with\n`\\insertCite` or `\\insertNoCite`. Putting this macro\nin the references section will keep it up to date automatically. \nThe Rd section may look something like:\n\n    \\insertAllCited{}\n\nor, in roxygen2, the references chunk might look like this:\n\n    #' @references\n    #'   \\insertAllCited{}\n\nDon't align the backslash with the second 'e' of `@references`, since roxygen2 may\ninterpret it as verbatim text, not macro.\n\n`\\insertCited{}` works like `\\insertAllCited` but empties the reference list after\nfinishing its work. This means that the second and subsequent `\\insertCited` in the same help\npage will list only citations done since the preceding `\\insertCited`. Prompted by issue 27\non github to allow separate reference lists for each method and the class in R6\ndocumentation.\n\nTo mix the citations with other text, such as \\`\\`see also'' and \\`\\`chapter 3'',\nwrite the list of keys as a free text, starting it with the symbol `@` and\nprefixing each key with it.  The `@` symbol will not appear in the output. For\nexample, the following code\n\n    \\insertCite{@see also @parseRd and @Rpackage:rbibutils}{Rdpack}\n    \\insertCite{@see also @parseRd; @Rpackage:rbibutils}{Rdpack}\n    \\insertCite{@see also @parseRd and @Rpackage:rbibutils;textual}{Rdpack}\n\nproduces:\n\n(see also Murdoch 2010 and Boshnakov and Putman 2020) \n\n(see also Murdoch 2010; Boshnakov and Putman 2020) \n\nsee also Murdoch (2010) and Boshnakov and Putman (2020)\n\nWith the parenthesised citations, if you need markup for the text before or after the\ncitations, say `see also` in italic, put `;nobrackets`\u003csup\u003e\u003ca id=\"fnr.1\" class=\"footref\" href=\"#fn.1\"\u003e1\u003c/a\u003e\u003c/sup\u003e at the end of the first argument of\nthe Rd macro, take out the part containing markup, and put the parentheses were suitable. For\nexample,\n\n    (\\emph{see also} \\insertCite{@@parseRd and @Rpackage:rbibutils;nobrackets}{Rdpack})\n\n(in markdown, use `_see also_` in place of `\\emph{see also})`. This gives:\n\n(*see also* Murdoch 2010 and Boshnakov and Putman 2020) \n\n\u0026#x2014;\n\n`\\insertCiteOnly{key}{package}` is as `\\insertCite` but does not include the key\nin the list of references for `\\insertAllCited`.\n\n\n\u003ca id=\"orge63a829\"\u003e\u003c/a\u003e\n\n## Changing the style of references\n\nBibliography styles for lists of references are supported from \u003cspan class=\"underline\"\u003eRdpack (\u003e=\n0.8)\u003c/span\u003e. Currently the only alternative offered is to use long names (Georgi\nN. Boshnakov) in place of the default style (Boshnakov GN). More comprehensive\nalternatives can be included if needed or requested.\n\nTo cause all lists of references produced by `\\insertAllCited` in a package to appear with\nfull names, add `.onLoad()` function to your package. If you don't have `.onLoad()`, just\ncopy the following definition: \n\n    .onLoad \u003c- function(lib, pkg){\n        Rdpack::Rdpack_bibstyles(package = pkg, authors = \"LongNames\")\n        invisible(NULL)\n    }\n\nIf you already have `.onLoad()`, add the line containing the\n`Rdpack::Rdpack_bibstyles` call to it.\n\nAfter installling/reloading your package the lists of references should appear\nwith long author names. \"Rdpack\" itself now uses this style.\n\n\n\u003ca id=\"org35439dc\"\u003e\u003c/a\u003e\n\n## Troubleshooting\n\n\n\u003ca id=\"orgc0ddf98\"\u003e\u003c/a\u003e\n\n### A puzzling message in devtools development mode\n\nThe described procedure works transparently in `roxygen2` chunks and with Hadley\nWickham's package `devtools`.  Packages are built and installed properly with\nthe `devtools` commands and the references are processed as expected.\n\nCurrently (2017-08-04) if you run help commands `?xxx` for functions from the\npackage you are working on *in developement mode* and their help pages contain\nreferences, you may encounter some puzzling warning messages, something like:\n\n    1: In tools::parse_Rd(path) :\n      ~/mypackage/man/abcde.Rd: 67: unknown macro '\\insertRef'\n\nThese warnings are harmless and can be ignored \u0026#x2014; the help pages are built\nproperly and no warnings appear outside *developer's mode*, e.g. in a separate R\nsession\u003csup\u003e\u003ca id=\"fnr.2\" class=\"footref\" href=\"#fn.2\"\u003e2\u003c/a\u003e\u003c/sup\u003e. Even better, use the function `viewRd()` described\nbelow to view the required help file.\n\n\n\u003ca id=\"orge94900c\"\u003e\u003c/a\u003e\n\n### Typical errors\n\nThe functions underlying the processing of references and citations intercept\nerrors, such as missing BibTeX labels or badly formed items in REFERENCES.bib,\nand issue informative warnings during the building and installation of the\npackage, so that the developer is alerted but the package can still be built and\ninstalled. In these cases the functions usually insert a suitable text in the\ndocumentation, as well. If you encounter a situation contradicting this\ndescription, it is probably a bug \u0026#x2014; please report it (but check first for the\ntypical errors listed below).\n\nA non-decipherable error message is probably caused by one of the following \ntypical errors:\n\n-   misspelled `RdMacros:` field in file DESCRIPTION. The safest way to avoid this\n    is to copy it from the DESCRIPTION file of a working package.\n\n-   omitted second argument of a reference or citation macro. Most of these macros\n    have the package name as a second argument.\n\nThese errors occur during parsing of the Rd files, before the control is passed\nto the `Rdpack`'s macros. \n\n\n\u003ca id=\"org7490870\"\u003e\u003c/a\u003e\n\n## Latex markup in BibTeX entries\n\nIn principle, BibTeX entries may contain arbitrary Latex markup, while the Rd format\nsupports only a subset. As a consequence, some BibTeX entries may need some editing when\nincluded in REFERENCES.bib\u003csup\u003e\u003ca id=\"fnr.3\" class=\"footref\" href=\"#fn.3\"\u003e3\u003c/a\u003e\u003c/sup\u003e. Only do this for entries that do not render properly or\ncause errors, since most of the time this should not be necessary.\n\nIf mathematics doesn't render properly replace the Latex dollar syntax with Rd's `\\eqn`,\ne.g. `$x^2$` with `\\eqn{x^2}`. This should not be needed for versions of Rdpack\n0.8-4 or later. \n\nSome Latex macros may have to be removed or replaced with suitable Rd markup. Again,\ndo this only if they cause problems, since some are supported, e.g. `\\doi`.\n\nSee also the overview help page, `help(\"Rdpack-package\")`, of package `\"Rdpack\"`. \nAmong other things, it contains some dummy references which illustrate the above.\n\n\n\u003ca id=\"org5fd3efd\"\u003e\u003c/a\u003e\n\n## Encoding of file REFERENCES.bib\n\nIf a package has a declared encoding (in file `DESCRIPTION`), `REFERENCES.bib` is read-in\nwith that encoding\u003csup\u003e\u003ca id=\"fnr.4\" class=\"footref\" href=\"#fn.4\"\u003e4\u003c/a\u003e\u003c/sup\u003e.  Otherwise, the encoding of `REFERENCES.bib` is assumed to be\nUTF-8 (which includes ASCII as a subset).\n\nNote that BibTeX entries downloaded from online databases and similar sources may contain\nunexpected characters in other encodings, e.g. 'latin1'. In such cases the check tools in\nR-devel (since about 2018-10-01) may give warnings like:\n\n    prepare_Rd: input string 1 is invalid in this locale\n\nTo resolve this, convert the file to the declared encoding or UTF-8. Alternatively, replace\nthe offending symbols with their classic TeX/LaTeX equivalents (which are ASCII). Non-ASCII\nsymbols in BibTeX entries obtained from online databases are often in fields like \"Abstract\",\nwhich are normally not included in lists of references and can be deleted from REFERENCES.bib.\n\nOne way to check for non-ASCII symbols in a file is `tools::showNonASCIIfile()`.\n\nInternally, LaTeX sequences standing for accented Latin characters, such as `\\'e` and `\\\"o`,\nare converted to UTF-8.  So, even if the file REFERENCES.bib is pure ASCII, it may implicitly\ngive raise to non-ASCII characters. This may cause R's checking tools to complain about\nnon-ASCII characters even after it has been verified that there are none. If this happens,\nadd the encoding declaration to file DESCRIPTION\u003csup\u003e\u003ca id=\"fnr.5\" class=\"footref\" href=\"#fn.5\"\u003e5\u003c/a\u003e\u003c/sup\u003e:\n\n    Encoding: UTF-8\n\nNeedless to say, make sure that there are really no characters from encodings like 'latin1'.\n\n\n\u003ca id=\"orgb41e139\"\u003e\u003c/a\u003e\n\n# Viewing Rd files\n\nThe function `viewRd()` can be used to view Rd files in the source directory of a\npackage\u003csup\u003e\u003ca id=\"fnr.6\" class=\"footref\" href=\"#fn.6\"\u003e6\u003c/a\u003e\u003c/sup\u003e.  A typical user call would look something like:\n\n    Rdpack::viewRd(\"./man/filename.Rd\")\n\nThe requested help page is shown in the default format for the current R session (taken from\n`getOption(\"help_type\")`). To request a specific format set `type` to `\"html\"` or `\"text\"`,\nas in:\n\n    Rdpack::viewRd(\"./man/filename.Rd\", type = \"html\") # open in a browser\n    Rdpack::viewRd(\"./man/filename.Rd\", type = \"text\") # text\n\n`viewRd()` renders references and citations correctly, since it processes Rd macros.\n\nUsers of 'devtools' can use `viewRd` in place of `help()` to view rendered Rd\nsources in development mode. This should work also in development mode on any\nplatform (e.g. RStudio, Emacs/ESS, Rgui)\u003csup\u003e\u003ca id=\"fnr.7\" class=\"footref\" href=\"#fn.7\"\u003e7\u003c/a\u003e\u003c/sup\u003e.\n\n\n\u003ca id=\"orgcdf91db\"\u003e\u003c/a\u003e\n\n# Using Rdpack::reprompt()\n\n\n\u003ca id=\"orge44c86a\"\u003e\u003c/a\u003e\n\n## What it does\n\n`Rdpack::reprompt()` updates `Rd` documentation. In the most common case when it\nis called on an `Rd` file, it updates the documentation of all functions,\nmethods and classes documented in the file. For functions this includes\nupdating the usage section, adding missing aliases and `\\item`'s for arguments\nnot described yet. For methods and classes entries for new methods and slots\nare updated in a similar way. See the documentation for details.\n\n`Rdpack::reprompt()` can also be invoked on an object or the name of an object,\njust as `utils::prompt`. In that case it checks for installed documentation for\nthe object and works on it if found. Otherwise it creates an `Rd` file with\ninitial content similar to the one generated by `utils::prompt` but modified\nso that the package can be built.\n\nIf a new function, say `newfun` is to be documented in an existing Rd file, just add\n`newfun()` to the usage section in the file and call `Rdpack::reprompt()` to insert the\ncorrect usage statement, add an alias, and add items for any new arguments. Put quotes around\nthe function name if it is non-syntactic.  For replacement functions (functions with names\nending in `\u003c-`) `reprompt()` will insert the proper usage statement. For example, if the\nsignature of `xxx\u003c-` is `(x, ..., value)`, then both, `\"xxx\u003c-\"()` and `xxx() \u003c- value` will\nbe replaced by `xxx(x, ...) \u003c- value`.\n\n`Rdpack::reprompt()` **does not remove** anything that has become obsolete \nbut it alerts the user to remove aliases, methods, and descriptions of arguments\nthat have been removed. \n\n\n\u003ca id=\"org975854d\"\u003e\u003c/a\u003e\n\n## Reprompt and open in an editor\n\nTo open the `reprompt()`-ed file, argument `edit` can be used.  For this to\nwork, `options(\"editor\")` needs to be set suitably but it usually is.  If `edit\n= TRUE`, then `Rdpack::reprompt()` will open the Rd file in an editor.  For more\nconvenient access to this feature, use `Rdpack::ereprompt()` (edit reprompt),\nwhich calls `Rdpack::reprompt()` with `edit = TRUE` and sets the output filename\nto be the same as the input filename.\n\nIn RStudio, `reprompt()` can be invoked on the `Rd` file being edited or the\nselected name of an object in a source code file using RStudio add-in\n`Repropmpt` (contributed by Duncan Murdoch). Obviously, this makes sense only\nfor Rd files not generated by `roxygen2`.\n\nIn Emacs/ESS there are various ways to use `Rdpack::reprompt()` and\n`Rdpack::ereprompt()`. If `options(\"editor\")` is set to `emacsclient`,\n`Rdpack::ereprompt` is one option. It can also be assigned to a key (wrapped in\nElisp code), for example to be invoked on the currently edited file. Such a\nfunction and example key binding can be found at [georgisemacs](https://github.com/GeoBosh/georgisemacs).\n\n\n\u003ca id=\"orgb77362a\"\u003e\u003c/a\u003e\n\n# Inserting evaluated examples\n\n`Rdpack` provides a macro that takes a chunk of R code, evaluates it, and includes both the code and\nthe results in the rendered documentation. The layout is similar to that in the R console but\nthe code is not prefixed with anything and the output is prefixed with comment symbols.\nFor example,\n\n    \\printExample{2+2; a \u003c- 2*3; a}\n\ngives\n\n    2 + 2\n    ##: 4\n    a \u003c- 2 * 3\n    a\n    ##: 6\n\nThe help page of `?Rdpack::promptUsage` contains a number of examples created with\n`\\printExample`. The corresponding Rd file can be obtained from the package tarball or from\n\u003chttps://github.com/GeoBosh/Rdpack/blob/master/man/promptUsage.Rd\u003e. \n\nVignette [`Inserting_figures_and_evaluated_examples`](https://github.com/GeoBosh/Rdpack/blob/master/vignettes/Inserting_figures_and_evaluated_examples.pdf) gives further details.\n\n\n\u003ca id=\"org3bee793\"\u003e\u003c/a\u003e\n\n## Evaluating the examples in section Examples\n\nThe macro `\\runExamples` can be used as a replacement of section `examples`.  For example, if\nthe following code is put at the top level in an Rd file (i.e. not in a section):\n\n    \\runExamples{2+2; a \u003c- 2*3; a}\n\nthen it will be evaluated and replaced by a normal section examples:\n\n    \\examples{\n    2 + 2\n    ##: 4\n    a \u003c- 2 * 3\n    a\n    ##: 6\n    }\n\nThis generated examples section is processed by the standard R tools (almost) as if it was\nthere from the outset. In particular, the examples are run by the R's quality control tools\nand tangled along with examples in other documentation files\u003csup\u003e\u003ca id=\"fnr.8\" class=\"footref\" href=\"#fn.8\"\u003e8\u003c/a\u003e\u003c/sup\u003e. A small example package\nusing this feature is at [runExamplesCheck](https://github.com/GeoBosh/reprexes/tree/master/runExamplesCheck).\n\n\n\u003ca id=\"org9b84bd5\"\u003e\u003c/a\u003e\n\n# Inserting figures/graphs/plots\n\nFigures can be inserted with the help of the standard Rd markup command `\\figure`.  To\ngenerate figures on the fly, package `\"Rdpack\"` provides the Rd macro `\\insertFig` which\ntakes a snipped of R code, evaluates it and inserts the plot produced by it (using\n`\\figure`).  `\\insertFig` takes three arguments: a filename, the package name and the code to\nevaluate to produce the figure.  For example,\n\n    \\insertFig{cars.png}{mypackage}{x \u003c- cars$speed; y \u003c- cars$dist; plot(x,y)}\n\nwill evaluate the code, save the graph in file `\"man/figures/cars.png\"` subdirectory of\npackage `\"mypackage\"`, and include the figure using `\\figure`. \n\nSee vignette [`Inserting_figures_and_evaluated_examples`](https://github.com/GeoBosh/Rdpack/blob/master/vignettes/Inserting_figures_and_evaluated_examples.pdf) for more details.\n\n\n# Footnotes\n\n\u003csup\u003e\u003ca id=\"fn.1\" href=\"#fnr.1\"\u003e1\u003c/a\u003e\u003c/sup\u003e From `Rdpack (\u003e 2.1.3)` (prompted by Martin R. Smith, issue #23).\n\n\u003csup\u003e\u003ca id=\"fn.2\" href=\"#fnr.2\"\u003e2\u003c/a\u003e\u003c/sup\u003e If you care, here is what happens.  These warnings appear\nbecause `devtools` reroutes the help command to process the developer's Rd\nsources (rather than the documentation in the installed directory) but doesn't\ntell `parse_Rd` where to look for additional macros. Indeed, the message above\nshows that the error is in processing a source Rd file in the development\ndirectory of the package and that the call to `parse_Rd` specifies only the\nfile.\n\n\u003csup\u003e\u003ca id=\"fn.3\" href=\"#fnr.3\"\u003e3\u003c/a\u003e\u003c/sup\u003e Thanks to Michael Dewey for suggesting the discussion of this.\n\n\u003csup\u003e\u003ca id=\"fn.4\" href=\"#fnr.4\"\u003e4\u003c/a\u003e\u003c/sup\u003e From `Rdpack (\u003e=0.9-1)` The issue of not handling the encoding was raised by\nProfessor Brian Ripley.\n\n\u003csup\u003e\u003ca id=\"fn.5\" href=\"#fnr.5\"\u003e5\u003c/a\u003e\u003c/sup\u003e Admittedly, this is not ideal since the user should not need to care how things are\nprocessed internally but I haven't pinpointed the exact cause for this.\n\n\u003csup\u003e\u003ca id=\"fn.6\" href=\"#fnr.6\"\u003e6\u003c/a\u003e\u003c/sup\u003e From `Rdpack (\u003e= 0.4-23)`.\n\n\u003csup\u003e\u003ca id=\"fn.7\" href=\"#fnr.7\"\u003e7\u003c/a\u003e\u003c/sup\u003e In recent versions of Rstudio this function is no longer needed, since\n`?fun` now handles the macros.\n\n\u003csup\u003e\u003ca id=\"fn.8\" href=\"#fnr.8\"\u003e8\u003c/a\u003e\u003c/sup\u003e In versions of `R` before `3.6.0`  the macro `\\runExamples` may cause\n`R CMD check` to give a warning warning about unknown `\\Sexpr` section at top level.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeobosh%2Frdpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeobosh%2Frdpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeobosh%2Frdpack/lists"}