README.md

In Thell/knitLiteral: Literal Verbatim Knitr Chunks

knitLiteral

A knitr hook to output chunks as you intend them to be displayed for examples and tutorials.

Motivation

When writing documents about knitr usage I wanted to be able to output a full chunk as it would be written and it seems I'm not the only one.

Currently knitr-examples $062$ and $065$ give methods of accomplishing a wrap of the current option labels and the code. Another common option is wrapping html tags around chunks (authoring rcodechunks). Thankfully some nice results can be obtained using the hooking mechanisms provided by Yihui in knitr (example 1 and example 2).

In the end something is needed that will

• Be in line with the spirit of the knitr front end. ( Easy to use and explain. )
• Follow the DRY/SPOT principle.
• Enhance reproducability. ( Literally cut and paste into new source documents. )
• Be accessible for styling and scripting in the final output.
• Be compatible with multiple knitr input/output combinations.

and most of all...

• Follow the original philosophy of markdown.

  ... A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. ...

Also see the upcoming version of r markdown.

Installing

Install from source using devtools:

install_github("thell/knitLiteral")

Usage

Basic

Create your source document as normal. In your setup chunk include

knitLiteral::kast_on()

At the end of your chunk parameters include literal=TRUE, then knit.

Advanced

Naming:

A "name" argument may be provided to kast_on. When a name is provided the parameter name, option template names and the associated .opts parameter will use it.

Chunk Parameters:

Knitr processes chunk parameters in the order they appear in the chunk header so any chunk options following the literal=TRUE will be active but will not appear in the output giving you the ability to create chunks that literally display what you want.

Option Templates:

Some option templates have been provided and can be enabled in the setup chunk with the templates flag of the kast_on function. Any opts.label template beginning with the kast hook's name are treated the same as literal=TRUE for output.

literal.opts:

`empty=TRUE` - omit chunk contents from output.

At this time only a single option is available.

Styling:

Each literal chunk is giving a unique id with classes assigned to assist in styling.

Thell/knitLiteral documentation built on May 9, 2019, 4:28 p.m.