update

Author: salim-b

R/rstd-GEN.R

@@ -1,5 +1,5 @@
 # DO NOT EDIT THIS FILE BY HAND! Instead edit the R Markdown source file `Rmd/rstd.Rmd` and run `pkgpurl::purl_rmd()`.
-# See `README.md#literate-programming` for more information on the literature programming approach used applying the R Markdown format.
+# See `README.md#r-markdown-format` for more information on the literature programming approach used applying the R Markdown format.
 
 utils::globalVariables(names = c(".",
                                  "Key",
@@ -33,7 +33,7 @@ is_uptodate <- function(stable = TRUE,
 #' @param pro `TRUE` for the proprietary RStudio (Server) Pro edition and `FALSE` for the open-source RStudio (Server) edition.
 #' @param os The OS _codename_ for which the RStudio version was built. If `NULL`, it will be auto-detected for the current system.
 #'
-#' @return `r pkgsnippets::return_label("version_nr")`
+#' @return `r pkgsnip::return_label("version_nr")`
 #' @export
 #'
 #' @examples
@@ -93,10 +93,10 @@ latest_version <- function(type = c("desktop", "server"),
 #'   [RStudio Server](https://rstudio.com/products/rstudio/#rstudio-server) release metadata.
 #' @param stable Set to `FALSE` to retrieve release metadata of [RStudio preview builds](https://rstudio.com/products/rstudio/download/preview/) instead of
 #'   [stable builds](https://rstudio.com/products/rstudio/download/).
-#' @param use_cache `r pkgsnippets::param_label("use_cache")`
-#' @param cache_lifespan `r pkgsnippets::param_label("cache_lifespan")` Defaults to 1 day (24 hours).
+#' @param use_cache `r pkgsnip::param_label("use_cache")`
+#' @param cache_lifespan `r pkgsnip::param_label("cache_lifespan")` Defaults to 1 day (24 hours).
 #'
-#' @return `r pkgsnippets::return_label("data")`
+#' @return `r pkgsnip::return_label("data")`
 #' @export
 #'
 #' @examples
@@ -167,7 +167,7 @@ get_releases <- function(type,
 
 #' Determine version of Pandoc bundled with RStudio
 #'
-#' @return `r pkgsnippets::return_label("version_nr")`
+#' @return `r pkgsnip::return_label("version_nr")`
 #' @export
 bundled_pandoc_version <- function() {
 

README.Rmd

@@ -7,17 +7,17 @@ output: pal::gitlab_document
 `r pal::desc_value("Description")`
 
 ## Installation
-```{r, install-snippet-dev, child = pkgsnippets::snippet_path("installation-notice_dev-version_gitlab.Rmd")}
+```{r, install-snippet-dev, child = pkgsnip::snip_path("installation-notice_dev-version_gitlab.Rmd")}
 ```
 
 ## Development
 
-### Literate Programming
-```{r, literate-programming-snippet, child = pkgsnippets::snippet_path("literate-programming-notice.Rmd")}
+### R Markdown format
+```{r, rmd-pkg-snippet, child = pkgsnip::snip_path("rmd-package-notice.Rmd")}
 ```
 
-### Coding Style
-```{r, coding-style-snippet, child = pkgsnippets::snippet_path("coding-style-notice.Rmd")}
+### Coding style
+```{r, coding-style-snippet, child = pkgsnip::snip_path("coding-style-notice.Rmd")}
 ```
 
 ## See also

README.md

@@ -17,19 +17,21 @@ remotes::install_gitlab(repo = "salim_b/r/pkgs/rstd")
 
 ## Development
 
-### Literate Programming
+### R Markdown format
 
-This package is written using a [literate programming](https://en.wikipedia.org/wiki/Literate_programming) approach [originally proposed by Yihui Xie](https://yihui.name/rlp/). All the `-GEN.R` suffixed R source code found under [`R/`](R/) is generated from their respective [R Markdown](https://rmarkdown.rstudio.com/) counterparts using [`pkgpurl::purl_rmd()`](https://gitlab.com/salim_b/r/pkgs/pkgpurl/). Always make changes only to the `.Rmd` files – not the `.R` files – and then run `pkgpurl::purl_rmd()` to regenerate the R source code.
+This package’s source code is written in the [R Markdown](https://rmarkdown.rstudio.com/) file format to facilitate practices commonly referred to as [*literate programming*](https://en.wikipedia.org/wiki/Literate_programming). It allows the actual code to be freely mixed with explanatory and supplementary information in expressive Markdown format instead of having to rely on [`#` comments](https://cran.r-project.org/doc/manuals/r-release/R-lang.html#Comments) only.
 
-### Coding Style
+All the `-GEN.R` suffixed R source code found under [`R/`](R/) is generated from the respective R Markdown counterparts under [`Rmd/`](Rmd/) using [`pkgpurl::purl_rmd()`](https://gitlab.com/salim_b/r/pkgs/pkgpurl/)[^1]. Always make changes only to the `.Rmd` files – never the `.R` files – and then run `pkgpurl::purl_rmd()` to regenerate the R source files.
+
+### Coding style
 
 This package borrows a lot of the [Tidyverse](https://www.tidyverse.org/) design philosophies. The R code adheres to the principles specified in the [Tidyverse Design Guide](https://principles.tidyverse.org/) wherever possible and is formatted according to the [Tidyverse Style Guide](https://style.tidyverse.org/) (TSG) with the following exceptions:
 
 -   Line width is limited to **160 characters**, double the [limit proposed by the TSG](https://style.tidyverse.org/syntax.html#long-lines) (80 characters is ridiculously little given today’s high-resolution wide screen monitors).
 
--   Usage of [magrittr’s compound assignment pipe-operator `%<>%`](https://magrittr.tidyverse.org/reference/compound.html) is desirable[^1].
+-   Usage of [magrittr’s compound assignment pipe-operator `%<>%`](https://magrittr.tidyverse.org/reference/compound.html) is desirable[^2].
 
--   Usage of [R’s right-hand assignment operator `->`](https://rdrr.io/r/base/assignOps.html) is not allowed[^2].
+-   Usage of [R’s right-hand assignment operator `->`](https://rdrr.io/r/base/assignOps.html) is not allowed[^3].
 
 As far as possible, these deviations from the TSG plus some additional restrictions are formally specified in the [lintr configuration file](https://github.com/jimhester/lintr#project-configuration) [`.lintr`](.lintr), so lintr can be used right away to check for formatting issues:
 
@@ -41,6 +43,8 @@ pkgpurl::lint_rmd()
 
 -   The official [**rstudioapi**](https://rstudio.github.io/rstudioapi/) R package containing a handful of useful wrapper functions to access the [RStudio API](https://rstudio.github.io/rstudio-extensions/rstudioapi.html).
 
-[^1]: The TSG [explicitly instructs to avoid this operator](https://style.tidyverse.org/pipes.html#assignment-1) – presumably because it’s relatively unknown and therefore might be confused with the forward pipe operator `%>%` when skimming code only briefly. I don’t consider this to be an actual issue since there aren’t many sensible usage patterns of `%>%` at the beginning of a pipe sequence inside a function – I can only think of creating side effects and relying on [R’s implicit return of the last evaluated expression](https://rdrr.io/r/base/function.html). Therefore – and because I really like the `%<>%` operator – it’s usage is welcome.
+[^1]: This naming convention as well as the very idea to leverage the R Markdown format to author R packages was originally proposed by Yihui Xie. See his excellent [blog post](https://yihui.name/rlp/) for more detailed information about the benefits of literate programming techniques and some practical examples. Note that using `pkgpurl::purl_rmd()` is a less cumbersome alternative to the Makefile approach outlined by him.
+
+[^2]: The TSG [explicitly instructs to avoid this operator](https://style.tidyverse.org/pipes.html#assignment-1) – presumably because it’s relatively unknown and therefore might be confused with the forward pipe operator `%>%` when skimming code only briefly. I don’t consider this to be an actual issue since there aren’t many sensible usage patterns of `%>%` at the beginning of a pipe sequence inside a function – I can only think of creating side effects and relying on [R’s implicit return of the last evaluated expression](https://rdrr.io/r/base/function.html). Therefore – and because I really like the `%<>%` operator – it’s usage is welcome.
 
-[^2]: The TSG [explicitly accepts `->` for assignments at the end of a pipe sequence](https://style.tidyverse.org/pipes.html#assignment-1) while Google’s R Style Guide [considers this bad practice](https://google.github.io/styleguide/Rguide.html#right-hand-assignment) because it “makes it harder to see in code where an object is defined”. I second the latter.
+[^3]: The TSG [explicitly accepts `->` for assignments at the end of a pipe sequence](https://style.tidyverse.org/pipes.html#assignment-1) while Google’s R Style Guide [considers this bad practice](https://google.github.io/styleguide/Rguide.html#right-hand-assignment) because it “makes it harder to see in code where an object is defined”. I second the latter.

Rmd/rstd.Rmd

@@ -79,7 +79,7 @@ is_uptodate <- function(stable = TRUE,
 #' @param pro `TRUE` for the proprietary RStudio (Server) Pro edition and `FALSE` for the open-source RStudio (Server) edition.
 #' @param os The OS _codename_ for which the RStudio version was built. If `NULL`, it will be auto-detected for the current system.
 #'
-#' @return `r pkgsnippets::return_label("version_nr")`
+#' @return `r pkgsnip::return_label("version_nr")`
 #' @export
 #'
 #' @examples
@@ -162,10 +162,10 @@ TODO:
 #'   [RStudio Server](https://rstudio.com/products/rstudio/#rstudio-server) release metadata.
 #' @param stable Set to `FALSE` to retrieve release metadata of [RStudio preview builds](https://rstudio.com/products/rstudio/download/preview/) instead of
 #'   [stable builds](https://rstudio.com/products/rstudio/download/).
-#' @param use_cache `r pkgsnippets::param_label("use_cache")`
-#' @param cache_lifespan `r pkgsnippets::param_label("cache_lifespan")` Defaults to 1 day (24 hours).
+#' @param use_cache `r pkgsnip::param_label("use_cache")`
+#' @param cache_lifespan `r pkgsnip::param_label("cache_lifespan")` Defaults to 1 day (24 hours).
 #'
-#' @return `r pkgsnippets::return_label("data")`
+#' @return `r pkgsnip::return_label("data")`
 #' @export
 #'
 #' @examples
@@ -240,7 +240,7 @@ get_releases <- function(type,
 ```{r}
 #' Determine version of Pandoc bundled with RStudio
 #'
-#' @return `r pkgsnippets::return_label("version_nr")`
+#' @return `r pkgsnip::return_label("version_nr")`
 #' @export
 bundled_pandoc_version <- function() {