-
-
Notifications
You must be signed in to change notification settings - Fork 227
/
Copy path01-installation.Rmd
127 lines (82 loc) · 8.69 KB
/
01-installation.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
\mainmatter
# Installation
To use R Markdown, you have to install R [@R-base] and the R package **rmarkdown** [@R-rmarkdown].
```{r eval=FALSE}
# install the rmarkdown package from CRAN in R
install.packages('rmarkdown')
# or install from GitHub if you want to test the development version
if (!requireNamespace("remotes")) install.packages('remotes')
remotes::install_github('rstudio/rmarkdown')
```
Unless you have a favorite editor or IDE (Integrated Development Environment), we recommend that you also install the RStudio\index{RStudio} IDE (https://www.rstudio.com). RStudio is not required, but it will make it easier for an average user to work with R Markdown because of the strong editor support. If you choose not to use the RStudio IDE, you will need to install Pandoc\index{Pandoc} (see Section \@ref(install-pandoc)), which is the tool used by **rmarkdown** to convert Markdown to other document formats.
If you need to create PDF output, you may need to install LaTeX\index{LaTeX} (Section \@ref(install-latex)) and certain LaTeX packages (Section \@ref(install-latex-pkgs)).
## Use a Pandoc version not bundled with the RStudio IDE {#install-pandoc}
The RStudio IDE has bundled a version of Pandoc\index{Pandoc}, so you do not need to install Pandoc by yourself if you use the RStudio IDE. However, for some advanced usage, the bundled version may differ from the exact version you want. You can choose to install a separate copy of Pandoc by yourself. Please remember that the bundled version may be more thoroughly tested with R Markdown, because most RStudio users may just use the bundled version. If you want to go with a different version (especially a higher version), you might run into problems that other R Markdown users or developers have yet to discover.
Some configurations are required if you have installed a specific Pandoc version by yourself.
First, before running `rmarkdown::render()`, you may inform the **rmarkdown** package by calling the function `rmarkdown::find_pandoc()` in the same R session, e.g.,
```{r, eval=FALSE}
# to find a specific version (e.g., if lower version on PATH)
rmarkdown::find_pandoc(version = '2.9.1')
# to find Pandoc under a specific directory (e.g., if a specific version cannot be in PATH)
rmarkdown::find_pandoc(dir = '~/Downloads/Pandoc')
# ignore the previously found Pandoc and search again (i.e., opt out of the caching mechanism).
rmarkdown::find_pandoc(cache = FALSE)
```
As you can see in the above code chunk, several ways exist to find a version of Pandoc. By default, `rmarkdown::find_pandoc()` tries to find your system's highest version of Pandoc. Once found, the version information is cached, and you can invalidate the cache with `cache = FALSE`. Please see the help page `?rmarkdown::find_pandoc` for the potential directories where the `pandoc` executable may be found.
This function needs to be called outside of the Rmd document, as **rmarkdown** may use the Pandoc version information before knitting with code cells execution happens.
If you want an Rmd document to be compiled by a specific version of Pandoc installed on your computer, the **pandoc** package [@R-pandoc]\index{R package!pandoc} will help.
This package is designed to help test R code with different Pandoc versions. It allows installing and managing several Pandoc binary versions on the system and easily switching between versions. The function `pandoc::with_pandoc_version()` can help to render a document with a specific version of Pandoc, e.g., the following will render the document with Pandoc 2.9.1:
```r
pandoc::with_pandoc_version(
version = '2.9.1',
rmarkdown::render('input.Rmd')
)
```
The **pandoc** package works by default with its Pandoc binaries installation. See `?pandoc::pandoc_install()` for installation instructions of 2.9.1 in the example and, more generally, the [Get Started](https://cderv.github.io/pandoc/articles/pandoc.html) article.
For use with the Knit button in RStudio (See Section \@ref(custom-knit) about Knit button customization.), you can also customize the behavior like this:
````yaml
knit: (function(input, ...) { pandoc::with_pandoc_version("2.9.1", rmarkdown::render(input)) })
````
`pandoc::with_pandoc_version()` is a wrapper for `rmarkdown::find_pandoc()`, so you could also get inspiration from it to use your own version. See `?pandoc::with_pandoc_version()` for more details.
## Install LaTeX (TinyTeX) for PDF reports {#install-latex}
If you would like to create PDF documents from R Markdown, you will need to have a LaTeX\index{LaTeX} distribution installed. Although there are several traditional options including MiKTeX\index{LaTeX!MiKTeX}, MacTeX, and TeX Live, we recommend that R Markdown users install [TinyTeX.](https://yihui.org/tinytex/)
TinyTeX\index{LaTeX!TinyTeX} is a custom LaTeX distribution based on TeX Live that is relatively small in size, but functions well in most cases, especially for R users. Installing or running TinyTeX does not require sysadmin privileges.^[Actually, we recommend that you **do not** use your root privilege (i.e., `sudo`) to install TinyTeX on Linux or macOS, if you are the only user of your system.] You can install TinyTeX with the R package **tinytex**\index{LaTeX!tinytex} [@R-tinytex]:
```{r eval=!nzchar(tinytex::tinytex_root())}
tinytex::install_tinytex()
# to uninstall TinyTeX, run tinytex::uninstall_tinytex()
```
Please note that "**tinytex**" refers to the R package, and "TinyTeX" refers to the LaTeX distribution. There are two advantages of using TinyTeX:
1. TinyTeX is lightweight (compared to other LaTeX distributions), cross-platform, and portable. For example, you can store a copy of TinyTeX on your USB drive or other portable devices, and use it on other computers with the same operating system.
1. When R Markdown is converted to PDF, Pandoc converts Markdown to an intermediate LaTeX document first. The R package **tinytex** has provided helper functions to compile LaTeX documents to PDF (the main function is `tinytex::latexmk()`). If you use TinyTeX and certain LaTeX packages are required but not installed, **tinytex** will try to automatically install them for you. It will also try to compile the LaTeX file for a sufficient number of times to make sure all cross-references are resolved.
If you are interested in the technical details, you may check out the article @tinytex2019 and the FAQ page at https://yihui.org/tinytex/faq/.
## Install missing LaTeX packages {#install-latex-pkgs}
When you compile a document to PDF through LaTeX, you may run into errors like these:
```latex
! LaTeX Error: File `ocgbase.sty' not found.
!pdfTeX error: pdflatex (file 8r.enc):
cannot open encoding file for reading
!pdfTeX error: /usr/local/bin/pdflatex (file tcrm0700):
Font tcrm0700 at 600 not found
```
If you are using TinyTeX as introduced in Section \@ref(install-latex), usually you do not need to deal with such errors, since **tinytex** [@R-tinytex] will automatically deal with them, but if you run into such errors anyway, it is still easy to install the missing LaTeX package(s)\index{LaTeX!packages} via `tinytex::parse_install()`\index{tinytex!parse\_install()}. This function takes the path of the LaTeX log file as the input, tries to figure out the missing packages automatically, and installs them if they are found on CTAN (the Comprehensive TEX Archive Network, https://ctan.org). The LaTeX log file typically has the same base name as your input document, and has an extension `.log`. If you cannot find this log file, you can pass the error message to the `text` argument of this function. Both ways should work:
```{r, tidy=FALSE, eval=FALSE}
# if the log file is filename.log
tinytex::parse_install("filename.log")
# or use the `text` argument
tinytex::parse_install(
text = "! LaTeX Error: File `ocgbase.sty' not found."
)
# it will install the "ocgx2" package
```
If you do not use TinyTeX, the R package **tinytex** can still help you figure out the LaTeX package names from the error log---use the function `tinytex::parse_packages()`\index{tinytex!parse\_packages()}, e.g.,
```{r, tidy=FALSE, eval=FALSE}
# if the log file is filename.log
tinytex::parse_packages("filename.log")
# or use the `text` argument
tinytex::parse_packages(
text = "! LaTeX Error: File `ocgbase.sty' not found."
)
# it should return "ocgx2"
```
Once you know the package names, you can install them with the package manager of your LaTeX distribution.
If you are using MiKTeX\index{LaTeX!MiKTeX} instead, it can also install missing packages automatically. During the installation of MiKTeX, be sure to check the setting "Always install missing packages on-the-fly." If you have already installed it without this setting, [you can still change it in the MiKTeX Console.](https://github.com/rstudio/rmarkdown/issues/1285#issuecomment-374340175)