95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
# Instructions for compiling LaTeX documents in Visual Studio Code
|
||
|
||
This tutorial demonstrates how to set up VS Code to compile the LaTeX script. Make sure to have a [LaTeX compiler installed](./README.md) before continuing.
|
||
|
||
## Software installation
|
||
|
||
1. Download and install [VS Code](https://code.visualstudio.com/) or its open-source version [VS Codium](https://vscodium.com/).
|
||
2. Install the [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) plugin.
|
||
|
||
## Build recipes
|
||
|
||
LaTeX Workshop uses so-called recipes to compile documents. A recipe refers to a list of commands that are executed one after the other. For our exercises, we will need one basic recipe which simply runs the compiler twice. Later on, we will need a second recipe to deal with bibliographic data.
|
||
|
||
1. Launch the VS Code settings and search for “recipes.”
|
||
2. In the “Latex-workshop > LaTeX: Recipes” section, click on “Edit in settings.json.”
|
||
3. Go ahead and add the following two entries to the list. The first one just uses the `pdflatex` compiler twice to build our document, whereas the second one adds an intermediate round of `biber` compilation and changes the LaTeX compiler to `lualatex`.
|
||
|
||
```json
|
||
"latex-workshop.latex.recipes": [
|
||
{
|
||
"name": "pdflatex × 2",
|
||
"tools": [
|
||
"pdflatex",
|
||
"pdflatex"
|
||
]
|
||
},
|
||
{
|
||
"name": "lualatex -> biber -> lualatex × 2",
|
||
"tools": [
|
||
"lualatex",
|
||
"biber",
|
||
"lualatex",
|
||
"lualatex"
|
||
]
|
||
},
|
||
// EXISTING ENTRIES GO HERE
|
||
]
|
||
```
|
||
|
||
4. Now search for “latex tools” in the settings search.
|
||
5. In the “Latex-workshop > LaTeX: Tools section, click on “Edit in settings.json.”
|
||
6. Make sure the following entry is part of the list.
|
||
|
||
```json
|
||
"latex-workshop.latex.tools": [
|
||
{
|
||
"name": "biber",
|
||
"command": "biber",
|
||
"args": [
|
||
"%DOC%"
|
||
],
|
||
"env": {}
|
||
},
|
||
{
|
||
"name": "lualatex",
|
||
"command": "lualatex",
|
||
"args": [
|
||
"-synctex=1",
|
||
"-interaction=nonstopmode",
|
||
"-file-line-error",
|
||
"%DOC%"
|
||
],
|
||
"env": {}
|
||
},
|
||
// EXISTING ENTRIES GO HERE
|
||
]
|
||
```
|
||
|
||
7. Save and close the settings file.
|
||
8. For later convenience, set the “Latex-workshop > Latex > Recipe: Default” option to `lastUsed`.
|
||
|
||
## Compiling
|
||
|
||
1. Open the unzipped project archive (available in the [Releases section](https://git.stuve-bamberg.de/latex/latex-skript/releases)).
|
||
2. To test your installation, open `main-exercises.tex`.
|
||
3. In the left side bar, click on the TeX symbol, open the “Build LaTeX project entry” (clicking on the little arrow on the left) and choose the “pdflatex × 2” recipe. For the duration of the compilation, you should see a spinning icon in the bottom row next to the Git icons. Any errors will appear in the problems tab.
|
||
4. To open the resulting document, click on “View LaTeX PDF” in the TeX section below the recipes. If this succeeded, you are ready to work on the exercises. The document will compile again once you save it.
|
||
|
||
## Some useful notes
|
||
|
||
+ LaTeX Workshop has a [process of deciding which file to compile](https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#latex-workshoplatexbuildforceRecipeUsage). Unfortunately, our project archive tends to confuse the plugin, resulting in compiler errors. You can **specify the document root** by adding a magic TeX root comment. We provided these comments for you in all exercise files:
|
||
|
||
```
|
||
% !TeX root = ../../main-exercises.tex
|
||
```
|
||
|
||
+ However, by default, **LaTeX Workshop ignores them** because they may pose a security threat if you cannot trust the project you are compiling. See [this issue](https://github.com/James-Yu/LaTeX-Workshop/issues/3027) for more details. To enable them anyway, go to your settings and deactivate the “Force Recipe Usage” checkbox.
|
||
|
||
The **LaTeX Workshop** plugin offers a couple of other handy features:
|
||
|
||
+ Sometimes, it is helpful to kill all compiler processes and **clean up the auxiliary files** afterwards.
|
||
+ If you need to **find a certain section** in the PDF or in the source document, you can use the “Navigate, select and edit” menu.
|
||
+ In the left sidebar, you will also find the entire **document structure** and **snippets** that will make your life easier.
|
||
|