---
title: "knit literal knitr chunks"
author: "Thell"
date: "04/03/2014"
output:
  html_document:
    toc: yes
    toc_depth: 4
  pdf_document:
    toc: yes
    toc_depth: 4
  word_document: default
---

```{r "knitr-setup", include=FALSE, cache=FALSE}
# knitr-setup should be the first chunk in the document.
knitLiteral::kast_on()
```

# About

The knitLiteral package gives authors the ability to easily output
the exact the source of a chunk without side-effects. It is simple
to use; just remember that knitr processes chunk options as they occur
and options can occur more than once.

The main option that knitLiteral allows is `literal=TRUE`. This
option allows you to generate the output you literally want to use
in knitr to produce a result _without_ repeating yourself or
breaking the parser. (_Notice the use of 4 backticks instead of
the minimal 3 to allow R syntax highlighting to work._)

If the _literal_ label is used more than once in a particular chunk
and the options __end__ with `literal=TRUE` then only the final
`literal=TRUE` will be removed, which allows for illustrating how
the literal chunk was produced.

The rmarkdown in this sample document should produce _very_ similar
results using either rmarkdown v1 or v2 and using pandoc to generate
Word, pdf or html output. Other output formats have not been tested.

# Setup

It is very easy to initialize using `kast_on` in your first chunk.

````{r "knitr-setup", include=FALSE, cache=FALSE, literal=TRUE, include=TRUE, echo=FALSE}
````

It is very easy to style using `dye` in your closing chunk.

````{r "include-after", echo=FALSE, results='asis', opts.label="literal"}
# include-after should be the last chunk in the document.
knitLiteral::dye()
````

# Examples

Each sample shows the _Source_ along with the rendered _Literal_ and
normal _Output_.

## No output, caching only

__Source__
_Following the DRY principle this is the source for __all__ "example" chunks._

````{r "example", eval=FALSE, echo=FALSE, literal=TRUE, opts.label="literal-quote"}
print('hello world!')
print('hello again!')
````

__Literal__

````{r "example", eval=FALSE, echo=FALSE, literal=TRUE}
````

__Output__ (_none_)

## Default

__Source__

