Standard formatting style for Bioconductor documents

• LaTeX .sty file for PDF documents (v1.0)

• CSS definitions for markdown HTML documents (v1.4)

• rmarkdown templates for HTML/PDF vignettes (v1.8)

• New LaTeX style (v2.0)

• New HTML style supporting cross-references* (v2.2)

* software and experiment data packages

* software packages

Inconsistent formatting

• within document (title page vs. document body)
• across output formats (PDF vs. HTML)

Non-distinctive structuring elements

• running head, folio (PDF)
• figure captions

Format-varying appearance of code chunks

• code highlighting
• background

No support for the recent rmarkdown features (HTML)

• floating TOC, code folding, …

Design goals

• Easy to read and visually attractive
• Clear separation between content and structuring elements
• Common style regardless of input (Rnw/Rmd) and output format (PDF/HTML)

Implementation

• Consistent layout emphasizing relationships
  • horizontal content alignment
  • distinct fonts for structuring elements and main text
• Common themes for code highlighting
• Footnotes as margin notes

• Add to DESCRIPTION

  VignetteBuilder: knitr
  Suggests: BiocStyle, knitr, rmarkdown

• Specify BiocStyle output format and vignette metadata in document header

  ---
  title: "Vignette Title"
  author: "Vignette Author"
  package: PackageName
  output: 
    BiocStyle::html_document2
  vignette: >
    %\VignetteIndexEntry{Vignette Title}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}  
  ---

YAML header demonstrating anchor-reference notation

author:
- name: First Author
  affiliation: 
  - &id Shared affiliation
  - Additional affiliation
- name: Second Author
  affiliation: *id
- name: Last Author
  affiliation: *id
  email: corresponding@author.com

Functionality provided by bookdown

• automatic numbering of figures, tables and equations
• output-independent syntax for specifying cross-references
  • label (\#label)
  • reference \@ref(label)

Macros for linking to R packages

• Biocpkg("IRanges") : IRanges

• CRANpkg("data.table") : data.table

• Githubpkg("rstudio/rmarkdown") : rmarkdown

Called inline: `r Biocpkg("IRanges")`

Three figure sizes with predefined aspect ratio

• specified through fig.small and fig.wide

Caption titles

• emphasized first sentence of captions

Numbering and referencing

• specify fig.cap and use \@ref(fig:label)

Assign labels (\#tab:label) in captions and refer to them by \@ref(tab:label)

Fruit   | Price
------- | -----
bananas | 1.2
apples  | 1.0
oranges | 2.5
  
: (\#tab:table) A simple table. With caption.

To number and reference equations put them in equation environments and assign labels (\#eq:label) to them

\begin{equation}
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation}

\[ \qquad\qquad\qquad\qquad f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k} \qquad\qquad\qquad\quad(1) \]
Use \@ref(eq:binom) to refer to Equation (1)