body.Rmd

## What is 'bookdown' {#what_is__bookdown_}

A book titled *R bookdownplus Textbook* is surely talking about 'bookdownplus' [@R-bookdownplus], but let's start with 'bookdown' [@R-bookdown].

'bookdown' is a software package for writing books or documents based on R language [@R-base] and Markdown syntax. It is something like Microsoft Word, but more elegant, more powerful, and easier. If you know LaTeX, it would be much helpful to get into 'bookdown'.  If not, don't worry, it is the reason why I wrote this book. With 'bookdown', users can

- easily insert table of contents, figures and tables with cross-reference, footnotes, and index; 

- easily embed equations, citations, R scripts;

- obtain multiple formats of outputs such as pdf, word and html files;

- have the best experience of writing reproducible documents.

If my description is insufficient for you to know what is 'bookdown', you could have a brief look at the official website of 'bookdown'^[http://bookdown.org], where some of numerous books written with 'bookdown' are listed. Three of them on its home page are authored by me \m{21 June 2017}.

## What is 'bookdownplus' {#what_is__bookdownplus_}

Thus, 'bookdownplus' sounds like something related to 'bookdown' ? 

Yes, you **_R_** right. Many people know that 'bookdown' is an excellent package for authoring books on programming languages especially R books. Few people know that it can do more than expected. 'bookdown' looks like a delicious cake. People are wondering how it tastes, but people don't know how to cut it and or how to grab a piece onto their own plates.

```{r imgcake, fig.cap="A cake of 'bookdown'. How should I cut it in a right way?", out.width='50%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/cake.jpg")
```

I expected someone to cut it for me. I was too hungry to wait and I was helping myself. Therefore I developed 'bookdownplus'.

'bookdownplus' is an extension of 'bookdown'. It is a collection of multiple templates, which I have been collecting since years ago on the basis of LaTeX, and have been tailoring them so that I can work happily under the umbrella of 'bookdown'. 'bookdownplus' helps you (and me) write varied types of books and documents.  This book you are reading at the moment was exactly produced by 'bookdownplus'.

'bookdownplus' was developed on Windows OS. It has not fully been tested on MacOS or Linux yet. Therefore the examples given in this book should be reproduced on Windows. I am not sure how bookdownplus performs on other OS. Please let me know if there is any problem.

I believe some official 'bookdown' templates will be available in the near future, but I cannot wait. Can you? If so, I am afraid that the cake will not be fresh any more.

\m{The former project was called bookdown-plus, providing a folder for users to download and modify. It was later abandoned because it was not so convenient as an R package.}

'bookdownplus' is a knife for cutting the 'bookdown' cake. Frankly speaking, I am not an expert to cut this cake. Feel free to join me in sharpening it if you would like to.

## Why 'bookdownplus' {#why__bookdownplus_}

A tasty cake is not necessarily easy to cut. 'bookdown' is not easy for beginners. Try reading the official manual of 'bookdown'^[https://bookdown.org/yihui/bookdown/]. If you are able to build your own book in one hour, I am sure you are a genius and please send me a postcard with your signature. An R beginner might be confused or depressed in struggling in the flood of LaTeX, YAML, Markdown, Pandoc, etc. It would be a pity if users stop their steps at the door and give up the courage of entering the wonderful world of 'bookdown'.

'bookdownplus' is the easiest shortcut to the world of 'bookdown'. With **just one single command** users can get a demo book (or multiple demo books) in .pdf or .doc, or even more formats (see Chapter \@ref(quickstart) ).  'bookdownplus' extends the features of 'bookdown', and simplifies the procedure. Users only have to choose a template, clarify the book title and author name, and then focus on writing the text. No need to struggle in YAML and LaTeX.

With 'bookdownplus' you can easily:

- write a mail in an elegant layout,

- write a laboratory journal, or a personal diary,

- draw a monthly or weekly or conference calendar, \m{although still in LaTeX format.}

- and, of course, write academic articles in your favourite way,

- with chemical molecular formulae and equations,

- even in Chinese, \m{Perhaps in some other languages as well. I have not tried yet.}

- write guitar chords,

- and more wonders are coming soon.

## Shoulders of Giants {#giants__shoulders}

'bookdownplus' is developed on the basis of the following outstanding work:

- R [@R-base], of course;

- R 'bookdown' package [@R-bookdown];

- book examples by Yihui Xie ^[https://github.com/yihui/bookdown-minimal] ^[https://github.com/rstudio/bookdown-demo];

- gchords, a LaTeX package for typesetting guitar chord diagrams by Kasper Peeters ^[http://kasper.phi-sci.com/gchords/];

- Copernicus Publications LaTeX Package ^[http://publications.copernicus.org/for_authors/latex_instructions.html];

- MDPI LaTeX template ^[http://www.mdpi.com/];

- mhchem package by Martin Hensel ^[https://www.ctan.org/pkg/mhchem];

- kuleuven-templates ^[https://github.com/exporl/kuleuven-templates]; 

- classicthesis package by Andre Miede ^[http://www.ctan.org/tex-archive/macros/latex/contrib/classicthesis/]. \m{Users are encouraged to send Prof. Miede a postcard if they like this package. He has received 417 postcards by 2017-04-30.}

As some codes in 'bookdownplus' were collected long time ago, and some might be re-used and re-re-used many time before apprearing in 'bookdownplus', I might miss some citations. It would be appreciated if you find them and let me know.

## About this book

This book is a tutorial or a documentation of 'bookdownplus'. Beginners could read Chapter \@ref(quickstart) to get a general idea of how bookdownplus works. Chapter \@ref(basic) could be skipped for the first time but could be referred later.  From Chapter \@ref(simple) to \@ref(academic), the templates in bookdownplus are introduced one by one in detail in four groups. Finally Chapter \@ref(advanced)  provides some information for Chinese users, mind map fans, and those who would like to contribute to bookdownplus.

You do not have to read this book if you can play well with bookdown or bookdownplus. However, Chapter \@ref(basic) could always be useful as a cheat sheet of bookdown or markdown syntax. 

# Quick start {#quickstart}

## Preparation {#preparation}

Before starting, you have to install 'R', 'RStudio', 'bookdown' package, and
other software and packages (i.e.'Pandoc', 'LaTeX', 'rmarkdown', 'rticle',
'knitr', etc.) which 'bookdown' depends on. See the official manual of 'bookdown'^[https://bookdown.org/yihui/bookdown/]  for details. A brief list is as follows:

1. Download R ^[https://cran.r-project.org/bin/windows/base/] and install it.

2. Download RStudio ^[https://www.rstudio.com/products/rstudio/download/] and install it.

3. Download LaTeX ^[http://www.ctex.org/CTeXDownload] and install it. 

4. Download Pandoc ^[http://pandoc.org/installing.html] and install it.

5. Run RStudio. Type the following codes in the top-left panel to install 'bookdown' and 'servr' packages:

```{r, eval=FALSE}
install.packages('bookdown')
install.packages('servr')
```

Additionally, if you want to produce a poster, python must be installed before using, and the path of python might have to be added to the environmental variables for Windows users. The usage of the poster template is described in Chapter \@ref(poster).

## Installation of 'bookdownplus' {#installation_of__bookdownplus_}

You can either install the stable version of 'bookdownplus' on CRAN:

```R
install.packages('bookdownplus')
```

or the development version on GitHub:

```R
devtools::install_github('pzhaonet/bookdownplus')
```

## Three Steps {#how_to_use}

Beginners can follow the three steps given below:

**Step 1. Generate a demo book** 

1. Make sure you are working in an empty directory, because 'bookdownplus' will generate lots of files. It is highly recommended not mix them with your old files. You could either use the function `setwd()` to set your working directory as the empty folder. or use RStudio to create a new project (File -- New Project - New Directory -- Empty Project) in a new folder and work always in this project.

2. Load the bookdownplus package by typing:

```{r}
require(bookdownplus)
```

in the console window (or select the  "Packages" Tab in the lower right pane, search for the bookdownplus package and tick its check mark).

3. Run the following codes so as to get a demo book:

``` r
bookdownplus()
```

Although there are many arguments available in `bookdownplus()`, you can simply ignore them and they will use their default values, especially when you use 'bookdownplus' package for the first time.

Now a demo file named `*.pdf` in `_book/` folder in your working directory is generated automatically. Open it with any pdf viewer so as to get an impression.

**Step 2. Write your own book on the basis of the demo book**

You can see some other files (e.g. 'index.Rmd', 'body.Rmd', 'bookdownplus.Rproj') and folders. Write your own texts in `body.Rmd` and revise the author and the book title in `index.Rmd`. You can use RStudio or any other text editor (but please don't use Microsoft Word, believe it or not).

**Step 3. Build your book**

After writing some texts, open `bookdownplus.Rproj` with RStudio, and click the 'Build' tab in the upper right pane. Ether click on the "Build Book" tab for producing all formats or select the desired format.

Instead of clicking the 'Build' tab, you can use the shortcut `ctrl-shift-b` (Windows) or `cmd-shift-b` (Mac) for building all formats.

 `bookdownplus()`  is designed for creating a demo book at the very beginning of your writing. After you start your own text, you can totally forget `bookdownplus()` and work with 'bookdown' pakcage. However, if you run `bookdownplus()` again in the same working directory, new 'index.Rmd' and 'body.Rmd' will be created, and you may find the old 'index.Rmd' and 'body.Rmd' gone, which might contain your own texts in them. Don't panic. They have been moved to the '/backup' folder automatically with a time stamp added in the file names.

## More output formats

By default of bookdownplus, the book is built in a pdf file. From 'bookdownplus v1.0.3', users can get more output formats, including word (Microsoft Word), html (any web browser) and epub (for smart phones, or displayed by Calibre on desktop computers).  md (markdown) output is supported from bookdownplus v1.3.1 besides pdf by default. From 'bookdownplus v1.2.0', uses can see the available output formats by running:

```{r}
more_output()
```

You can specify the `more_output` argument in the `bookdownplus()` function:

```{r, eval=FALSE}
bookdownplus(more_output = more_output())
```

Then all the required output files are in `_book/` folder.

## More templates

By default, the demo book is built from the 'thesis_classic' template. From 'bookdownplus v1.2.0', uses can see the available templates by running:

```{r}
template()
```

You can specify the `template` argument in the `bookdownplus()` function:

```{r, eval=FALSE}
bookdownplus(template = template()[1])
```

Then all the required output files are in `_book/` folder. 

The detailed usage of each template is described in Chapter \@ref(simple) to \@ref(advanced).


## Magic tricks

Now it is time to witness the miracles. With the following magic tricks you will see what 'bookdownplus' can do.

**Magic I**

Run the following codes, and go and have a coffee break. When you come back, you will get 19 demo books generated from available templates, each in .pdf, .doc, .html, and .epub formats, in `_book/`:

``` r
for (i in template()[1:19]) 
  bookdownplus(template = i, more_output = more_output()[1:3])
```

If your computer does not support Chinese characters in the demo books, you might encounter some errors. You can run the following codes instead, which exclude the Chinese templates:

```r
for (i in template()[-c(grep('_zh$', template()), 20)]) 
  bookdownplus(template = i, more_output = more_output()[1:3])
```

**Magic II**

Run the following codes. You will get all the demo files for different fonts, themes and styles from the 'mail' template:

``` r
for (mf in mail_font()) {
  for (ms in mail_style()) {
    for (mt in mail_theme()) {
      bookdownplus(template = 'mail', 
      mail_style = ms, 
      mail_font = mf, 
      mail_theme = mt, 
      output_name = paste('mail', ms, mf, mt, sep = '_'))
    }
  }
}
```

## Recommendations

As mentioned before, 'bookdownplus' generates multiple files. Most of them are useful to your computer rather than to you. They are annoying. You might wonder: may I remove them? Here is the answer. 

- If you are a beginner, I would suggest that you should keep all these files when writing your own book. As soon as your book is done, make sure to backup the files you have modified, such as `body.Rmd` and `index.Rmd`, as well as the productions in `_book/`, and then be free to remove all the rest files. If you have to revise your book in the future, your can run `bookdownplus()` again, and then replace the demo .Rmd files with your own ones. 

- If you are an expert, I would suggest that you could pick out those useful demo files in each sub-folder of your working directory, keep them, and remove the redundant files. In the future version of 'bookdownplus', redundant files might be filtered automatically if necessary.

Furthermore, I have been developing some other packages, which bring more features into 'bookdown', such as:

- [mindr](https://cran.r-project.org/package=mindr) [@R-mindr], which can extract the outline of your book and turn it into a mind map, 

- [pinyin](https://cran.r-project.org/packages=pinyin) [@R-pinyin], which can automatically generate ['{#ID}'](https://bookdown.org/yihui/bookdown/cross-references.html) of the chapter headers even if there are Chinese characters in them, and

- [beginr](https://cran.r-project.org/packages=beginr) [@R-beginr], which can generate bibliography entries for installed R packages.

Both of them have been released on CRAN and can be installed via `install.packages()` function:

```{r, eval=FALSE}
install.packages('mindr')  
install.packages('pinyin')
install.packages('beginr')
```

Enjoy your bookdowning!

# Basic {#basic}

## Markdown Syntax {#markdown_syntax}

This chapter briefly introduces Markdown and its syntax in 'bookdown'. You can skip this chapter if you are already an R 'bookdown' user. This chapter is a simply memo comprised of some summarized notes without detailed explanation. You can check this chapter if you forget something when using 'bookdown'. The details and explanations of the syntax can be found in the bookdown manual ^[https://bookdown.org/yihui/bookdown/] or the Markdown cheatsheets in RStudio - Help - Cheatsheets.

### What is Markdown {#what_is_markdown}

'bookdownplus' is based of 'bookdown', which is based on 'markdown'. Markdown is a lightweight markup language with plain text formatting syntax ^[https://en.wikipedia.org/wiki/Markdown]. It means, for example, if you want to display italic texts in your document, you don't choose your texts and click an format button of 'italic' like what you do in Microsoft Word. Instead, you type `*my texts*` and the italic texts *my texts* will be displayed in your output documents. 

One of the advantages of such a markup language is that the typing is fast. You don't have to move your fingers between your keyboard and your mouse. Another advantage is that it is easy to change the style or formats of your document. For example, you can replace all `CO2` with `CO~2~`, then the chemical formula of carbon dioxide will be displayed as CO~2~  .  

### Basic syntax {#basic_syntax}

marks                              output
---------------------------------  -----
`*Italic*`                         *Italic*
`**bold**`                         **bold**
`CO~2~`                            CO~2~ (subscript)
`R^2^`                             R^2^ (superscript)
`$E = mc^2$`                       $E = mc^2$ inline equation
                                   (`$$` for displayed equation)
`[hyperlink](http://pzhao.net)` [hyperlink](http://pzhao.net)
`<pzhao@pzhao.net>`                <pzhao@pzhao.net> email
`![](hyperlink of figure)`         insert a figure
`> quote`                          quote
\texttt{`code`}                    `code`
`# Chapter One`                    chapter title
`1. First`                         numbered list 
`- First`                          unnumbered list
`^[footnote]`                      footnote
`<!-- hidden texts -->`            hidden texts

### Chapters {#chapters}

```
# (PART) Part I {-} 
# (APPENDIX) Appendix {-} 
# References {-}
# chapter {#ID}
## section {#ID}
# chapter {#ID .unnumbered}
```

`\@ref(ID)`

### Figures and tables {#figures_and_tables}

A figure can be inserted with R plotting codes:

    `r ''````{r fig1, fig.cap='caption', out.width='80%', 
    fig.align='center', echo=FALSE}
    plot(1:10)
    ```

`\@ref(fig:fig1)`

or with R inserting codes:

    `r ''````{r img1, fig.cap='caption', out.width='80%', 
    fig.align='center', echo=FALSE}
    knitr::include_graphics("images/img1.png")
    ```

`\@ref(fig:img1)`

or with markdown basic syntax:

```
![caption](images/img1.png)
```

A table can be inserted with basic markdown syntax:

```
col one      col two
----------- ----------
row 1.1     row 1.2
row 2.1     row 2.2
```
and you will get:

col one      col two
----------- ----------
row 1.1     row 1.2
row 2.1     row 2.2

or with R codes:

    `r ''````{r tab1, tidy=FALSE, echo=FALSE}
    knitr::kable(
    head(iris, 20), caption = 'Here is a nice table!',
    booktabs = TRUE
    )
    ```

`\@ref(tab:tab1)`

### References {#references}

Bibliography entries must be saved in .bib.

Citation: `[@R-bookdown]` , `[@zhao2017; @xie2016]`

Bibliography: `# References {-}`

Created a library of R packages for bibliography:

```{r, eval=FALSE}
knitr::write_bib(c("bookdownplus", "beginr"), "", width = 60)
# or
beginr::bib(c("bookdownplus", "beginr"))
```

### Theorems, lemma, definitions, etc. {#theorems__lemma__definitions__etc_}

Full name 	Abbreviations
---------- --------------
theorems    thm
lemma	      lem  
definition	def        
corollary	  cor     
proposition prp
example	    exm
exercise       exr

r {Full name, label=, name=}


`\@ref(Abbreviation:label)`



### Equations numbering {#equations_numbering}


```
(@eq-mc) $E = mc^2$

I like Eq. (@eq-mc) so much that I am falling love with her.
```


```
\begin{equation} 
E = mc^2
  (\#eq:mc2)
\end{equation} 

I like Eq. \@ref(eq:mc2) so much that I am falling love with her.
```

## R, RStudio and bookdown {#r__rstudio_and_bookdown}
## LaTeX and Pandoc {#latex_and_pandoc}
## Workflow {#workflow}

# Simple {#simple}

There are three *simple* templates in 'bookdownplus': 'yihui_mini' ^[https://github.com/yihui/bookdown-minimal], 'yihui_demo' ^[https://github.com/rstudio/bookdown-demo], and 'yihui_zh' ^[https://github.com/yihui/bookdown-chinese]. They are not really simple. I call them *simple* only because I simply copied them from Yihui Xie's GitHub repos. My contribution was that I tailored them into 'bookdownplus' so that I don't have to download those repos every time when I start a new book.

You can write a standard book with the 'yihui_demo' template by simply running:

```{r, eval=FALSE}
bookdownplus(template = 'yihui_demo')
```

or a standard article with the 'yihui_mini' template by running 

```{r, eval=FALSE}
bookdownplus(template = 'yihui_mini')
```

or a book in Chinese with the 'yihui_zh' template by running 

```{r, eval=FALSE}
bookdownplus(template = 'yihui_zh')
```

Your will get a book file named 'yihui_*.pdf' in '_book/' folder as an example.

If you would like to specify the title and author, you can either use the `author` and `title` arguments, e.g.:

```{r, eval=FALSE}
bookdownplus(template = 'yihui_demo',
             author = 'John Smith',
             title = 'My book')
```

or modify them in 'index.Rmd' later.

In your working directory you could now open 'bookdownplus.Rproj' with RStudio. Write your own text in 'index.Rmd' and 'body.Rmd', and press 'ctrl+shift+b' to build your own book.



# Lifestyle {#lifestyle}

## Journal {#journal}


```{r imgjournal, fig.cap="A demo book produced by the 'journal' template.", out.width='90%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/journal_cropped.png")
```

You can write a laboratory journal or a personal diary with the 'journal' template (Fig. \@ref(fig:imgjournal)) by simply running:

```{r, eval=FALSE}
bookdownplus(template = 'journal')
```

Your will get a book file named 'journal.pdf' in '_book/' folder as an example. 

If you would like to specify the title and author, you can run the following code instead:

```{r, eval=FALSE}
bookdownplus(template = 'journal',
             author = 'John Smith',
             title = 'My journal')
```

In your working directory you could now open 'bookdownplus.Rproj' with RStudio. Write your own text in 'index.Rmd' and 'body.Rmd', and press 'ctrl+shift+b' to build your own journal book. You could revise the title and author list in 'index.Rmd'.

You might notice the wide margin of the pages. The margins are for your future use, i.e. adding comments or notes.

The 'journal' template is built on the basis of the LaTeX class 'labbook.cls' by Frank Küster. You could customize 'style/labbook.cls' if you are an expert on LaTeX.

## Poem book {#poem_book}

A poem book produced with 'bookdownplus' looks like Fig. \@ref(fig:imgpoem). You can write such a book with the 'poem' template by simply running:

```{r, eval=FALSE}
bookdownplus(template = 'poem')
```
Your will get a book file named 'poem.pdf' in '_book/' folder as an example.

```{r imgpoem, fig.cap="A demo book produced by the 'poem' template.", out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/poem_cropped.png")
```

If you would like to specify the title and author, you can run the following code instead:

```{r, eval=FALSE}
bookdownplus(template = 'poem',
             author = 'John Smith',
             title = 'My Poem book')
```

In your working directory you could now open 'bookdownplus.Rproj' with RStudio. Write your own text in 'index.Rmd' and 'body.Rmd', and press 'ctrl+shift+b' to build your own poem book. You could revise the title and author list in 'index.Rmd'.

In 'body.Rmd' you can use the mark `\bb{}` to enlarge the first letter of each paragraph of a poem. \m{Is it called 'paragraph' or something else? I am not sure.}

## Music {#music}

Writing books including music pieces is difficult. Think about how to do it in Microsoft Word. Fortunately 'bookdown' works on the top of LaTeX, and there are LaTeX solutions for music books.

For example, you can write a guitar chord book by simply running:

```{r, eval=FALSE}
bookdownplus(template = 'guitar')
```
Your will get a book file named 'guitar.pdf' in '_book/' folder as an example. The book looks like Fig. \@ref(fig:imgguitar).

```{r imgguitar, fig.cap='A guitar chord book', out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/guitar_cropped.png")
```

If you would like to specify the title and author, you can run the following code instead:

```{r, eval=FALSE}
bookdownplus(template = 'guitar',
             author = 'John Smith',
             title = 'My Guitar book')
```

In your working directory you could now open 'bookdownplus.Rproj' with RStudio. Write your own text in 'index.Rmd' and 'body.Rmd', and press 'ctrl+shift+b' to build your own guitar chord book. You could revise the title and author list in 'index.Rmd'.

Open 'body.Rmd', and you could see how the chords are inserted. For example, the mark `\F` means 'F chord', and the mark `\Am` means 'A minor chord'. These marks are pre-defined by users in 'tex/template_guitar.tex'. I have defined some often-used chords. If you are interested, you can add more chords and share them with me, so that we could build a complete chord library for 'bookdownplus' users. The method to define a new chord can be found in the documentation of 'gchord' ^[http://kasper.phi-sci.com/gchords/], which is a LaTeX package for typesetting guitar chord diagrams by Kasper Peeters.

Writing a guitar chord book ^[https://bookdown.org/baydap/bdguitar/] is the upper limit of my knowledge in music. I would not go further in this direction, but you can do more with 'bookdown' if you want to. For instance, the 'musixtex' package ^[https://www.ctan.org/pkg/musixtex?lang=en] of LaTeX makes it possible to typesetting music like Fig. \@ref(fig:imgmusixtex). I guess it should not be difficult to tailor it into 'bookdownplus'. Be brave to do it!

```{r imgmusixtex, fig.cap='Typesetting music with musixtex package.', out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/musixtex.png")
```

# Office {#office}

## Mail {#mail}

The 'mail' template generates a mail like Fig. \@ref(fig:imgmail). There are multiple options in the 'mail' template, with which you can produce different types of letters. These options can be classified into two groups: contents and themes.

```{r imgmail, fig.cap="A personal mail produced by the 'mail' template", out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/mail_cropped.png")
```

### Arguments for mail content

A letter has a unique structure, different from other documents. There are e.g. the sender's and recipient's addresses, their phones and affiliations, the opening and closing words, etc.. These must be specified in the arguments of `bookdownplus()`:

```{r, eval=FALSE}
bookdownplus(template = 'mail',
             author = "Peng Zhao",
             mail_from_address = "15 Robin Hood Lane", 
             mail_from_town = "11758  Massapequa, New York", 
             mail_from_phone = "31415926", 
             mail_from_mobile = "31415927", 
             mail_from_fax = "31415928", 
             mail_from_email = "dapengde@live.com", 
             mail_to_who = "recipient", 
             mail_to_affiliation = "University of Innsbruck", 
             mail_to_address = "recipient address", 
             mail_to_town = "100000 Beijing, China", 
             mail_opening = "Dear Sir or Madam,", 
             mail_closing = "Yours faithfully,", 
             mail_date = "25 June, 2017")
```

I believe these arguments are self-explanatory.

If you would like to change these pieces of information, you change revise  `\tex\template_mail_user.tex`, which requires a little knowledge in LaTeX.

### Mail themes

You can use several functions to decide how your mail looks.

The function `mail_style()` displays the available layouts of the mail:

```{r}
mail_style()
```

You can use these layouts for the `mail_style` argument in `bookdownplus()`:

```{r, eval=FALSE}
bookdownplus(mail_style = 'banking')
```

The function `mail_theme()` displays the available themes for the sender's header of the letter:

```{r}
mail_theme()
```

They are actually the colors of the sender's name.

Some different themes might result in the same output, because they are not all supported by a certain style.

As you are writing a mail to print, it would be nice if you think about the receiver's eyesight. You could change the font size of your mail by using the `mail_font()` argument for the fonts of your mail body, `mail_bodysize` argument for the font size of the mail body, and `mail_fontsize()` argument of the entire mail.

```{r, eval=FALSE}
bookdownplus(mail_font = 'calligra',
             mail_fontsize = '12pt', 
             mail_bodysize = 'large')
```

If you are too lazy to memorize their values, you can use the following functions to  remind you:

```{r}
mail_font()
mail_fontsize()
mail_bodysize()
```

## Calendar {#calendar}

Creating a calendar with 'bookdown' is challenging, but possible, if only you accept LaTeX. More or less, the 'calendar' template may help us see how far we can go with 'bookdown'.

A calendar template can be created by running:

```{r, eval=FALSE}
bookdownplus(template = 'calendar')
```

In your working directory you could now open 'bookdownplus.Rproj' with RStudio. Press 'ctrl+shift+b' to build it. Your will get a file named 'calendar.pdf' in '_book/' folder as an example. The calendar looks like Fig. \@ref(fig:imgcalendar).

```{r imgcalendar, fig.cap="A monthly calendar produced by the 'calendar' template.", out.width='100%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/calendar.png")
```

The content of the calendar can be revised in 'body.tex'. There are examples and fully explanations in it. I am not that interested in creating calendars, but I will be glad if you let me know how you like it.

# Academic {#academic}

## Articles {#articles}

Writing academic articles with 'bookdown' was my original intention of developing 'bookdownplus'. This chapter comes so late because I would not like those non-academic users to be scared. Actually, writing academic articles is the most beautiful essence of 'bookdown' from my point of view. Only in an academic article can users utilize the full support of superscripts, subscripts, footnotes, equations, tables, reproducible figures, citations, and cross-references.

An academic article produced with 'bookdownplus' looks like Fig. \@ref(fig:imgarticle). You can write such an article with the 'copernicus' template by simply running:

```{r, eval=FALSE}
bookdownplus(template = 'copernicus')
```
Your will get a book file named 'copernicus.pdf' in '_book/' folder as an example.

```{r imgarticle, fig.cap="An academic article produced by the 'copernicus' template.", out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/article_cropped.png")
```

If you would like to specify the title and author, you can either run the following code instead:

```{r, eval=FALSE}
bookdownplus(template = 'copernicus',
             author = 'John Smith',
             title = 'My article')
```


In your working directory you could now open 'bookdownplus.Rproj' with RStudio. 
Write your own text in 'index.Rmd' and 'body.Rmd', and press 'ctrl+shift+b' to build your own article. You could revise the title and author list in 'index.Rmd'.

By default, the 'copernicus' templates uses the two-columned LaTeX package by Copernicus Publications ^[http://publications.copernicus.org/for_authors/latex_instructions.html]. They provide a template for discussion layout as well, which was tailored as the 'discussion' template:

```{r, eval=FALSE}
bookdownplus(template = 'discussion')
```

For the sake of the copyright, you can find in the header the following texts: 

> Manuscript prepared for J. Name with version 4.2 of the LATEX class copernicus.cls.

You can remove them for personnel use if you don't like it. Open 'style/copernicus.cls' with a text editor, and remove or revise Line 1006 and 1192.


Furthermore, numerous academic journals provide their own LaTeX templates. Although I will add more article templates to 'bookdownplus' \m{quite dependent on my academic career} in the future, it would be appreciated if you join me and share your work.

## Thesis {#thesis}

An academic thesis produced with 'bookdownplus' looks like Fig. \@ref(fig:imgthesisubt). Multiple templates for thesis are available in 'bookdownplus'. You can create such a thesis with the 'thesis_ubt' template by simply running:

```{r, eval=FALSE}
bookdownplus(template = 'thesis_ubt')
```

Your will get a book file named 'thesis_ubt.pdf' in '_book/' folder as an example.

```{r imgthesisubt, fig.cap="A demo thesis of University of Bayreuth, produced by the thesis ubt template.",  out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/thesis-ubt_cropped.png")
```

In your working directory you could now open 'bookdownplus.Rproj' with RStudio. Press 'ctrl+shift+b' to build it. 

The postfix 'ubt' is the abbreviation of University of Bayreuth (UBT) where I achieved my PhD. The 'thesis_ubt' template is actually originated from the LaTeX file of my PhD dissertation. Thanks to my UBT colleagues who taught me how to use LaTeX. 

To modify the demo thesis into your own, you have to go through more steps than creating single articles due to the complicated structure of a dissertation. Don't worry. Follow me and you can eat it like a piece of cake.

1. The main part of your thesis can be written in 'body.Rmd' and 'index.Rmd' in the same way as other templates. Congratulations! You have done 90% of the work.

2. Open 'tex/template_thesis_ubt.tex' with a text editor (e.g. 'NotePad++'). Now you see scary LaTeX codes in it. Be brave. You will conquer them.

3. In Line 68 -- 82 you can specify your own subject, institute, supervisor's name, etc.

4. In Line 94 -- 119 you can modify them into the symbols and abbreviations of your own. If you don't need them, just remove these lines.

5. In Line 122 -- 136 you can remove the chapters you don't need, but leave `$body$` untouched. `$body$` is the location where the content of 'body.Rmd' will be inserted. 

Now it is done.

The dissertation of UBT requires some chapters written in German, which you can see in 'tex/template_thesis_ubt.tex'. I leave them there for the convenience of those users studying in German speaking regions. If you don't need them, just simply remove them as you like.

Besides 'thesis_ubt', a simple template called 'thesis_mypku_zh' can be performed for those written in Chinese:

```{r, eval=FALSE}
bookdownplus(template = 'thesis_mypku_zh')
```

This template was modified from 'yihui_zh' template with some pages from my master thesis in Peking University (PKU). Be careful, though, if you use this template to write your PKU thesis. There have been official requirements for the thesis format recently, which is different from my thesis written more than a decade ago. 

Other templates for academic thesis are 'thesis_classic' and 'thesis_zju_zh'. The [pdf version of this book](https://bookdown.org/baydap/bookdownplus/bookdownplus.pdf) you are reading now is created with 'thesis_classic' by Andre Miede ^[http://www.ctan.org/tex-archive/macros/latex/contrib/classicthesis/]. You can see how it works in the source code of this book ^[https://github.com/pzhaonet/bookdown-plus-textbook]. For example, you could add a `subtitle` field in the YAML header of 'index.Rmd', then the subtitle apprears on the cover page of the book.

The 'thesis_zju_zh' template is modified from the LaTeX template of thesis of Zhejiang University, which will be described in Chapter \@ref(thesis).

Numerous universities and institutes provide their own LaTeX templates for thesis. Although I will add more thesis templates to 'bookdownplus' in the future, it would be appreciated if you join me and share your work.

## Poster {#poster}

I did not expect to create academic posters with R 'bookdown' or 'markdown', because I think posters are not necessarily as structured as articles. Microsoft Powerpoint is still the easiest way to make a poster. A poster created in markdown syntax has its own advantages, though. It is reproducible, easy to maintain, easy to change the style, and has the common features of R markdown. You could see the posters generated by 'bookdownplus' in Fig. \@ref(fig:imgposter). Not bad, hmmm?

```{r imgposter, fig.cap='Themes of the poster template: eco, ocean, and rose ', out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/poster.jpg")
```

The procedure of creating a poster template is different from other 'bookdownplus' templates. Firstly, you have to prepare the software environment. Windows users can do the following steps: 

- Install [Python 2](https://www.python.org/downloads/windows/).

- Install [Python filter support for Pandoc](https://pypi.python.org/pypi/pandocfilters):
  on a Windows command prompt, type `pip install pandocfilters`

- Install [SumatraPDF](http://www.sumatrapdfreader.org/download-free-pdf-viewer.html) for auto-refresh of PDF previews

- Add the Python directory to the system PATH variable (Computer -- right click -- Properties -- Advanced System Settings -- Environmental Variables -- PATH -- Edit).

Linux users can refer to the instruction of kuleuven-templates ^[https://github.com/exporl/kuleuven-templates], which is the origin of the 'poster' template.

Now you can create such a poster with the 'poster' template by running:

```{r, eval=FALSE}
bookdownplus(template = 'poster',
             theme = 'eco',
             email = 'youremail@email',
             institute = 'your institute',
             web = 'http://youdomain.com',
             logo = 'your logo picture',
             backimg = 'your background image',
             bibliofiles = 'your bib file')
```

In 'bookdownplus()', only `template` and `theme` have to be specified. Other arguments are optional, which can be modified later.

Three themes for posters are available in 'bookdownplus 1.0.2': 'eco' (default), 'ocean', and 'rose'. Of course you can create your own theme on the basis of 'tex/poster_eco.tex' if you are a LaTeX expert \m{It would be appreciated if you could share your templates with me}. 

In your working directory you could now open 'index.Rmd' with RStudio. Click the 'Knit' button in the toolbar of the top-left panel, and you will get a file named 'index.pdf' in your working directory as a demo. However, the Bibliography section in the poster is empty. Click the 'Knit' button once again and it will be filled. If you know how bibtex works, it will be easy to understand why you have to knit twice. But just do it and never be bothered.

As you know the steps of creating a demo poster, now it is time to build your own poster. I would recommend you to read the demo 'index.Rmd' from A to Z, then you will get all the ideas of the key elements in a markdown poster. Besides the common bookdown syntax, the following is a list of specific ones for the poster:

- Use `[columns=2]` to make a new row split into 2 columns and `[/columns]` to end the row. Use `[column]` to start a new column in the row. 

- Use `\vskip0.5cm` to adjust the verticle blank space in a column.

- Use `\printbibliography` to create the Bibliography section.

Have you noticed something? The hot key or button of building a 'bookdown' document has never been used for the 'poster' template! Indeed 'bookdownplus' poster template is nothing to do with 'bookdown'. It is a 'markdown' solution for posters extracted from kuleuven-templates ^[https://github.com/exporl/kuleuven-templates] with my additional contribution. I put it in the 'bookdownplus' package only because poster is a piece of the puzzle in academic productions, and I would like to build 'bookdownplus' as a complete academic tool.

In the meanwhile I am developing a stand-alone version of the poster template as the 'postr' package [@R-postr] for non 'bookdown' users. This stand-alone version is more advanced and up-to-date with some more themes and features. For instance, it has a function for removing unnecessary files and folders bi-produced by the poster template. 

## Chemistry {#chemistry}

A chemistry article or book produced with 'bookdownplus' looks like Fig. \@ref(fig:imgchemistry). You can write such a book with the 'chemistry' template by simply running:

```{r, eval=FALSE}
bookdownplus(template = 'chemistry')
```

Your will get a book file named 'chemistry.pdf' in '_book/' folder as an example.

```{r imgchemistry, fig.cap="A chemistry book produced by the 'chemistry' template.", out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/chemistry_cropped.png")
```

In your working directory you could now open 'bookdownplus.Rproj' with RStudio. Write your own text in 'index.Rmd' and 'body.Rmd', and  press 'ctrl+shift+b' to build your own chemistry book. You could revise the title and author list in 'index.Rmd'.

In 'body.Rmd' you can see how to insert chemical formulae, chemical equations, and structural formulae. For more details, please see the 'mhchem' LaTeX package by Martin Hensel ^[https://www.ctan.org/pkg/mhchem].

# Advanced {#advanced}

## Chinese Support {#chinese}

The support for Chinese typesetting with 'bookdown' is tricky. Briefly speaking, you need a LaTeX template which supports Chinese characters and styles. In Chapter \@ref(simple) the template 'yihui_zh' was introduced. It is a nice template for daily use. However, you might encounter some problems when producing html files from the chapter headers which contains Chinese characters, especially those mixed with Latin letters. See the discussion between me and Yihui ^[https://disqus.com/home/discussion/yihui/_yihui_xie_679/#comment-3175332429]. One solution is to add `{#identifier}` manually to those problematic headers. I tried this. It works fine if you do it when writing a new chapter, but it is boring if you do it after finishing a book. Another solution is using the 'pinyin' package [@R-pinyin]. A function called `bookdown2py()` can convert the headers into pinyin (the official romanization system for Standard Chinese^[https://en.wikipedia.org/wiki/Pinyin]) and add the #IDs automatically:

```{r, eval=FALSE}
install.packages('pinyin')
library('pinyin')
?bookdown2py
```

More details about the 'pinyin' package can be found on my GitHub repo^[https://github.com/pzhaonet/pinyin].

'bookdownplus' gives your more options to create other documents in Chinese. For example, the 'nte_zh' template is designed for writing novels or proses which are not as structured as academic thesis:

```{r, eval=FALSE}
bookdownplus(template = `nte_zh`)
```

The template name 'nte' is short for 'Nothing to Envy', the title of the book whose LaTeX code was the origin of this template. I have written a book with the 'nte_zh' template, which is online^[https://bookdown.org/baydap/papasdiary/].

If you are writing an academic article in Chinese, you can use the 'article_zh' template:

```{r, eval=FALSE}
bookdownplus(template = 'article_zh')
```
You will get a file named 'article_zh.pdf' in '_book/' folder as an example (Fig. \@ref(fig:imgarticlezh)). 


```{r imgarticlezh, fig.cap="An academic article in Chinese produced by the 'article zh' template. ", out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/article-zh_cropped.png")
```

Similar to other templates, in your working directory you could now open 'bookdownplus.Rproj' with RStudio. You can write your own text in 'index.Rmd' and 'body.Rmd', and then press 'ctrl+shift+b' to build it.

The particular section of this demo file is the abstract. It is bilingual with different formats from the main body. You can revise your abstract in 'abstract.tex'. It is self-explanatory, although written in LaTeX. I wish I could tailor it into markdown, but I don't think it is necessary. 

If these templates do not fulfil your request for academic thesis in Chinese, you could use the 'theis_zju' template:

```{r, eval=FALSE}
bookdownplus(template = 'thesis_zju_zh')
```
You will get a file named 'thesis_zju_zh.pdf' in '_book/' folder as an example (Fig. \@ref(fig:imgthesiszju)).


```{r imgthesiszju, fig.cap="A thesis generated from 'zju' template.", out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/thesis-zju_cropped.png")
```

Now you can write your own text in 'index.Rmd' and 'body.Rmd'. There are much more fields in 'index.Rmd' for you owing to the complicated structure of the thesis. Be patient. It is only the beginning of a dissertation.

The postfix 'zju' is short for Zhejiang University, one of the top universities in China. I have never been there. I tailored it into 'bookdownplus' only because I found a LaTeX template of ZJU thesis and compiled it successfully. There are templates available for the thesis of other universities and institutes, such as Peking University ^[https://github.com/CasperVector/pkuthss] and Tsinghua University ^[https://github.com/xueruini/thuthesis]. Unfortunately I failed in compiling these LaTeX templates on my computer. I am not a LaTeX expert. I wish these templates could perhaps be tailored and included in 'bookdownplus' in the future, if you can help and join me.

A combination of multiple templates could generate a new one, such as the 'chemistry_zh' template:

```{r, eval=FALSE}
bookdownplus(template = 'chemistry_zh')
```
You will get a file named 'chemistry_zh.pdf' in '_book/' folder.

This template is the child parented by 'yihui_zh' and 'chemistry' templates. In this way you could customize your own template. A further description of creating your own templates is in Chapter \@ref(customize).

Each of the templates which support Chinese characters has name ended with '_zh'. To display these templates, run:

```{r}
grep('_zh$', template(), value = TRUE)
```
As a regular expression, `$` means the end of a string.

## Mind Map {#mind_map}

Now you have your books or thesis done. It would be nice to show the outline of your book in a mind map. The mind map of this book is shown in Fig. \@ref(fig:imgmindmap).

```{r imgmindmap, fig.cap='Mind map of R bookdownplus Textbook', out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/mindmap.jpg")
```

Owing to the advantage of 'bookdown', you don't have to draw such a mind map by hand. This mind map is automatically generated from the 'body.Rmd' file of the 'R bookdownplus Textbook' by using the R package 'mindr' [@R-mindr]:

```{r, eval=FALSE}
install.packages('mindr')
library('mindr')
?md2mm()
```

With the 'mindr' package you can easily extract the outline from your 'bookdown' file. More details about the 'mindr' package can be found on my GitHub repo^[https://github.com/pzhaonet/mindr].

## Create Your Own Templates {#customize}

'bookdownplus' provides you around 20 templates (Version 1.2.0) and more will be included in the future. I am not an expert in LaTeX but I have successfully created the pdf templates described in this book. It means that creating a LaTeX template does not require much knowledge in LaTeX. If you know the general workflow of LaTeX, and study the 'bookdownplus' templates carefully, and read Chapter 4 of the official manual of 'bookdown'^[https://bookdown.org/yihui/bookdown/], you will get the idea of how to create your own templates. 

Here is some hints from my experience on creating a new template from am existing LaTeX template:

- Find a nice LaTeX template. There are many websites that provide free LaTeX templates. You can download one you like most. Those with good documentations and comments are highly recommended.

- Compile the LaTeX template file to make sure that it can work fine and produce the right pdf file. You could either use command lines or use some software like TexStudio to compile it. You could send to me this template with its full documentation and your pdf file, if you do not want to continue by yourself. I would try tailoring it into 'bookdownplus' but it is not guaranteed. It depends on my time and mood. Thus I recommend you to be brave and continue the next steps.  

- Cut the template into 'template_yours.tex' and 'index.Rmd' in the following way:

  - The main body of the LaTeX are the part between `\begin{document}` and `\end{document}`. Replace the main body with `$body$`, which will be filled with 'body.Rmd'. You can use any demo 'body*.Rmd' created by 'bookdownplus'.

  - Use any 'index.Rmd' created by 'bookdownplus' and modify the name of the LaTex template in 'index.Rmd'.

- If the LaTeX template is simple enough, now you may build this template book with 'bookdown'. 

- Usually it won't work. A good-looking LaTeX template is most likely complicated, especially those in Chinese. Probably you have to modify the preamble, pick out some parts and save them and specify them in 'index.Rmd'. See the official manual of 'bookdown'^[https://bookdown.org/yihui/bookdown/yaml-options.html].

- If you can successfully build your book with your new template, congratulations. It would be appreciated if you could send me your 'index.Rmd', 'body.Rmd', 'template_yours.tex' and other related files. I will add them into 'bookdownplus' templates and add your name into the contributor list. 

Let's build a 'bookdownplus' template library!

# FAQ {#faq}

# Bibliography {-}