---
title: "Introduction to INBOmd"
author: "Thierry Onkelinx"
date: "2018-06-20"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to INBOmd}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Goal

The `INBOmd` package provides several styles for [`rmarkdown`](https://rmarkdown.rstudio.com/) files.
The styles are based on the corporate identity of the Research Institute for Nature and Forest 
(Instituut voor Natuur en Bosonderzoek, [INBO](vlaanderen.be/inbo/en/)). <!-- spell-check: ignore -->
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`](https://bookdown.org/home/about/), 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`](https://www.r-project.org/) code with text in [`markdown`](https://en.wikipedia.org/wiki/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.
1. 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.
1. Storing the `R` code within the report makes it easy to rerun the report when the data is updated. 
1. The plain text source code is lightweight.
  The source code of a report is seldom larger than a few hundred kilobyte.
  Yes, kilobyte.
1. Plain text files work great in combination with [version control systems](https://en.wikipedia.org/wiki/Version_control) like [Git](https://en.wikipedia.org/wiki/Git).
1. `bookdown` is a useful tool for conducting [open research](https://en.wikipedia.org/wiki/Open_research) and [open science](https://en.wikipedia.org/wiki/Open_science).
1. You can get multiple output formats from the same source. The report template can yield a pdf, an e-book and a website.
1. 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](https://www.vlaanderen.be/).
  `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.
    1. "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.
    1. "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](https://www.vlaanderen.be/).
  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`.

```{r eval = FALSE}
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`.

```{r eval = FALSE}
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`

## Recommended way to start a new report

`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](https://bookdown.org/yihui/bookdown/usage.html) 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.