Table of Contents _________________ 1. lsp-mode client for Texlab. 2. How to Use? 3. Variables .. 1. `lsp-latex-texlab-executable' .. 2. `lsp-latex-texlab-executable-argument-list' .. 3. Others, provided by texlab server 4. Build .. 1. `lsp-latex-build' 5. Workspace commands .. 1. `lsp-latex-clean-auxiliary' .. 2. `lsp-latex-clean-artifacts' .. 3. `lsp-latex-change-environment' .. 4. `lsp-latex-find-environments' ..... 1. `lsp-latex-complete-environment' .. 5. `lsp-latex-show-dependency-graph' .. 6. `lsp-latex-cancel-build' 6. Commands with `lsp-latex-complete-environment' .. 1. `lsp-latex-goto-environment' .. 2. `lsp-latex-select-and-change-environment' 7. Forward/inverse search .. 1. Forward search .. 2. Inverse search .. 3. Examples ..... 1. SumatraPDF ..... 2. Evince ..... 3. Okular ..... 4. Zathura ..... 5. qpdfview ..... 6. Skim ..... 7. `pdf-tools' integration 8. License [https://img.shields.io/github/tag/ROCKTAKEY/lsp-latex.svg?style=flat-square] [https://img.shields.io/github/license/ROCKTAKEY/lsp-latex.svg?style=flat-square] [https://img.shields.io/github/actions/workflow/status/ROCKTAKEY/lsp-latex/CI.yml.svg?style=flat-square] [file:https://melpa.org/packages/lsp-latex-badge.svg] [https://img.shields.io/github/tag/ROCKTAKEY/lsp-latex.svg?style=flat-square] [https://img.shields.io/github/license/ROCKTAKEY/lsp-latex.svg?style=flat-square] [https://img.shields.io/github/actions/workflow/status/ROCKTAKEY/lsp-latex/CI.yml.svg?style=flat-square] [file:https://melpa.org/packages/lsp-latex-badge.svg] 1 lsp-mode client for Texlab. ============================= While `lsp-tex.el', included by [lsp-mode], provides minimal setting for [Texlab], `lsp-latex.el' provides full features of [Texlab] v5.19.0. [lsp-mode] [Texlab] 2 How to Use? ============= - First, you have to install Texlab. Please install this [here]. - Next, you should make `lsp-mode' available. See [lsp-mode]. - Now, you can use Language Server Protocol (LSP) on (la)tex-mode or yatex-mode just to evaluate this: ,---- | 1 (add-to-list 'load-path "/path/to/lsp-latex") | 2 (require 'lsp-latex) | 3 ;; "texlab" executable must be located at a directory contained in `exec-path'. | 4 ;; If you want to put "texlab" somewhere else, | 5 ;; you can specify the path to "texlab" as follows: | 6 ;; (setq lsp-latex-texlab-executable "/path/to/texlab") | 7 | 8 (with-eval-after-load "tex-mode" | 9 (add-hook 'tex-mode-hook 'lsp) | 10 (add-hook 'latex-mode-hook 'lsp)) | 11 | 12 ;; For YaTeX | 13 (with-eval-after-load "yatex" | 14 (add-hook 'yatex-mode-hook 'lsp)) | 15 | 16 ;; For bibtex | 17 (with-eval-after-load "bibtex" | 18 (add-hook 'bibtex-mode-hook 'lsp)) `---- [here] [lsp-mode] 3 Variables =========== 3.1 `lsp-latex-texlab-executable' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Where Texlab server executable located. 3.2 `lsp-latex-texlab-executable-argument-list' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Argument list passed to Texlab server. 3.3 Others, provided by texlab server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These variables are connected to Texlab configuration variables. See also [Texlab official wiki]. Custom variable in Emacs Configuration provided by Texlab ----------------------------------------------------------------------------------------------- lsp-latex-build-executable texlab.build.executable lsp-latex-build-args texlab.build.args lsp-latex-build-forward-search-after texlab.build.forwardSearchAfter lsp-latex-build-on-save texlab.build.onSave lsp-latex-build-use-file-list texlab.build.useFileList lsp-latex-build-aux-directory texlab.build.auxDirectory lsp-latex-build-log-directory texlab.build.logDirectory lsp-latex-build-pdf-directory texlab.build.pdfDirectory lsp-latex-forward-search-executable texlab.forwardSearch.executable lsp-latex-forward-search-args texlab.forwardSearch.args lsp-latex-chktex-additional-args texlab.chktex.additionalArgs lsp-latex-chktex-on-open-and-save texlab.chktex.onOpenAndSave lsp-latex-chktex-on-edit texlab.chktex.onEdit lsp-latex-diagnostics-delay texlab.diagnosticsDelay lsp-latex-diagnostics-allowed-patterns texlab.diagnostics.allowedPatterns lsp-latex-diagnostics-ignored-patterns texlab.diagnostics.ignoredPatterns lsp-latex-symbol-allowed-patterns texlab.symbol.allowedPatterns lsp-latex-symbol-ignored-patterns texlab.symbol.ignoredPatterns lsp-latex-bibtex-formatter-line-length texlab.formatterLineLength lsp-latex-bibtex-formatter texlab.bibtexFormatter lsp-latex-latex-formatter texlab.latexFormatter lsp-latex-latexindent-local texlab.latexindent.local lsp-latex-latexindent-modify-line-breaks texlab.latexindent.modifyLineBreaks lsp-latex-completion-matcher texlab.completion.matcher lsp-latex-inlay-hints-label-definitions texlab.inlayHints.labelDefinitions lsp-latex-inlay-hints-label-references texlab.inlayHints.labelReferences lsp-latex-experimental-math-environments texlab.experimental.mathEnvironments lsp-latex-experimental-enum-environments texlab.experimental.enumEnvironments lsp-latex-experimental-verbatim-environments texlab.experimental.verbatimEnvironments lsp-latex-experimental-citation-commands texlab.experimental.citationCommands lsp-latex-experimental-label-reference-commands texlab.experimental.labelReferenceCommands lsp-latex-experimental-label-definition-commands texlab.experimental.labelDefinitionCommands lsp-latex-experimental-label-reference-prefixes texlab.experimental.labelReferencePrefixes lsp-latex-experimental-label-definition-prefixes texlab.experimental.labelDefinitionPrefixes [Texlab official wiki] 4 Build ======= 4.1 `lsp-latex-build' ~~~~~~~~~~~~~~~~~~~~~ Request texlab to build `.tex' files. It use [`latexmk'] by default, so add `.latexmkrc' if you want to customize latex commands or options. You can change build command and option to other such as `make', by changing `lsp-latex-build-executable' and `lsp-latex-build-args'. This command build asynchronously by default, while it build synchronously with prefix argument(`C-u'). [`latexmk'] 5 Workspace commands ==================== These commands are connected to Texlab Workspace commands. See also [Texlab official wiki]. Custom variable in Emacs Configuration provided by Texlab ------------------------------------------------------------------- lsp-latex-clean-auxiliary texlab.cleanAuxiliary lsp-latex-clean-artifacts texlab.cleanArtifacts lsp-latex-change-environment texlab.changeEnvironment lsp-latex-find-environments texlab.findEnvironments lsp-latex-show-dependency-graph texlab.showDependencyGraph lsp-latex-cancel-build texlab.cancelBuild [Texlab official wiki] 5.1 `lsp-latex-clean-auxiliary' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command removes LaTeX auxiliary files. It will run `latexmk -c' in the project. 5.2 `lsp-latex-clean-artifacts' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command removes LaTeX auxiliary files and artifacts It will run `latexmk -C' in the project. 5.3 `lsp-latex-change-environment' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command replaces enviroment name to NEW-NAME in current position. This edits most-inner environment containing the current position. 5.4 `lsp-latex-find-environments' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This function get list of environments containing the current point. Each element of the list is `lsp-latex-environment-location' instance. See the docstring of `lsp-latex-environment-location'. 5.4.1 `lsp-latex-complete-environment' -------------------------------------- This function reads environment name from minibuffer and returns `lsp-latex-environment-location' instance. It takes three arguments, `BUFFER', `POINT', `PROMPT'. `PROMPT' is used as prompt for `consult--read', which is wrapper of `completing-read'. `BUFFER' and `POINT' specify basis to find environments. 5.5 `lsp-latex-show-dependency-graph' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Show dependency graph written by DOT format. [`graphviz-dot-mode'] is needed if you needs syntax highlights or a graphical image. [`graphviz-dot-mode'] 5.6 `lsp-latex-cancel-build' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command request Texlab to cancel the proceeding build. 6 Commands with `lsp-latex-complete-environment' ================================================ `lsp-latex-find-environments', which is interface for `texlab.FindEnvironments', does nothing but returns list of environments. So this package provide some additional commands to utilize it. 6.1 `lsp-latex-goto-environment' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Go to selected environment containing the current point. 6.2 `lsp-latex-select-and-change-environment' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Change name of selected environment to NEW-NAME. 7 Forward/inverse search ======================== Forward search and inverse search are available. See also [Texlab official wiki]. [Texlab official wiki] 7.1 Forward search ~~~~~~~~~~~~~~~~~~ You can move from Emacs to current position on pdf viewer by the function `lsp-latex-forward-search'. To use, you should set `lsp-latex-forward-search-executable' and `lsp-latex-forward-search-args' according to your pdf viewer. You can see [Texlab official wiki], but you should replace some VSCode words with Emacs words. `latex.forwardSearch.executable' should be replaced with `lsp-latex-forward-search-executable', and `latex.forwardSearch.args' with `lsp-latex-forward-search-args'. You should setq each variable instead of writing like json, and vector in json is replaced to list in Emacs Lisp. So the json: ,---- | { | "texlab.forwardSearch.executable": "FavoriteViewer", | "texlab.forwardSearch.args": [ "%p", "%f", "%l" ] | } `---- should be replaced with the Emacs Lisp code: ,---- | (setq lsp-latex-forward-search-executable "FavoriteViewer") | (setq lsp-latex-forward-search-args '("%p" "%f" "%l")) `---- In `lsp-latex-forward-search-args', the string "%f" is replaced with "The path of the current TeX file", "%p" with "The path of the current PDF file", "%l" with "The current line number", by Texlab (see [Forward search arg section in Texlab official wiki]). For example of SumatraPDF, write in init.el: ,---- | (setq lsp-latex-forward-search-executable "C:/Users/{User}/AppData/Local/SumatraPDF/SumatraPDF.exe") | (setq lsp-latex-forward-search-args '("-reuse-instance" "%p" "-forward-search" "%f" "%l")) `---- while VSCode config with json (see [Texlab official wiki]) is: ,---- | { | "texlab.forwardSearch.executable": "C:/Users/{User}/AppData/Local/SumatraPDF/SumatraPDF.exe", | "texlab.forwardSearch.args": [ | "-reuse-instance", | "%p", | "-forward-search", | "%f", | "%l" | ] | } `---- Then, you can jump to the current position on pdf viewer by command `lsp-latex-forward-search'. [Texlab official wiki] [Forward search arg section in Texlab official wiki] [Texlab official wiki] 7.2 Inverse search ~~~~~~~~~~~~~~~~~~ You can go to the current position on Emacs from pdf viewer. Whatever pdf viewer you use, you should start Emacs server by writing in init.el: ,---- | (server-start) `---- Then, you can jump to line {{LINE-NUMBER}} in file named {{FILENAME}} with the command: ,---- | 1 emacsclient +{{LINE-NUMBER}} {{FILENAME}} `---- {{LINE-NUMBER}} and {{FILENAME}} should be replaced with line number and filename you want to jump to. Each pdf viewer can provide some syntax to replace. For example of SmatraPDF (see [Texlab official wiki]), "Add the following line to your SumatraPDF settings file (Menu -> Settings -> Advanced Options):" ,---- | 1 InverseSearchCmdLine = C:\path\to\emacsclient.exe +%l %f `---- Then, "You can execute the search by pressing Alt+DoubleClick in the PDF document". [Texlab official wiki] 7.3 Examples ~~~~~~~~~~~~ These examples are according to [Texlab official wiki]. Especially, quoted or double-quoted sentences are citation from [Texlab official wiki]. [Texlab official wiki] 7.3.1 SumatraPDF ---------------- We highly recommend SumatraPDF on Windows because Adobe Reader locks the opened PDF file and will therefore prevent further builds. * 7.3.1.1 Forward search Write to init.el: ,---- | (setq lsp-latex-forward-search-executable "C:/Users/{User}/AppData/Local/SumatraPDF/SumatraPDF.exe") | (setq lsp-latex-forward-search-args '("-reuse-instance" "%p" "-forward-search" "%f" "%l")) `---- * 7.3.1.2 Inverse Search Add the following line to your [SumatraPDF] settings file (Menu -> Settings -> Advanced Options): ,---- | 1 InverseSearchCmdLine = C:\path\to\emacsclient.exe +%l "%f" `---- You can execute the search by pressing `Alt+DoubleClick' in the PDF document. [SumatraPDF] 7.3.2 Evince ------------ The SyncTeX feature of [Evince] requires communication via D-Bus. In order to use it from the command line, install the [evince-synctex] script. [Evince] [evince-synctex] * 7.3.2.1 Forward search Write to init.el: ,---- | (setq lsp-latex-forward-search-executable "evince-synctex") | (setq lsp-latex-forward-search-args '("-f" "%l" "%p" "\"emacsclient +%l %f\"")) `---- * 7.3.2.2 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. 7.3.3 Okular ------------ * 7.3.3.1 Forward search Write to init.el: ,---- | (setq lsp-latex-forward-search-executable "okular") | (setq lsp-latex-forward-search-args '("--unique" "file:%p#src:%l%f")) `---- * 7.3.3.2 Inverse search Change the editor of Okular (Settings -> Configure Okular... -> Editor) to "Custom Text Editor" and set the following command: ,---- | emacsclient +%l "%f" `---- You can execute the search by pressing `Shift+Click' in the PDF document. 7.3.4 Zathura ------------- * 7.3.4.1 Forward search Write to init.el: ,---- | (setq lsp-latex-forward-search-executable "zathura") | (setq lsp-latex-forward-search-args '("--synctex-forward" "%l:1:%f" "%p")) `---- * 7.3.4.2 Inverse search Add the following lines to your `~/.config/zathura/zathurarc' file: ,---- | 1 set synctex true | 2 set synctex-editor-command "emacsclient +%{line} %{input}" `---- You can execute the search by pressing `Alt+Click' in the PDF document. 7.3.5 qpdfview -------------- * 7.3.5.1 Forward search Write to init.el: ,---- | (setq lsp-latex-forward-search-executable "qpdfview") | (setq lsp-latex-forward-search-args '("--unique" "%p#src:%f:%l:1")) `---- * 7.3.5.2 Inverse search Change the source editor setting (Edit -> Settings... -> Behavior -> Source editor) to: ,---- | 1 emacsclient +%2 "%1" `---- 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. 7.3.6 Skim ---------- We recommend [Skim] on macOS since it is the only native viewer that supports SyncTeX. Additionally, enable the "Reload automatically" setting in the Skim preferences (Skim -> Preferences -> Sync -> Check for file changes). [Skim] * 7.3.6.1 Forward search Write to init.el: ,---- | (setq lsp-latex-forward-search-executable "/Applications/Skim.app/Contents/SharedSupport/displayline") | (setq lsp-latex-forward-search-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" `lsp-latex-forward-search-args'. * 7.3.6.2 Inverse search Select Emacs 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." 7.3.7 `pdf-tools' integration ----------------------------- If you want to use forward search with `pdf-tools', follow the setting: ,---- | ;; Start Emacs server | (server-start) | ;; Turn on SyncTeX on the build. | ;; If you use `lsp-latex-build', it is on by default. | ;; If not (for example, YaTeX or LaTeX-mode building system), | ;; put to init.el like this: | (setq tex-command "platex --synctex=1") | | ;; Setting for pdf-tools | (setq lsp-latex-forward-search-executable "emacsclient") | (setq lsp-latex-forward-search-args | '("--eval" | "(lsp-latex-forward-search-with-pdf-tools \"%f\" \"%p\" \"%l\")")) `---- Inverse research is not provided by Texlab, so please use `pdf-sync-backward-search-mouse'. 8 License ========= This package is licensed by GPLv3. See [LICENSE]. [LICENSE]