This repository has been archived as this solution was not found to be favorable for our community More information can be found in our blog post detailing the results of Alpha Testing
A dovetail joint or simply dovetail is a joinery technique most commonly used in woodworking joinery (carpentry) …
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.
To use {dovetail}, add library("dovetail") in the setup chunk of your
Rmarkdown document and set the engine to one of the following options:
callout, challenge, checklist, discussion, keypoints, objectives,
prereq, solution, testimonial.
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")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:
> ## 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.
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:
````{challenge}
#' ## 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)
#' ```
````
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>