In grimbough/msmbstyle: MSMB Styles for R Markdown Documents

Questions and Solutions

In teaching material it is common to want to include questions (and possibly solutions) to the reader. It is possible to use custom blocks to achieve distinct styling, however this doesn't provide internal labelling, referencing and numbering. bookdown doesn't current provide an environment for questions and answers, although one can manipulate the various "theorems" to achieve something similar.

msmbstyle provides a set of functions that can be used to demark questions and answers in the the R Markdown document. They can be used either inline or in code chunks, and the precise usage may vary depending upon the complexity of the text you wish to include.

Questions

Simple question

If your question is simply a paragraph of text, you can use msmbstyle::question() and provide the paragraph via the argument text. We see an example of this approach below r tufte::margin_note('The code is shown here, but it would be more typical to hide it via \x60echo = FALSE\x60').

msmbstyle::question(text = "Is this question displaying correctly?")

You can also include a question using inline code e.g. `r knitr::inline_expr("msmbstyle::question()")`. This is perhaps simpler than using code chunks, since it is unlikely we ever want to display the function call itself. The question below is generated in this fashion.

r msmbstyle::question(text = "This is our second question. It should not be numbered. Is it?")

In addition to the text argument, you can also provide a label to the function. label is optional, and if provided can be used to reference the label in the main text of the book. Labels for questions must start with the string 'ques:' In Question \@ref(ques:two) we can see an example of a labelled question that can be referenced (as seen in this sentence).

r tufte::margin_note("Currently using references to a question will result in a warning such as '\x60The label(s) ques:two not found\x60'. This is because **knitr** is unable to resolve the reference (since this is an addon). This is irritating, but can be ignored, and may be addressed in the future")

r msmbstyle::question(label = "ques:two", text = "This is our second question. We expect this to have a number.")

Including "code" in a question. {-}

In order to include text formated to look like R code in you can use the sequence '\x60' to represent the backticks inside the text argument e.g.

r msmbstyle::question(text = "Does this question include \x60x\x60 and \x60y\x60?")

More complex questions

If you need to provide more detail than a single paragraph in a question, you can use the functions question_begin() and question_end() to demark the content of the document you wish to be included in the question. r tufte::margin_note("This is similar to using \x60\\begin{}\x60 and \x60\\end{}\x60 tags in a Latex document.").\@ref(ques:fail)

They can again be called either inline or in code chunks (inline seems simpler) within the R Markdown document, and it is imperative they be used as a pair, otherwise the resulting document will have missmatched HTML tags r tufte::margin_note("currently there's no sanity checking for this, it's up to the author!").

The example below shows a question that involves several paragraphs of text, along with a code block and the output created by running this code.

r msmbstyle::question_begin()

This is a more complex question. It involves both this text, some code, and the plot produced by that code.

plot( 1:10 )

What do you think about the data shown in Figure \@ref(fig:longer-question)?

r msmbstyle::question_end()

Solutions

In similar fasion to questions, you can insert solutions using either the function msmbstyle::solution(), or a combination of msmbstyle::solution_begin() & msmbstyle::solution_end(). Currently solutions can not be labelled or reference in the text. This is primarily because of an assumption that they would always have an accompanying question that could be referenced, and may change in the future.

Simple solution

Again, if your solution is just a single a paragraph of text, you can use msmbstyle::solution() and provide the paragraph via the argument text. We see an example of this approach below:

r msmbstyle::solution(text = "This is a single paragraph providing an answer.")

There are additional arguments to this function: header and toggle. header allows you to set the headeing text that begins a solution e.g. if you would rather they were called 'answers'. toggle expects a logical which, if set to TRUE (the default), will create the solution in a 'collapsed' format. Pressing the plus icon will then show the content of the solution. This gives the option of initially hiding a solution, so the reader is forced into taking an active step to reveal the answer.

Below is an example where the collapsing behaviour has been turned off and the section header renamed.

msmbstyle::solution(text = "This an 'Answer' and cannot be hidden",
                    header = "Answer",
                    toggle = FALSE)

More complex solutions

More comprehensive solutions can similarly be indicated with calls to solution_begin() and solution_end(). The first of these takes the same arguments as solution() allowing you to set the visibility toggle and section heading text.

r msmbstyle::solution_begin()

This is a more complex solution. We'll reuse some plotting code from the tufte vignette to include a figure in the margin.

library(ggplot2)
mtcars2 <- mtcars
mtcars2$am <- factor(
  mtcars$am, labels = c('automatic', 'manual')
)
ggplot(mtcars2, aes(hp, mpg, color = am)) +
  geom_point() + geom_smooth() +
  theme(legend.position = 'bottom')

r msmbstyle::solution_end()

Everything including the margin figure is contained within our 'collapsed' solution environment and can be revealed by clicking on the plus symbol.

grimbough/msmbstyle documentation built on April 9, 2022, 5:09 p.m.