# Syntax

::: {.Summary data-latex=""}
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
```


## Write

The main features of Markdown are summarized here.
A quick and complete training is offered by RStudio[^821].

[^821]: https://rmarkdown.rstudio.com/lesson-1.html

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.


## 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}`r ''`
#| label: 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

```{r}
#| echo: true
2+2
```



## Figures

```{r}
#| label: pressure
#| fig-cap: "A figure"
plot(pressure)
```

Figures can be created by the R code (figure \@ref(fig:pressure)).
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 \@ref(fig:pressure) is:

````
```{r}`r ''`
#| label: 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 \@ref(fig:pressure2) benefits from an improved caption.

(ref:pressure2) Title with _italic_, math ($\sqrt\pi$) and reference to figure \@ref(fig:pressure)
```{r}
#| label: pressure2
#| fig-cap: "(ref:pressure2)"
#| echo: false
plot(pressure)
```

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.


## 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.

```{r}
#| label: kable
#| echo: true
#| warning: false
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)
```

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 \@ref(tab:kable)).
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.

(ref:Paracou) Disturbance intensity of the 4 plot treatments in Paracou.
```{r}
#| label: Paracou
#| echo: false
#| warning: false
logging <- data.frame(
  Treatment = c("Control", "T1", "T2", "T3"),
  Timber = c(
    "", 
    "DBH $\\geq$ 50 cm, commercial species, $\\approx$ 10 trees/ha", 
    "DBH $\\geq$ 50 cm, commercial species, $\\approx$ 10 trees/ha",
    "DBH $\\geq$ 50 cm, commercial species, $\\approx$ 10 trees/ha"
  ),
  Thinning = c(
    "", 
    "", 
    "DBH $\\geq$ 40 cm, non-valuable species, $\\approx$ 30 trees/ha", 
    "DBH $\\geq$ 50 cm, non-valuable species, $\\approx$ 15 trees/ha  "
  ),
  Fuelwood = c(
    "", 
    "", 
    "", 
    "40 cm $\\leq$ DBH $\\leq$ 50 cm, non-valuable species, $\\approx$ 15 trees/ha"
  ),
  AGBLost = c(0, "$[12\\%-33\\%]$", "$[33\\%-56\\%]$", "$[35\\%-56\\%]$")
)
names(logging)[5] <- "\\%AGB lost"
kableExtra::kbl(
  logging, 
  caption = "(ref:Paracou)", 
  longtable = FALSE, 
  booktabs = TRUE, 
  escape = FALSE) |>
  kableExtra::kable_styling(
    bootstrap_options = "striped", 
    full_width = TRUE
  ) |> 
  kableExtra::row_spec(row = 0, bold = TRUE)
```


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 \@ref(tab:Paracou).

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 \@ref(tab:Paracou)) is set to bold this way.


## 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 \@ref(eq:disk), using the `\equation` environment.

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

The numbered equation is created by the following code:

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

## 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()`.


## 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 [@Xie2016], or without square brackets, to include the authors' names in the text, such as @Xie2018 .

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 [^822].

[^822]: <https://github.com/citation-style-language/styles>

For PDF documents, the bibliography is handled by BibLaTeX, see section \@ref(index).


## 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.


## Languages {#sec: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[^823].

[^823]: http://mirrors.ctan.org/macros/unicodetex/latex/polyglossia/polyglossia.pdf


## 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.


## 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.


## Boxed text

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

(ref:pythbox) Pythagorean theorem

:::{#pythbox .greybox data-latex='[frametitle=(ref:pythbox)]' title='(ref:pythbox)'}
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[^824]. `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`.

[^824]: https://www.w3schools.com/colors/colors_picker.asp

## Documentation

### User documentation

- The book [bookdown: Authoring Books and Technical Documents with R Markdown](https://bookdown.org/yihui/bookdown/) 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](https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf) for the syntax.


### Documentation for developers

- [LaTeX file format customization](http://rmarkdown.rstudio.com/pdf_document_format.html#advanced_customization).
- The [Pandoc manual](https://pandoc.org/MANUAL.html) for possible options in the YAML header.

