summaryrefslogtreecommitdiff
path: root/support/texlab/docs/previewing.md
diff options
context:
space:
mode:
Diffstat (limited to 'support/texlab/docs/previewing.md')
-rw-r--r--support/texlab/docs/previewing.md217
1 files changed, 217 insertions, 0 deletions
diff --git a/support/texlab/docs/previewing.md b/support/texlab/docs/previewing.md
new file mode 100644
index 0000000000..16a047190b
--- /dev/null
+++ b/support/texlab/docs/previewing.md
@@ -0,0 +1,217 @@
+# Previewing
+
+We believe that previewing should be a concern of the build system.
+With [`latexmk`](https://ctan.org/pkg/latexmk?lang=en), you can enable the preview feature by adding the `-pv` flag
+to the [`texlab.build.args`](/docs/reference/configuration/#latexbuildargs) setting.
+After that, the configured previewer will start on each rebuild of the document.
+Alternatively, use the `-pvc` flag to tell the previewer to continuously check for updates,
+instead of opening a new window each time a build completes.
+
+If you want to use [SyncTeX](http://www.tug.org/TUGboat/tb29-3/tb93laurens.pdf),
+you need to configure the settings in the [`texlab.forwardSearch`](/docs/reference/configuration#latexforwardsearchexecutable) section
+and configure your previewer to call your editor correctly.
+A forward search can then be executed by invoking the [`texlab.forwardSearch`](/docs/reference/commands#latexforwardsearch) command.
+
+In the following sections, we will give configurations for popular viewers with `latexmk` and Visual Studio Code.
+For other build systems and editors, please refer to their respective manuals.
+
+---
+
+## SumatraPDF
+
+We highly recommend [SumatraPDF](https://www.sumatrapdfreader.org) on Windows
+because Adobe Reader locks the opened PDF file and will therefore prevent further builds.
+To use [SumatraPDF](https://www.sumatrapdfreader.org) as previewer, add the following line to your `%USERPROFILE%/.latexmkrc` file:
+
+```perl
+$pdf_previewer = 'start "C:\Program Files\SumatraPDF\SumatraPDF.exe" %O %S';
+```
+
+### Forward Search
+
+Add the following lines to your editor config:
+
+```json
+{
+ "texlab.forwardSearch.executable": "C:/Program Files/SumatraPDF/SumatraPDF.exe",
+ "texlab.forwardSearch.args": [
+ "-reuse-instance",
+ "%p",
+ "-forward-search",
+ "%f",
+ "%l"
+ ]
+}
+```
+
+### Inverse Search
+
+Add the following line to your SumatraPDF settings file (Menu -> Settings -> Advanced Options):
+
+```ini
+InverseSearchCmdLine = "C:\Users\{User}\AppData\Local\Programs\Microsoft VS Code\Code.exe" -g "%f":%l
+```
+
+> **Note**: Please make sure to replace `{User}` with your Windows username.
+
+You can execute the search by pressing `Alt+DoubleClick` in the PDF document.
+
+---
+
+## Evince
+
+The SyncTeX feature of [Evince](https://wiki.gnome.org/Apps/Evince) requires communication via D-Bus.
+In order to use it from the command line, install the [evince-synctex](https://github.com/latex-lsp/evince-synctex) script.
+Then add the following line to your `~/.latexmkrc` file:
+
+```perl
+$pdf_previewer = 'start evince-synctex %S "code -g %f:%l"';
+```
+
+### Forward Search
+
+Add the following lines to your editor config:
+
+```json
+{
+ "texlab.forwardSearch.executable": "evince-synctex",
+ "texlab.forwardSearch.args": ["-f", "%l", "%p", "\"code -g %f:%l\""]
+}
+```
+
+### Inverse Search
+
+The inverse search feature is already configured if you use `evince-synctex`.
+You can execute the search by pressing `Ctrl+Click` in the PDF document.
+
+---
+
+## Okular
+
+To use [Okular](https://okular.kde.org/) as previewer, add the following line to your `~/.latexmkrc` file:
+
+```perl
+$pdf_previewer = 'start okular';
+```
+
+### Forward Search
+
+Add the following lines to your editor config:
+
+```json
+{
+ "texlab.forwardSearch.executable": "okular",
+ "texlab.forwardSearch.args": ["--unique", "file:%p#src:%l%f"]
+}
+```
+
+### Inverse Search
+
+Change the editor of Okular (Settings -> Configure Okular... -> Editor) to "Custom Text Editor" and set the following command:
+
+```bash
+code -g "%f":%l
+```
+
+You can execute the search by pressing `Shift+Click` in the PDF document.
+
+---
+
+## Zathura
+
+To use [Zathura](https://pwmt.org/projects/zathura/) as previewer, add the following line to your `~/.latexmkrc` file:
+
+```perl
+$pdf_previewer = 'start zathura';
+```
+
+### Forward Search
+
+Add the following lines to your editor config:
+
+```json
+{
+ "texlab.forwardSearch.executable": "zathura",
+ "texlab.forwardSearch.args": ["--synctex-forward", "%l:1:%f", "%p"]
+}
+```
+
+### Inverse Search
+
+Add the following lines to your `~/.config/zathura/zathurarc` file:
+
+```bash
+set synctex true
+set synctex-editor-command "code -g %{input}:%{line}"
+```
+
+You can execute the search by pressing `Alt+Click` in the PDF document.
+
+---
+
+## qpdfview
+
+To use [qpdfview](https://launchpad.net/qpdfview) as previewer, add the following line to your `~/.latexmkrc` file:
+
+```perl
+$pdf_previewer = 'start qpdfview --unique %S';
+```
+
+### Forward Search
+
+Add the following lines to your editor config:
+
+```json
+{
+ "texlab.forwardSearch.executable": "qpdfview",
+ "texlab.forwardSearch.args": ["--unique", "%p#src:%f:%l:1"]
+}
+```
+
+### Inverse Search
+
+Change the source editor setting (Edit -> Settings... -> Behavior -> Source editor) to:
+
+```bash
+code -g "%1":%2
+```
+
+and select a mouse button modifier (Edit -> Settings... -> Behavior -> Modifiers -> Mouse button modifiers -> Open in Source Editor)
+of choice.
+You can execute the search by pressing `Modifier+Click` in the PDF document.
+
+---
+
+## Skim
+
+We recommend [Skim](https://skim-app.sourceforge.io/) on macOS since it is the only native viewer that supports SyncTeX.
+To use [Skim](https://skim-app.sourceforge.io/) as previewer, add the following line to your `~/.latexmkrc` file:
+
+```perl
+$pdf_previewer = 'open -a Skim';
+```
+
+If you want Skim to stay in the background after building,
+you can add the `-g` option to the `open` arguments.
+
+Additionally, enable the "Reload automatically" setting in the Skim preferences (Skim -> Preferences -> Sync -> Check for file changes).
+
+### Forward Search
+
+Add the following lines to your editor config:
+
+```json
+{
+ "texlab.forwardSearch.executable": "/Applications/Skim.app/Contents/SharedSupport/displayline",
+ "texlab.forwardSearch.args": ["%l", "%p", "%f"]
+}
+```
+
+If you want Skim to stay in the background after
+executing the forward search, you can add the `-g` option
+to `latex.forwardSearch.args`.
+
+### Inverse Search
+
+Select the Visual Studio Code preset in the Skim preferences (Skim -> Preferences -> Sync -> PDF-TeX Sync support).
+You can execute the search by pressing `Shift+⌘+Click` in the PDF document.