2 Syntax

Deliver the take-home message here.

It can contain several paragraphs.

The syntax of R Mardown extended by Bookdown is recalled here.

In RStudio, create a new document of type Document R Markdown. The wizard allows you to choose between different formats.

Click on From template: from templates installed by packages. The memoiR package templates are displayed: choose Memoir.

Each chapter of the book is an Rmd file, whose name normally starts with its number (e.g. 01-intro.Rmd). All Rmd files in the project folder are actually treated as chapters, sorted by file name, including those provided by the template (startup and syntax) which should be deleted except for 99-references.Rmd which contains the bibliography, placed at the end. The index.Rmd file is special: it contains the document header and the first chapter.

Each other file starts with a top-level title:

# Title of the Chapter

If the document is made of parts containing chapters, the file with the fist chapter of each part must start with:

# (PART) Title of the Part {-}
  
# Title of the Chapter

Note the {-} instruction after the title of the part to avoid having it numbered.

Appendices are introduced as a special part:

# (APPENDIX) Appendix {-} 

# Title of the first appendix

2.1 Write

The main features of Markdown are summarized here. A quick and complete training is offered by RStudio³.

The text is written without any formatting other than line breaks. A simple line break has no effect on the document produced: it allows to separate sentences to simplify the tracking of the source code by git.

A line break marks a paragraph change.

The different levels of the plan are designated by the number of braces at the beginning of the line: # for a level 1 title, ## for a level 2 title, etc. A space separates the hashes and the title text.

Bullet lists are marked by a dash (followed by a space) at the beginning of the line. An empty line is required before the beginning of the list, but the elements of the list are separated by a simple line break. Indented lists are created by inserting 4 spaces before the dash at the beginning of the line. Last, numbered lists are created in the same way by replacing the hyphens by numbers, whose value does not matter.

In the text, the italicized parts are surrounded by a star or an underscore (*italic*), while two stars mark the bold.

2.2 R code

R code is included in code chunks (code chunks) that are easily created by clicking on the “Insert a new code chunk” button above the source code window in RStudio. They start and end with three quotation marks on a new line. These code chunks can contain R code but also Python code for example: the type of code is indicated in the header on the first line, before the name of the code chunk, then a comma separated list of options, for example:

```{r cars, echo=TRUE}
```

The name and options are optional: the minimum header is {r}.

The most useful options are:

echo to show (=TRUE) or hide (=FALSE) the code.
message=FALSE to hide the opening messages of some packages.
warning=FALSE to hide warnings.

The default options are declared in the code snippet named “Options” at the beginning of the Markdown document, in the opts_chunk$set() function. The echo option should be set to FALSE by default for a scientific article for example.

When it is TRUE, the code is printed as follows

2 + 2

## [1] 4

2.3 Figures

plot(pressure)

Figure 2.1: A figure

Figures can be created by the R code (figure 2.1). With Bookdown, a label is associated with each figure: its name is fig:xxx where xxx is the name of the R code snippet. References are made with the command \@ref(fig:xxx).

The header of the code snippet of the figure 2.1 is:

```{r pressure, fig.cap="Title of the figure"}
```

It contains at least the name of the figure and its caption.

The default width of figures is set in the option chunk in index.Rmd. It is out.width='80%' in this template, i.e. 80% of the width of the text. If a full-width figure is needed, including the margin width, use out.width='\\widthw' in its code chunk header.

When large margins are used in memoirs, figure captions are set in the margins of PDF outputs. Margins can be used to enlarge a figure: add knitr options out.width='\\widthw' and fig.env='figure' in the code chunk header. Figure alignment must be fig.align = 'center' (which is by default). The caption is then inserted below the figure. Small figures can be put in the margin by the option fig.env='marginfigure'. These changes are ignored in the HTML output.

If the caption is long, the header is not easy to read. Also, the caption is limited to simple text. For more elaborate captions, it is possible to declare the caption in a separate paragraph that begins with the text (ref:FigureName). The figure 2.2 benefits from an improved caption.

$Title with italic, math ($\sqrt\pi$) and reference to figure 2.1$

Figure 2.2: Title with italic, math ($\sqrt\pi$) and reference to figure 2.1

The text in fig.cap, “Title of figure” previously, is replaced by (ref:pressure) within the quotation marks and the caption is entered in a paragraph starting with (ref:pressure) followed by a space. Captions are limited to a single paragraph. They should not contain bibliographic references or references to the figures may not find them: if necessary, cite the source of a figure in the text.

Figures that are not created by R but come from files are embedded in a piece of code by the include_graphics() function whose argument is the file containing the image to be displayed. Always place these files in the images folder for good organization.

