Skip to contents

Introduction to INBOmd

Thierry Onkelinx

2018-06-20

Source: vignettes/inbomd.Rmd
inbomd.Rmd

Goal

The INBOmd package provides several styles for rmarkdown files. The styles are based on the corporate identity of the Research Institute 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 hundred 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.
  • vlaanderen_rapport and flanders_report are similar templates as inbo_rapport. They use the corporate identity of Flanders. flanders_report is available in English and French.
  • 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 presentation 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",
  "babel-english",
  "babel-french",
  "babel-dutch"
))

Using INBOmd

INBOmd version 0.6.0 introduces the interactive function create_report(). This function uses the same template as the legacy way to start a new report. create_report() has the advantage that it interactively guides the user through the set-up. It asks the user for the important parts of the meta data and fills that information into the yaml header.

Once the report is near completion, use add_report_numbers() to append the DOI, report number, depot number and other information to the meta data.

Legacy way to start a new document from RStudio templates

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 recommend 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 pop-up 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 drop-down 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 https://inbomd-examples.netlify.app/. 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.