2 Quick start

2.1 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’¹¹ for details. A brief list is as follows:

Download R¹² and install it.
Download RStudio¹³ and install it.
Download LaTeX¹⁴ and install it.
Download Pandoc¹⁵ and install it.
Run RStudio. Type the following codes in the top-left panel to install ‘bookdown’ and ‘servr’ packages:

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

2.2 Installation of ‘bookdownplus’

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

install.packages('bookdownplus')

or the development version on GitHub:

devtools::install_github('pzhaonet/bookdownplus')

2.3 Three Steps

Beginners can follow the three steps given below:

Step 1. Generate a demo book

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.
Load the bookdownplus package by typing:

require(bookdownplus)

## Loading required package: 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).

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

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.

2.4 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:

more_output()

## [1] "word_document2" "html_document2" "epub_book"      "gitbook"

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

bookdownplus(more_output = more_output())

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

2.5 More templates

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

template()

##  [1] "article"         "article_mdpi"    "article_zh"     
##  [4] "calendar"        "chemistry"       "chemistry_zh"   
##  [7] "discussion"      "guitar"          "journal"        
## [10] "mail"            "nte_zh"          "poem"           
## [13] "thesis_classic"  "thesis_mypku_zh" "thesis_ubt"     
## [16] "thesis_zju_zh"   "yihui_demo"      "yihui_mini"     
## [19] "yihui_zh"        "poster"

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

bookdownplus(template = template()[1])

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

The detailed usage of each template is described in Chapter 4 to 8.

2.6 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/:

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:

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:

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 = '_'))
    }
  }
}

2.7 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 (Zhao 2017 c), which can extract the outline of your book and turn it into a mind map,
pinyin (Zhao 2017 d), which can automatically generate ‘{#ID}’ of the chapter headers even if there are Chinese characters in them, and
beginr (Zhao 2017 a), 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:

install.packages('mindr')  
install.packages('pinyin')
install.packages('beginr')

Enjoy your bookdowning!

Bibliography

Zhao, Peng. 2017c. Mindr: Convert Files Between Markdown or Rmarkdown Files and Mindmaps. https://CRAN.R-project.org/package=mindr.

Zhao, Peng. 2017d. Pinyin: Convert Chinese Characters into Pinyin. https://CRAN.R-project.org/package=pinyin.

Zhao, Peng. 2017a. Beginr: Functions for R Beginners. https://CRAN.R-project.org/package=beginr.