2.4 Tables

The horizontal - and vertical separators | allow you to draw a table according to Markdown syntax, but this is not the best method.

Tables can also be produced by R code. The content of the table is in a dataframe. The kbl() function in the kableExtra package (which enhances the original kable() function from knitr) prepares the table for display and passes the result to the kable_styling function for final formatting.

names(iris) <- c("Sepal length", "Width", "Petal length", "Width",
    "Species")
kableExtra::kbl(head(iris), caption = "Table created by R", longtable = TRUE,
    booktabs = TRUE) %>%
    kableExtra::kable_styling(bootstrap_options = "striped",
        full_width = FALSE)

Table 2.1: Table created by R
Sepal length	Width	Petal length	Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa

The caption is specified by the caption argument and referencing is possible because the table receives a label whose name is tab: followed by the name of the code snippet (table 2.1). Always use the booktabs = TRUE argument so that the thickness of the separator lines is optimal in LaTeX. The bootstrap_options = "striped" option provides more readable tables in HTML.

Table 2.2: Intervention table, summary of the disturbance intensity for the 4 plot treatments in Paracou.
Treatment	Timber	Thinning	Fuelwood	%AGB lost
Control				0
T1	DBH $\geq$ 50 cm, commercial species, $\approx$ 10 trees/ha			$[12\%-33\%]$
T2	DBH $\geq$ 50 cm, commercial species, $\approx$ 10 trees/ha	DBH $\geq$ 40 cm, non-valuable species, $\approx$ 30 trees/ha		$[33\%-56\%]$
T3	DBH $\geq$ 50 cm, commercial species, $\approx$ 10 trees/ha	DBH $\geq$ 50 cm, non-valuable species, $\approx$ 15 trees/ha	40 cm $\leq$ DBH $\leq$ 50 cm, non-valuable species, $\approx$ 15 trees/ha	$[35\%-56\%]$

In LaTeX, tables can have the width of the column and possibly span multiple pages (longtable = TRUE), or use the width of the page (longtable = FALSE), like table 2.2.

This table contains mathematics: the escape = FALSE option is necessary.

Finally, the full_width = FALSE option adjusts the width of the table to its content instead of occupying all the available width. It must be TRUE for correct formatting of two-column tables, i.e. with longtable = FALSE in LaTeX.

The content of table cells can be formatted following the Markdown syntax, with some limits due to kableExtra: the argument format="markdown" is necessary in kbl() or LaTeX output will ignore formatting, but this is not compatible with full_width = TRUE in kable_styling(). See kableExtra’s documentation to format rows or columns globally without using Markdown (e.g. function row_spec(). The header of 2.2) is set to bold this way.

2.5 Maths

Equations in LaTeX format can be inserted in line, like $A=\pi r^2$ (code: $A=\pi r^2$ ) or isolated (the $ are doubled) like \[e^{i \pi} = -1.\]

They can be numbered: see equation (2.1), using the \equation environment.

\[\begin{equation} A = \pi r^2. \tag{2.1} \end{equation}\]

The numbered equation is created by the following code:

