Introduction to INBOmd

Thierry Onkelinx

2018-06-20

Source: vignettes/introduction.Rmd

Goal

The INBOmd package provides several styles for rmarkdown files. The styles are based on the corporate identity of the Research Instutite for Nature and Forest (Instituut voor Natuur en Bosonderzoek, INBO). The styles itself are not intended for use by parties external to INBO. We still provide them to other users as an inspiration and example on how to create their own corporate identity styles for rmarkdown files.

All templates are based on bookdown, which is an extension of rmarkdown. It is tailored towards writing books and technical documentation.

Benefits of writing with bookdown

  1. It is based on rmarkdown a combination of R code with text in markdown plain text formatting syntax.
    • R is freeware open source statistical software.
    • markdown is a lightweight markup language. The formatting doesn’t hinder when reading the plain text. It is short and easy to remember, so you can edit it in any plain text editor.
  2. No need to run R in a script and copy the output into another document.
    • rmarkdown will first execute the R code in the document and paste its output in a plain markdown file. This is then rendered into the requested output format.
    • This saves a lot of work and avoid copy/paste errors.
  3. Storing the R code within the report makes it easy to rerun the report when the data is updated.
  4. The plain text source code is lightweight. The source code of a report is seldom larger than a few hunderd kilobyte. Yes, kilobyte.
  5. Plain text files work great in combination with version control systems like Git.
  6. bookdown is a useful tool for conducting open research and open science.
  7. You can get multiple output formats from the same source. The report template can yield a pdf, an e-book and a website.
  8. The author doesn’t have to worry about the lay-out. The software takes care of that when rendering the documents. This frees up time which the author can invest in more important things. And it guarantees a consistent lay-out both with the document as across documents.

Available templates in INBOmd

  • The most important template is inbo_rapport, a template for creating technical reports. The available output formats are pdf, epub and html.
  • inbo_slides is a template for presentations. It has three different pdf output formats
    1. “presentation”: each time point of the presentation is one page in a pdf. Incremental slides will result in several pages, one for each increment.
    2. “handout”: a single page for each slide. In case of incremental slides, only the last slide will be shown. Useful when handouts are required in combination with incremental slides.
    3. “report”: mostly relevant when the slides are used for teaching code. The output may not fit on a single single slide, resulting is a substantial number of slides. Using a “report” like style makes handouts more compact and readable.
  • flanders_slides is a similar template as inbo_slides. It uses the corporate identity of Flanders. Only the presenation and handout versions are available.
  • inbo_poster is a template for A0 posters in pdf format.

Installation

INBOmd requires a working installation of XeLaTeX. We highly recommend to use the TinyTeX. Close all open R sessions and start a fresh R session. Execute the commands below. This will install TinyTeX on your machine. No admin rights are required. Although TinyTeX is a lightweight installation, it still is several 100 MB large. Please note that TinyTex is not compatible with MikTex. Remove MikTex before installing TinyTex

update.packages(ask = FALSE, checkBuilt = TRUE)
if (!"tinytex" %in% rownames(installed.packages())) {
  install.packages("tinytex")
}
if (!tinytex:::is_tinytex()) {
  tinytex::install_tinytex()
}

Once TinyTeX is installed, you need to restart RStudio. Then you can proceed with the installation of INBOmd.

if (!"remotes" %in% rownames(installed.packages())) {
  install.packages("remotes")
}
remotes::install_github("inbo/INBOmd", dependencies = TRUE)
tinytex::tlmgr_install(c(
  "inconsolata", "times", "tex", "helvetic", "dvips"
))
tinytex::tlmgr_conf(
  c("auxtrees", "add", system.file("local_tex", package = "INBOmd"))
)
tinytex::tlmgr_install(c("hyphen-dutch", "hyphen-french"))

Using INBOmd

Starting a new document

INBOmd contains several templates which are available in RStudio. Go in the menu to File > New File > R Markdown. A new window will open were you select From template. This will show a list of all available templates. Select the template INBOmd you want, set the name of the new document and the base location. This will create a new directory with the specified name in the base location. Each report will reside in its own directory.

This new directory contains _bookdown.yml and an .Rmd file with the same base name as the directory. We highly recommened to rename the .Rmd file to index.Rmd, see usage section in the bookdown book for more details. Next you need to open _bookdown.yml in RStudio. Here you can configure the render settings of the report. book_filename defines the filename of the output. output_dir is the relative path for the output.

Finally, you need to activate the Build pane in RStudio. By far the easiest way to do this, is the create a new project. Go in the menu to File > New Project and choose in the popup window Existing directory. Note that this only works if there is an index.Rmd file at the root of the project.

Rendering a document

Go the Build pane and click on the Build book button. This button doubles as a dropdown menu. In this menu you can select which output format will be rendered. By default all output formats will be rendered. The report templates define three output formats: pdf, html and e-pub. Rendering all three output formats can take some time. Therefore it is best to select one output format while working on the content of the document.

Examples of INBOmd

We maintain a separate collection of examples based on INBOmd. The rendered versions are available through http://inbomd-examples.netlify.com/. Visit https://github.com/inbo/inbomd_examples if you are looking for the source code of these examples. Please note that the main intention of these examples is to show what is available with INBOmd and how to code it. We will add links to real documents based on INBOmd as well.