Text formatting reference sheet

Hadley Wickham

2019-08-12

Within roxygen tags, you use .Rd syntax to format text. This vignette shows you examples of the most important commands. The full details are described in R extensions.

Note that \ and % are special characters. To insert literals, escape with a backslash: \\, \%.

Character formatting

• \emph{italics}

• \strong{bold}

• \code{r_function_call(with = "arguments")}, \code{NULL}, \code{TRUE}

• \pkg{package_name}

Links

To other documentation:

• \code{\link{function}}: function in this package

• \code{\link[MASS]{abbey}}: function in another package

• \link[=dest]{name}: link to dest, but show name

• \code{\link[MASS:abbey]{name}}: link to function in another package, but show name.

• \linkS4class{abc}: link to an S4 class

To the web:

• \url{http://rstudio.com}

• \href{http://rstudio.com}{Rstudio}

• \email{hadley@@rstudio.com} (note the doubled @)

Lists

• Ordered (numbered) lists:

  #' \enumerate{
  #'   \item First item
  #'   \item Second item
  #' }

• Unordered (bulleted) lists

  #' \itemize{
  #'   \item First item
  #'   \item Second item
  #' }

• Definition (named) lists

  #' \describe{
  #'   \item{One}{First item}
  #'   \item{Two}{Second item}
  #' }

Mathematics

Standard LaTeX (with no extensions):

• \eqn{a + b}: inline eqution

• \deqn{a + b}: display (block) equation

Tables

Tables are created with \tabular{}. It has two arguments:

1. Column alignment, specified by letter for each column (l = left, r = right, c = centre.)

2. Table contents, with columns separated by \tab and rows by \cr.

The following function turns an R data frame into the correct format, adding a row consisting of the (bolded) column names and prepending each row with #' for pasting directly into the documentation.

tabular <- function(df, ...) {
  stopifnot(is.data.frame(df))

  align <- function(x) if (is.numeric(x)) "r" else "l"
  col_align <- vapply(df, align, character(1))

  cols <- lapply(df, format, ...)
  contents <- do.call("paste",
    c(cols, list(sep = " \\tab ", collapse = "\\cr\n#'   ")))

  paste("#' \\tabular{", paste(col_align, collapse = ""), "}{\n#'   ",
    paste0("\\strong{", names(df), "}", sep = "", collapse = " \\tab "), " \\cr\n#'   ",
    contents, "\n#' }\n", sep = "")
}

cat(tabular(mtcars[1:5, 1:5]))
#> #' \tabular{rrrrr}{
#> #'   \strong{mpg} \tab \strong{cyl} \tab \strong{disp} \tab \strong{hp} \tab \strong{drat} \cr
#> #'   21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
#> #'   21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
#> #'   22.8 \tab 4 \tab 108 \tab  93 \tab 3.85\cr
#> #'   21.4 \tab 6 \tab 258 \tab 110 \tab 3.08\cr
#> #'   18.7 \tab 8 \tab 360 \tab 175 \tab 3.15
#> #' }