diff --git a/docs/articles/r-markdown.html b/docs/articles/r-markdown.html
index eeb298b1..c403854e 100644
--- a/docs/articles/r-markdown.html
+++ b/docs/articles/r-markdown.html
@@ -40,7 +40,7 @@
cmdstanr
- 0.6.0
+ 0.6.1
@@ -143,13 +143,27 @@ Mikhail
R Markdown supports a variety of languages through the use of knitr
-language engines. One such engine is the stan engine, which
-allows users to write Stan programs directly in their R Markdown
-documents by setting the language of the chunk to stan.
-Behind the scenes, the engine relies on RStan to compile the model
-code into an in-memory stanmodel, which is assigned to a
-variable with the name given by the output.var chunk
-option. For example:
+language engines. Where users wish to write Stan programs as chunks
+directly in R Markdown documents there are three options:
+
+- the user wishes all the Stan chunks in the R Markdown document to be
+processed using RStan;
+
+- all Stan chunks are to be processed using CmdStanR; and.
+
+- some chunks are to be processed by RStan and some by CmdStanR.
+
+Behind the scenes in each option, the engine compiles the model code
+in each chunk and creates an object that provides methods to run the
+model: a stanmodel if Rstan is being used, or a
+CmdStanModel in the CmdStanR case. This model object is
+assigned to a variable with the name given by the
+output.var chunk option.
+
+
Option 1: Using RStan for all chunks
+
+
This is the default option. In that case we can write, for
+example:
```{stan, output.var="model"}
// Stan model code
```
@@ -157,19 +171,21 @@ Mikhail
```{r}
rstan::sampling(model)
```
-
CmdStanR provides a replacement engine, which can be registered as
-follows:
+
+
Option 2: Using CmdStanR for all chunks
+
+
If CmdStanR is being used a replacement engine needs to be registered
+along the following lines:
-
By default, this overrides knitr’s built-in stan engine
-so that all stan chunks are processed with CmdStanR, not
-RStan. Of course, this also means that the variable specified by
+register_knitr_engine(override = TRUE)
This overrides knitr’s built-in stan engine so that all
+stan chunks are processed with CmdStanR, not RStan. Of
+course, this also means that the variable specified by
output.var will no longer be a stanmodel
-object, but instead a CmdStanModel object, so the code
-above would look like this:
+object, but instead a CmdStanModel object, so the example
+code above would look like this:
```{stan, output.var="model"}
// Stan model code
```
@@ -177,6 +193,7 @@ Mikhail
```{r}
model$sample()
```
Example
@@ -212,7 +229,7 @@
-
Caching chunks
-
-
Use cache=TRUE chunk option to avoid re-compiling the
-Stan model code every time the R Markdown is knit/rendered.
-
You can find the Stan model file and the compiled executable in the
-document’s cache directory.
-
-
Using RStan and CmdStanR engines side-by-side
+Option 3: Using both RStan and CmdStanR in the same R Markdown
+document
While the default behavior is to override the built-in
stan engine because the assumption is that the user is
@@ -259,6 +269,14 @@
Using RStan and CmdStanR
```
+
Caching chunks
+
+
Use cache=TRUE chunk option to avoid re-compiling the
+Stan model code every time the R Markdown is knit/rendered.
+
You can find the Stan model file and the compiled executable in the
+document’s cache directory.
+
Running interactively
When running chunks interactively in RStudio (e.g. when using R
diff --git a/vignettes/r-markdown.Rmd b/vignettes/r-markdown.Rmd
index dac62ede..ec03831e 100644
--- a/vignettes/r-markdown.Rmd
+++ b/vignettes/r-markdown.Rmd
@@ -21,13 +21,21 @@ knitr::opts_chunk$set(
```
R Markdown supports a variety of languages through the use of knitr language
-engines. One such engine is the `stan` engine, which allows users to write Stan
-programs directly in their R Markdown documents by setting the language of the
-chunk to `stan`.
+engines. Where users wish to write Stan programs as chunks directly in R Markdown documents there are three options:
-Behind the scenes, the engine relies on RStan to compile the model code into an
-in-memory `stanmodel`, which is assigned to a variable with the name given by
-the `output.var` chunk option. For example:
+1. the user wishes all the Stan chunks in the R Markdown document to be processed using RStan;
+2. all Stan chunks are to be processed using CmdStanR; and.
+3. some chunks are to be processed by RStan and some by CmdStanR.
+
+Behind the scenes in each option, the engine compiles the model code in each
+chunk and creates an object that provides methods to run the model: a
+`stanmodel` if Rstan is being used, or a `CmdStanModel` in the CmdStanR case.
+This model object is assigned to a variable with the name given by the
+`output.var` chunk option.
+
+## Option 1: Using RStan for all chunks
+
+This is the default option. In that case we can write, for example:
````{verbatim}
```{stan, output.var="model"}
@@ -39,19 +47,19 @@ rstan::sampling(model)
```
````
-CmdStanR provides a replacement engine, which can be registered as follows:
+## Option 2: Using CmdStanR for all chunks
+
+If CmdStanR is being used a replacement engine needs to be registered along the following lines:
```{r register-engine, message=FALSE}
library(cmdstanr)
-check_cmdstan_toolchain(fix = TRUE, quiet = TRUE)
-
-register_knitr_engine()
+register_knitr_engine(override = TRUE)
```
-By default, this overrides knitr's built-in `stan` engine so that all `stan`
+This overrides knitr's built-in `stan` engine so that all `stan`
chunks are processed with CmdStanR, not RStan. Of course, this also means that
the variable specified by `output.var` will no longer be a `stanmodel` object,
-but instead a `CmdStanModel` object, so the code above would look like this:
+but instead a `CmdStanModel` object, so the example code above would look like this:
````{verbatim}
```{stan, output.var="model"}
@@ -89,15 +97,8 @@ fit <- ex1$sample(
print(fit)
```
-## Caching chunks
-
-Use `cache=TRUE` chunk option to avoid re-compiling the Stan model code every
-time the R Markdown is knit/rendered.
-
-You can find the Stan model file and the compiled executable in the document's
-cache directory.
-## Using RStan and CmdStanR engines side-by-side
+## Option 3: Using both RStan and CmdStanR in the same R Markdown document
While the default behavior is to override the built-in `stan` engine because the
assumption is that the user is probably not using both RStan and CmdStanR in the
@@ -130,6 +131,17 @@ model_obj2$sample()
```
````
+
+## Caching chunks
+
+Use `cache=TRUE` chunk option to avoid re-compiling the Stan model code every
+time the R Markdown is knit/rendered.
+
+You can find the Stan model file and the compiled executable in the document's
+cache directory.
+
+
+
## Running interactively
When running chunks interactively in RStudio (e.g. when using