Providing documentation for the `asis` engine

[lauracion]

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)."

[zachary-foster]

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.
``'

[zachary-foster]

Adding a knitr engine might work:

https://yihui.name/knitr/demo/engines/

[zachary-foster]

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.

[lauracion]

That was a fast resolution! Thank you!

[zachary-foster]

No problem!

[jtr13]

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.

[zachary-foster]

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.
``'

[jtr13]

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/

[zachary-foster]

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

[jtr13]

Ok, so I hereby change this issue to providing documentation for the asis engine!

[apreshill]

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!

[lauracion]

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.

[maurolepore]

Thank you @zachary-foster ! It'll be cool to tweet this on #rstats.

[yihui]

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.

[lauracion]

:heart_eyes: Thank you, @yihui!!