Link to GitHub wiki in README

2025-07-07 21:25:32 +00:00 · 2022-10-21 21:07:43 +02:00 · 2022-10-21 21:07:43 +02:00 · d03e350679
commit d03e350679
parent e353156ccd
8 changed files with 5 additions and 628 deletions
--- a/README.md
+++ b/README.md
@ -1,6 +1,7 @@
 [![CI](https://github.com/latex-lsp/texlab/workflows/CI/badge.svg)](https://github.com/latex-lsp/texlab/actions)
 [![Coverage](https://codecov.io/gh/latex-lsp/texlab/branch/master/graph/badge.svg)](https://codecov.io/gh/latex-lsp/texlab)
 ![Rust](https://img.shields.io/badge/rustc-1.60%2B-blue)
 [![Wiki](https://img.shields.io/badge/docs-Wiki-success)](https://github.com/latex-lsp/texlab/wiki)
 [![GitHub release](https://img.shields.io/github/release/latex-lsp/texlab?label=github)](https://github.com/latex-lsp/texlab/releases)
 [![crates.io](https://img.shields.io/crates/v/texlab)](https://crates.io/crates/texlab)
@ -12,7 +13,7 @@ A cross-platform implementation of the [Language Server Protocol](https://micros
 providing rich cross-editing support for the [LaTeX](https://www.latex-project.org/) typesetting system.
 The server may be used with [any editor that implements the Language Server Protocol](https://microsoft.github.io/language-server-protocol/implementors/tools/).
-![Demo](docs/demo.gif)
+![Demo](images/demo.gif)
 ## Getting Started
@ -59,7 +60,9 @@ There is no need for magic comments like `%!TEX root`
 and TexLab should figure out the dependencies of a file on its own.
 Note that you may need to set the `texlab.rootDirectory` option for some multi-folder projects.
-TexLab features a variety of [options](docs/options.md) which can be used to configure features like building or [forward search](docs/previewing.md).
+TexLab features a variety of options which can be used to configure features like building or forward search.
 See the [Wiki](https://github.com/latex-lsp/texlab/wiki) for more information.
 ## Development
@ -75,8 +78,6 @@ cargo test
 in the project folder.
 For a list of custom messages, please see [here](docs/custom_messages.md).
 ## Contributing
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
--- a/docs/custom_commands.md
+++ b/docs/custom_commands.md
@ -1,21 +0,0 @@
 # Custom Commands
 The server provides the following commands through the `workspace/executeCommand` request:
 ## texlab.cleanAuxiliary
 Removes the auxiliary files produced by compiling the specified LaTeX document.
 At the moment, this command simply calls `latexmk -c` with the currently configured output directory.
 Parameters:
 - `document`: `TextDocumentIdentifier` (_Required_)
 ## texlab.cleanArtifacts
 Removes the auxiliary files and the artifacts produced by compiling the specified LaTeX document.
 At the moment, this command simply calls `latexmk -C` with the currently configured output directory.
 Parameters:
 - `document`: `TextDocumentIdentifier` (_Required_)
--- a/docs/custom_messages.md
+++ b/docs/custom_messages.md
@ -1,102 +0,0 @@
 # Custom Messages
 We extend the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/specification)
 with custom messages to provide better LaTeX integration.
 These messages are _optional_ and it is up to the client to support them.
 ## Build Request
 The build request is sent from the client to the server to build a given LaTeX document.
 _Request_:
 - method: 'textDocument/build'
 - params: `BuildTextDocumentParams` defined as follows:
 ```typescript
 interface BuildTextDocumentParams {
  /**
   * The text document to build.
   */
  textDocument: TextDocumentIdentifier;
 }
 ```
 _Response_:
 - result: `BuildResult` defined as follows:
 ```typescript
 interface BuildResult {
  /**
   * The status of the build process.
   */
  status: BuildStatus;
 }
 enum BuildStatus {
  /**
   * The build process terminated without any errors.
   */
  Success = 0,
  /**
   * The build process terminated with errors.
   */
  Error = 1,
  /**
   * The build process failed to start or crashed.
   */
  Failure = 2,
  /**
   * The build process was cancelled.
   */
  Cancelled = 3,
 }
 ```
 ## Forward Search Request
 The forward search request is sent from the client to the server when the user requests a forward search via SyncTeX.
 _Request_:
 - method: 'textDocument/forwardSearch'
 - params: [`TextDocumentPositionParams`](https://microsoft.github.io/language-server-protocol/specification#textdocumentpositionparams)
 _Response_:
 - result: `ForwardSearchResult` defined as follows:
 ```typescript
 interface ForwardSearchResult {
  /**
   * The status of the previewer process.
   */
  status: ForwardSearchStatus;
 }
 enum ForwardSearchStatus {
  /**
   * The previewer process executed the command without any errors.
   */
  Success = 0,
  /**
   * The previewer process executed the command with errors.
   */
  Error = 1,
  /**
   * The previewer process failed to start or crashed.
   */
  Failure = 2,
  /**
   * The previewer command is not configured.
   */
  Unconfigured = 3,
 }
 ```
--- a/docs/lsp_kinds.md
+++ b/docs/lsp_kinds.md
@ -1,31 +0,0 @@
 The following table describes the mapping of LaTeX and BibTeX structures
 to their `CompletionItemKind` and `SymbolKind`.
 | LaTeX / BibTeX structure  | CompletionItemKind   | SymbolKind           |
 | ------------------------- | -------------------- | -------------------- |
 | Command                   | `Function` (3)       | `Function` (12)      |
 | Command Argument          | `Value` (12)         | `Number` (16)        |
 | Snippet                   | `Snippet` (15)       |                      |
 | Environment               | `Enum` (13)          | `Enum` (10)          |
 | Section                   | `Module` (9)         | `Module` (2)         |
 | Float                     | `Method` (2)         | `Method` (6)         |
 | Theorem                   | `Variable` (6)       | `Variable` (13)      |
 | Equation                  | `Constant` (21)      | `Constant` (14)      |
 | Enumeration Item          | `EnumMember` (20)    | `EnumMember` (22)    |
 | Label                     | `Constructor` (4)    | `Constructor` (9)    |
 | Folder                    | `Folder` (19)        | `Namespace` (3)      |
 | File                      | `File` (17)          | `File` (1)           |
 | PGF Library               | `Property` (10)      | `Property` (7)       |
 | TikZ Library              | `Property` (10)      | `Property` (7)       |
 | Color                     | `Color` (16)         |                      |
 | Color Model               | `Color` (16)         |                      |
 | Package                   | `Class` (7)          | `Class` (5)          |
 | Class                     | `Class` (7)          | `Class` (5)          |
 | BibTeX Entry (Misc)       | `Interface` (8)      | `Interface` (11)     |
 | BibTeX Entry (Article)    | `Event` (23)         | `Event` (24)         |
 | BibTeX Entry (Book)       | `Struct` (22)        | `Struct` (23)        |
 | BibTeX Entry (Collection) | `TypeParameter` (25) | `TypeParameter` (26) |
 | BibTeX Entry (Part)       | `Operator` (24)      | `Operator` (25)      |
 | BibTeX Entry (Thesis)     | `Unit` (11)          | `Object` (19)        |
 | BibTeX String             | `Text` (1)           | `String` (15)        |
 | BibTeX Field              | `Field` (5)          | `Field` (8)          |
--- a/docs/options.md
+++ b/docs/options.md
@ -1,225 +0,0 @@
 # Configuration
 This document describes the configuration settings
 that the server will query from the LSP client / extension.
 ---
 ## texlab.rootDirectory
 Defines the directory from which the source files get compiled.
 You may need to set this property for multi-folder projects
 where TexLab fails to detect the root document.
 **Type:** `string | null`
 **Default value**: `null`
 ---
 ## texlab.build.executable
 Defines the executable of the LaTeX build tool.
 **Type:** `string`
 **Default value:** `latexmk`
 ---
 ## texlab.build.args
 Defines additional arguments that are passed to the configured LaTeX build tool.
 Note that flags and their arguments need to be separate
 elements in this array.
 To pass the arguments `-foo bar` to a build tool,
 `latex.build.args` needs to be `["-foo", "bar"]`.
 The placeholder `%f` will be replaced by the server.
 **Placeholders:**
 - `%f`: The path of the TeX file to compile.
 **Type:** `string[]`
 **Default value:** `["-pdf", "-interaction=nonstopmode", "-synctex=1", "%f"]`
 ---
 ## texlab.build.forwardSearchAfter
 Set this property to `true` if you want to execute a forward search after a build.
 **Type:** `boolean`
 **Default value:** `false`
 ---
 ## texlab.build.onSave
 Set this property to `true` if you want to compile the project after saving a file.
 **Type:** `boolean`
 **Default value:** `false`
 ---
 ## texlab.auxDirectory
 Defines the directory containing the build artifacts.
 Note that you need to set the output directory in `latex.build.args` too,
 if you want to change the build directory.
 In this case, use the `-outdir` flag for `latexmk`.
 **Type:** `string`
 **Default value:** `.` (the same directory as the TeX file)
 ---
 ## texlab.forwardSearch.executable
 Defines the executable of the PDF previewer.
 The previewer needs to support [SyncTeX](http://www.tug.org/TUGboat/tb29-3/tb93laurens.pdf).
 **Type:** `string | null`
 **Default value:** `null`
 ---
 ## texlab.forwardSearch.args
 Defines additional arguments that are passed to the configured previewer to perform the forward search.
 The placeholders `%f, %p, %l` will be replaced by the server.
 **Placeholders:**
 - `%f`: The path of the current TeX file.
 - `%p`: The path of the current PDF file.
 - `%l`: The current line number.
 **Type:** `string[] | null`
 **Default value:** `null`
 ---
 ## texlab.chktex.onOpenAndSave
 Lint using [chktex](https://www.nongnu.org/chktex/) after opening and saving a file.
 **Type:** `boolean`
 **Default value:** `false`
 ---
 ## texlab.chktex.onEdit
 Lint using [chktex](https://www.nongnu.org/chktex/) after editing a file.
 **Type:** `boolean`
 **Default value:** `false`
 ---
 ## texlab.diagnosticsDelay
 Delay in milliseconds before reporting diagnostics.
 **Type:** `integer`
 **Default value:** `300`
 ---
 ## texlab.diagnostics.allowedPatterns
 A list of regular expressions used to filter the list of reported diagnostics.
 If specified, only diagnostics that match _at least one_ of the specified patterns
 are sent to the client.
 See also [`texlab.diagnostics.ignoredPatterns`](#texlabdiagnosticsignoredpatterns).
 _Hint_:
 If both `allowedPatterns` and `ignoredPatterns` are set,
 then allowed patterns are applied first. Afterwards, the results are filtered with the ignored patterns.
 **Type:** `RegExp[]`
 **Default value:** `[]`
 ---
 ## texlab.diagnostics.ignoredPatterns
 A list of regular expressions used to filter the list of reported diagnostics.
 If specified, only diagnostics that match _none_ of the specified patterns
 are sent to the client.
 See also [`texlab.diagnostics.allowedPatterns`](#texlabdiagnosticsallowedpatterns).
 **Type:** `RegExp[]`
 **Default value:** `[]`
 ---
 ## texlab.formatterLineLength
 Defines the maximum amount of characters per line (0 = disable) when formatting BibTeX files.
 **Type:** `integer`
 **Default value:** `80`
 ---
 ## texlab.bibtexFormatter
 Defines the formatter to use for BibTeX formatting.
 Possible values are either `texlab` or `latexindent`.
 **Type:** `string`
 **Default value:** `texlab`
 ---
 ## texlab.latexFormatter
 Defines the formatter to use for LaTeX formatting.
 Possible values are either `texlab` or `latexindent`.
 Note that `texlab` is not implemented yet.
 **Type:** `string`
 **Default value:** `latexindent`
 ---
 ## texlab.latexindent.local
 Defines the path of a file containing the `latexindent` configuration.
 This corresponds to the `--local=file.yaml` flag of `latexindent`.
 By default the configuration inside the project root directory is used.
 **Type:** `string`
 **Default value:** `null`
 ---
 ## texlab.latexindent.modifyLineBreaks
 Modifies linebreaks before, during, and at the end of code blocks
 when formatting with `latexindent`.
 This corresponds to the `--modifylinebreaks` flag of `latexindent`.
 **Type:** `boolean`
 **Default value:** `false`
--- a/docs/previewing.md
+++ b/docs/previewing.md
@ -1,197 +0,0 @@
 # Previewing
 `texlab` supports compiling LaTeX using a custom request (`textDocument/build`)
 and by building a document after saving if configured to do so.
 To enable building on save, simply set `texlab.build.onSave` to true.
 Previewing can be configured in a variety of ways:
 1. If you are using `latexmk`, you can create a `.latexmkrc` file and call your viewer accordingly.
   Afterwards, you can add the `-pv` flag to your `texlab.build.args`.
 2. If you want the PDF viewer to stay synchronized with the cursor position in your editor,
   you can instruct `texlab` to execute a forward search after every build (`texlab.build.forwardSearchAfter`).
   To do so, you need to enable [SyncTeX](http://www.tug.org/TUGboat/tb29-3/tb93laurens.pdf)
   and update the `texlab.forwardSearch` configuration.
   If you want to use this feature, we do _not_ recommend the `-pvc` flag
   because `texlab` does not get notified by `latexmk` when a document gets built.
   Instead, you can use `texlab.build.onSave`.
 In the following sections, we will give forward search configurations for several popular viewers.
 If your viewer is not listed here, you can send us a pull request or create an issue.
 The inverse search configuration depends on the editor.
 In this section, we will give instructions for [Visual Studio Code](https://code.visualstudio.com/).
 However, these settings can easily be adapted to other editors.
 Some plugins can help with setting up inverse search:
 - `Neovim`: [`f3fora/nvim-texlabconfig`](https://github.com/f3fora/nvim-texlabconfig)
 - `Emacs`: [`ROCKTAKEY/lsp-latex`](https://github.com/ROCKTAKEY/lsp-latex#inverse-search)
 ---
 ## 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.
 ### Forward Search
 Add the following lines to your editor config:
 ```json
 {
  "texlab.forwardSearch.executable": "C:/Users/{User}/AppData/Local/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.
 ### 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
 ### 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 editor command.
 For Visual Studio Code, you can use the following command:
 ```bash
 code -g "%f":%l
 ```
 You can execute the search by pressing `Shift+Click` in the PDF document.
 ---
 ## 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 `Ctrl+Click` in the PDF document.
 ---
 ## qpdfview
 ### 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.
 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 `texlab.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.
 ---
--- a/docs/tectonic.md
+++ b/docs/tectonic.md
@ -1,48 +0,0 @@
 # Usage with `tectonic`
 [`tectonic`](https://tectonic-typesetting.github.io/) is a modernized, alternative TeX engine.
 Most features of `texlab` work out of the box when using `tectonic`.
 To compile documents through `texlab`, you need to change the configuration.
 See `tectonic --help` for more information about the flags.
 ---
 **Hint:**
 Please make sure to set `texlab.auxDirectory` if you change the build directory with the `--outdir` argument.
 Also, `--keep-intermediates` is recommended because they allow `texlab`
 to find out the section numbers and show them in the completion.
 Without the `--keep-logs` flag, `texlab` won't be able to report compilation warnings.
 ---
 ## V2 CLI
 ```json
 {
  "texlab.build.executable": "tectonic",
  "texlab.build.args": [
    "-X",
    "compile",
    "%f",
    "--synctex",
    "--keep-logs",
    "--keep-intermediates"
  ]
 }
 ```
 ## V1 CLI
 ```json
 {
  "texlab.build.executable": "tectonic",
  "texlab.build.args": [
    "%f",
    "--synctex",
    "--keep-logs",
    "--keep-intermediates"
  ]
 }
 ```
--- a/images/demo.gif
+++ b/images/demo.gif