In carpentries/dovetail: Document Engine to Insert Nested Block Quotes

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
ic <- knitr::all_patterns$md$inline.code
tic <- substr(ic, nchar(ic), nchar(ic))
ntic <- function(n = 4) paste(rep(tic, n), collapse = "")
chlng <- paste0(ntic(4), "{challenge}")

dovetail

A dovetail joint or simply dovetail is a joinery technique most commonly used in woodworking joinery (carpentry) ...

Source: https://en.wikipedia.org/wiki/Dovetail

The goal of {dovetail} is to provide a {knitr} engine that allows users to write nested div tags or blockquotes containing executable code as {roxygen2}-formatted blocks. This will provide a simpler syntax for construction of special blockquotes in Carpentries lessons. These nested block quotes normally represent solutions that the learner should not see until they have attempted a given challenge.

Usage

To use {dovetail}, add library("dovetail") in the setup chunk of your Rmarkdown document and set the engine to one of the following options: r dovetail:::OUR_TAGS[dovetail:::OUR_TAGS != "end"].

Installation

This project is currently a Work In Progress, but you can install it from the Carpentries github account:

if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
remotes::install_github("carpentries/dovetail")

Example

Consider the following block quote (taken from episode 6 of R novice gapminder) that gives a challenge block with a single solution block nested within it.

Written without the {dovetail} engine, the lesson contributor previously had to write nested block quotes with kramdown tags like so:

r invisible(knitr::opts_chunk$set(eval = FALSE))

> ## Challenge 2
> 
> Given the following code:
> 
> ```r
> x <- c(5.4, 6.2, 7.1, 4.8, 7.5)
> names(x) <- c('a', 'b', 'c', 'd', 'e')
> print(x)
> ```
> 
> Write a subsetting command to return the values in x that are greater than 4 and less than 7.
> 
> > ## Solution to challenge 2
> > 
> > ```r
> > x_subset <- x[x<7 & x>4]
> > print(x_subset)
> > ```
> {: .solution}
{: .challenge}

While this solution does provide a way of constructing the nested block quotes for lessons, it comes with a downside that it's no longer easy to evaluate code within these blocks since they are pre-pended by any number of > symbols.

invisible(knitr::opts_chunk$set(eval = TRUE))

With {dovetail}, the above block quote becomes a series of roxygen blocks with r-code interspersed. The beginning of a nested block is a special #' @solution tag that will indicate the start of a nested block:

`r invisible(knitr::opts_chunk$set(eval = FALSE)); chlng`
#' ## Challenge 2
#' 
#' Given the following code:
#'
#' ```r
x <- c(5.4, 6.2, 7.1, 4.8, 7.5)
names(x) <- c('a', 'b', 'c', 'd', 'e')
print(x)
#' ```
#'
#' Write a subsetting command to return the values in x that are greater than 4 and less than 7.
#'
#' @solution Solution to challenge 2
#'
#' ```r
x_subset <- x[x<7 & x>4]
print(x_subset)
#' ```
```r
invisible(knitr::opts_chunk$set(eval = TRUE))
cat(ntic(4))
```

The result looks like this:

<div class='challenge' markdown='1'>

## Challenge 2

Given the following code:

```r
x <- c(5.4, 6.2, 7.1, 4.8, 7.5)
names(x) <- c('a', 'b', 'c', 'd', 'e')
print(x)
```

```
##   a   b   c   d   e 
## 5.4 6.2 7.1 4.8 7.5
```
Write a subsetting command to return the values in x that are greater than 4 and less than 7.

<div class='solution' markdown='1'>

## Solution to challenge 2


```r
x_subset <- x[x<7 & x>4]
print(x_subset)
```

```
##   a   b   d 
## 5.4 6.2 4.8
```

</div>

</div>

carpentries/dovetail documentation built on Sept. 23, 2021, 9:35 p.m.