-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Bruno Rodrigues
committed
Sep 14, 2023
1 parent
c168dba
commit 1295d74
Showing
3 changed files
with
224 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
161 changes: 161 additions & 0 deletions
161
vignettes/building-an-environment-for-literate-programming.Rmd
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,161 @@ | ||
| --- | ||
| title: "Building an environment for literate programming" | ||
| output: rmarkdown::html_vignette | ||
| vignette: > | ||
| %\VignetteIndexEntry{building-an-environment-for-literate-programming} | ||
| %\VignetteEngine{knitr::rmarkdown} | ||
| %\VignetteEncoding{UTF-8} | ||
| --- | ||
|
|
||
| ```{r, include = FALSE} | ||
| knitr::opts_chunk$set( | ||
| collapse = TRUE, | ||
| comment = "#>" | ||
| ) | ||
| ``` | ||
|
|
||
| ```{r setup} | ||
| library(rix) | ||
| ``` | ||
|
|
||
| <!-- WARNING - This vignette is generated by {fusen} from dev/literate_programming.Rmd: do not edit by hand --> | ||
|
|
||
| ## Introduction | ||
|
|
||
| This vignette will walk you through setting up a development environment with | ||
| `{rix}` that can be used to compile Quarto documents into PDFs. We are going to | ||
| use the [Quarto template for the JSS](https://github.com/quarto-journals/jss) to | ||
| illustrate the process. | ||
|
|
||
|
|
||
| ## Starting with the basics | ||
|
|
||
| Since we need both the `{quarto}` R package as well as the `quarto` engine, we | ||
| add both of them to the `r_pkgs` and `system_pkgs` of arguments of `{rix}`. | ||
| Because we want to compile a PDF, we also need to have `texlive` installed, as | ||
| well as some LaTeX packages. For this, we use the `tex_pkgs` argument: | ||
|
|
||
|
|
||
| ```{r} | ||
| path_default_nix <- tempdir() | ||
| rix(r_ver = "4.3.1", | ||
| r_pkgs = c("quarto"), | ||
| system_pkgs = "quarto", | ||
| tex_pkgs = c("amsmath"), | ||
| ide = "other", | ||
| shell_hook = "", | ||
| project_path = path_default_nix, | ||
| overwrite = TRUE, | ||
| print = TRUE) | ||
| ``` | ||
|
|
||
| (Save these lines into a script called `build_env.R` for instance, and run the | ||
| script into a new folder made for this project.) | ||
|
|
||
| By default, `{rix}` will install the "small" version of the `texlive` | ||
| distribution available on Nix. To see which `texlive` packages get installed | ||
| with this small version, you can click | ||
| [here](https://search.nixos.org/packages?channel=unstable&show=texlive.combined.scheme-small&from=0&size=50&sort=relevance&type=packages&query=scheme-small). | ||
| We start by adding the `amsmath` package then build the environment using: | ||
|
|
||
|
|
||
| ```{r eval = F} | ||
| nix_build() | ||
| ``` | ||
|
|
||
| Then, drop into the Nix shell with `nix-shell`, and run `quarto add | ||
| quarto-journals/jss`. This will install the template linked above. Then, in the | ||
| folder that contains `build_env.R`, the generated `default.nix` and `result` | ||
| download the following files from | ||
| [here](https://github.com/quarto-journals/jss/): | ||
|
|
||
| - article-visualization.pdf | ||
| - bibliography.bib | ||
| - template.qmd | ||
|
|
||
| and try to compile `template.qmd` by running: | ||
|
|
||
| ``` | ||
| quarto render template.qmd --to jss-pdf | ||
| ``` | ||
|
|
||
| You should get the following error message: | ||
|
|
||
| ``` | ||
| Quitting from lines 99-101 [unnamed-chunk-1] (template.qmd) | ||
| Error in `find.package()`: | ||
| ! there is no package called 'MASS' | ||
| Backtrace: | ||
| 1. utils::data("quine", package = "MASS") | ||
| 2. base::find.package(package, lib.loc, verbose = verbose) | ||
| Execution halted | ||
| ``` | ||
|
|
||
| So there's an R chunk in `template.qmd` that uses the `{MASS}` package. Change | ||
| `build_env.R` to generate a new `default.nix` file that will now add `{MASS}` to | ||
| the environment when built: | ||
|
|
||
|
|
||
| ```{r} | ||
| rix(r_ver = "4.3.1", | ||
| r_pkgs = c("quarto", "MASS"), | ||
| system_pkgs = "quarto", | ||
| tex_pkgs = c("amsmath"), | ||
| ide = "other", | ||
| shell_hook = "", | ||
| project_path = path_default_nix, | ||
| overwrite = TRUE, | ||
| print = TRUE) | ||
| ``` | ||
|
|
||
| Trying to compile the document results now in another error message: | ||
|
|
||
| ``` | ||
| compilation failed- no matching packages | ||
| LaTeX Error: File `orcidlink.sty' not found | ||
| ``` | ||
|
|
||
| This means that the LaTeX `orcidlink` package is missing, and we can solve the | ||
| problem by adding `"orcidlink"` to the list of `tex_pkgs`. Rebuild the | ||
| environment and try again to compile the template. Trying again yields a new | ||
| error: | ||
|
|
||
| ``` | ||
| compilation failed- no matching packages | ||
| LaTeX Error: File `tcolorbox.sty' not found. | ||
| ``` | ||
|
|
||
| Just as before, add the `tcolorbox` package to the list of `tex_pkgs`. You will | ||
| need to do this several times for some other packages. There is unfortunately no | ||
| easier way to list the dependencies and requirements of a LaTeX document. | ||
|
|
||
| This is what the final script to build the environment looks like: | ||
|
|
||
|
|
||
| ```{r} | ||
| rix(r_ver = "4.3.1", | ||
| r_pkgs = c("quarto", "MASS"), | ||
| system_pkgs = "quarto", | ||
| tex_pkgs = c( | ||
| "amsmath", | ||
| "environ", | ||
| "fontawesome5", | ||
| "orcidlink", | ||
| "pdfcol", | ||
| "tcolorbox", | ||
| "tikzfill" | ||
| ), | ||
| ide = "other", | ||
| shell_hook = "", | ||
| project_path = path_default_nix, | ||
| overwrite = TRUE, | ||
| print = TRUE) | ||
| ``` | ||
|
|
||
| The template will now compile with this environment. To look for a LaTeX | ||
| package, you can use the [search engine on | ||
| CTAN](https://ctan.org/pkg/orcidlink?lang=en). | ||
|
|