unconf18
unconf18 copied to clipboard
ropensci
Providing documentation for the `asis` engine
Another of the projects that came up while discussing #42
@jtr13 wrote: "there's one small piece of the puzzle that I doubt would be hard to implement and would make a big difference. That is, having an echo=FALSE option for text, to provide the same flexibility for text in progress as we have with code in progress. I can think of so many uses: the ability for example to create assignments with and without solutions (... there are workarounds using comments in code chunks but that's not the same)."
Good idea!
I recently got something like this to work using another kind of workaround. I was using knitr hooks to hide the results of a chunk until a button is pressed:
knitr::knit_hooks$set(
hide_button = function(before, options, envir) {
if (is.character(options$hide_button)) {
button_text = options$hide_button
} else {
button_text = "Show solution"
}
block_label <- paste0("hide_button", options$label)
if (before) {
return(paste0(sep = "\n",
'<button class="btn btn-danger" data-toggle="collapse" data-target="#', block_label, '"> ', button_text, ' </button>\n',
'<div id="', block_label, '" class="collapse">\n'))
} else {
return("</div><br />\n")
}
}
}
Then you can add something like this to the Rmd:
```{r hide_button = "Show Answer", results = 'asis', echo = FALSE}
cat(
"The answer."
)
``'
It would be great if I did not have to use cat and results = 'asis', echo = FALSE. Perhaps there is / could be a "plain text" chunk type. Perhaps something like:
```{text echo = FALSE}
## Something entirely not thought out
I really would rather people not see this yet.
``'
This would also allow for varaibles to determine which parts of the rmd are shown, like:
```{r include = FALSE}
show_in_progress = TRUE
``'
bla bla
```{text echo = show_in_progress}
## Something entirely not thought out
I really would rather people not see this yet.
``'
Adding a knitr engine might work:
https://yihui.name/knitr/demo/engines/
Oh wait, it already exists, you can use the asis chunk type to put markdown in chunks and use echo = FALSE to not include them. I just tried it and it works.
Thanks... The problem though with asis is that you still need cat() which is a pain. In addition, with math equations you have to double escape the tex stuff, which is difficult. (See here: https://community.rstudio.com/t/echo-false-type-option-for-rmarkdown-text/2384 -- this has been on my mind for a while!)
I have in mind being able to write markdown paragraphs that are included or not, without having to wrap each line in r code.
I dont think you need cat. I meant the chunk engine asis, not the chunk option results = "asis". Like so:
# Show
```{asis echo = FALSE}
## Something entirely not thought out
I really would rather people not see this yet.
``' # (' instead of ` is for github markdown formatting)
# Dont show
```{asis echo = FALSE}
## Something entirely not thought out
I really would rather people not see this yet.
``'
Aha... brilliant! Where can I apply to get back the time I lost on workarounds??? :-) Also, is that documented anywhere? Not here: https://yihui.name/knitr/demo/engines/
Where can I apply to get back the time I lost on workarounds???
Haha, there is probably a form you can fill out somewhere.
Also, is that documented anywhere?
Not that I saw. I had to look through the source code to find it:
https://github.com/yihui/knitr/blob/dc028f4c9698f84999b53edc5f6f255b29d7e5a2/R/engine.R#L390-L392
Ok, so I hereby change this issue to providing documentation for the asis engine!
A related tool I was just made aware of from issue #63 is assignr: https://github.com/coatless/assignr
I have not used, but looks promising @jtr13!
Summary: engine asis in knitr can be used to easily exclude from the final report chunks of text that are still in progress. asis needs to be documented.
It was only documented in two places: 1) the source code in knitr:::eng_asis (in the spirit of "Luke, use the source"); and 2) the knitr book, which is unfortunately not freely available like my other books, but you can still see the relevant text from Google Books: https://books.google.com/books?id=fyIuDwAAQBAJ&lpg=PP1&dq=dynamic%20documents%20with%20r%20and%20knitr&pg=PT145#v=onepage&q=asis%20engine&f=false
There are still many other features of knitr that are not publicly documented, and I plan to address this problem later this year by writing another book that will be free to read.