\begin{equation}
  A = \pi r^2.
  (\#eq:disk)
\end{equation}

2.6 Cross-references

Figures and tables have an automatically generated label, identical to the name of the code snippet prefixed with fig: and tab:.

For equations, the label is added manually by the code (\#eq:xxx) before the end of the equation.

Sections can be tagged by ending their title with {#yyy}.

In all cases, the call to the reference is made by the command \@ref().

2.7 Bibliography

Bibliographic references in bibtex format must be included in the .bib file declared in the header of the Markdown document.

bibliography: references.bib

They can be called in the text, between brackets by the code [@CitationKey], as sidenotes (Xie 2016), or without square brackets, to include the authors’ names in the text, such as Xie, Allaire, and Grolemund (2018) .

Bibliography is handled by pandoc when producing Word or HTML documents. The bibliographic style can be specified, by adding the line

csl:file_name.csl

in the document header and copying the .csl style file into the project folder. The default style (if no csl is specified) is “chicago-author-date”. Several thousand styles are available ⁴.

For PDF documents, the bibliography is handled by BibLaTeX, see section 1.1.

2.8 Forcing line breaks

Hyphenation is handled automatically in LaTeX. If a word is not hyphenated correctly, add its hyphenation in the preamble of the file with the command hyphenation (words are separated by spaces, hyphenation locations are represented by dashes).

If LaTeX can’t find a solution for the line break, for example because some code is too long a non-breaking block, add the LaTeX command \break to the line break location. Do not leave a space before the command. The HTML document ignores LaTeX commands.

2.9 Languages

Languages are declared in the document header.

The main language of the document (lang) changes the name of some elements, such as the table of contents. The change of language in the document (one of otherlangs) is managed in LaTeX but not in HTML by inserting on a new line the following command:

\selectlanguage{english}

The current language has an effect only in LaTeX output: a space is added before double punctuation in French, the size of spaces is larger at the beginning of sentences in English, etc. The \selectlanguage command is simply ignored in HTML.

Language codes are used in the header, such as en-US but language names are necessary in \selectlanguage{}. Name matches are listed in table 3 of the polyglossia package documentation⁵.

2.10 Chapter summary

The take-home message of each chapter can be displayed in a box, see the beginning of this one. The code is that of a code block of type “Summary”.

::: {.Summary data-latex=""}
Some text for this block.
:::

Its heading text is set in the header of index.Rmd:

chaptersummary: In a Nutshell

Note that the chapter summaries are formatted as simple text in Word outputs.

2.11 Local table of contents

At the beginning of each chapter of the PDF document, a local table of content can be added with the following code:

\toc{1}

It is ignored in HTML. 1 is the depth of the table of contents: sections of the chapters are included. It can be changed for 2 to display subsections too, and so on.

2.12 Boxed text

Boxed text allows summarizing important points out of the main text. An example is given here, to define the Pythagorean theorem.

For a right triangle, if $c$ denotes the length of the hypotenuse and $a$ and $b$ denote the lengths of the other two sides, we have

\[a^2 + b^2 = c^2\]

These boxes are included in the document as fenced blocks, whose syntax is as follows:

:::{#pythbox .greybox data-latex='[frametitle=Pythagorean theorem]'
title='Pythagorean theorem'}
For a right triangle, if $c$ denotes the length of the hypotenuse
and $a$ and $b$ denote the lengths of the other two sides, we have

$$a^2 + b^2 = c^3$$
:::

The text block is delimited by ::: instead of the backquotes of code chunks. The header of the block contains its name, prefixed by #. The type of block follows, here: .greybox. Arguments data-latex and title contain the title of the box in the PDF and HTML outputs, so a referenced text caption is useful to avoid repeating it. Enter it in a paragraph starting with (ref:pythbox) followed by a space. Then, call the text with the code (ref:pythbox). This technique is identical to that used for elaborate figure captions. Note the particular syntax of the title in the PDF output.

Grey text boxes (.greybox) are provided by the memoir template. Advanced users can define other colored boxes, say a yellow box, following the next steps:

Obtain the HTML code of the color, for instance with a color picker⁶. ffff66 is suitable for yellow.
In latex/preamble.tex, define the color by adding the following line below the definition of the grey color:

\definecolor{yellow}{HTML}{FFFF66}

Also define the text box environment by duplicating the greybox item and replacing grey with yellow three times:

\newmdenv[
    style=boxstyle,
    backgroundcolor=yellow,
    frametitlebackgroundcolor=yellow,
]{yellowbox}

In style.css, duplicate all lines that define “Grey text box”, including the starting and ending comment lines. Replace .greybox with .yellowbox everywhere, “Grey” with “Yellow” in the comments and change the background-color with #ffff66.
In the text, use the same syntax as above but declare the class of the fenced block as .yellowbox instead of .greybox.

2.13 Documentation

2.13.1 User documentation

The book bookdown: Authoring Books and Technical Documents with R Markdown by Yihui Xie, the author of bookdown and knitr. All the necessary details for writing (writing equations, cross-references, etc.) are given.
The R Markdown cheat sheet for the syntax.

2.13.2 Documentation for developers

LaTeX file format customization.
The Pandoc manual for possible options in the YAML header.

References

Xie, Yihui. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/bookdown.

Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.

Treatment	Timber	Thinning	Fuelwood	%AGB lost
Control				0
T1	DBH \(\geq\) 50 cm, commercial species, \(\approx\) 10 trees/ha			\([12\%-33\%]\)
T2	DBH \(\geq\) 50 cm, commercial species, \(\approx\) 10 trees/ha	DBH \(\geq\) 40 cm, non-valuable species, \(\approx\) 30 trees/ha		\([33\%-56\%]\)
T3	DBH \(\geq\) 50 cm, commercial species, \(\approx\) 10 trees/ha	DBH \(\geq\) 50 cm, non-valuable species, \(\approx\) 15 trees/ha	40 cm \(\leq\) DBH \(\leq\) 50 cm, non-valuable species, \(\approx\) 15 trees/ha	\([35\%-56\%]\)