In yihui/rlp: An Example of Using Literate Programming for R Package Development

Use the Two-column Docco Style

The two-column Docco style is one of my favorite HTML layouts for R Markdown (v1) output. You can use the vignette engine knitr::docco_classic, or the function knitr::rocco() to compile an R Markdown document to HTML using this style. The main feature of this layout is that it arranges text in the left column, and code in the right column.

Setup

Just like the vignette LP-demo1, we set up some knitr chunk options first.

knitr::opts_chunk$set(eval = FALSE, tidy = FALSE)

A Markdown Generator

First we create a list md with a few function members to generate raw Markdown output.

#' A Markdown generator
#' 
#' You can generate Markdown text using the function elements of this object.
#' @return Each function element returns a character vector.
#' @export
#' @examples md$b('bold'); md$em('emphasize'); md$ul(head(letters))
md = local({

I'm using local() here because I want to create a local function enclose() below, which wraps its argument x by a character string by:

  enclose = function(x, by = '') paste0(by, x, by)

Then md is basically a list of members b (bold), em (emphasize), code, link, ol (ordered list), and ul (unordered list):

  list(
       b = function(x) enclose(x, '**'),
      em = function(x) enclose(x, '_'),
    code = function(x) enclose(x, '`'),
    link = function(href, text) sprintf('[%s](%s)', text, href),
      ol = function(x) sprintf('1. %s\n', x),
      ul = function(x) sprintf('- %s\n', x)
  )
})

Examples

Now we show some text output, including plain R console output as well as Markdown output.

1 + 1
10:1 + 10
dnorm(0)

For raw Markdown output, you need the chunk option results = 'asis'.

library(rlp)
cat(
  'Show some raw Markdown content here. ',
  'This is ', md$b('bold'), ' and ', md$em('emphasized'), '. ',
  'Also a code fragment ', md$code('fivenum(1:10)'), '. ',
  'A link to ', md$link('http://www.r-project.org', 'R homepage'), '. ',
  '\n\n',
  'An ordered list:\n\n', md$ol(head(letters)),
  '\n\n',
  'An unordered list:\n\n', md$ul(head(LETTERS)),
  sep = ''
)