````{r "example", literal=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", literal=TRUE}
````

## Default comment

Set the global default `comment` option to match normal console output
using `opts_chunk$set(comment=NA)`.

`r knitr::opts_chunk$set(comment=NA)`

__Source__

````{r "example", literal=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", literal=TRUE}
````

## Chunk comment

__Source__

````{r "example", comment="override > ", literal=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", comment="override > ", literal=TRUE}
````

## No echo

__Source__

````{r "example", echo=FALSE, literal=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", echo=FALSE, literal=TRUE}
````

## Collapse

__Source__

````{r "example", collapse=TRUE, literal=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", collapse=TRUE, literal=TRUE}
````

## Hold {#Hold}

__Source__

````{r "example", results='hold', literal=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", results='hold', literal=TRUE}
````

## Collapse & hold

__Source__

````{r "example", collapse=TRUE, results='hold', literal=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", collapse=TRUE, results='hold', literal=TRUE}
````

## Echo & no-eval, no-echo & hold combo

__Source__

````{r "example", eval=FALSE, literal=TRUE, echo=FALSE, opts.label="literal-literal"}
````

````{r "example", echo=FALSE, results='hold', opts.label="literal-reuse", literal=TRUE, indent="> "}
````

````{r "example", eval=FALSE, opts.label="literal-literal"}
````

````{r "example", echo=FALSE, results='hold', opts.label="literal-literal"}
````

__Rendered__ _(the normal output is the same as a simple [hold](#Hold))_

````{r "example", eval=FALSE, literal=TRUE, echo=FALSE}
````

````{r "example", echo=FALSE, results='hold', opts.label="literal-reuse"}
````

````{r "example", eval=FALSE}
````

````{r "example", echo=FALSE, results='hold'}
````

## Echo & no-eval, no-echo & collapse combo {#MDExample}

__Source__

````{r "example", eval=FALSE, literal=TRUE, echo=FALSE, opts.label="literal-reuse", indent="> "}
````

````{r "example", echo=FALSE, collapse=TRUE, opts.label="literal-reuse", literal=TRUE, indent="> "}
````

````{r "example", eval=FALSE, opts.label="literal-literal"}
````

````{r "example", echo=FALSE, collapse=TRUE, opts.label="literal-literal"}
````

__Rendered__

````{r "example", eval=FALSE, literal=TRUE, echo=FALSE}
````

````{r "example", echo=FALSE, collapse=TRUE, opts.label="literal-reuse"}
````

````{r "example", eval=FALSE}
````

````{r "example", echo=FALSE, collapse=TRUE}
````

# Silent Tidy of training chunk.

Imagine having a chunk to use for training, but it needs tidying,
and the tidying has nothing to do with the training. By taking
advantage of how knitr handles chunk options a chunk can be
silently turned into a nice example.

Starting with a cached chunk like this

````{r "tidy-example", echo=FALSE, eval=FALSE, literal=TRUE}
# This should not be displayed, it is just a note to myself

# that this coding is horrible and would be _wrong_.

##' Without a doubt!

if ( ( knitr::opts_current$get("literal") == TRUE ) && ( knitr::opts_current$get("literal") == TRUE ) )
  {
  foo<-FALSE } else {
    foo = TRUE
  listfoo <- list( first="second", second="third", third="fourth", fourth=fifth, and="so on")
}
````

Make a new options template like this

````{r "opt_template", include=FALSE, cache=FALSE, literal=TRUE, include=TRUE, echo=FALSE}
knitr::opts_template$set( "literal-tidy"=
  list( literal=TRUE, echo=FALSE, eval=FALSE, tidy=TRUE,
        tidy.opts=c( width.cutoff=50, keep.comment=FALSE,
                     keep.blank.line=FALSE, replace.assign=TRUE)))
````

And use it like this

````{r "tidy-example", opts.label="literal-tidy", literal=TRUE, literal.opts=list(empty=TRUE)}
````

To get results like this

````{r "tidy-example", echo=FALSE, eval=FALSE, literal=TRUE, tidy=TRUE, tidy.opts=c("width.cutoff"=50, "keep.comment"=FALSE, "keep.blank.line"=FALSE, "replace.assign"=TRUE)}
````

Which is a much better, although still bad, example.

# knit markdown output.

If you are interested in keeping a clean and readable markdown file
the following is the knitr generated markdown from the
[Echo & no-eval, no-echo & collapse combo](#MDExample) example.

    ````{r "example", eval=FALSE, literal=TRUE, echo=FALSE}
    ````
    ````{r "example", echo=FALSE, collapse=TRUE, opts.label="literal-reuse"}
    ````
    ````{r "example", eval=FALSE}
    ````
    ````{r "example", echo=FALSE, collapse=TRUE}
    ````

# Styling Information

## HTML Classes

The knitr chunk `pre class` and `code class`.

~~~~~~~~~~~{.html}
<pre class="sourceCode knitr r markdown"><code class="sourceCode r">
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

## CSS

The style for the knitr blocks was accomplished by simply using four
back ticks instead of three so the R syntax highlighter would work
and by defining a style.

~~~~~~ {.css}
````{r "literalize.css", echo=FALSE, results='asis'}
css <- system.file("css/literalize.css", package = "knitLiteral")
css <- readLines(css)
cat( css, sep="\n" )
````
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

## Javascript for rmarkdown v1

~~~~~~ {.javascript}
````{r "literalize.js", echo=FALSE, results='asis'}
js <- system.file("js/literalize.js", package = "knitLiteral")
js <- readLines(js)
cat( js, sep="\n" )
````
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

````{r "include-after", echo=FALSE, results='asis'}
````