The current implementation replaces all chunks in a document with one set of strings. While this is simple and practical, it is not particularly flexible, and requires that all instructions be outside the code blocks. One alternative that would preserve flexibility would be to allow code blocks to retain their comments. This would allow more hints or directions to be left within the code block to prompt users.

A code block that looked like this:

```{r solution=TRUE}
# read in a tsv file
read_tsv("file.txt")
# write it as a csv
write_csv("file.csv")
```

would then be transformed to something like this:

```{r solution=TRUE}
# read in a tsv file
### Your code here
# write it as a csv
### Your code here
```

When we designate a chunk to be "exrcised", we use a flag like solution = TRUE, but these can be confusing for people opening the notebook, since they do not have a designated function in a normal notebook.

exrcise could have the option to remove this flag from the output, leaving a chunk with no trace of the exrcision* that it went through.

* now I am just making up words.

While #2 addresses the idea of leaving comments in code block as a guide to people completing the notebook, sometimes it may be desirable to have some working code retained, or a skeleton of the working code included, and not commented out. To accomplish this, it may be nice to have a way to designate lines that should be retained.

learnr accomplishes something like this with separate solution blocks, but that seems too heavyweight for this application, and potentially allows drift between the exercise block and the solution.

In the Jupyter world, nbgrader instead uses specific comments to designate the start and end of a solution section, retaining the code outside those comments, and replacing only the code within the comments with a code stub:
### BEGIN SOLUTION and ### END SOLUTION. This solution has the advantage that the solved code chunk will run in the original document as a check that it is correct behaving as intended.

Under this scheme code of the following form:

### BEGIN SOLUTION
plot(data)
### END SOLUTION

would become:

### YOUR CODE HERE

or similar.

One other alternative is an indicator that a specific line should be replaced by commenting at the end of the line that would indicate that particular line should be replaced.

This could look like this:

plot(data) ### SOLUTION

to get the same result as above.

One other implementation might include a way to strip a commented line. Something like this:

### BEGIN SOLUTION
plot(data)
#> plot(<YOURDATA>)
### END SOLUTION

could turn into:

plot(<YOURDATA>)

Right now, we can't exrcise shell chunks, or chunks without a language specification. It would be handy for our alevin material if we could do that.

While it is convenient and helpful to use knitr functions where possible to avoid new parsing errors, the use of unexported functions is not a good idea, as these could be changed in a future release.

knitr:::parse_params() is currently used to find whether a code block contains one of the flags that indicates a block should be replaced, but this could presumably be done by a more direct search for the flag options, without fully parsing the parameter list, and without relying on un exported external package code.