vimtex.txt

*vimtex.txt*    A modern Vim/neovim filetype and syntax plugin for LaTeX files.
*VimTeX* *Vimtex* *vimtex*

Author:  Karl Yngve Lervåg <karl.yngve@gmail.com>
License: MIT license {{{

  Copyright (c) 2021 Karl Yngve Lervåg

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to
  deal in the Software without restriction, including without limitation the
  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  sell copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.

}}}

==============================================================================
CONTENTS                                                      *vimtex-contents*

  Introduction                                  |vimtex-introduction|
    Comment on internal tex plugin              |vimtex-comment-internal|
    Feature overview                            |vimtex-features|
    Requirements                                |vimtex-requirements|
    Features provided by other plugins          |vimtex-non-features|
    Support for multi-file projects             |vimtex-multi-file|
    Support for TeX specifiers                  |vimtex-tex-directives|
    Package detection                           |vimtex-package-detection|
  Usage                                         |vimtex-usage|
    Default mappings                            |vimtex-default-mappings|
    Options                                     |vimtex-options|
    Commands                                    |vimtex-commands|
    Map definitions                             |vimtex-mappings|
    Insert mode mappings                        |vimtex-imaps|
    Events                                      |vimtex-events|
  Completion                                    |vimtex-completion|
    Complete citations                          |vimtex-complete-cites|
    Complete labels                             |vimtex-complete-labels|
    Complete commands                           |vimtex-complete-commands|
    Complete environments                       |vimtex-complete-environments|
    Complete file names                         |vimtex-complete-filenames|
    Complete glossary entries                   |vimtex-complete-glossary|
    Complete packages                           |vimtex-complete-packages|
    Complete documentclasses                    |vimtex-complete-classes|
    Complete bibliographystyles                 |vimtex-complete-bibstyle|
    Autocomplete                                |vimtex-complete-auto|
      coc.nvim                                  |vimtex-complete-coc.nvim|
      deoplete                                  |vimtex-complete-deoplete|
      Neocomplete                               |vimtex-complete-neocomplete|
      ncm2                                      |vimtex-complete-ncm2|
      nvim-completion-manager                   |vimtex-complete-ncm|
      YouCompleteMe                             |vimtex-complete-youcompleteme|
      VimCompletesMe                            |vimtex-complete-vcm|
  Folding                                       |vimtex-folding|
  Indentation                                   |vimtex-indent|
  Syntax highlighting                           |vimtex-syntax|
    Syntax core specification                   |vimtex-syntax-core|
    Syntax package specification                |vimtex-syntax-packages|
    Syntax conceal                              |vimtex-syntax-conceal|
    Syntax group reference                      |vimtex-syntax-reference|
  Navigation                                    |vimtex-navigation|
    Include expression (|gf| command)           |vimtex-includeexpr|
    Table of contents                           |vimtex-toc|
      Custom mappings                           |vimtex-toc-custom-maps|
    Denite/Unite source                         |vimtex-denite| / |vimtex-unite|
    fzf.vim integration                         |vimtex-fzf|
  Compilation                                   |vimtex-compiler|
    Latexmk                                     |vimtex-latexmk|
    Latexrun                                    |vimtex-latexrun|
    Tectonic                                    |vimtex-tectonic|
    Arara                                       |vimtex-arara|
    Generic                                     |vimtex-compiler-generic|
  Syntax Checking (Linting)                     |vimtex-lint|
  Grammar Checking                              |vimtex-grammar|
    textidote                                   |vimtex-grammar-textidote|
    vlty                                        |vimtex-grammar-vlty|
  View                                          |vimtex-view|
    Synctex                                     |vimtex-synctex|
    Forward search                              |vimtex-synctex-forward-search|
    Backward search                             |vimtex-synctex-backward-search|
  LaTeX Documentation                           |vimtex-latexdoc|
  Context menu                                  |vimtex-context-menu|
    Citation context                            |vimtex-context-citation|
  Code structure                                |vimtex-code|
    API                                         |vimtex-code-api|
  FAQ                                           |vimtex-faq|
  Troubleshooting                               |vimtex-troubleshooting|
  Credits                                       |vimtex-credits|
  Changelog                                     |vimtex-changelog|

==============================================================================
INTRODUCTION                                              *vimtex-introduction*

VimTeX provides convenient functionality for editing LaTeX documents.  The
main goal of VimTeX is to be simple, functional, and to be easy to customize
and evolve.

The documentation is understandably too long for a full read through. It is
recommended that new users read or skim the entire introduction, as it should
give a clear idea of what VimTeX is and is not. The remaining part of the
documentation should then be considered a reference for the various parts of
the plugin.

------------------------------------------------------------------------------
COMMENT ON INTERNAL TEX PLUGIN                        *vimtex-comment-internal*

Vim ships with pretty decent LaTeX support out of the box. In particular, it
provides syntax highlighting (|ft-tex-syntax|), indentation (see the source
file $VIMRUNTIME/indent/tex.vim for the documentation), and some sensible
options (|ft-tex-plugin|).

                                                            *vimtex-tex-flavor*
When VimTeX is active, it will override the internal TeX plugin for the
filetype `tex` (|ft-tex-plugin|), both for syntax highlighting and for
filetype specific features. To prevent the unexpected behaviour where `.tex`
files by default will be recognized as the filetype `plaintex`
(|ft-plaintex-syntax|) for e.g. empty documents, VimTeX overrides the filetype
detection for `.tex`. The user may prevent this overriding by specifying the
|g:tex_flavor| option something different than `'latex'`.

-----------------------------------------------------------------------------
FEATURE OVERVIEW                                              *vimtex-features*

- Document compilation with `latexmk`, `latexrun`, `tectonic` or `arara`
- LaTeX log parsing for quickfix entries using
  - internal method
  - `pplatex`
- Compilation of selected part of document
- Support for several PDF viewers with forward search
  - `MuPDF`
  - `Zathura`
  - `Okular`
  - `qpdfview`
  - `SumatraPDF`
  - Other viewers are supported through a general interface
- Completion of
  - citations
  - labels
  - commands
  - file names for figures, input/include, includepdf, includestandalone
  - glossary entries
  - package and documentclass names based on available `.sty` and `.cls` files
- Document navigation through
  - table of content
  - proper settings for |'include'|, |'includeexpr'|, |'suffixesadd'| and
    |'define'|, which among other things
    - allow |include-search| and |definition-search|
    - give enhanced |gf| command
- Easy access to (online) documentation of packages
- Word count (through `texcount`)
- Motions
  - Move between section boundaries with `[[`, `[]`, `][`, and `]]`
  - Move between environment boundaries with `[m`, `[M`, `]m`, and `]M`
  - Move between math environment boundaries with `[n`, `[N`, `]n`, and `]N`
  - Move between frame environment boundaries with `[r`, `[R`, `]r`, and `]R`
  - Move between comment boundaries with `[*` and `]*`
  - Move between matching delimiters with `%`
- Text objects
  - `ic` `ac` Commands
  - `id` `ad` Delimiters
  - `ie` `ae` LaTeX environments
  - `i$` `a$` Inline math structures
  - `iP` `aP` Sections
  - `im` `am` Items
- Other mappings
  - Delete the surrounding command, environment or delimiter with
    `dsc`/`dse`/`ds$`/`dsd`
  - Change the surrounding command, environment or delimiter with
    `csc`/`cse`/`cs$`/`csd`
  - Toggle starred command or environment with `tsc`/`tse`
  - Toggle between e.g. `()` and `\left(\right)` with `tsd`/`tsD`
  - Toggle (inline) fractions with `tsf`
  - Close the current environment/delimiter in insert mode with `]]`
  - Insert new command with `<F7>`
  - Convenient insert mode mappings for faster typing of e.g. maths
  - Context menu on citations (e.g. `\cite{...}`) mapped to `<cr>`
- Folding
- Indentation
- Syntax highlighting
  - A consistent core syntax specification
  - General syntax highlighting for several popular LaTeX packages
  - Nested syntax highlighting for several popular LaTeX packages
  - Highlight matching delimiters
- Support for multi-file project packages
  - `import`
  - `subfiles`

------------------------------------------------------------------------------
REQUIREMENTS                                              *vimtex-requirements*

The following is a list of specific requirements for running VimTeX and some
of its key features.  One may also be interested in reading |vimtex-faq-neovim|
and |vimtex-faq-windows|.

Vim version~
                                                         *vimtex_version_check*
  VimTeX requires Vim version 8.0.1453 or neovim version 0.4.3.  It will not
  load for older versions, unless one adds >

    let g:vimtex_version_check = 0
<
  to one's `vimrc` file.  This might work, but issues due to older versions
  than the mentioned here will be ignored.

Vim configuration~

  Some of the VimTeX scripts contain UTF-8 characters, and as such, it is
  necessary to have the 'encoding' option set to utf8. This is not necessary
  in neovim, only in Vim. Add the following to your vimrc file: >

    set encoding=utf8

Compiler backend~

  VimTeX uses `latexmk`, `latexrun`, `tectonic` or `arara` to compile the LaTeX document.

    `latexmk`: http://users.phys.psu.edu/~collins/software/latexmk-jcc
    "a perl script for running LaTeX the correct number of times to resolve
  cross references, etc; it also runs auxiliary programs (bibtex, makeindex if
  necessary, and dvips and/or a previewer as requested).  It has a number of
  other useful capabilities, for example to start a previewer and then run
  latex whenever the source files are updated, so that the previewer gives an
  up-to-date view of the document. The script runs on both UNIX and MS-WINDOWS
  (XP, etc)." [Copied from the latexmk page.]  (|vimtex-latexmk|)

    `latexrun`: https://github.com/aclements/latexrun
    Similar to `latexmk` in that it runs the desired LaTeX engine an
  appropriate number of times, including `bibtex`/`biber`. However, it differs
  in philosophy in that it only does the build part. It does not support
  continuous builds, nor automatic starting of the viewer. However, it does
  parse the output log in order to provide a more concise list of relevant
  warnings and error messages (this has currently not been adapted to VimTeX,
  as of yet). (|vimtex-latexrun|)

    `tectonic`: https://tectonic-typesetting.github.io/
    `tectonic` is a complete, self-contained TeX/LaTeX engine, powered by XeTeX
  and TeXLive. It doesn't support continuous build like `latexmk` but it
  presents other worth mentioning features such as automatic support file
  downloading along with reproduceable builds and full Unicode and OpenType
  fonts support thanks to the power of XeTeX. (|vimtex-tectonic|)

    `arara`: https://github.com/cereda/arara
    `arara` is a TeX automation tool similar to the above mentioned tools,
  but where the compilation behaviour is typically defined in the preamble
  of the document. (|vimtex-arara|)

Clientserver~
                                                          *vimtex-clientserver*
  |+clientserver| is necessary for backward search from PDF viewer to Vim.

  A server will be started automatically if Vim is running on Windows, or if
  running in a GUI.  If you use Vim under a terminal in Linux or macOS,
  a server will not be started by default.  Since Vim version 8.0.475, one can
  use |remote_startserver()| to start a server from your `vimrc` file. The
  following will ensure Vim starts with a server, if it is possible from
  vimscript: >

    if empty(v:servername) && exists('*remote_startserver')
      call remote_startserver('VIM')
    endif
<
  Alternatively, Vim can be started with the command line option
  `--servername`, e.g. `vim --servername VIM` .  The simplest way to ensure
  this is to add an alias to your `.bashrc` (or similar), that is, add: >

    alias vim='vim --servername VIM'
<
  For other methods of ensuring that Vim is started with a servername, see:
  https://vim.fandom.com/wiki/Enable_servername_capability_in_vim/xterm

  To test whether a server was successfully started, |serverlist()| can be
  used. E.g. `:echo serverlist()`

  Note: For |+clientserver| on neovim, see |vimtex-faq-neovim|.

------------------------------------------------------------------------------
FEATURES PROVIDED BY OTHER PLUGINS                        *vimtex-non-features*

The following is a list of features that one might think should be provided by
VimTeX, but that are instead better provided by other plugins.

* Linting and syntax checking                      |vimtex-nf-linting|
* Snippets/Templates                               |vimtex-nf-snippets|
* Tag navigation                                   |vimtex-nf-tag-nav|
* Manipulate surrounding cmds/delims/envs          |vimtex-nf-surround|
* Enhanced matching and higlighting of delimiters  |vimtex-nf-enhanced-matchparen|
* Formatting                                       |vimtex-nf-formatting|
* Filetype plugin for bib files                    |vimtex-nf-ftplugin-bib|
* Language server / texlab                         |vimtex-nf-lsp|

Linting and syntax checking~
                                                            *vimtex-nf-linting*
  VimTeX has some support for linting through the |:compiler| command, see
  |vimtex-lint|. There exists several more dedicated, automatic linting
  plugins. The following plugins have support for (La)TeX syntax checking
  through `lacheck` [0], `chktex` [1], and `proselint` [2].

    `ale`         https://github.com/dense-analysis/ale
    `neomake`     https://github.com/neomake/neomake
    `syntastic`   https://github.com/vim-syntastic/syntastic

  `neomake` also supports `rubberinfo` [3]. One may also be interested in
  `blacktex` [4], which may be used to clean up/fix LaTeX code.

  [0]: https://www.ctan.org/pkg/lacheck
  [1]: http://www.nongnu.org/chktex/
  [2]: http://proselint.com/
  [3]: https://www.systutorials.com/docs/linux/man/1-rubber-info/
  [4]: https://github.com/nschloe/blacktex

Snippets/Templates~
                                                           *vimtex-nf-snippets*
  Snippets and/or templates are provided by for instance `neosnippet` and
  `UltiSnips`. See |vimtex-neosnippet| and |vimtex-UltiSnips| for more info.

Tag navigation~
                                                            *vimtex-nf-tag-nav*
  One may navigate by tags with the |CTRL-]| mapping, e.g. from
  `\eqref{eq:example}` to the corresponding `\label{eq:example}`. However,
  this requires that a tag file has been generated with |ctags|. I recommend
  that one uses the maintained version of ctags [0]. In addition,
  I recommend that one uses a plugin that automatically generates the tag
  files as necessary, e.g. |gutentags| [1].

  See |vimtex-faq-tags| and |vimtex-faq-tags-bibtex| for concrete examples.

  [0]: https://ctags.io/
  [1]: https://github.com/ludovicchabant/vim-gutentags

Manipulate surrounding commands/delimiters/environments~
                                                           *vimtex-nf-surround*
  VimTeX provides mappings that change, delete and toggle commands,
  delimiters and environments (see the `ds`, `cs` and `ts` family of
  mappings listed under |vimtex-default-mappings|).  These mappings are
  inspired by the great `surround.vim` [0] (|surround.txt|) by Tim Pope,
  which provides mappings to manipulate surrounding delimiters such as `''`,
  `""`, `()`, `[]`, `{}`, and `<>`.  As such, the mappings from VimTeX
  should work well together with, and as an extension of, `surround.vim`.
  Consider also the customization described under |vimtex-faq-surround|.
  The mappings may be repeated with the dot (|.|) command. See also
  |g:vimtex_delim_list| if you are interested in customizing the delimiter
  pairs that are recognized.

  A different possibility is to use `vim-sandwich` [1] (|sandwich.txt|) by
  Machakann, which may be considered a generalisation of `surround.vim` in
  that it can handle much more complex sets of delimiters.  `vim-sandwich`
  is relatively easy to expand with custom surroundings and has built in
  support for LaTeX-specific surroundings such as quotations, ```text''`,
  and math delimiters, `$\left(a+b\right)$`.  For a list of supported
  delimiters, see |sandwich-filetype-recipes|.  `vim-sandwich` supports
  `vim-repeat` [2] in addition to `visualrepeat.vim` [3].

  Note: The default mappings of `vim-sandwich` differ from those of
    `surround.vim`, in that they use `s` as the prefix.  E.g., to add
    surroundings, one uses `sa{motion/textobject}{type-of-surrounding}`
    instead of `ys{motion/textobject}{type-of-surrounding}`.  If one prefers
    the map variants from `surround.vim`, these are also available as an
    option, see |sandwich-miscellaneous|.  And it is also easy to define
    custom mappings, if one prefers that.

  Note: `vim-sandwich` actually consists of three plugins that work
    together.  One should make sure to read the docs for all of them:
    |sandwich.txt|, |operator-sandwich.txt|, and |textobj-sandwich.txt|.

  [0]: https://github.com/tpope/vim-surround
  [1]: https://github.com/machakann/vim-sandwich
  [2]: https://github.com/tpope/vim-repeat
  [3]: http://www.vim.org/scripts/script.php?script_id=3848

Enhanced matching and highlighting of delimiters~
                                                *vimtex-nf-enhanced-matchparen*
  VimTeX highlights and allows navigation between matching pairs of
  delimiters including those in math mode, such as `\bigl(` and `\bigr)`, and
  the `\begin` and `\end` tags of environments. However, the implementation
  may be slow (see also |vimtex-faq-slow-matchparen|, and so one may use
  |g:vimtex_matchparen_enabled| to disable the highlighting).

  Alternatively, one may use the plugin |match-up| [0], which offers enhanced
  |matchparen| highlighting and `matchit.zip` style motions and |text-objects|
  for a variety of file types.  For LaTeX documents, it:
    - Extends highlighting and the `%` motion to a number of middle
      delimiters including
        - `\bigm` and `\middle` marked delimiters
        - `\item`s in `itemize` and `enumerate` environments
        - `\toprule`, `\midrule`, `\bottomrule` in the `tabular` environment.
        - `\if`, `\else` and `\endif`
      Note: VimTeX does not support highlighting the middle delimiters.
    - Adds motions, `g%`, `[%`, and `]%` and text objects, `a%` and `i%` which move
      between matching delimiters and operate on delimited text.

  For example, with match-up enabled, >

    \left( \frac{a}{b} \middle| q \right)
<
  the motion `%` will cycle through `\left(`, `\middle|`, and `\right)`, whereas
  with VimTeX only `\left(` and `\right)` will be matched.  The motion `g%`
  will do the same, except in reverse.

  To enable the plugin match-up after installation, add the following to
  your vimrc: >

    let g:matchup_override_vimtex = 1
<
  Matching may become computationally intensive for complex LaTeX documents.
  If you experience slowdowns while moving the cursor, the following option
  is recommended to delay highlighting slightly while navigating: >

    let g:matchup_matchparen_deferred = 1
<
  Note: The exact set of delimiters recognized may differ between match-up
    and VimTeX.  For example, the mappings `da%` and `dad` will not in general
    be identical, particularly if you have customized VimTeX's delimiters.

  [0]: https://github.com/andymass/vim-matchup

Formatting~
                                                         *vimtex-nf-formatting*
  VimTeX has a custom |formatexpr| that may be enabled with the option
  |g:vimtex_format_enabled|. However, there are a lot of different styles for
  formatting LaTeX manuscripts. These are typically much more relevant when
  writing in collaboration with others. A good reference on this topic is [0],
  and note in particular the box "Directives for using LaTeX with version
  control systems".

  The most basic style is to hard wrap lines at a given column, e.g. 80
  columns, and this is exactly the type of formatting that is supported by
  VimTeX. However, this is usually not very friendly when collaborating with
  others, as it tends to mess up diffs between versions of the document.
  Instead, one might want to consider one of these:

    a) keeping each sentence on a line (use soft wrapping)
    b) add additional indentation for split sentences [1]
    c) use semantic line feeds [2]

  In order to make it easier to use one of these styles of formatting, one may
  want to use an external formatter:

    - latexindent.pl [3]
    - vim-bucky [4] (note: this is an alpha version as of October 2018)

  Further, there are a range of Vim plugins that can be used to format your
  document with external tools. Some of these also allow autoformatting of
  some kind. In no particular order:

    - neoformat [5]
    - vim-codefmt [6]
    - vim-autoformat [7]
    - ale [8]
    - vim-sentence-chopper [9]

  [0]: https://en.wikibooks.org/wiki/LaTeX/Collaborative_Writing_of_LaTeX_Documents
  [1]: http://dustycloud.org/blog/vcs-friendly-patchable-document-line-wrapping/
  [2]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
  [3]: https://github.com/cmhughes/latexindent.pl
  [4]: https://github.com/dbmrq/vim-bucky
  [5]: https://github.com/sbdchd/neoformat
  [6]: https://github.com/google/vim-codefmt
  [7]: https://github.com/Chiel92/vim-autoformat
  [8]: https://github.com/dense-analysis/ale
  [9]: https://github.com/Konfekt/vim-sentence-chopper

Filetype plugin for bib files~
                                                       *vimtex-nf-ftplugin-bib*
  VimTeX is not a filetype plugin for bibliography (`.bib`) files. However,
  it does include a couple of minor things, such as setting the 'comments' and
  'commentstring' options and a simple indentation expression, see
  |g:vimtex_indent_bib_enabled|.

  Here are a couple of other related Vim plugins and external tools that might
  be of interest:

  - `bibtool`
    An external tool for formatting, sorting, filtering, merging, and more of
    `.bib` files.
    http://www.gerd-neugebauer.de/software/TeX/BibTool/
  - `tbibtools`
    A set of ruby-based bibtex-related utilities for sorting, reformatting,
    listing contents, and so on. Has optional Vim integration.
    https://www.vim.org/scripts/script.php?script_id=1915

  See also https://github.com/lervag/vimtex/issues/1293 for some related
  discussions.

Language server / texlab~
                                                                *vimtex-nf-lsp*
  In recent years, language servers (lsps) [0] has become very popular. There is
  a language server for LaTeX and bibtex called texlab [1]. It may be
  interesting both as an alternative to VimTeX and/or in addition. One may use
  it with e.g. |vim-lsp| [2] or |coc-nvim| [3, 4] or other lsps.

  See also this VimTeX issue [5] for more information.

  [0]: https://langserver.org/
  [1]: https://texlab.netlify.app/
  [2]: https://github.com/prabirshrestha/vim-lsp
  [3]: https://github.com/neoclide/coc.nvim
  [4]: https://github.com/fannheyward/coc-texlab
  [5]: https://github.com/lervag/vimtex/issues/1371

------------------------------------------------------------------------------
SUPPORT FOR MULTI-FILE PROJECTS                             *vimtex-multi-file*

VimTeX supports most multi-file documents.  The main method uses a recursive
search algorithm that should find the main LaTeX file in most cases.  For
special cases, there are several alternative methods for specifying the main
file.  These alternative methods all require some explicit declaration of the
main file.  Thus, these methods will be tried first, and the recursive search
is tried last if there are no explicit declarations that yield an appropriate
main LaTeX file candidate.

The methods are tried in the following order:

  1. Buffer variable
  2. TeX root directive
  3. Subfiles package
  4. File `.latexmain` specifier
  5. Local `latexmkrc` file specifier (from `@default_files` option)
  6. Recursive search

                                                                 *b:vimtex_main*
Buffer variable~
  The main file may be specified through the buffer variable `b:vimtex_main`.
  To take effect, it has to be set prior to loading the buffer. If set after
  the buffer is already loaded, |:VimtexReloadState| (by default bound to
  |<localleader>lX|) can be used to make VimTeX aware of its new value.
  If one uses project specific |vimrc| files, one may then use an |autocmd| to
  specify the main file through this buffer variable with >

    autocmd BufReadPre *.tex let b:vimtex_main = 'main.tex'
<
                                                              *vimtex-tex-root*
TeX root directive~
  It is also possible to specify the main TeX file with a comment in one of
  the first five lines of the current file. Some examples: >

    %! TEX root = /path/to/my-main.tex
    %! TEX root = ../*.tex
    %! TEX root = **/main.tex
<
  Note: It is allowed to use a globbing pattern (see |wildcards|). If there
  are multiple matches, then VimTeX will ask for input when the buffer is
  opened.

                                                               *vimtex-subfiles*
                                                                 *vimtex-import*
Subfiles package~
  VimTeX also supports the `import` [0] and the `subfiles` [1] packages that
  can be used to make it easier to work with multi-file projects. If one uses
  the `subfiles` package, the |:VimtexToggleMain| command is particularly
  useful. Also note the option |g:vimtex_subfile_start_local|, which can be
  used to automatically start in the local mode when opening a subfile
  document.

  With `subfiles`, included files will typically look like this: >

    \documentclass[<main-path>]{subfiles}
    \begin{document}
    ...
    \end{document}
<
  Here `<main-path>` is the path to the main file. It must be specified as
  relative to the particular subfile. So, given the structure: >

    main.tex
    sub/sub.tex
<
  The header in `sub.tex` should be `\documentclass[../main.tex]{subfiles}`.
  Absolute paths like `/home/user/main.tex` are also allowed and should work
  as expected.

  [0]: https://www.ctan.org/pkg/import
  [1]: https://www.ctan.org/pkg/subfiles

File .latexmain specifier~
  In some cases, it might be preferable to specify the main file by creating
  an indicator file.  The indicator file should be an empty file, and the name
  must be the name of the desired main file with `.latexmain` appended.  An
  example should make this clear: >

    path/file.tex
    path/file.tex.latexmain
    path/sections/file1.tex
    path/sections/file2.tex
<
  Here `path/file.tex.latexmain` indicates for `file1.tex` and `file2.tex`
  that `path/file.tex` is the main LaTeX file.

Local latexmkrc file specifier~
  It is possible to specify to latexmk which files to compile with the
  `@default_files` option in the `latexmkrc` configuration file. VimTeX
  supports reading this option in any LOCAL `latexmkrc` or `.latexmkrc` file.

  Note: `@default_files` is a list of files, VimTeX will use the first
        entry that is found.

Recursive search~
  If no other method provides an appropriate candidate, then the recursive
  search detects the main LaTeX file by searching for a file in the current
  and parent directories that includes the present file and has the
  `\documentclass` line.

  This should work in most cases, but it may fail if for instance the project
  structure is something like this: >

    path1/main.tex
    path2/chapter.tex
<
  That is, the main file detection will not work for the file `chapter.tex`,
  because the main file does not live in the same folder or a parent folder.
  In this particular case, the TeX root directive should work.

  Note: In rare cases, such as if there are _very_ many tex files in the
        directory tree, this method may be slow. One may therefore disable it
        through the option |g:vimtex_disable_recursive_main_file_detection|.

------------------------------------------------------------------------------
SUPPORT FOR TEX DIRECTIVES                              *vimtex-tex-directives*

VimTeX supports two of the commonly used TeX directives [0]: the TeX root and
the TeX program directive. The TeX root directive was already described above,
see |vimtex-tex-root|.

                                                           *vimtex-tex-program*
The TeX program directive works by specifying the TeX compiler program in
a comment in one of the first lines of the main project file. It is parsed
during initialization, but if desired one may manually reload VimTeX in order
to reset the program during an editing session. See |:VimtexReload| and
|<plug>(vimtex-reload)| (by default mapped to `<localleader>lx`).

The syntax is best explained with an example: >

    %! TEX program = program

Here `program` corresponds to a key in the |g:vimtex_compiler_latexmk_engines|
or |g:vimtex_compiler_latexrun_engines| dictionaries. See also [0,1].

[0]: https://tex.stackexchange.com/q/78101/34697
[1]: https://github.com/lervag/vimtex/issues/713

------------------------------------------------------------------------------
PACKAGE DETECTION                                    *vimtex-package-detection*

VimTeX maintains a list of latex packages that are required by the current
project. This list is used by VimTeX for instance to determine which commands
to suggest during command completion (see |vimtex-complete-commands|) and
which packages to look up documentation for (see |vimtex-doc-package|). The
list can be viewed with |:VimtexInfo|.

The package list is determined in two ways: >

1. If a `.fls` file exists having the name of the main file, it is scanned.
   This file is created by `latex` (or `pdflatex`, `xelatex`, ...) if it is
   run with the `-recorder` option. This is enabled by default with `latexmk`.
   Parsing the `.fls` file is done both at VimTeX initialization and after
   each successful compilation, if possible.

   Note: Parsing after successful compilations requires that one uses
         a) continuous compilation with callbacks (see the `callback` option
            for |g:vimtex_compiler_latexmk|), or
         b) single-shot compilation.

2. Otherwise, the preamble is parsed for `\usepackage` statements. This is
   slower and less accurate than `.fls` file parsing. Therefore, it is only
   done during VimTeX initialization. If desired, one may manually reload
   VimTeX to parse the preamble again during an editing session. See
   |:VimtexReload| and |<plug>(vimtex-reload)| (by default mapped to
   `<localleader>lx`).

==============================================================================
USAGE                                                            *vimtex-usage*

  Default mappings        |vimtex-default-mappings|
  Options                 |vimtex-options|
  Commands                |vimtex-commands|
  Map definitions         |vimtex-mappings|
  Insert mode mappings    |vimtex-imaps|
  Events                  |vimtex-events|

------------------------------------------------------------------------------
DEFAULT MAPPINGS                                      *vimtex-default-mappings*

VimTeX is designed to be controlled by a selection of mappings.  Note,
though, that most of the mappings are also available as commands, see
|vimtex-commands|.

Many of the mappings utilize the |maplocalleader|. The right-hand sides are
provided as <plug>-mappings, see |using-<plug>|. For any given <plug> map, the
default mapping will only be created if it does not already exist. This means
that if a user defines a custom mapping, e.g. with >

  nmap <space>li <plug>(vimtex-info)

then the corresponding default left-hand side will not be mapped.

If one prefers, one may disable all the default mappings through the option
|g:vimtex_mappings_enabled|.  Custom mappings for all desired features must
then be defined through the listed RHS <plug>-maps or by mapping the available
commands.

In the below list of mappings, LHS is the default mapping, RHS is the
corresponding <plug>-maps, and MODE indicates in which vim mode the mappings
are valid. See |map-modes| for an explanation of the various modes. The
indicator refers to the prefix of the corresponding map command, e.g. `n`
refers to an |nmap|, `nx` refers to both |nmap| and |xmap|, and so on.

In addition to the mappings listed below, VimTeX provides convenient insert
mode mappings to make it easier and faster to type mathematical equations.
This feature is explained in more detail later, see |vimtex-imaps|.

  ---------------------------------------------------------------------~
   LHS              RHS                                          MODE~
  ---------------------------------------------------------------------~
   <localleader>li  |<plug>(vimtex-info)|                           `n`
   <localleader>lI  |<plug>(vimtex-info-full)|                      `n`
   <localleader>lt  |<plug>(vimtex-toc-open)|                       `n`
   <localleader>lT  |<plug>(vimtex-toc-toggle)|                     `n`
   <localleader>lq  |<plug>(vimtex-log)|                            `n`
   <localleader>lv  |<plug>(vimtex-view)|                           `n`
   <localleader>lr  |<plug>(vimtex-reverse-search)|                 `n`
   <localleader>ll  |<plug>(vimtex-compile)|                        `n`
   <localleader>lL  |<plug>(vimtex-compile-selected)|               `nx`
   <localleader>lk  |<plug>(vimtex-stop)|                           `n`
   <localleader>lK  |<plug>(vimtex-stop-all)|                       `n`
   <localleader>le  |<plug>(vimtex-errors)|                         `n`
   <localleader>lo  |<plug>(vimtex-compile-output)|                 `n`
   <localleader>lg  |<plug>(vimtex-status)|                         `n`
   <localleader>lG  |<plug>(vimtex-status-all)|                     `n`
   <localleader>lc  |<plug>(vimtex-clean)|                          `n`
   <localleader>lC  |<plug>(vimtex-clean-full)|                     `n`
   <localleader>lm  |<plug>(vimtex-imaps-list)|                     `n`
   <localleader>lx  |<plug>(vimtex-reload)|                         `n`
   <localleader>lX  |<plug>(vimtex-reload-state)|                   `n`
   <localleader>ls  |<plug>(vimtex-toggle-main)|                    `n`
   <localleader>la  |<plug>(vimtex-context-menu)|                   `n`
   dse              |<plug>(vimtex-env-delete)|                     `n`
   dsc              |<plug>(vimtex-cmd-delete)|                     `n`
   ds$              |<plug>(vimtex-env-delete-math)|                `n`
   dsd              |<plug>(vimtex-delim-delete)|                   `n`
   cse              |<plug>(vimtex-env-change)|                     `n`
   csc              |<plug>(vimtex-cmd-change)|                     `n`
   cs$              |<plug>(vimtex-env-change-math)|                `n`
   csd              |<plug>(vimtex-delim-change-math)|              `n`
   tsf              |<plug>(vimtex-cmd-toggle-frac)|                `nx`
   tsc              |<plug>(vimtex-cmd-toggle-star)|                `n`
   tse              |<plug>(vimtex-env-toggle-star)|                `n`
   tsd              |<plug>(vimtex-delim-toggle-modifier)|          `nx`
   tsD              |<plug>(vimtex-delim-toggle-modifier-reverse)|  `nx`
   <F7>             |<plug>(vimtex-cmd-create)|                     `nxi`
   ]]               |<plug>(vimtex-delim-close)|                    `i`
   ac               |<plug>(vimtex-ac)|                             `xo`
   ic               |<plug>(vimtex-ic)|                             `xo`
   ad               |<plug>(vimtex-ad)|                             `xo`
   id               |<plug>(vimtex-id)|                             `xo`
   ae               |<plug>(vimtex-ae)|                             `xo`
   ie               |<plug>(vimtex-ie)|                             `xo`
   a$               |<plug>(vimtex-a$)|                             `xo`
   i$               |<plug>(vimtex-i$)|                             `xo`
   aP               |<plug>(vimtex-aP)|                             `xo`
   iP               |<plug>(vimtex-iP)|                             `xo`
   am               |<plug>(vimtex-am)|                             `xo`
   im               |<plug>(vimtex-im)|                             `xo`
   %                |<plug>(vimtex-%)|                              `nxo`
   ]]               |<plug>(vimtex-]])|                             `nxo`
   ][               |<plug>(vimtex-][)|                             `nxo`
   []               |<plug>(vimtex-[])|                             `nxo`
   [[               |<plug>(vimtex-[[)|                             `nxo`
   ]m               |<plug>(vimtex-]m)|                             `nxo`
   ]M               |<plug>(vimtex-]M)|                             `nxo`
   [m               |<plug>(vimtex-[m)|                             `nxo`
   [M               |<plug>(vimtex-[M)|                             `nxo`
   ]n               |<plug>(vimtex-]n)|                             `nxo`
   ]N               |<plug>(vimtex-]N)|                             `nxo`
   [n               |<plug>(vimtex-[n)|                             `nxo`
   [N               |<plug>(vimtex-[N)|                             `nxo`
   ]r               |<plug>(vimtex-]r)|                             `nxo`
   ]R               |<plug>(vimtex-]R)|                             `nxo`
   [r               |<plug>(vimtex-[r)|                             `nxo`
   [R               |<plug>(vimtex-[R)|                             `nxo`
   ]/               |<plug>(vimtex-]/|                              `nxo`
   ]*               |<plug>(vimtex-]star|                           `nxo`
   [/               |<plug>(vimtex-[/|                              `nxo`
   [*               |<plug>(vimtex-[star|                           `nxo`
   K                |<plug>(vimtex-doc-package)|                    `n`
  ---------------------------------------------------------------------~

------------------------------------------------------------------------------
OPTIONS                                                        *vimtex-options*

*g:vimtex_enabled*
  Set to 0 to disable VimTeX.

  Default value: Undefined.

*g:vimtex_cache_root*
  Specify the cache directory for VimTeX.

  Default value:
    `'$XDG_CACHE_HOME/vimtex'`   if `$XDG_CACHE_HOME` is defined
    `'~/.cache/vimtex'`          otherwise

*g:vimtex_cache_persistent*
  Specify whether to use persistant caching.

  Default value: 1

*g:vimtex_compiler_enabled*
  Use this option to disable/enable the `compiler` interface, see |vimtex-compiler|.

  Default value: 1

*g:vimtex_compiler_progname*
  Path to vim executable used for the callback functionality. It must be set
  correctly in order for the callback function to work.  The default value
  should work correctly in most cases, but in some cases, e.g. for MacVim, one
  might need to set it manually to get the callbacks to work as expected.

  Default value on Vim:    |v:progpath| or |v:progname|
  Default value on neovim: `nvr` if available, else same as Vim

  See also: |vimtex-faq-neovim|

*g:vimtex_compiler_method*
  Set the compiler method. Available choices are:

    latexmk~
      See |vimtex-latexmk| for more details, and |g:vimtex_compiler_latexmk|
      for customization.

    latexrun~
      See |vimtex-latexrun| for more details, and |g:vimtex_compiler_latexrun|
      for customization.

    tectonic~
      See |vimtex-tectonic| for more details, and |g:vimtex_compiler_tectonic|
      for customization.

    arara~
      See |vimtex-arara| for more details, and |g:vimtex_compiler_arara| for
      customization.

    generic~
      See |vimtex-compiler-generic| for more details, and
      |g:vimtex_compiler_generic| for customization.

  Default value: 'latexmk'

*g:vimtex_compiler_latexmk*
  This is a dictionary that allows customization of the |vimtex-latexmk|
  compiler. The values set by the user will take precedence over the default
  values.

  Default value: >

    let g:vimtex_compiler_latexmk = {
        \ 'build_dir' : '',
        \ 'callback' : 1,
        \ 'continuous' : 1,
        \ 'executable' : 'latexmk',
        \ 'hooks' : [],
        \ 'options' : [
        \   '-verbose',
        \   '-file-line-error',
        \   '-synctex=1',
        \   '-interaction=nonstopmode',
        \ ],
        \}
<
  The default value shows which entries may be changed. Here the different
  keys are explained in more detail:

  build_dir~
    This option sets the compilation build directory.  It corresponds to the
    `-output-directory` option in `latexmk`.  If the path is a relative path,
    then it will be considered relative to the main project file.

    Note 1: This option only works with `latexmk` version 4.27 and later.
    Note 2: If `$out_dir` is added to `.latexmkrc`, then the `.latexmkrc` setting
            will have priority.
    Note 3: If |$VIMTEX_OUTPUT_DIRECTORY| is defined, it will have the highest
            priority.

  callback~
    If enabled, this option tells `latexmk` to run |vimtex#compiler#callback|
    after compilation is finished.

    Note: When using |clientserver|, the callback is run with the vim
          executable defined by |g:vimtex_compiler_progname|.

  continuous~
    If enabled, `latexmk` will run in continuous mode, i.e. with the `-pvc`
    argument. This means that the document is compiled automatically by
    `latexmk` every time a related file has been changed, until the processes
    is stopped.

    If disabled, `latexmk` will run single shot compilations.

    Note: The events |VimtexEventCompileStarted| and |VimtexEventCompileStopped|
          are only relevant when this option is enabled.

  executable~
    The name/path to the `latexmk` executable.

  hooks~
    A list of |Funcref|s. If running in continuous mode, each hook will be
    called for each line of output from `latexmk`, with that line as argument.
    E.g., to show information about the compilation run numbers, one could do
    this: >

      function! Callback(msg)
        let l:m = matchlist(a:msg, '\vRun number (\d+) of rule ''(.*)''')
        if !empty(l:m)
          echomsg l:m[2] . ' (' . l:m[1] . ')'
        endif
      endfunction
      let g:vimtex_compiler_latexmk = { 'hooks': [function('Callback')] }
<
  options~
    This is a list of options that are passed to `latexmk`. The default
    options should work well for most people.

    Note: Options like `-pdf` or `-lualatex` should NOT be added to this list.
          These are options used to specify the LaTeX processor/engine, see
          instead |g:vimtex_compiler_latexmk_engines|.

    Note: Options may also be specified indirectly to `latexmk` through both
          a global and a project specific `.latexmkrc` file. One should know,
          though, that options specified on the command line has priority, and
          so if one wants to override one of the above default options, then
          one has to set this key to a list that contains the desired options.

*g:vimtex_compiler_latexmk_engines*
  Defines a map between TeX program directive (|vimtex-tex-program|) and
  compiler engine. This is used by |vimtex-latexmk| to define the LaTeX
  program. The `_` key defines the default engine.

  Note: If the TeX program directive is not specified within the main project
        file, and if `$pdf_mode` is added to a project-specific `.latexmkrc`
        file, then the compiler engine will be deduced from the value of
        `$pdf_mode`. The supported values of `$pdf_mode` are 0 (pdflatex), 4
        (lualatex) and 5 (xelatex). See the latexmk documentation for details.

  Default value: >

    let g:vimtex_compiler_latexmk_engines = {
        \ '_'                : '-pdf',
        \ 'pdflatex'         : '-pdf',
        \ 'dvipdfex'         : '-pdfdvi',
        \ 'lualatex'         : '-lualatex',
        \ 'xelatex'          : '-xelatex',
        \ 'context (pdftex)' : '-pdf -pdflatex=texexec',
        \ 'context (luatex)' : '-pdf -pdflatex=context',
        \ 'context (xetex)'  : '-pdf -pdflatex=''texexec --xtx''',
        \}

*g:vimtex_compiler_latexrun*
  This is a dictionary that allows customization of the |vimtex-latexrun|
  compiler. The values set by the user will take precedense over the default
  values.

  Default value: >

    let g:vimtex_compiler_latexrun = {
        \ 'build_dir' : '',
        \ 'options' : [
        \   '-verbose-cmds',
        \   '--latex-args="-synctex=1"',
        \ ],
        \}
<
  The default value shows which entries may be changed. Here the different
  keys are explained in more detail:

  build_dir~
    Same as |g:vimtex_compiler_latexmk| / `build_dir`.

  options~
    This is a list of options that are passed to `latexrun`. The default
    options should work well for most people.

    Note: By default, the option `-pdf` is also supplied to indicate the LaTeX
          engine. This may be changed on a per project basis with TeX
          directives, see |vimtex-tex-program| or the two compiler-specific
          options
            |g:vimtex_compiler_latexmk_engines|
            and |g:vimtex_compiler_latexrun_engines|.
          The latter two options may also be used to change the default engine.

*g:vimtex_compiler_latexrun_engines*
  Defines a map between TeX program directive (|vimtex-tex-program|) and
  compiler engine, i.e. as should be specified to the `--latex-cmd` argument
  to `latexrun`. This is used by |vimtex-latexrun| to define the LaTeX
  program. The `_` key defines the default engine.

  Default value: >

    let g:vimtex_compiler_latexrun_engines = {
        \ '_'                : 'pdflatex',
        \ 'pdflatex'         : 'pdflatex',
        \ 'lualatex'         : 'lualatex',
        \ 'xelatex'          : 'xelatex',
        \}

*g:vimtex_compiler_tectonic*
  This is a dictionary that allows customization of the |vimtex-tectonic|
  compiler. The values set by the user will take precedense over the default
  values.

  Default value: >

    let g:vimtex_compiler_tectonic = {
        \ 'build_dir' : '',
        \ 'options' : [
        \   '--keep-logs',
        \   '--synctex'
        \ ],
        \}
<
  The default value shows which entries may be changed. Here the different
  keys are explained in more detail:

  build_dir~
    Same as |g:vimtex_compiler_latexmk| / `build_dir`. This will be created if
    needed, since tectonic won't build anything unless it exists.

  options~
    This is a list of options that are passed to `tectonic`. The default
    options should work well for most people. For anyone who wishes to modify
    these, please note:
    - Don't use `--outdir` or `-o` here. Use the `build_dir` option instead.
    - Without `--keep-logs` (or `--keep-intermediates` or `-k)`, you won't see
      errors/warnings in the quickfix list when compilations finish.
    - By default, `tectonic` cleans all auxiliary files (such as `.aux`,
      `.toc`, etc.). If you omit the `--keep-logs` (or similar) options that
      specify to keep these files, |:VimtexClean| and |<plug>(vimtex-clean)|
      won't delete anything (as there is nothing to delete).

*g:vimtex_compiler_arara*
  This is a dictionary that allows customization of the |vimtex-arara|
  compiler. The values set by the user will take precedense over the default
  values.

  Default value: >

    let g:vimtex_compiler_arara = {
        \ 'options' : ['-v'],
        \}
<
  The default value shows which entries may be changed. Here the different
  keys are explained in more detail:

  options~
    This is a list of options that are passed to `arara`. The default options
    should work well for most people.

*g:vimtex_compiler_generic*
  This is a dictionary that allows customization of the
  |vimtex-compiler-generic| compiler. This compiler is, as the name hints,
  generic. It allows to specify a custom command to run for compilation. As
  for the other compilers, the configuration values set by the user will take
  precedense over the default values.

  Default value: >

    let g:vimtex_compiler_generic = {
        \ 'cmd' : '',
        \ 'build_dir' : '',
        \}
<
  The default value shows which entries may be changed. Here the different
  keys are explained in more detail:

  cmd~
    This is the command to run to start compilation. This can be any command,
    and the command is run from the project root.

    Note: This value must be specified; an empty value will return an error.

  build_dir~
    Same as |g:vimtex_compiler_latexmk| / `build_dir`. This will be created if
    needed, since tectonic won't build anything unless it exists.

*g:vimtex_complete_enabled*
  Use this option to disable/enable VimTeX completion.

  Default value: 1

*g:vimtex_complete_smart_case*
  If enabled, then VimTeX will filter case sensitive if there is a capital
  letter in the completion input. This is only relevant if
  |g:vimtex_complete_ignore_case| is also enabled.

  Default value: Same as your 'smartcase' value

*g:vimtex_complete_ignore_case*
  If enabled, then VimTeX will filter case insensitive.

  Default value: Same as your 'ignorecase' value

*g:vimtex_complete_close_braces*
  This option controls whether to append a closing brace after a label or
  a citation has been completed.

  Default value: 0

*g:vimtex_parser_bib_backend*
  This option sets the desired default backend for parsing bibliographies.
  This is used e.g. for gathering completion candidates. Possible values:

    `bibtex`:   The fastest, but most hacky solution. Should work well in most
              cases.

    `bibparse`: Also fast, but might be more robust.

    `vim`:      The slowest but perhaps most robust solution, as it does not
              require any external utilities.

  Default value: `bibtex`

*g:vimtex_bibliography_commands*
    A list of command names for commands that include bibliography files.
    Each list entry is interpreted as a pattern (very magic, see |/\v|) to
    match a particular command name. This option may be useful if one defines
    custom commands that includes bibliography files.

    Default value: >
        ['%(no)?bibliography', 'add%(bibresource|globalbib|sectionbib)']

*g:vimtex_complete_bib*
  This option is a dictionary for controlling the citation completion. The
  keys each control a different thing:

  simple~
    Default value: 0
    If nonzero, then cite completion only searches on the bib keys. This may
    work better e.g. if one uses an autocomplete plugin.

                                               *g:vimtex_complete_bib.menu_fmt*
  menu_fmt~
    Default value: `'[@type] @author_short (@year), "@title"'`
    The format used for the `menu` entry for bib completion candidates (see
    |complete-items|). The following keys may be used to define the string:

      @key           The bibtex key
      @title         Title
      @year          Publication year
      @author_all    Full author list
      @author_short  Shortened author list
      @type          Type of entry

    If the key is set to an empty string, then the `menu` entry is not added
    to the completion canidates.

    Note: If you change this option, you should also clear the related cache
    files (i.e. `~/.cache/vimtex/bibcomplete*.json` on Linux systems).

  abbr_fmt~
    Default value: `''`
    The format used for the `abbr` entry for bib completion candidates. See
    `menu_fmt` for further description.

  custom_patterns~
    Default value: []
    List of custom trigger patterns that may be used to allow completion for
    e.g. custom macros.

  If one wants to overwrite one of the keys, e.g. the `simple` entry, one can do: >

    let g:vimtex_complete_bib = { 'simple': 1 }
<
  This does not modify the other keys and their default values.

*g:vimtex_complete_ref*
  This option is a dictionary for controlling the label completion. The
  keys each control a different thing:

  custom_patterns~
    Default value: []
    List of custom trigger patterns that may be used to allow completion for
    e.g. custom macros.

  For example, if one has defined the command `\figref`, one could add following
  custom pattern >

     let g:vimtex_complete_ref = {
        \ 'custom_patterns' = ['\\figref\*\?{[^}]*$']
        \ }

*g:vimtex_context_pdf_viewer*
  Specify PDF viewer to use to open PDF files with the |vimtex-context-menu|, for
  instance for citations with the `file` key (see |vimtex-context-citation|).

  The default value is based on the |vimtex-view| and is determined as follows:

    * If |g:vimtex_view_method| is not `general`, then the specified viewer is
      used. However, the viewer will by default start without any of the
      regular options.

    * Else fall back to the value of |g:vimtex_view_general_viewer|.

*g:vimtex_delim_list*
  A dictionary that defines the pairs of delimiters that are recognized by
  VimTeX for various commands and functions. The dictionary contains 5 sub
  dictionaries:

    `env_tex`     Pairs of environment delimiters in normal TeX mode
    `env_math`    Pairs of special math environment delimiters
    `delim_tex`   Pairs of delimiters in normal TeX mode
    `delim_math`  Pairs of delimiters in math mode
    `mods`        Pairs of modifiers for math mode delimiters

  Each entry is a dictionary with the following format: >

    {
    \ 'name' : [
    \   ['\(', '\)'],
    \   ['\[', '\]'],
    \   ['$$', '$$'],
    \   ['$', '$'],
    \ ],
    \ 're' : [
    \   ['\\(', '\\)'],
    \   ['\\\@<!\\\[', '\\\]'],
    \   ['\$\$', '\$\$'],
    \   ['\$', '\$'],
    \ ],
    \}
<
  Here the `name` entry is a list of delimiter pairs as they are typed, and the
  `re` entry is a corresponding list of regexes that matches the delimiters.

  The default value should generally suffice for most people. If one wants to
  overwrite one of the main entries, e.g. the `mods` entry, one can do: >

    let g:vimtex_delim_list = {
          \ 'mods' : {
          \   'name' : [ ... ],
          \ }
          \}
<
  Here the `re` entry was not provided, in which case it will be automatically
  generated based on the `name` entry. The remaining four entries will remain
  the default value.

  Some people may be interested in adding support for e.g. german or french
  quotation marks. These may be added by extending the default `delim_tex`
  entries, like this: >

    let g:vimtex_delim_list = {
        \ 'delim_tex' : {
        \   'name' : [
        \     ['[', ']'],
        \     ['{', '}'],
        \     ['\glq', '\grq'],
        \     ['\glqq', '\grqq'],
        \     ['\flq', '\frq'],
        \     ['\flqq', '\frqq'],
        \    ]
        \  }
        \}
<
                                                         *g:vimtex#delim#lists*
                                                         *g:vimtex#delim#re*
  Note: This option is parsed on plugin initialization into a new variable,
        |g:vimtex#delim#lists| where the `re` entries are added and that also
        contains some combinations such as `tex_all`, `delim_all`, and `all`.
        Further, the option is also used as a basis for the variable
        |g:vimtex#delim#re|, which contains full regexes for matching opening
        and/or closing delimiters of the desired type.

  Default value: See `s:init_delim_lists()` in `autoload/vimtex/delim.vim`.

*g:vimtex_delim_toggle_mod_list*
  Defines a list of delimiter modifiers to toggle through using the maps:

    |<plug>(vimtex-delim-toggle-modifier)|
    |<plug>(vimtex-delim-toggle-modifier-reverse)|

  The list must be a subset of the `mods` entry of |g:vimtex_delim_list|,
  otherwise the toggle will not work properly.  Thus, if one wants to toggle
  non-standard delimiters, then one must also update the above option.

  Example 1: to toggle between no modifiers, the `\left/\right` pair, and the
  `\mleft/\mright` pair, one may use the following options: >

    let g:vimtex_delim_list = {'mods' : {}}
    let g:vimtex_delim_list.mods.name = [
          \ ['\left', '\right'],
          \ ['\mleft', '\mright'],
          \ ['\bigl', '\bigr'],
          \ ['\Bigl', '\Bigr'],
          \ ['\biggl', '\biggr'],
          \ ['\Biggl', '\Biggr'],
          \ ['\big', '\big'],
          \ ['\Big', '\Big'],
          \ ['\bigg', '\bigg'],
          \ ['\Bigg', '\Bigg'],
          \]
    let g:vimtex_delim_toggle_mod_list = [
      \ ['\left', '\right'],
      \ ['\mleft', '\mright'],
      \]
<
  Example 2: to step through no modifiers, and the pairs `\bigl/\bigr`,
  `\Bigl/\Bigr`, `\biggl/\biggr`, and `\Biggl/\Biggr`, one may use: >

    let g:vimtex_delim_toggle_mod_list = [
      \ ['\bigl', '\bigr'],
      \ ['\Bigl', '\Bigr'],
      \ ['\biggl', '\biggr'],
      \ ['\Biggl', '\Biggr'],
      \]
<
  Default value: `[['\left', '\right']]`

*g:vimtex_delim_timeout*
*g:vimtex_delim_insert_timeout*
  Timeout (in milliseconds) when searching for matching delimiters. It is used
  for the {timeout} argument of |search()|-like function calls. If the option
  is increased it will make the matching more accurate, at the expense of
  potential lags. The default value should work well for most people.

  Default values: 300, 60 (respectively)

*g:vimtex_delim_stopline*
  A tolerance for the number of lines to search for matching delimiters in
  each direction. It is used in an expression for the {stopline} argument of
  |search()| function calls. If the option is increased it will make the
  matching more accurate, at the expense of potential lags. The default value
  should work well for most people.

  Default value: 500

*g:vimtex_disable_recursive_main_file_detection*
  In rare cases, the recursive method of finding the main file in multi file
  projects may be slow. This might happen for instance when there are _very_
  many tex files in the directory tree that is searched. In such cases, one
  may disable the recursive method by setting this variable to a nonzero
  value.

  Default value: 0

*g:vimtex_doc_handlers*
  By default, package documentation is looked up online through
  http://texdoc.net/pkg/packagename. With this option, one may specify a list
  of custom handlers. A handler is a function that takes a single |Dict|
  argument with the following keys:

    type~
      One of `documentclass`, `usepackage`, `command` or `word`.

    candidates~
      A list of detected packages (for the types `command` and `usepackage`,
      this list may be larger than 1.

    selected~
      The currently selected entry. This is the package name that will
      ultimately be passed to the lookup function.

    name~
      If the type is `command`, this is the name of the command. Else it is
      not defined.

  Each handler in the list will be tried until a handler provides a return
  value of 1. One may add handlers that only makes minor modifications of the
  context and passes it on to the default handler, as well as handlers that
  fully completes the lookup e.g. through a local lookup with `texdoc`.

  Note that the context may have multiple candidates, and that the handlers
  are applied before any internal selection is made. Thus the `selected` key
  may not defined. This allows the handler to perform the selection itself, or
  one may manually call the selection function `vimtex#doc#make_selection` to
  get a simple selection menu.

  The following example uses the local `texdoc` to open the documentation: >

    let g:vimtex_doc_handlers = ['MyHandler']
    function! MyHandler(context)
      call vimtex#doc#make_selection(a:context)
      if !empty(a:context.selected)
        execute '!texdoc' a:context.selected '&'
      endif
      return 1
    endfunction
<
  Default value: []

*g:vimtex_echo_verbose_input*
  For the set of operator mappings that change a surrounding type [0],
  VimTeX by default prints some information about what you are doing while
  waiting for user input. For advanced/experienced users, one will not need
  this info and can get a slightly clearner UI by disabling this feature (set
  the option 0).

  Default value: 1

  [0]: This affects the following mappings:
    |<plug>(vimtex-env-change)|        (default map: `cse`)
    |<plug>(vimtex-env-change-math)|   (default map: `cs$`)
    |<plug>(vimtex-cmd-change)|        (default map: `csc`)
    |<plug>(vimtex-delim-change-math)| (default map: `csd`)

*g:vimtex_env_change_autofill*
  If enabled, the current environment value is used as a default input for
  |<plug>(vimtex-env-change)| and |<plug>(vimtex-env-change-math)|. Some users
  may find this useful in order to quickly change from things like `align` to
  `aligned`.

  Note: If enabled, one may erase the autofilled content with |c_CTRL-U| (i.e.
        `<c-u>`).

  Default: 0

*g:vimtex_fold_enabled*
  Use this option to enable folding. More detailed info can be found in the
  section |vimtex-folding|.

  Default value: 0

*g:vimtex_fold_manual*
  With this option enabled, VimTeX uses |fold-manual| as the main
  |foldmethod|.  It still uses the |foldexpr| function to compute the fold
  levels, but it only computes the fold levels on demand, see
  |:VimtexRefreshFolds| and |vimtex-zx|.

  The reasoning behind this option is that the |fold-expr| method of folding
  may sometimes be slow, e.g. for long lines and large files. |fold-manual| is
  very fast.

  An alternative to this method of speeding up is to use a dedicated plugin
  for optimizing the fold functionality, see e.g.
  https://github.com/Konfekt/FastFold.

  Default value: 0

*g:vimtex_fold_levelmarker*

  Use custom section symbol for folding.

  Default value: '*'

*g:vimtex_fold_types*
*g:vimtex_fold_types_defaults*
  This is a dictionary where each key configures the corresponding fold type.
  One may disable the fold types by setting the key `enabled` to 0. If a type
  can be configured with a list of patterns or similar, the patterns assume
  that one uses very magic regexes (see |\v|).

  Each entry in |g:vimtex_fold_types| is combined with the corresponding entry
  of |g:vimtex_fold_types_defaults|. If there are conflicting entries, then
  |g:vimtex_fold_types| take presedence. This way, it is easy to customize
  various fold types without touching those that can stay with default
  configuration.

  The available fold types (and keys) are listed below, and the default
  configurations are listed at the bottom.

    <preamble>          Fold the preamble.

    <sections>          Fold sections and parts of documents. Can be
                        configured with the following extra keys:
                        - `parse_levels`: Whether to use detailed parsing to
                                        set fold text levels similar to how
                                        they are displayed in |vimtex-toc|.
                                        Disabled by default, because it uses
                                        more resources and may be slow.
                        - `sections`:     List of sections that should be folded.
                        - `parts`:        List of parts that should be folded.

                        When a LaTeX document is opened, the document is
                        parsed in order to define the highest fold level based
                        on which parts (such as frontmatter, backmatter, and
                        appendix) and section types (parts, chapter, section,
                        etc.) are present. This parsing is done automatically
                        every time the folds are recomputed, if there are any
                        changes to the file.

                        The fold function also recognizes "fake" sections.
                        That is, it parses comments similar to: >

                          % Fakepart title
                          % Fakechapter title
                          % Fakesection title
                          % Fakesubsection title
<
                        The fake sections are folded at the same level as the
                        corresponding "real" sections. The fold title is the
                        provided title with the `Fake...` part prepended.

    <comments>          Fold multiline comments. This is disabled by default.

    <markers>           Fold on vim-style markers inside comments, that is,
                        pairs of e.g. `{{{` and `}}}` (the default markers).
                        |regex| patterns for the opening and closing markers
                        may be customized with the keys:
                        - `open`
                        - `close`

                        Note: Patterns are only searched inside comments!

    <envs>              Fold environments.
                        Can be further configured with a blacklist and
                        whitelist of environments to be folded.

                        Note: The `document` environment will never be folded.

    <env_options>       This fold type allows to fold the `\begin` command if
                        it contains a long optional argument. Consider the
                        following example: >

                          \begin{axis}[    --->    \begin{axis}[...]
                              width=6cm,
                              height=8cm,
                              ...,
                          ]
<
                        Here the `axis` environment must not be otherwise
                        folded through the <envs> fold type.

    <items>             `\item` blocks in itemize like environments. The
                        recognized environments are the same as specified by
                        |g:vimtex_indent_lists|.

    <cmd_single>        Fold long commands with a single argument. E.g.: >

                          \hypersetup{    --->    \hypersetup{...}
                            option 1,
                            ...,
                            option n
                            }
<
    <cmd_single_opt>    Fold commands that opens with a single long optional
                        argument that is followed by a short "real" argument.
                        E.g.: >

                          \usepackage[    --->    \usepackage[...]{name}
                            option 1,
                            ...,
                            option n
                            ]{name}
<
    <cmd_multi>         Fold commands that start with a short regular argument
                        and continue with long optional and/or regular
                        arguments. E.g.: >

                          \newcommand{\xx}[3]{    --->    \newcommand{\xx} ...
                            Hello #1, #2, and #3.
                          }
<
    <cmd_addplot>       Folding of the `\addplot` series of commands from the
                        `pgfplots` package. E.g.: >

                          \addplot+[] table[] {    --->    \addplot+[] table[] {...};
                            table data
                          };
<
  As an example, the following configuration will disable folding of the
  preamble, as well as the `figure` and `table` environments. >

    let  g:vimtex_fold_types = {
           \ 'preamble' : {'enabled' : 0},
           \ 'envs' : {
           \   'blacklist' : ['figure', 'table'],
           \ },
           \}
<
  Default value: >
    let g:vimtex_fold_types = {}
    let g:vimtex_fold_types_defaults = {
          \ 'preamble' : {},
          \ 'items' : {},
          \ 'comments' : {'enabled' : 0},
          \ 'envs' : {
          \   'blacklist' : [],   !!! This is a list of strings
          \   'whitelist' : [],   !!! This is a list of strings
          \ },
          \ 'env_options' : {},
          \ 'markers' : {},
          \ 'sections' : {
          \   'parse_levels' : 0,
          \   'sections' : [      !!! This is a list of (very magic) regexes
          \     '%(add)?part',
          \     '%(chapter|addchap)',
          \     '%(section|addsec)',
          \     'subsection',
          \     'subsubsection',
          \   ],
          \   'parts' : [         !!! This is a list of regexes
          \     'appendix',
          \     'frontmatter',
          \     'mainmatter',
          \     'backmatter',
          \   ],
          \ },
          \ 'cmd_single' : {
          \   'cmds' : [          !!! This is a list of regexes
          \     'hypersetup',
          \     'tikzset',
          \     'pgfplotstableread',
          \     'lstset',
          \   ],
          \ },
          \ 'cmd_single_opt' : {
          \   'cmds' : [          !!! This is a list of regexes
          \     'usepackage',
          \     'includepdf',
          \   ],
          \ },
          \ 'cmd_multi' : {
          \   'cmds' : [          !!! This is a list of regexes
          \     '%(re)?new%(command|environment)',
          \     'providecommand',
          \     'presetkeys',
          \     'Declare%(Multi|Auto)?CiteCommand',
          \     'Declare%(Index)?%(Field|List|Name)%(Format|Alias)',
          \   ],
          \ },
          \ 'cmd_addplot' : {
          \   'cmds' : [          !!! This is a list of regexes
          \     'addplot[+3]?',
          \   ],
          \ },
          \}

*g:vimtex_format_enabled*
  If enabled, VimTeX uses a custom |formatexpr| that should handle inline
  comments and environments. That is, if it is enabled, comments at end of
  lines will not be joined with the |gq| command, and environments like
  `equation` will not be joined/changed.

  Default value: 0

*g:vimtex_grammar_textidote*
  This option is used to configure the `textidote` grammar and document checker,
  see |vimtex-grammar-textidote|. It is a dictionary with the following keys 

    jar~
      The path to `textidote.jar`. This key must be defined if you want to use
      the TeXtidote wrapper! Please note that if one installs `textidote` with
      a package manager e.g. in some common Linux distributions, the `.jar`
      file might be missing. If so, it should be possible to download it
      manually.

    args~
       Specify arguments to be passed to the TeXtidote grammar checker.

  Default: >

      let g:vimtex_grammar_textidote = {
            \ 'jar': '',
            \ 'args': '',
            \}

*g:vimtex_grammar_vlty*
  This option is used to configure the `vlty` grammar checker. It is a
  dictionary with the following keys (see |vimtex-grammar-vlty| for more
  details):

    lt_directory~
      Path to the `LanguageTool` software, if installed manually.

    lt_command~
      Name of `LanguageTool` executable, if installed via package manager. Note
      that this has presedence over `lt_directory`!

    lt_disable~
    lt_enable~
    lt_disablecategories~
    lt_enablecategories~
      Options for `LanguageTool` that control application of rules and rule
      categories. For more info, see:
      http://wiki.languagetool.org/command-line-options

    server~
      Specify whether an HTTP server should be used. This may be faster for
      short texts. Possible values are:

      `no`    Do not use a server.
      `my`    Use a local `LanguageTool` server. If not yet running, it is
              started.
      `lt`    Contact the Web server provided by `LanguageTool`. In this case,
            no local installation is necessary. Please see the following page
            for conditions and restrictions:
            https://dev.languagetool.org/public-http-api

    shell_options~
      Pass additional options to `YaLafi`, e.g., `--equation-punctuation displ`;
      for more info, see:
      https://github.com/matze-dd/YaLafi

    show_suggestions~
      If set to 1, then `LanguageTool's` replacement suggestions are included
      in the |quickfix| or |location-list| messages.

    encoding~
      Encoding of the (La)TeX source file. For default value `auto`, the
      encoding is taken from |fileencoding| or |encoding|.

  Default: >

      let g:vimtex_grammar_vlty = {
            \ 'lt_directory': '~/lib/LanguageTool',
            \ 'lt_command': '',
            \ 'lt_disable': 'WHITESPACE_RULE',
            \ 'lt_enable': '',
            \ 'lt_disablecategories': '',
            \ 'lt_enablecategories': '',
            \ 'server': 'no',
            \ 'shell_options': '',
            \ 'show_suggestions': 0,
            \ 'encoding': 'auto',
            \}

*g:vimtex_imaps_enabled*
  Use this option to disable/enable the insert mode mappings.

  Default value: 1

*g:vimtex_imaps_leader*
  The default leader key for insert mode mappings.

  Default value: '`'

*g:vimtex_imaps_disabled*
  A list of mappings to disable. That is, any left-hand side that matches
  a string in this list will not be mapped to its corresponding right-hand
  side. This may be used to selectively disable one or more from the default
  list of mappings.

  Default value: []

*g:vimtex_imaps_list*
  The list of mappings to generate on start up. The list of activated mappings
  can be viewed with |:VimtexImapsList|.

  Default value: See `autoload/vimtex/options.vim` (it's a long list)

*g:vimtex_include_indicators*
  VimTeX will recognize included files for a lot of different purposes. Most
  of these come from e.g. `\input{file}` or `\include{file}`. This option
  allows to add more commands that are used to include files, e.g. custom
  macros.

  Note: This option is read during initialization of VimTeX, and so it must be
        set early. I.e., it can not be set in `after/ftplugin/tex.vim`.

  Default value: ['input', 'include']

*g:vimtex_include_search_enabled*
  VimTeX sets 'includeexpr' to recognize included files. If a file isn't found
  in the current directory, VimTeX uses `kpsewhich` to search for it in the
  system TeX distribution. If the 'complete' option includes "i", invoking
  keyword completion with |i_CTRL-N| will search included files for completion
  possibilities. In this case, there may be a lot of calls to `kpsewhich`
  while scanning for included files during the first invocation of keyword
  completion, and this may introduce a significant delay. Subsequent keyword
  completions should be faster, as the calls to `kpsewhich` are cached.

  This option allows to disable searching for included files with `kpsewhich`,
  and with that prevent the above explained delay.

  Default value: 1

*g:vimtex_indent_enabled*
  Use this option to disable/enable VimTeX indentation.

  Default value: 1

*g:vimtex_indent_bib_enabled*
  Use this option to disable/enable VimTeX indentation of bibliography files.

  Default value: 1

*g:vimtex_indent_conditionals*
  This is a dictionary that defines regexes for indenting conditionals. Set it
  to an empty dictionary to disable this type of indentation.

  Default value: >
    let g:vimtex_indent_conditionals = {
          \ 'open': '\v%(\\newif)@<!\\if%(field|name|numequal|thenelse)@!',
          \ 'else': '\\else\>',
          \ 'close': '\\fi\>',
          \}

*g:vimtex_indent_delims*
  A dictionary that specifies how to indent delimiters. The dictionary has
  four keys:

    open~
      List of regexes for opening delimiters that should add indents.

    close~
      List of regexes for closing delimiters that should reduce indents.

    close_indented~
      Set this to 1 if you want the line with the closing delimiter to stay
      indented.

    include_modified_math~
      Set this to 0 if you do not want modified math delimiters such as
      `\left(` and `\right)` to add/reduce indents.

  Note: VimTeX does not allow indents for parantheses only in math mode or any
        similar kind of context aware delimiter indents.

  Note: If one of the keys of the dictionary is not specified, the default
        value is assumed.

  Default value: >
    let g:vimtex_indent_delims = {
          \ 'open' : ['{'],
          \ 'close' : ['}'],
          \ 'close_indented' : 0,
          \ 'include_modified_math' : 1,
          \}

*g:vimtex_indent_ignored_envs*
  List of environments that should not add/reduce indentation.

  Default value: ['document']

*g:vimtex_indent_lists*
  List of environments that act like lists with `\item` entries.

  Default value: [
      \ 'itemize',
      \ 'description',
      \ 'enumerate',
      \ 'thebibliography',
      \]

*g:vimtex_indent_on_ampersands*
  By default, VimTeX will align on `leading` ampersands e.g. in math aligned
  environments or in tabular environments. If this feature is not wanted it
  may be disabled through this option.

  Note: To get a more advanced tabular like alignment feature, you may be
        interested in something like |vim-easy-align|:
        https://github.com/junegunn/vim-easy-align

  Default value: 1

*g:vimtex_indent_tikz_commands*
  Use this option to disable/enable VimTeX indentation of multi-line commands
  in TikZ pictures.

  Default value: 1

*g:vimtex_mappings_enabled*
  Control whether or not to load the default mappings.

  Default value: 1

*g:vimtex_mappings_disable*
  A dictionary that can be used to disable specific mappings.  The dictionary
  keys are the mapping modes, and the values are lists of default mappings
  that should be disabled.  The following example will ensure that the default
  `tse` and `tsd` mappings are disabled: >

    let g:vimtex_mappings_disable = {
        \ 'n': ['tse', 'tsd'],
        \ 'x': ['tsd'],
        \}
<
  Default value: {}

*g:vimtex_mappings_override_existing*
  Control behaviour on mapping conflicts, in particular whether or not to
  override pre-existing mappings. By default, VimTeX does not override existing
  mappings. If this option is enabled, then VimTeX will override existing
  mappings on conflict.

  Default value: 0

*g:vimtex_matchparen_enabled*
  Enable highlighting of matching delimiters.

  Note: This is an improved version of |matchparen|. It should be possible to
        keep |matchparen| activated, which matches delimiters listed in
        'matchpairs'. The VimTeX specific version will also match LaTeX
        specific delimiters, which is not possible with |matchparen|.

  Note: If you think this feature is slow, see |vimtex-faq-slow-matchparen|.

  Default value: 1

*g:vimtex_motion_enabled*
  This option enables the motion mappings `%`, `[[`, `[]`, `][`, and `]]`. It
  also enables the highlighting of matching delimiters.

  Default value: 1

*g:vimtex_log_ignore*
  A list of regexes to filter info, warning, and error messages. If a logged
  message matches any of the regexes in this list, the message will not be
  printed to screen.

  Note: All messages may still be viewed with |:VimtexLog|.

  Default: []

*g:vimtex_log_verbose*
  Whether or not to print messages to screen. Should generally be on, but may
  be turned off e.g. for debugging or testing purposes.

  Default: 1

*g:vimtex_quickfix_enabled*
  Use this option to disable/enable the quickfix integration.

  Default value: 1

*g:vimtex_quickfix_method*
  This option sets the quickfix method. The following methods are available:

  latexlog~
    This is the standard method which parses the normal LaTeX output.

  pplatex~
    Uses `pplatex` (https://github.com/stefanhepp/pplatex) to parse the LaTeX
    output file. `pplatex` is a command line utility used to pretify the
    output of the LaTeX compiler.

  pulp~
    Uses `pulp` (https://github.com/dmwit/pulp) to parse the LaTeX output
    file, similar to `pplatex`.

  Note: `pplatex` and `pulp` require that `-file-line-error` is NOT passed to the LaTeX
  compiler. |g:vimtex_compiler_latexmk| will be updated automatically if one
  uses `latexmk` through VimTeX. However, if one uses other compiler
  methods, either through VimTeX (see |g:vimtex_compiler_method|) or
  externally, this requirement must be ensured by the user.

  Default value: 'latexlog'

*g:vimtex_quickfix_blgparser*
  This option controls the parsing of `blg` log files (created by bibtex or
  biber) for warnings and errors.  The option is a dictionary with the
  following keys:

    disable~
      Disable the parsing of `blg` entries.

  Default value: {}

*g:vimtex_quickfix_autojump*
  This option controls if vim should automatically jump to the first error
  whenever the |quickfix| window is opened.

  Note: This option does not go well with continuous compilation and
        callbacks, since the callbacks will open the quickfix window if there
        are errors.  Thus I recommend to keep it disabled for continuous
        compilation, and rather enable it if one prefers single shot
        compilations.

  Default value: 0

*g:vimtex_quickfix_ignore_filters*
  This option allows to provide a list of |regular-expression|s for filtering
  out undesired errors and warnings. This works regardless of which quickfix
  method is enabled.

  The following example will ignore any messages that match "Marginpar on
  page": >

    " Disable custom warnings based on regexp
    let g:vimtex_quickfix_ignore_filters = [
          \ 'Marginpar on page',
          \]
<
  Default: []

*g:vimtex_quickfix_mode*
  This option controls the behaviour of the |quickfix| window in case errors
  and/or warnings are found.  The recognized options are:

  Value  Effect ~
  0      The quickfix window is never opened/closed automatically.
  1      The quickfix window is opened automatically when there are errors,
         and it becomes the active window.
  2      The quickfix window is opened automatically when there are errors,
         but it does not become the active window.

  Note: The quickfix window will only be opened automatically if the compiler
        is set to `continuous` mode and has `callbacks` enabled, or if
        `continuous` mode is disabled.

  Default value: 2

*g:vimtex_quickfix_autoclose_after_keystrokes*
  If set to value greater than zero, then the quickfix window will close after
  this number of motions (i.e. |CursorMoved| and |CursorMovedI| events). This
  is most useful if one sets |g:vimtex_quickfix_mode| to 2, in which case this
  option allows one to continue editing and removing the distraction of the
  quickfix window automatically.

  Note: The count is reset when the quickfix window is entered.

  Default value: 0

*g:vimtex_quickfix_open_on_warning*
  Control whether or not to automatically open the |quickfix| window in case
  there are warning messages and no error messages.

  Default value: 1

*g:vimtex_subfile_start_local*
  This option allows to specify that one should start with the local file for
  subfile'd documents instead of the main project file. See |vimtex-subfiles|
  for further info.

  Default value: 0.

*g:vimtex_syntax_enabled*
  Use this option to disable/enable syntax highlighting as provided by VimTeX.

  Default value: 1.

*g:vimtex_syntax_conceal_default*
  Specify the default flag for the conceal feature. This is used e.g. in
  |vimtex_syntax_conceal| and for package specific options in
  |vimtex_syntax_packages|. For more info, see |vimtex-syntax-conceal|.

  Default value: 1

*g:vimtex_syntax_conceal*
  A dictionary for specifying which core conceal features to activate. This
  mostly implies concealing particular elements with a replacement unicode
  character. For more info, see |vimtex-syntax-conceal|.

  The following keys are available:

    accents~
      Replace TeX accents into the accented character, e.g. `\aa` --> å. This
      will also replace a few ligatures.

    fancy~
      Some extra fancy replacements, e.g. `\item` --> ○.

    greek~
      Replace TeX greek letter commands into the equivalent unicode greek
      letter.

    math_bounds~
      Conceal the TeX math bounds characters: pairs of `$` and `$$`, `\(` ...
      `\)`, and `\[` ... `\]`.

    math_delimiters~
      Replace possibly modified math delimiters with a single unicode
      letter. Modified means delimiters prepended with e.g. `\left` or
      `\bigl`. As an example, this will perform the replacement

        `\Biggl\langle ... \Biggr\rangle` --> `〈 ... 〉`

    math_fracs~
    Replace some simple fractions like `\frac 1 2` --> ½.

    math_super_sub~
      Replace simple math super and sub operators, e.g. `x^2` --> `x²`.

    math_symbols~
      Replace various math symbol commands to an equivalent unicode character.
      This includes quite a lot of replacements, so be warned!

    styles~
      Conceal the LaTeX command "boundaries" for italized and bolded style
      commands, i.e. `\emph`, `\textit`, and `\textbf`. This means that one
      will see something like:

        `\emph{text here}` --> `text here`

    cites~
      Conceal LaTeX cite commands such as `\citet[...]{ref00}`. The conceal
      style is specified by |g:vimtex_syntax_conceal_cites|.

  Default value: All keys set to |g:vimtex_syntax_conceal_default|.

*g:vimtex_syntax_conceal_cites*
  A simple dictionary to control how citation conceal should work. It has
  three keys:

    type~
      Specify the type of concealment. There are two options, and the
      difference is best explained by example:

        Value       LaTeX             Concealed
        -----       -----             ---------
        `'icon'`      `\cite{Knuth1981}`  `📖`
        `'brackets'`  `\cite{Knuth1981}`  `[Knuth1981]`

    icon~
      Specify an icon for `icon` conceal. This must be a single (possibly
      multibyte) character.

    verbose~
      Specify how much to conceal in bracket mode (`type` set to `'bracket'`).
      The following table shows how the concealed result depending on the
      `'verbose'` value for `\cite[Figure 1]{Knuth1981}`:

        Value    Concealed
        -----    ---------
        |v:true|   `[Figure 1][Knuth1981]`
        |v:false|  `[Knuth1981]`

  Default value: >

    let g:vimtex_syntax_conceal_cites = {
          \ 'type': 'brackets',
          \ 'icon': '📖',
          \ 'verbose': v:true,
          \}

*g:vimtex_syntax_nested*
  A dictionary for configuring nested syntaxes. The following keys are
  available for configuration:

    aliases~
      Holds a dictionary of aliases, such as mapping `C` to `c`. This is
      useful e.g. because the Vim syntax files are case sensitive.

    ignored~
      Holds a dictionary of ignore lists for each language. This is useful to
      ignore some groups that may conflict in e.g. the `\begin{...}` or
      `\end{...}` part of the nested syntax regions.

  Default value: >

    let g:vimtex_syntax_nested = {
          \ 'aliases' : {
          \   'C' : 'c',
          \   'csharp' : 'cs',
          \ },
          \ 'ignored' : {
          \   'cs' : [
          \     'csBraces',
          \   ],
          \   'python' : [
          \     'pythonEscape',
          \     'pythonBEscape',
          \     'pythonBytesEscape',
          \   ],
          \   'java' : [
          \     'javaError',
          \   ],
          \   'haskell' : [
          \     'hsVarSym',
          \   ],
          \ }
          \}

*g:vimtex_syntax_nospell_commands*
  A list of commands whose argument should be excluded from spell checking.

  Default value: []

*g:vimtex_syntax_nospell_comments*
  Set to 1 to disable spell checking in comments.

  Default value: 0

*g:vimtex_syntax_packages*
  A dictionary for package specific syntax configuration. Each key represent
  a single package and the values are themselves configuration dictionaries.
  All packages share the following options:

    `load`  Specify when to load the package syntax addon.
      0 = disable this syntax package
      1 = enable this syntax package if it is detected (DEFAULT)
      2 = always enable this syntax package

  The following is a list of the available packages and, if applicable, their
  configuration keys or where they deviate from the above specified defaults.

    amsmath~
      `load`  is 2 by default
    array~
    asymptote~
    babel~
      `conceal`  whether to enable conceal
        Default: |g:vimtex_syntax_conceal_default|
    beamer~
    biblatex~
    booktabs~
    breqn~
    cases~
    circuitikz~
    cleveref~
    comment~
    csquotes~
    dot2texi~
    geometry~
    glossaries_extra~
    glossaries~
    gnuplottex~
    hyperref~
    ieeetrantools~
    listings~
    luacode~
    markdown~
    mathtools~
    minted~
    moreverb~
    natbib~
    pdfpages~
    pgfplots~
    pythontex~
    siunitx~
    subfile~
    tabularx~
    tcolorbox~
    tikz~
    todonotes~
    url~
    varioref~
    wiki~

*g:vimtex_texcount_custom_arg*
  Option that makes it possible to add custom arguments to `texcount` for
  |:VimtexCountWords| and |:VimtexCountLetters|.

  Default value: ''

*g:vimtex_text_obj_enabled*
  Use this option to disable the text object mappings.

  Default value: 1

*g:vimtex_text_obj_linewise_operators*
  List of operators that will act linewise on the delimiter text objects (i.e.
  `ie/ae`, `i$/a$`, and `id/ad`). Note, for inline regions the operators will not
  act linewise, since that would lead to side effects.

  Default value: ['d', 'y']

*g:vimtex_text_obj_variant*
  Select text object variants for command and environment text objects. The
  choice is either VimTeX or |targets.vim|. Possible configuration options
  are:

    1. `'auto'`     (select `'targets'` if |targets.vim| is installed)
    2. `'vimtex'`
    3. `'targets'`

  When using `'targets'`, the following additional text object kinds are
  available:

  - Prefix `I` and `A` instead of `i` and `a` for excluding inner whitespace or
    including outer whitespace, respectively.
  - Modifier `n` and `l` for next or previous (mnemonic: last).

  For more details, see `doc/targets-textobj-cheatsheet.md`.

  Default value: `'auto'`

*g:vimtex_toc_enabled*
  Use this option to disable/enable table of contents (ToC).

  Default value: 1

*g:vimtex_toc_config*
  This is a dictionary that can be used to configure the ToC. Each key
  specifies a configuration option that can be changed. For configuration of
  specific matchers, see |g:vimtex_toc_config_matchers|.

  In the following, the possible configuration keys are explained briefly and
  the default values are indicated.

    `name` : `Table of contents (VimTeX)`
      The name of the ToC buffer.

    `mode` : 1
      The ToC display mode, one of:
        1: Separate window.
        2: Separate window and location list.
        3: Location list (and don't open it).
        4: Location list (and open it).

    `fold_enable` : 0
      Wheter to enable folding in the ToC window.

    `fold_level_start` : -1
      The starting fold level. The value -1 indicates that the start level is
      the same as the `tocdepth` value.

    `hide_line_numbers` : 1
      If enabled, then line numbers will be hidden in the ToC window by
      setting |nonumber| and |norelativenumber| locally.

    `hotkeys_enabled` : 0
      Set to 1 to enable individual hotkeys for ToC entries.

    `hotkeys` : `abcdegijklmnopuvxyz`
      A string of keys that are used to create individual hotkeys.

    `hotkeys_leader` : `;`
      The hotkey leader. Set to empty string to disable the leader.

    `indent_levels` : 0
      Set to 1 to indent the section levels in the ToC window.

    `layers` : Undefined
    `layer_status` : Dictionary >
        { 'content': 1,
          'label': 1,
          'todo': 1,
          'include': 1 }
<      The initial state of the layers (1 for active, 0 for inactive). The
      `layers` key may be used as a shorthand: it accepts a list of layers
      that should be active.

    `layer_keys` : Dictionary >
        { 'content': 'C',
          'label': 'L',
          'todo': 'T',
          'include': 'I'}
<      Specify hotkeys for enabling/disabling the different layers.

    `resize` : 0
      Whether or not to automatically resize vim when index windows are
      opened.

      Note: This option makes sense if the index window is vertically split.

    `refresh_always` : 1
      Set to 0 to manually refresh ToC entries. This may be useful for very
      large projects where generating the ToC entries becomes slow.

      It may be useful to combine manually refreshing with a |BufWritePost|
      autocommand, e.g.: >

        augroup VimTeX
          autocmd!
          autocmd BufWritePost *.tex call vimtex#toc#refresh()
        augroup END
<
      Or, if preferred, one may use a mapping such as: >

        nnoremap <silent> <localleader>lf :call vimtex#toc#refresh()
<
    `show_help` : 1
      Whether to display the index help text.

    `show_numbers` : 1
      Set whether or not to show section numbers in ToC.

    `split_pos` : `vert leftabove`
      Define where index windows should be opened. This is a string that
      contains either the word 'full' to open in the current window, or
      a position command. Use |:vert| if a vertical split is desired, and one
      of |:leftabove|, |:rightbelow|, |:topleft|, and |:botright| to specify
      the desired split position.

    `split_width` : 30
      For vertically split windows: Set width of index window.

    `tocdepth` : 3
      Define the depth of section levels to display. This attempts to mimic
      the corresponding latex variable `tocdepth`. For more info, see:
      https://en.wikibooks.org/w/index.php?title=LaTeX/Document_Structure

      Note: This will also change the width of the number column according to
            the space needed to show the section numbers.

    `todo_sorted` : 1
      Whether or not to sort the TODOs at the top of the ToC window.

*g:vimtex_toc_config_matchers*
  This is a dictionary that can be used to configure the built-in ToC
  matchers. See below for a specification of the ToC matcher "objects" and the
  various keys that can be defined/changed (|toc_matcher_specification|).

  To configure/alter a built-in matcher, one can do this: >

    let g:vimtex_toc_config_matchers = {
          \ 'MATCHER1': {OPTIONS},
          \ 'MATCHER2': {OPTIONS},
          \}
<
  The available options are described in |toc_matcher_specification|. Please
  note that the built-in matchers should generally just work well for most
  people. However, this option allows at least two useful things: to disable
  a built-in matcher and to change the priority of a built-in matcher. The
  following is a full example that shows how this could be used: >

    let g:vimtex_toc_config_matchers = {
          \ 'beamer_frame': {'disable': 1},
          \ 'todo_fixme': {'priority': -1},
          \ 'index': {'title': 'MyFancy Index Title'},
          \}
<
  Note: The available built-in matchers are defined in separate files under
        `autoload/vimtex/parser/toc/*.vim`.

  Default value: {}

                                                    *toc_matcher_specification*
  A ToC matcher is defined as a |Dictionary| where the possible keys are
  specified below. In order to write a matcher, one should also be aware of
  the `context` argument that is passed to the matcher functions, as well as
  the specification of the `toc entry` return value. However, since this kind
  of customization is advanced I refer users to the source file for further
  specification of these objects. In particular, see the function
  `s:toc.parse(...)` in `autoload/vimtex/toc.vim`.

    re~
      Type: |String|
      Required: `yes`
      This specifies a regular expression that should match the current line
      for the desired ToC entry.

    prefilter_re~
      Type: |String|
      Required: `maybe` (this or `prefilter_cmds` should be specified)
      This specifies a regular expression that must match the current line for
      the desired ToC entry. This is used as a prefilter to make things
      faster, and it does not need to be a perfect match. The `re` key may
      often be a complex and therefore slow regular expression. This key
      should represent a simple and fast regular expression that may match
      more than the desired entry.

    prefilter_cmds~
      Type: List of |String|
      Required: `maybe` (this or `prefilter_re` should be specified)
      This is similar to `prefilter_re`, except it specifies a list of command
      names (regular expressions). For instance, it should contain `todo` for
      a ToC matcher for `\todo` commands.

    priority~
      Type: |expr-number| (default: 0)
      Required: `no`
      Priority is used for sorting the ToC matchers. High priority matchers
      will be tried first, and only one matcher will match a given line. Note
      that the built-in matchers have priority values between 0 and 2.

    in_preamble~
      Type: 0 or 1 (default: 0)
      Required: `no`
      If the entry may appear in the preamble.

    in_content~
      Type: 0 or 1 (default: 1)
      Required: `no`
      If the entry may appear in the main content.

    title~
      Type: |String|
      Required: `no`
      If the matcher does not have a `get_entry` key, then it will use
      a simple, general matcher function to generate the entry. In this case,
      the `title` key should be specified to give the title of the ToC entry.

    get_entry~
      Type: |Dictionary-function|
      Arguments: `context`
      Returns: `toc entry`
      Required: `no`
      This is the general way to define ToC entries. It allows to define the
      ToC entry based on the context. See `autoload/vimtex/parser/toc.vim` for
      examples on how to use this.

    continue~
      Type: |Dictionary-function|
      Arguments: `context`
      Returns: `toc entry`
      Required: `no`
      Some entries may be specified over several lines, in which case this key
      becomes necessary in combination with the `get_entry` key. See the built
      in `s:matcher_section` matcher for an example on how to use this.

    name~
      Type: |String|
      Required: `no`
      Mostly for making it easier to debug a specific matcher. Without a name,
      the matcher will be registered with a semi random numbered name like
      `custom1`.

    disable~
      Type: |Boolean| (default: |v:false|)
      Required: `no`
      If true, then the matcher will be disabled.

*g:vimtex_toc_custom_matchers*
  This option is a list of custom ToC matchers, see |toc_matcher_specification|.

  As an example, one can use this option to add ToC entries for a custom
  environment. Say you have defined an environment `mycustomenv`, then
  instances of this environment could be added to the ToC with the following
  configuration: >

    let g:vimtex_toc_custom_matchers = [
            \ { 'title' : 'My Custom Environment',
            \   're' : '\v^\s*\\begin\{mycustomenv\}' }
            \]
<
  Default value: []

*g:vimtex_toc_todo_labels*
  Dictionary of keywords that should be recognized in comments for the todo
  layer. The values represent the labels used in the ToC.

  Default value: `{'TODO': 'TODO: ', 'FIXME': 'FIXME: '}`

*g:vimtex_toc_show_preamble*
  Whether to include the preamble in the ToC.

  Default value: 1

*g:vimtex_view_enabled*
  Use this option to disable/enable the VimTeX viewer interface.

  Default value: 1

*g:vimtex_view_automatic*
  If enabled, the viewer will open automatically when compilation has started
  in `continuous` mode and if `callback` is enabled, or if `continuous` mode
  is disabled.

  `latexmk` will typically start the viewer directly.  However, with this
  option enabled, VimTeX will start the viewer through callbacks also for
  the |vimtex-latexrun|, |vimtex-arara| and |vimtex-tectonic| compilers.

  Default value: 1

*g:vimtex_view_use_temp_files*
  If nonzero, this will copy output files to a corresponding set of files
  with `_vimtex` prepended to the name. If one combines this with the callback
  feature, this may provide a very convenient way to avoid that the pdf
  becomes unavailable during compilation, as it will only update the viewer
  outut file after a successful compilation.

  The behaviour depends on the value:

    1: Copy output files after successful compilations and then update.
    2: Copy output files after all compilations and then update.

  Note: This is only relevant for the `latexmk` compiler backend. `latexrun`
        already ensures that the output file is updated only after the
        compilation is completed.

  Note: This will disable the viewer from the `latexmk` end. That is, if this
        option is enabled, opening and updating the pdf viewer will have to be
        done by the user or by VimTeX, even if `latexmk` is chosen as the
        compiler.

  Note: This works best with the 'mupdf' and 'zathura' viewers. In particular,
        these viewers should update automatically after the pdf is updated.
        For general viewers, one has to create a callback function and connect
        it through the |VimtexEventCompileSuccess| event to update the viewer.

  Default value: 0

*g:vimtex_view_forward_search_on_start*
  If disabled, the first invocation of the viewer will not perform a forward
  search to the current cursor position.

  Note: This option is only relevant for the following view methods (see
        |g:vimtex_view_method|):
        * |vimtex_viewer_mupdf|
        * |vimtex_viewer_zathura|

  Default value: 1

*g:vimtex_view_method*
  Set the viewer method.

  Note: The general viewer |vimtex_viewer_general| is a generic interface
        that allows sufficient customization for most viewer applications.

  Note: For reverse search with neovim, please see |vimtex-faq-neovim|.

  Possible values:
    'general' (default)
    'mupdf'
    'skim'
    'zathura'

    *vimtex_viewer_general*
      This is a generic interface where the viewer application is specified
      through |g:vimtex_view_general_viewer| and the viewer options are given
      with |g:vimtex_view_general_options|.  With the `latexmk` compiler, the
      viewer is started after successful compilation with the options provided
      by |g:vimtex_view_general_options_latexmk|.  The interface allows the
      general viewer to support forward search with a lot of different
      applications, such as the ones listed below.

      Note: For backward search to work, one needs to have a proper
            |clientserver|, see |vimtex-clientserver| for more info.

        *vimtex_viewer_okular*
          https://okular.kde.org/
          Okular is a very feature rich PDF viewer that supports forward
          and backward search. Recommended settings are: >

            let g:vimtex_view_general_viewer = 'okular'
            let g:vimtex_view_general_options = '--unique file:@pdf\#src:@line@tex'
            let g:vimtex_view_general_options_latexmk = '--unique'
<
          Backward search must be set up from the viewer through
          "Settings > Editor > Custom Text Editor". The following settings
          should work for Vim and neovim (Note: see |vimtex-faq-neovim|),
          respectively: >

            vim --remote-silent +%l %f
            nvr --remote-silent +%l %f

            " Or with arguably more convenient reverse goto function:
            vim --remote-expr "vimtex#view#reverse_goto(%l, '%f')"

            " nvr uses the server name /tmp/nvimsocket by default. If you
            " use a different server name, remember to specify it:
            nvr --servername /tmp/mynvimserver --remote-silent +%l "%f"
<
          Note: To perform a backward (or inverse) search in Okular, you do
                `shift + click` while browse mode is enabled, not `ctrl + click`
                as in most other viewers.

          Note: With |neovim|, it is useful to start the LaTeX editing session
                with `nvim --listen /tmp/mynvimserver` (e.g. by using an alias)
                so as to use a predictable servername. Then one may specify
                the servername in the "Custom Text Editor" as indicated above.

        *vimtex_viewer_evince*
          https://wiki.gnome.org/Apps/Evince
          > Evince is a document viewer for multiple document formats. The
          > goal of evince is to replace the multiple document viewers that
          > exist on the GNOME Desktop with a single simple application.

          Recommended settings are: >

            let g:vimtex_view_general_viewer = 'evince'
<
          Note: It is not so easy to setup forward and backward search with
                Evince [0]. If anyone has a good setup that could be
                documented here, please open an issue or email me. In the
                meantime, I can recommend to look into the other alternative
                viewers.

          [0]: https://github.com/lervag/vimtex/issues/179

        *vimtex_viewer_qpdfview*
          https://launchpad.net/qpdfview
          qpdfview is a tabbed document viewer. It supports forward search.
          Backward search must be set up from the viewer. >

            let g:vimtex_view_general_viewer = 'qpdfview'
            let g:vimtex_view_general_options
              \ = '--unique @pdf\#src:@tex:@line:@col'
            let g:vimtex_view_general_options_latexmk = '--unique'
<
        *vimtex_viewer_sumatrapdf*
          https://www.sumatrapdfreader.org/free-pdf-reader.html
          SumatraPDF is a PDF viewer for windows that is powerful, small,
          portable and starts up very fast. It supports forward search. The
          following settings are applied as defaults on Windows if
          `SumatraPDF` is detected as executable: >

            let g:vimtex_view_general_viewer = 'SumatraPDF'
            let g:vimtex_view_general_options
                \ = '-reuse-instance -forward-search @tex @line @pdf'
            let g:vimtex_view_general_options_latexmk = '-reuse-instance'
<
          Note: See |vimtex-faq-sumatrapdf| for more info on how to properly
                set up SumatraPDF for backward search.

          Note: There is a known issue with VimTeX + SumatraPDF when you use
                `xelatex`, where the pdf file in SumatraPDF is not refreshed
                after compilation. A workaround was found and posted by
                @Whitebeard0 here:
                https://github.com/lervag/vimtex/issues/1410#issuecomment-506143020

    *vimtex_viewer_mupdf*
      https://www.mupdf.com/
      A very minimalistic and quick PDF viewer.  Supports forward and backward
      search.  Backward search is available via xdotool (under Unix) with
      |:VimtexViewRSearch|, which is mapped to '<localleader>lr'.  One may also
      define a set of keys that is sent to MuPDF on startup with
      |g:vimtex_view_mupdf_send_keys|.

      Note: Both forward and backward search requires `xdotool` to work.
            Forward search will only take you to the correct page.  Backward
            search will take you to the line in Vim that corresponds to the
            first line of the current page in MuPDF.

      Note: Viewer handling uses window title matching. If there exists
            another pdf viewer with the same name as the current project pdf
            file, then there might be conflicts, and so MuPDF might not work
            as expected.

    *vimtex_viewer_skim*
      https://skim-app.sourceforge.net/
      Skim is a PDF reader and note-taker for OS X.  It is designed to help
      you read and annotate scientific papers in PDF, but is also great
      for viewing any PDF file. The VimTeX implementation supports forward
      search and uses a callback to update Skim after successful compilations.

      Note: One may set |g:vimtex_view_automatic| to 1 if one wants to prevent
            `latexmk` (or other build tools) from starting Skim and instead
            let VimTeX start Skim through the callback feature.

      Note: See |vimtex-faq-skimviewer| for more info on how to properly set
            up the Skim viewer for backward search.

    *vimtex_viewer_zathura*
      https://pwmt.org/projects/zathura/
      Zathura is, like MuPDF, a very fast and minimalistic viewer, but it
      allows more user configuration.  Zathura supports forward search and
      backward search.  Zathura should be straightforward to install and use
      on Linux with Xorg.  It should also work on macOS, but users may want to
      read |vimtex-faq-zathura-macos|.

      Note: Forward search requires `xdotool` to work properly, in order to
            not open a new Zathura instance for invocation of |:VimtexView|.

      Note: VimTeX attempts to pass the server name to zathura for use in
            reverse searches. neovim users should read |vimtex-faq-neovim|
            for more detail on configuration of neovim's client server
            functionality.

      Note: Recent versions of Zathura no longer ensures synctex support. This
            has resulted in synctex support being dropped on some platforms,
            e.g. on OpenSUSE, cf. https://github.com/lervag/vimtex/issues/384.
            A workaround is to build Zathura from source manually.

      Note: Viewer handling uses window title matching. If there exists
            another pdf viewer with the same name as the current project pdf
            file, then there might be conflicts. In particular, this might
            affect forward/backward searching for Zathura.

*g:vimtex_view_general_options*
  Set options for the specified general viewer, see |vimtex_viewer_general|.
  The options are parsed to substitute the following keywords:

    `@pdf`    Path to pdf file
    `@tex`    Path to tex file
    `@line`   Current line number
    `@col`    Current column number

  Default value: '@pdf'

*g:vimtex_view_mupdf_options*
*g:vimtex_view_zathura_options*
  Set options for mupdf/zathura (|vimtex_viewer_mupdf|, |vimtex_viewer_zathura|).

  Default value: ''

*g:vimtex_view_general_viewer*
  Use generic viewer application, see |vimtex_viewer_general|.

  Default value:
    Linux:   `xdg-open`
    macOS:   `open`
    Windows: `SumatraPDF` or `mupdf` if available, else `start`

*g:vimtex_view_general_options_latexmk*
  Set options that are passed on to `latexmk` for the specified general
  viewer, see |vimtex_viewer_general|.  This allows to send options that
  ensures a unique viewer, e.g. with |vimtex_viewer_qpdfview|. Only the
  `@line` escape is expanded.

  Note: This option is only relevant with |vimtex-latexmk| as the compiler.

  Default value: ''

*g:vimtex_view_mupdf_send_keys*
  A string of keys that will be sent to MuPDF just after the PDF file has been
  opened.

  Default value: ''

*g:vimtex_view_skim_activate*
  Set this option to 1 to make Skim have focus after command |:VimtexView| in
  addition to being moved to the foreground.

  Default value: 0

*g:vimtex_view_skim_reading_bar*
  Set this option to 1 to highlight current line in PDF after command
  |:VimtexView|.

  Default value: 1

*g:vimtex_view_zathura_check_libsynctex*
  Check on startup if Zathura is compiled with libsynctex. This is done by
  default because Zathura on some systems is compiled without libsynctex
  support, in which case forward and backward search will not work. When this
  is the case, the startup check will provide a notification to the user.

  If this option is set to 0 or |v:false|, then the check is skipped.

  Default value: 1

*$VIMTEX_OUTPUT_DIRECTORY*
  This environment variable allows to specify the output directory of
  auxiliary LaTeX files. If it exists and is a valid path, this path will be
  used as the output directory (aka build directory). That is, it overrides
  options such as |g:vimtex_compiler_latexmk| / `build_dir`. This has two main
  use cases:

    1. It allows to use a custom build directory for different projects.
    2. It allows to specify an output directory for projects where one uses
       compiler backends such as |vimtex-arara|. This makes it possible to
       make e.g. the |vimtex-view| feature to work as expected if output
       directories are used with arara.

------------------------------------------------------------------------------
COMMANDS                                                      *vimtex-commands*

                                             *:VimtexContextMenu*
                                             *<plug>(vimtex-context-menu)*
:VimtexContextMenu        Show a context menu on the item below cursor. See
                          |vimtex-context-menu| for more information.

                                             *:VimtexInfo*
                                             *<plug>(vimtex-info)*
:VimtexInfo               Show information that is stored by VimTeX about the
                          current LaTeX project (available mostly for debug
                          purposes).

                                             *:VimtexInfo!*
                                             *<plug>(vimtex-info-full)*
:VimtexInfo!              Show information that is stored by VimTeX about all
                          open LaTeX projects (available mostly for debug
                          purposes).

                                             *:VimtexDocPackage*
                                             *<plug>(vimtex-doc-package)*
:VimtexDocPackage         Show documentation for packages. The command takes
                          one optional argument, which is the name of the
                          package to show docs for. If no argument is
                          supplied, it parses the command under the cursor and
                          opens the most relevant documentation.

                                             *:VimtexRefreshFolds*
:VimtexRefreshFolds       Refresh folds, see |vimtex-zx|.

                                             *:VimtexTocOpen*
                                             *<plug>(vimtex-toc-open)*
:VimtexTocOpen            Open table of contents.

                                             *:VimtexTocToggle*
                                             *<plug>(vimtex-toc-toggle)*
:VimtexTocToggle          Toggle table of contents.

                                             *:VimtexLog*
                                             *<plug>(vimtex-log)*
:VimtexLog                Open a scratch buffer to show message log with
                          timestamps and traces from where the messages were
                          raised. To close the log buffer, one may press `q`
                          or `<esc>`.

                                             *:VimtexCompile*
                                             *<plug>(vimtex-compile)*
:VimtexCompile            If the compiler supports and is set to run in
                          continuous mode, then this command works as
                          a compiler toggle. If not, this command will run
                          a single shot compilation.

                                             *:VimtexCompileSS*
                                             *<plug>(vimtex-compile-ss)*
:VimtexCompileSS          Start single shot compilation.

                                             *:VimtexCompileSelected*
                                             *<plug>(vimtex-compile-selected)*
:VimtexCompileSelected    Compile the selected part of the current LaTeX file.
                          When used as a command, it takes a range, e.g.: >

                            :start,end VimtexCompileSelected

<                          When used as a normal mode mapping, the mapping
                          will act as an |operator| on the following motion or
                          text object. Finally, when used as a visual mode
                          mapping, it will act on the selected lines.

                          Note: This always works linewise!

                          The command compiles the selected text by copying it
                          to a temporary file with the same preamble as the
                          current file. It will be compiled similarly to
                          a single shot compile (see |:VimtexCompileSS|. If
                          there are errors, they will be shown in the quickfix
                          list.

                          One may specify a custom template with a template
                          file in which any (single!) line with the exact
                          content `%%% VIMTEX PLACEHOLDER` will be
                          interchanged with the selected lines. This allows to
                          customize the preamble and surrounding content. The
                          template file should be named `vimtex-template.tex`
                          or `<head>-vimtex-template.tex`, where `<head>`
                          implies the head of the current file name with the
                          extension removed. E.g., for a file `foo.tex`, one
                          may specify a custom template
                          `foo-vimtex-template.tex`. This will have a higher
                          priority than `vimtex-template.tex`.

                                             *:VimtexCompileOutput*
                                             *<plug>(vimtex-compile-output)*
:VimtexCompileOutput      Open file where compiler output is redirected.

                                             *:VimtexStop*
                                             *<plug>(vimtex-stop)*
:VimtexStop               Stop compilation for the current project.

                                             *:VimtexStopAll*
                                             *<plug>(vimtex-stop-all)*
:VimtexStopAll            Stop compilation for all open projects in the
                          current vim instance.

                                             *:VimtexStatus*
                                             *<plug>(vimtex-status)*
:VimtexStatus             Show compilation status for current project.

                                             *:VimtexStatus!*
                                             *<plug>(vimtex-status-all)*
:VimtexStatus!            Show compilation status for all open projects in the
                          current vim instance.

                                             *:VimtexClean*
                                             *<plug>(vimtex-clean)*
:VimtexClean              Clean auxiliary files.

                          Note: If compilation is running continuously in the
                                background (which is the default behaviour),
                                then this command will first temporarily stop
                                compilation, then execute the clean command,
                                and finally restart the compilation.

                                             *:VimtexClean!*
                                             *<plug>(vimtex-clean-full)*
:VimtexClean!             As |:VimtexClean|, but also remove output files.

                                             *:VimtexErrors*
                                             *<plug>(vimtex-errors)*
:VimtexErrors             Open |quickfix| window if there are errors or
                          warnings.

                                             *:VimtexView*
                                             *<plug>(vimtex-view)*
:VimtexView               View `pdf` for current project, perform forward
                          search if available.

                                             *:VimtexViewRSearch*
                                             *<plug>(vimtex-reverse-search)*
:VimtexViewRSearch        Do reverse search (only available for MuPDF viewer),
                          see also |vimtex_viewer_mupdf|.

                                             *:VimtexReload*
                                             *<plug>(vimtex-reload)*
:VimtexReload             Reload VimTeX scripts. This is primarely useful
                          when developing and debugging VimTeX itself.

                                             *:VimtexReloadState*
                                             *<plug>(vimtex-reload-state)*
:VimtexReloadState        Reload the state for the current buffer.

                                             *:VimtexCountLetters*
                                             *:VimtexCountWords*
                                             *vimtex#misc#wordcount(opts)*
:VimtexCountLetters       Shows the number of letters/characters or words in
:VimtexCountWords         the current project or in the selected region. The
                          count is created with `texcount` through a call on
                          the main project file similar to: >

                            texcount -nosub -sum [-letter] -merge -q -1 FILE
<
                          Note: Default arguments may be controlled with
                                |g:vimtex_texcount_custom_arg|.

                          Note: One may access the information through the
                                function `vimtex#misc#wordcount(opts)`, where
                                `opts` is a dictionary with the following
                                keys (defaults indicated): >

                                'range' : [1, line('$')]
                                'count_letters' : 0/1
                                'detailed' : 0
<
                                If `detailed` is 0, then it only returns the
                                total count. This makes it possible to use for
                                e.g. statusline functions. If the `opts` dict
                                is not passed, then the defaults are assumed.

                                             *:VimtexCountLetters!*
                                             *:VimtexCountWords!*
:VimtexCountLetters!      Similar to |:VimtexCountLetters|/|:VimtexCountWords|, but
:VimtexCountWords!        show separate reports for included files.  I.e.
                          presents the result of: >

                            texcount -nosub -sum [-letter] -inc FILE
<
                                             *:VimtexImapsList*
                                             *<plug>(vimtex-imaps-list)*
:VimtexImapsList          Show the list of insert mode mappings created by the
                          |vimtex-imaps| feature. The mappings are displayed
                          in a scratch buffer. Press `q` or `<esc>` to close
                          the buffer.

                                             *:VimtexToggleMain*
                                             *<plug>(vimtex-toggle-main)*
:VimtexToggleMain         In general, VimTeX detects the main file for the
                          current LaTeX project and uses it for compilation
                          and many other features. However, in some cases it
                          may be useful to instead focus on the current file,
                          for instance in large projects. In such cases, one
                          can use |:VimtexToggleMain| to change which file to
                          use as the "current project". It is easy to toggle
                          back and forth, and both the "main project" and the
                          "local project" can be used simultaneously if
                          desired (e.g. for compilation).

                          Note: To compile the current file when it is part of
                                a larger project, one must of course include
                                a preamble and the `\begin/\end{document}`! It is
                                possible to have a working preamble in every
                                file in a multi-file project with `subfiles`,
                                see |vimtex-subfiles|. See also
                                |g:vimtex_subfile_start_local|.

------------------------------------------------------------------------------
MAP DEFINITIONS                                               *vimtex-mappings*

*vimtex-zx*
  When VimTeX folding is enabled and when the manual mode is turned on
  (|g:vimtex_fold_manual|), then VimTeX remaps |zx| and |zX| in such that
  the folds are refreshed appropriately.

*<plug>(vimtex-env-delete)*
*<plug>(vimtex-env-delete-math)*
*<plug>(vimtex-env-change)*
*<plug>(vimtex-env-change-math)*
  Delete/Change surrounding environment. When changing, there will be
  sensible completion candidates, see |cmdline-completion|. See also
  |g:vimtex_env_change_autofill| and |g:vimtex_echo_verbose_input|.

*<plug>(vimtex-cmd-delete)*
*<plug>(vimtex-cmd-delete-math)*
*<plug>(vimtex-cmd-change)*
  Delete/Change surrounding command. See also |g:vimtex_echo_verbose_input|.

*<plug>(vimtex-delim-delete)*
*<plug>(vimtex-delim-change-math)*
  Delete/Change surrounding (math) delimiter. See also
  |g:vimtex_echo_verbose_input|.

*<plug>(vimtex-cmd-toggle-frac)*
  Toggle fractions between inline mode (`num/den`) and command mode
  (`\frac{num}{den}`).

  In visual mode, the selected text is toggled if it matches either
  a `\frac{}{}` command or a `numerator / denominator` string. In normal mode,
  we try to detect the surrounding fraction command or inline fraction
  expression. If successful, the detected fraction is toggled.

*<plug>(vimtex-cmd-toggle-star)*
*<plug>(vimtex-env-toggle-star)*
  Toggle starred command/environment.

*<plug>(vimtex-delim-toggle-modifier)*
*<plug>(vimtex-delim-toggle-modifier-reverse)*
  Toggle delimiter modifiers, by default alternating between `(...)` and
  `\left(...\right)`.  The normal mode mapping toggles the closest surrounding
  delimiter, whereas the visual mode mapping toggles all delimiters that are
  fully contained in the visual selection.  The visual selection is preserved.

  When |g:vimtex_delim_toggle_mod_list| is set to contain more than one set of
  modifiers, these mappings iterate through the list instead of just toggling.
  For example, one may alternate between `(...)`, `\bigl(...\bigr)`,
  `\Bigl(...\Bigr)`, and so on.  These mappings accept a [count], which allows
  the modifier to be incremented multiple steps at a time.  The `-reverse`
  mapping goes backwards through the modifier list instead of forwards.

  See also |g:vimtex_delim_toggle_mod_list| and |g:vimtex_delim_list|.

*<plug>(vimtex-cmd-create)*
  This mapping works in both insert mode, normal mode and visual mode. It is
  mapped by default to <f7>. See below for the behaviour in the different
  modes.

  Insert mode:
    Convert the preceding text into a LaTeX command. That is, it prepends
    a backslash and adds an opening brace. It also moves the cursor to the end
    of the word.

  Normal/Visual mode:
    Surrounds the word under the cursor/visual selection by the command
    provided in an input prompt.

*<plug>(vimtex-delim-close)*
  Close the current environment or delimiter (insert mode).


Note: The following describe text objects and motions. For the text objects,
the usual convention is used where the "a" select "a"n object, including the
whitespace/delimiters/etc, whereas the "i" selects the corresponding "inner"
object, see |text-objects|.

*<plug>(vimtex-ac)*
*<plug>(vimtex-ic)*
  Text object for commands.

*<plug>(vimtex-ad)*
*<plug>(vimtex-id)*
  Text object for delimiters.

*<plug>(vimtex-ae)*
*<plug>(vimtex-ie)*
  Text object for environments.

*<plug>(vimtex-a$)*
*<plug>(vimtex-i$)*
  Text object for inline math.

*<plug>(vimtex-aP)*
*<plug>(vimtex-iP)*
  Text object for sections.

*<plug>(vimtex-am)*
*<plug>(vimtex-im)*
  Text object for items.

*<plug>(vimtex-%)*
  Find matching pair.

*<plug>(vimtex-]])*
  go to [count] next end of a section.
  |exclusive| motion.

*<plug>(vimtex-][)*
  go to [count] next beginning of a section.
  |exclusive| motion.

*<plug>(vimtex-[])*
  go to [count] previous end of a section.
  |exclusive| motion.

*<plug>(vimtex-[[)*
  go to [count] previous beginning of a section.
  |exclusive| motion.

*<plug>(vimtex-]m)*
  go to [count] next start of an environment `\begin`.
  |exclusive| motion.

*<plug>(vimtex-]M)*
  go to [count] next end of an environment `\end`.
  |exclusive| motion.

*<plug>(vimtex-[m)*
  go to [count] previous start of an environment `\begin`.
  |exclusive| motion.

*<plug>(vimtex-[M)*
  go to [count] previous end of an environment `\end`.
  |exclusive| motion.

*<plug>(vimtex-]n)*
  go to [count] next start of a math zone.
  |exclusive| motion.

*<plug>(vimtex-]N)*
  go to [count] next end of a math zone.
  |exclusive| motion.

*<plug>(vimtex-[n)*
  go to [count] previous start of a math zone.
  |exclusive| motion.

*<plug>(vimtex-[N)*
  go to [count] previous end of a math zone.
  |exclusive| motion.

*<plug>(vimtex-]r)*
  go to [count] next start of a frame environment.
  |exclusive| motion.

*<plug>(vimtex-]R)*
  go to [count] next end of a frame environment.
  |exclusive| motion.

*<plug>(vimtex-[r)*
  go to [count] previous start of a frame environment.
  |exclusive| motion.

*<plug>(vimtex-[R)*
  go to [count] previous end of a frame environment.
  |exclusive| motion.

*<plug>(vimtex-]/)*
  go to [count] next start of a LaTeX comment "%".
  |exclusive| motion.

*<plug>(vimtex-]star)*
  go to [count] next end of a LaTeX comment "%".
  |exclusive| motion.

*<plug>(vimtex-[/)*
  go to [count] previous start of a LaTeX comment "%".
  |exclusive| motion.

*<plug>(vimtex-[star)*
  go to [count] previous end of a LaTeX comment "%".
  |exclusive| motion.

------------------------------------------------------------------------------
INSERT MODE MAPPINGS                                             *vimtex-imaps*

Some LaTeX commands are very common, and so it is both natural and convenient
to have insert mode mappings/abbreviations for them. VimTeX therefore
provides a list of such mappings that are enabled by default, see
|g:vimtex_imaps_list|. The mappings utilize a map leader defined by
|g:vimtex_imaps_leader|. The default list of maps are all math mode mappings,
but one may also add mappings that are available and useful outside of math
mode. To see the list of mappings that are created, one can use the command
|:VimtexImapsList|, which is by default mapped to `<localleader>lm`.

It is of course possible to customize the list of mappings. First, one may
specifically disable the entire imaps feature with |g:vimtex_imaps_enabled| or
specific default mappings through |g:vimtex_imaps_disabled|. Second, one may
specify |g:vimtex_imaps_list|, which will overwrite the default list. Finally,
one may add new maps through calls to the function |vimtex#imap#add_map|. The
following are some examples of how to customize the mappings: >

  " Disable \alpha and \beta mappings
  let g:vimtex_imaps_disabled = ['a', 'b']

  " Add custom mapping through vimtex#imap#add_map
  call vimtex#imaps#add_map({
        \ 'lhs' : 'test',
        \ 'rhs' : '\tested',
        \ 'wrapper' : 'vimtex#imaps#wrap_trivial'
        \})

  " Add custom mapping: #rX -> \mathrm{X}
  call vimtex#imaps#add_map({
        \ 'lhs' : 'r',
        \ 'rhs' : 'vimtex#imaps#style_math("mathrm")',
        \ 'expr' : 1,
        \ 'leader' : '#',
        \ 'wrapper' : 'vimtex#imaps#wrap_math'
        \})
<
                                                         *vimtex#imaps#add_map*

This function is used to add new insert mode mappings. It takes a single
dictionary argument: >

  map = {
    \ 'lhs' : lhs,
    \ 'rhs' : rhs,
    \ 'expr' : bool,
    \ 'leader' : leader_key,
    \ 'wrapper' : function_name,
    \ 'context' : value,
    \ }

Explanation of the keys:

  lhs~
    Mandatory argument. The left-hand side part of the map.

  lhs_rhs~
    Mandatory argument. The right-hand side part of the map. There is one
    utility function that can be useful:

      *vimtex#imaps#style_math*
        Wraps the RHS inside a specified command, e.g. `\myarg{RHS}`, if the
        cursor is inside math mode.

  expr~
    Either 0/|v:false| or 1/|v:true| (default: 0). If true, then the
    right-hand side is evaluated before it is passed to the wrapper.
    This is necessary e.g. for use with |vimtex#imaps#style_math|.

  leader~
    Custom leader key. If the key is not present, then |g:vimtex_imaps_leader|
    is used as leader key.

  wrapper~
    The name of a wrapper function that is used to generate the `rhs`. Two
    functions are available from VimTeX:

      *vimtex#imaps#wrap_trivial*
        Trivial wrapper: Simply returns `rhs`.

      *vimtex#imaps#wrap_math*
        Only define `rhs` if inside a math environment. This is the default
        wrapper function and will be used if no other wrapper is supplied.

      *vimtex#imaps#wrap_environment*
        Only define `rhs` if inside a specified environment. The wrapper works
        by utilizing the `context` key, which is a list that contains strings
        and/or dictionaries:

          i.  If the entry is a string, then the `lhs` is mapped to `rhs`
              inside the specified environment.
          ii. If the entry is a dictionary, then we assume it has two entries,
              `envs` and `rhs`, where `envs` is a list of environment names.
              If inside any environment in this list, then we expand to the
              corresponding `rhs`. This allows one to create a mapping that
              expands to different `rhs`s in different environments.

    Of course, one may use custom wrapper functions. To write a custom wrapper
    function, please see the source for examples on how the VimTeX wrappers
    are written.

  context~
    A value that can be used by the chosen wrapper function.

                                                            *vimtex-neosnippet*
                                                             *vimtex-UltiSnips*
Note: that this feature is not the same as the snippet feature of |UltiSnips|
or |neosnippet|. The imaps feature of VimTeX previously supported `automatic`
snippets, but these have been removed after careful considerations and input
from VimTeX users, please see VimTeX issue #295:
https://github.com/lervag/vimtex/issues/295#issuecomment-164262446
It has been decided that the best approach is to only provide basic mappings,
and to let users manully create automatic snippets through the anonymous
snippet functions in |UltiSnips| and |neosnippet|, please see |UltiSnips#Anon|
and |neosnippet#anonymous|, respectively. Here are a couple of examples that
show how to create such mappings: >

    " Using neosnippet#anonymous
    inoremap <silent><expr> __ neosnippet#anonymous('_${1}${0}')
    inoremap <silent><expr> ^^ neosnippet#anonymous('^${1}${0}')

    " Using UltiSnips#Anon
    inoremap <silent> __ __<c-r>=UltiSnips#Anon('_{$1}$0', '__', '', 'i')<cr>
    inoremap <silent> ^^ ^^<c-r>=UltiSnips#Anon('^{$1}$0', '^^', '', 'i')<cr>

A drawback with the anonymous UltiSnips snippets is that they do not nest.
That is, if you did `__` twice in a row, only the second one could be escaped.
In recent versions of |UltiSnips|, one may set normal snippets to trigger
automatically, see |UltiSnips-autotrigger|. This allows nesting, and is
therefore a better approach than using the anonymous snippet function.

------------------------------------------------------------------------------
EVENTS                                                          *vimtex-events*

VimTeX defines some events using the |User| autocmd that may be used for
further customization.

  *VimtexEventQuit*
    This event is triggered when the last buffer for a particular LaTeX project
    is wiped (for example, using `:bwipeout`) and when Vim is quit.  The event
    may be used, for instance, to cleanup up auxiliary build files or close
    open viewers (see Examples below).  With Vim defaults, this event is not
    triggered when using `:quit` or `:bdelete` since these commands merely hide
    the buffer.  In multi-file projects, the event may be triggered multiple
    times.  The 'b:vimtex' variable contains context data for the quitting
    file or project.  For example, 'b:vimtex.tex' identifies the tex file being
    wiped, or the main tex file of a multi-file project.

    Note: Commands such as |:VimtexClean| cannot be used in this autocommand
    because when quitting vim the current buffer does not necessarily have
    filetype 'tex'.

  *VimtexEventInitPre*
  *VimtexEventInitPost*
    This event is triggered at the start/end of VimTeX initialization.  The
    post event may e.g. be used to automatically start compiling a document.

  *VimtexEventCompileStarted*
    This event is triggered after compilation is started (in continuous mode).

  *VimtexEventCompileStopped*
    This event is triggered after compilation is stopped.

  *VimtexEventCompileSuccess*
  *VimtexEventCompileFailed*
    These events are triggered after successful/failed compilation and
    allows users to add custom callback functionality.

  *VimtexEventTocCreated*
    This event is triggered after a ToC window is created.

  *VimtexEventTocActivated*
    This event is triggered when a ToC entry has been activated. This allows
    to add custom behaviour after opening an entry, e.g. positioning the
    buffer window with the |zt| or |zz| mappings.

  *VimtexEventView*
    This event is triggered after the viewer has opened/forward search has
    been performed by the command |:VimtexView| or the related mapping.

Examples: >

  " Compile on initialization, cleanup on quit
  augroup vimtex_event_1
    au!
    au User VimtexEventQuit     VimtexClean
    au User VimtexEventInitPost VimtexCompile
  augroup END

  " Close viewers when VimTeX buffers are closed
  function! CloseViewers()
    " Close viewers on quit
    if executable('xdotool') && exists('b:vimtex')
        \ && exists('b:vimtex.viewer') && b:vimtex.viewer.xwin_id > 0
      call system('xdotool windowclose '. b:vimtex.viewer.xwin_id)
    endif
  endfunction

  augroup vimtex_event_2
    au!
    au User VimtexEventQuit call CloseViewers()
  augroup END

  " Add custom mappings in ToC buffer
  function! TocMappings()
    " You probably don't want to do this, though...
    nnoremap <silent><buffer><nowait> q :quitall!
  endfunction

  augroup vimtex_event_3
    au!
    au User VimtexEventTocCreated call TocMappings()
  augroup END

  " Specify window position when opening ToC entries
  augroup vimtex_event_4
    au!
    au User VimtexEventTocActivated normal! zt
  augroup END


==============================================================================
COMPLETION                                                  *vimtex-completion*

If |g:vimtex_complete_enabled| is 1 (default), then VimTeX sets the
'omnifunc' to provide omni completion, see |compl-omni|.  Omni completion is
then accessible with |i_CTRL-X_CTRL-O|.

The omni completion completes citations, labels, glossary entries and
filenames. If desired, one may set |g:vimtex_complete_close_braces|, which
makes the completion include closing braces.

Associated settings:
* |g:vimtex_complete_bib|
* |g:vimtex_complete_close_braces|
* |g:vimtex_complete_enabled|
* |g:vimtex_complete_ignore_case|
* |g:vimtex_complete_ref|
* |g:vimtex_complete_smart_case|

------------------------------------------------------------------------------
COMPLETE CITATIONS                                      *vimtex-complete-cites*

Citation completion is triggered by '\cite{' commands.  The completion parses
included bibliography files (`*.bib`) and `thebibliography` environments to
gather the completion candidates.

By default, cite completion is "smart" in that it allows to complete on
author name, title and similar. As an example, assume that a bibliography file
is included with the following entry: >

        @book { knuth1981,
                author = "Donald E. Knuth",
                title = "Seminumerical Algorithms",
                publisher = "Addison-Wesley",
                year = "1981" }

Then the bibliography key `knuth1981` will be completed with e.g.: >

        \cite{Knuth 1981<CTRL-X><CTRL-O>
        \cite{algo<CTRL-X><CTRL-O>
        \cite{Don.*Knuth<CTRL-X><CTRL-O>

In particular, note that regular expressions (or vim patterns) can be used
after '\cite{' to search for candidates. By default, the regex is applied to
the completion menu, which is defined by |g:vimtex_complete_bib.menu_fmt|.

However, if one prefers, one may set the `simple` key of |g:vimtex_complete_bib|
to only allow completion on the bibkeys directly. This should typically work
better with autocomplete plugins.

------------------------------------------------------------------------------
COMPLETE LABELS                                        *vimtex-complete-labels*

Label completion is triggered by `\ref{` commands.  The completion parses every
relevant aux file to gather the completion candidates.  This is important,
because it means that the completion only works when the LaTeX document has
been compiled.

As an example: >

        \ref{sec:<CTRL-X><CTRL-O>

offers a list of all matching labels with a menu that contains the associated
value and page number.

The completion base is matched as a regex in the following order: >

        \ref{<base><CTRL-X><CTRL-O>
<
    1. The menu, which contains the reference value and page number.
    2. The actual labels.
    3. The menu and label, separated by whitespace. An example: >

        \ref{eq 2<CTRL-X><CTRL-O>
<
       This matches "eq" in the label and "2" in the menu.

Finally, it should also be mentioned that for `\eqref`, the candidates will
automatically be filtered to only show equation references.

------------------------------------------------------------------------------
COMPLETE COMMANDS AND ENVIRONMENTS                   *vimtex-complete-commands*
                                                 *vimtex-complete-environments*

Command completion is available after `\` and should provide completion
candidates for relevant LaTeX commands.  The document's preamble is analysed,
and commands will be completed for the loaded packages as well as those
defined within the preamble using `\newcommand`, `\let` and `\def`.  Environment
completion is also available after `\begin{` or `\end{`.  As with commands, the
suggested environment names come from the loaded packages and `\newenvironment`
definitions in the preamble.

A lot of packages are supported, see the path `VIMTEX/autoload/vimtex/complete`
for a relevant file listing.

------------------------------------------------------------------------------
COMPLETE FILE NAMES                                 *vimtex-complete-filenames*

File name completion is available for the following macros:

  `\includegraphics{`
    Completes image file names.

  `\input{`
  `\include{`
  `\includeonly{`
    Complete `.tex` files.

  `\includepdf{`
    Complete `.pdf` files. This macro is provided by the `pdfpages` package.

  `\includestandalone{`
    Complete `.tex` files. This macro is provided by the `standalone` package.

------------------------------------------------------------------------------
COMPLETE INCLUDE GLOSSARY ENTRIES                    *vimtex-complete-glossary*

Glossary entry completion from the `glossaries` package are triggered by the
commands '\gls{', '\glspl{' and their variations.

------------------------------------------------------------------------------
COMPLETE PACKAGE FILES                               *vimtex-complete-packages*
                                                      *vimtex-complete-classes*
                                                     *vimtex-complete-bibstyle*

Package, documentclass, and bibliography style completion are available for
the `\usepackage{`, `\documentclass{`, and `\bibliographystyle` commands,
respectively.

The completion relies on the contents of `ls-R` files that are found with: >

  kpsewhich --all ls-R

Packages and documentclasses installed at `TEXMFHOME` will also be searched.
The default value can be found with: >

  kpsewhich --var-value TEXMFHOME

Note: If you want to change the default value of `TEXMFHOME` in your shell
      startup file and use `gvim` started from the desktop environment, please
      read |vimtex-faq-texmfhome|.

------------------------------------------------------------------------------
AUTOCOMPLETE                                             *vimtex-complete-auto*

Vim does not provide automatic completion by itself, but there exist at least
several good plugins that provide this: |coc-nvim|, |deoplete|, |neocomplete|, |ncm2|,
|nvim-completion-manager| and |youcompleteme|.  Moreover, there is |VimCompletesMe|
that overrides <tab> to trigger different built-in completions, such as the
omni-completion by VimTeX, depending on the context. See below for
descriptions on how to setup these with VimTeX.

coc.nvim~
                                                     *vimtex-complete-coc.nvim*
|coc-nvim| is an intellisense engine for Vim8 & Neovim. It's a completion
framework and language server client which supports extension features of
Visual Studio Code. The project is here: https://github.com/neoclide/coc.nvim.

|coc-nvim| can be installed using vim-plug: >

  Plug 'neoclide/coc.nvim'

However, it does require some more steps, and users are recommended to read
the installation instructions in the `coc.nvim` wiki:
https://github.com/neoclide/coc.nvim/wiki/Install-coc.nvim

To configure for VimTeX, one should use the extension plugin |coc-vimtex|,
which may be found here: https://github.com/neoclide/coc-vimtex. To use it,
first make sure you have |coc-nvim| installed, then just run: >

  :CocInstall coc-vimtex

The `coc-vimtex` extension has a few options that can be configured in the
`coc-settings.json` file. See the documentation for |coc-nvim| to learn how to
apply the configurations. The following is a list of the options with a short
description as it is specified on the project web page: >

  coc.source.vimtex.disableSyntaxes    disabled syntax names
  coc.source.vimtex.enable             set to false to disable this source
  coc.source.vimtex.priority           priority of source, default 99
  coc.source.vimtex.shortcut           shortcut used in menu of completion item

Note: The README of `coc.nvim` suggests using `noremap K` to show
documentation. `K` is also used by VimTeX as one of the default maps (see
|vimtex-default-mappings|) for the same purpose. To enable VimTeX's mapping
for `.tex` files (since `coc.nvim` does not have a doc source), do one of the
following:

* Manually remap for `.tex` files: Put the following in your
  `$HOME/.vim/after/ftplugin/tex.vim:` >

    map <buffer> K <Plug>(vimtex-doc-package)

* Use a custom function in your |vimrc| file, something like this: >

    nnoremap <silent> K :call <sid>show_documentation()<cr>
    function! s:show_documentation()
      if index(['vim', 'help'], &filetype) >= 0
        execute 'help ' . expand('<cword>')
      elseif &filetype ==# 'tex'
        VimtexDocPackage
      else
        call CocAction('doHover')
      endif
    endfunction

deoplete~
                                                     *vimtex-complete-deoplete*
|deoplete| is a modern remake of |neocomplete|, and was originally written
specifically for Neovim, see here: https://github.com/Shougo/deoplete.nvim. It
is a highly customizable and flexible completion manager.

To configure for VimTeX, one may use: >

  " This is new style
  call deoplete#custom#var('omni', 'input_patterns', {
          \ 'tex': g:vimtex#re#deoplete
          \})

  " This is old style (deprecated)
  if !exists('g:deoplete#omni#input_patterns')
      let g:deoplete#omni#input_patterns = {}
  endif
  let g:deoplete#omni#input_patterns.tex = g:vimtex#re#deoplete

neocomplete~
                                                  *vimtex-complete-neocomplete*
|neocomplete| is also a flexible automatic completion engine for vim, although
active development has been stopped. Users are recommended to change to
|deoplete|, see also |vimtex-complete-deoplete|. The plugin is available here:
https://github.com/Shougo/neocomplete.vim.

The following options may be used to enable automatic completion for LaTeX
documents with |neocomplete| and VimTeX's omni completion function: >

  if !exists('g:neocomplete#sources#omni#input_patterns')
    let g:neocomplete#sources#omni#input_patterns = {}
  endif
  let g:neocomplete#sources#omni#input_patterns.tex =
        \ g:vimtex#re#neocomplete

ncm2~
                                                         *vimtex-complete-ncm2*
|ncm2| is a modern remake and replacement of |nvim-completion-manager| and is
supposed to be a "Slim, Fast and Hackable Completion Framework for Neovim":
https://github.com/ncm2/ncm2

The following simple configuration should work well with VimTeX: >

  " include the following plugins (here using junnegun/vim-plug)
  Plug 'roxma/nvim-yarp'
  Plug 'ncm2/ncm2'

  set completeopt=noinsert,menuone,noselect

  augroup my_cm_setup
    autocmd!
    autocmd BufEnter * call ncm2#enable_for_buffer()
    autocmd Filetype tex call ncm2#register_source({
            \ 'name': 'vimtex',
            \ 'priority': 8,
            \ 'scope': ['tex'],
            \ 'mark': 'tex',
            \ 'word_pattern': '\w+',
            \ 'complete_pattern': g:vimtex#re#ncm2,
            \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'],
            \ })
  augroup END
<
For more lenient, omni-complete-like, filtering of completion candidates,
use the following setup (in your init.vim or a personal ftplugin) instead: >

  augroup my_cm_setup
    autocmd!
    autocmd BufEnter * call ncm2#enable_for_buffer()
    autocmd Filetype tex call ncm2#register_source({
            \ 'name' : 'vimtex-cmds',
            \ 'priority': 8,
            \ 'complete_length': -1,
            \ 'scope': ['tex'],
            \ 'matcher': {'name': 'prefix', 'key': 'word'},
            \ 'word_pattern': '\w+',
            \ 'complete_pattern': g:vimtex#re#ncm2#cmds,
            \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'],
            \ })
    autocmd Filetype tex call ncm2#register_source({
            \ 'name' : 'vimtex-labels',
            \ 'priority': 8,
            \ 'complete_length': -1,
            \ 'scope': ['tex'],
            \ 'matcher': {'name': 'combine',
            \             'matchers': [
            \               {'name': 'substr', 'key': 'word'},
            \               {'name': 'substr', 'key': 'menu'},
            \             ]},
            \ 'word_pattern': '\w+',
            \ 'complete_pattern': g:vimtex#re#ncm2#labels,
            \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'],
            \ })
    autocmd Filetype tex call ncm2#register_source({
            \ 'name' : 'vimtex-files',
            \ 'priority': 8,
            \ 'complete_length': -1,
            \ 'scope': ['tex'],
            \ 'matcher': {'name': 'combine',
            \             'matchers': [
            \               {'name': 'abbrfuzzy', 'key': 'word'},
            \               {'name': 'abbrfuzzy', 'key': 'abbr'},
            \             ]},
            \ 'word_pattern': '\w+',
            \ 'complete_pattern': g:vimtex#re#ncm2#files,
            \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'],
            \ })
    autocmd Filetype tex call ncm2#register_source({
            \ 'name' : 'bibtex',
            \ 'priority': 8,
            \ 'complete_length': -1,
            \ 'scope': ['tex'],
            \ 'matcher': {'name': 'combine',
            \             'matchers': [
            \               {'name': 'prefix', 'key': 'word'},
            \               {'name': 'abbrfuzzy', 'key': 'abbr'},
            \               {'name': 'abbrfuzzy', 'key': 'menu'},
            \             ]},
            \ 'word_pattern': '\w+',
            \ 'complete_pattern': g:vimtex#re#ncm2#bibtex,
            \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'],
            \ })
  augroup END
<
nvim-completion-manager~
                                                          *vimtex-complete-ncm*
Note: |nvim-completion-manager| has been replaced by |ncm2|, and users are
recommended to change. See |vimtex-complete-ncm2| for hints on how to setup
|ncm2| for VimTeX.

|nvim-completion-manager| is a fast, extensible, async completion framework
for neovim (and Vim version 8.0 and above).  The project is available here:
https://github.com/roxma/nvim-completion-manager

To configure for VimTeX, one can use the following code: >

  augroup my_cm_setup
    autocmd!
    autocmd User CmSetup call cm#register_source({
          \ 'name': 'vimtex',
          \ 'priority': 8,
          \ 'scoping': 1,
          \ 'scopes': ['tex'],
          \ 'abbreviation': 'tex',
          \ 'cm_refresh_patterns': g:vimtex#re#ncm,
          \ 'cm_refresh': {'omnifunc': 'vimtex#complete#omnifunc'},
          \ })
  augroup END

YouCompleteMe~
                                                *vimtex-complete-youcompleteme*
|youcompleteme| is probably the most popular code-completion engine for Vim.  The
github repository is here: https://github.com/ycm-core/YouCompleteMe.
It is described as:

> YouCompleteMe is a fast, as-you-type, fuzzy-search code completion engine
> for Vim. It has several completion engines: an identifier-based engine that
> works with every programming language, a semantic, Clang [3]-based engine
> that provides native semantic code completion for the C-family languages,
> a Jedi [4]-based completion engine for Python, an OmniSharp [5]-based
> completion engine for C# and an omnifunc-based completer that uses data from
> Vim's omnicomplete system to provide semantic completions for many other
> languages (Ruby, PHP etc.).

To enable automatic completion with |youcompleteme|, use the following options: >

  if !exists('g:ycm_semantic_triggers')
    let g:ycm_semantic_triggers = {}
  endif
  au VimEnter * let g:ycm_semantic_triggers.tex=g:vimtex#re#youcompleteme

VimCompletesMe~
                                                          *vimtex-complete-vcm*
A plugin that maps <tab> to trigger the built-in completion that is most
suitable to the current contex.  The plugin is available here:
https://github.com/ajh17/VimCompletesMe.

The following options may be used to enable completion with the <tab> trigger
for LaTeX documents with |VimCompletesMe| and VimTeX's omni completion function: >

  augroup VimCompletesMeTex
    autocmd!
    autocmd FileType tex
        \ let b:vcm_omni_pattern = g:vimtex#re#neocomplete
  augroup END

==============================================================================
FOLDING                                                        *vimtex-folding*

VimTeX can fold documents according to the LaTeX structure (part, chapter,
section and subsection).  Folding is turned off by default, but it can be
enabled if desired, either through the option |g:vimtex_fold_enabled|, or
manually with >

  set foldmethod=expr
  set foldexpr=vimtex#fold#level(v:lnum)
  set foldtext=vimtex#fold#text()

The folding is mainly configured through the dictionary option
|g:vimtex_fold_types|.

Note: The |fold-expr| method of folding is well known to be slow, e.g. for
      long lines and large files. To speed things up, the user may want to
      enable the |g:vimtex_fold_manual| option. An alternative is to add
      a dedicated plugin that improves folding speed for the slow fold
      methods, e.g. https://github.com/Konfekt/FastFold.

In order to get slightly cleaner fold text, I recommend setting the global
'fillchars' option to a single space for folds: >

  set fillchars=fold:\

Note: Remember to include the whitespace after backslash!

Associated settings:
* |g:vimtex_fold_enabled|
* |g:vimtex_fold_manual|
* |g:vimtex_fold_levelmarker|
* |g:vimtex_fold_types|
* |g:vimtex_fold_types_defaults|

==============================================================================
INDENTATION                                                     *vimtex-indent*
                                                            *vimtex-bib-indent*

VimTeX provides custom indentation functions both for LaTeX documents and
for bibliography files (`.bib` files).

Associated settings:
* |g:vimtex_indent_enabled|
* |g:vimtex_indent_bib_enabled|
* |g:vimtex_indent_delims|
* |g:vimtex_indent_ignored_envs|
* |g:vimtex_indent_lists|
* |g:vimtex_indent_on_ampersands|
* |g:vimtex_indent_tikz_commands|

==============================================================================
SYNTAX HIGHLIGHTING                                             *vimtex-syntax*

VimTeX provides a core syntax plugin combined with package specific addons.
The syntax plugin aims to be both consistent, structured, and efficient. The
package specific addons are generally only loaded when applicable.

LaTeX is a macro expansion language and it impossible to write a fully correct
syntax parser without running the `tex` compiler itself. VimTeX aims to be
pragmatic and provide a best-effort syntax highlighting - a decent trade of
between simplicity and completeness.

The VimTeX syntax plugin is loosely based on Dr Chip's syntax plugin for LaTeX
which is shipped by default with Vim and neovim (|ft-tex-syntax|) [0]. There
are several major differences that users may want to be aware of:
* VimTeX syntax use different names for almost all syntax groups.
* VimTeX syntax does not support syntax based folding.
* VimTeX syntax does not lint `@` in commands, e.g. `\@cmd` (you should know
  what you are doing).

[0]: http://www.drchip.org/astronaut/vim/index.html#SYNTAX_TEX

Associated settings:
* |g:vimtex_syntax_enabled|
* |g:vimtex_syntax_conceal|
* |g:vimtex_syntax_conceal_default|
* |g:vimtex_syntax_nested|
* |g:vimtex_syntax_nospell_commands|
* |g:vimtex_syntax_packages|

------------------------------------------------------------------------------
SYNTAX CONCEAL                                          *vimtex-syntax-conceal*

VimTeX utilizes the |syn-conceal| feature of Vim to allow displaying commands
like `\alpha` as `α`. That is, various elements/commands can be concealed or
substituted with a unicode symbol.

This feature is enabled by default. It can be fully disabled with
|g:vimtex_syntax_conceal_default| or specific types of concealments can be
disabled with |g:vimtex_syntax_conceal|.

For conceals to work properly, one must set the option 'conceallevel' to 2. It
is also good to be aware of the 'concealcursor' option.

It is very important to note that not all fonts are suitable for this feature.
That is, for this feature to work well, you should install and use a font that
includes unicode characters. For Vim or Neovim in a terminal, this means you
must configure your terminal to use such a font. This is, of course, an
exercise for the reader, but here is a list of some possibly useful links:

* https://www.programmingfonts.org/
  * A convenient site to test different "programming" fonts. Not always easy
    to see if the unicode support is good, but at least you can see examples
    of how they look.
* https://wiki.archlinux.org/index.php/Fonts
  * The Arch Wiki is famous for being useful, and it does not fail. But it is
    rather technical and of course refers to Arch Linux packages. It may still
    be a good source of knowledge and inspiration.
* https://www.binarytides.com/gorgeous-looking-fonts-ubuntu-linux/
  * This is a blog post on how to install some modern/good looking/better
    fonts on a Ubuntu system.
* https://github.com/cormullion/juliamono
  * This is the font that I personally use (2021-03-24, @lervag).

------------------------------------------------------------------------------
SYNTAX CORE SPECIFICATION                                  *vimtex-syntax-core*

As it is relatively common for some users to customize their colorschemes, it
is useful to describe some of the underlying "philosophy" of the syntax rules.
Note that, for the following information to be useful, the reader should have
at least some basic understanding of how to customize their colorschemes and
syntax highlighting. The best resources to learn about this are:

  i)   |usr_06|  "Using syntax highlighting" (READ THIS FIRST)
  ii)  https://gist.github.com/romainl/379904f91fa40533175dfaec4c833f2f
       "The right way to override any highlighting if you don't want to edit
       the colorscheme file directly"
       This is a good resource that describes how to properly customize
       the highlighting of syntax groups on top of a basic colorscheme.
  iii) https://github.com/lervag/vimtex/wiki/Syntax
       This wiki page gives an example of how to customize and fine-tune
       syntax highlighting of TeX and BibTeX files.
  iv)  |usr_44|  "Your own syntax highlighted" (ADVANCED)

The main philosophy of the VimTeX syntax plugin is to keep things simple,
structured, and consistent. There is a small set of primitive syntax elements
whose higlighting rules are linked to conventional highlight groups (see
|group-name|). More specialized syntax elements are then linked to
a corresponding primitive syntax element. This allows a user to change the
highlighting of primitives with the effect that corresponding elements are
automatically also updated. It is also possible to override specialized groups
to link them to other conventional groups or set colors directly. This gives
a high degree of flexibility with regards to customizing colorschemes for
LaTeX files. See |vimtex-syntax-reference| for tables of the most important
syntax groups with examples and descriptions.

Most of LaTeX syntax is based around the macro expansion where forms are of
the type `\name` + `[optional group(s)]` + `{argument group(s)}`, where there
can often (not always) be white spaces and newlines between the elements. An
argument group can often consist of other top level elements, but not always.
Further, since LaTeX is designed to have very strong support for typing
mathematical equations, there are several ways to start math mode, e.g.
`$ ... $`, `$$ ... $$`, `\( ... \)`, `\[ ... \]`, and `\begin{equation}`
matched with `\end{equation}`. Within math mode, there's a different subset of
commands available, and it is common to want a slightly different highlighting
of the math mode regions.

VimTeX's syntax script is implemented to support these basic structures as
well as a large set of more specific commands and elements. The more specific
rules define groups whose names are are more specific, and it is usually
possible to define custom highlighting of specific commands and argument
groups.

Finally, it is useful to explain the naming scheme of specialized groups. The
general idea can be described as follows.

  `texCmd{type}`
  `tex{type}Opt`
  `tex{type}Arg`
      A lot of LaTeX macros and commands are specified specifically with
    a given number of optional and real arguments. They may also specify what
    those arguments are. In most cases, the highlighting of `texCmd{type}` is
    linked to `texCmd` and the highlighting of `tex{type}Opt` and
    `tex{type}Arg` are respectively linked to `texOpt` and `texArg`. An
    example of this scheme is `texCmdAuthor`, `texAuthorOpt`, and
    `texAuthorArg` for `\author[...]{...}`.
      Often, but not always, `texCmd{name}` is coupled with `tex{name}*`
    groups. For example, `\include{...}` wants a file argument. The command is
    matched as `texCmdInput`, but it is followed by a `texFileArg` argument
    group.

  `tex{type}Zone`
    Some commands open specific syntax regions that have different rules. Math
    mode is a good example. Math mode is highlighted differently, and the
    syntax regions are name `texMathZone*`. The `tex{type}Zone`s may typically
    contain their own (sub)sets of syntax groups that are only matched within
    the specific region. Another example is the inclusion of nested syntax
    highlighting with e.g. the `minted` or `listings` packages.

  `tex{type}{element}`
    Some regions or commands include other types of elements, e.g. parameters
    like in `\def\name #1` where `#1` is matched as `texDefParm`. For
    completeness: `\def` is matched as `texCmdDef` and `\name` is matched as
    `texDefArgName`.

------------------------------------------------------------------------------
SYNTAX PACKAGE SPECIFICATION                           *vimtex-syntax-packages*

VimTeX provides several package specific syntax addons that provide richer
syntax highlighting. These are built around the same principles as explained
in |vimtex-syntax-core|.

The syntax improvements for a specific package are by default loaded only if
that package is detected in the current document (as explained in
|vimtex-package-detection|). This generally works well when a document is
compiled, but VimTeX may fail to detect packages for new documents or
documents that are not compiled. It is therefore possible to configure that
individual syntax packages should always load. One may also disable individual
syntax packages. See |g:vimtex_syntax_packages| for a full list of which
syntax addons exist and how to configure them.

------------------------------------------------------------------------------
SYNTAX GROUP REFERENCE                                *vimtex-syntax-reference*

The following is a reference of the main syntax groups and its default
highlighting, as well as one ore more examples of what it matches. Most of the
primitive groups are linked to conventional syntax groups as listed in
|group-name|. In the examples, capital letters are used to indicate which
parts are matched by the current group. For even more details, please refer to
the code itself:
* Core elements: The `s:init_highlights()` function in the file
  `autoload/vimtex/syntax/core.vim` specifies the highlighting of the core
  groups.
* Package specific groups and elements are defined in the package specific
  scripts: `autoload/vimtex/syntax/p/*.vim`.

Note:
* This is only a reference of the main groups. There are also other groups
  available. See the source files for the full lists.
* The following lists might not be always completely up to date. If you find
  inconsistencies or errors, please open an issue.

Table 1: A list of groups that are only primitive link targets.~
>
  GROUP                DEFAULT
  ----------------------------------------------------------------------------
  texCmdType           Type
  texError             Error
  texParm              Special
  texZone              PreCondit
  texSymbol            SpecialChar

Table 2: A list of the most common normal LaTeX groups.~
>
  GROUP                DEFAULT      EXAMPLE
  ----------------------------------------------------------------------------
  texComment           Comment      % COMMENT
  texCommentTodo       Todo         % TODO
  texDelim             Delimiter    {, }, [, and ]
  texCmd               Statement    \CMD
  texOpt               Identifier   \cmd[OPT]
  texOptSep            NormalNC     [a, b] (commas)
  texOptEqual          texSymbol    [a=b]
  texArg               Include      \cmd[...]{ARG}
  texSpecialChar       SpecialChar  \S, \P, \$, \;, ...
  texCmdInput          texCmd       \INPUT
                                    \INCLUDE
                                    \INCLUDEONLY
                                    \INCLUDEGRAPHICS
  texCmdBib            texCmd       \BIBLIOGRAPHY
                                    \BIBLIOGRAPHYSTYLE
  texCmdClass          texCmd       \DOCUMENTCLASS
  texCmdPackage        texCmd       \USEPACKAGE
                                    \REQUIREPACKAGE
  texFileOpt           texOpt       \includegraphics[PACKAGE OPTIONS]
                                    \documentclass[CLASS OPTIONS]
  texFileArg           texArg       \input{FILE}
                                    \include{FILE}
                                    \includegraphics[...]{FILE}
                                    \bibliographystyle{FILE}
                                    \documentclass[...]{CLASS}
  texFilesOpt          texFileOpt   \usepackage[PACKAGE OPTIONS]
                                    \RequirePackage[PACKAGE OPTIONS]
  texFilesArg          texFileArg   \includeonly{FILE1, FILE2}
                                    \bibliography{FILE1, FILE2}
                                    \usepackage[...]{PACKAGE1, PACKAGE2}
                                    \RequirePackage[...]{PACKAGE1, PACKAGE2}
  texCmdTitle          texCmd       \TITLE
  texTitleArg          Underlined   \title{MAIN TITLE}
  texCmdAuthor         texCmd       \AUTHOR
  texAuthorOpt         texOpt       \author[OPT]
  texAuthorArg         NONE         \author[...]{AUTHOR LIST}
  texCmdPart           texCmd       \(SUB*)SECTION
  texPartArgTitle      String       \(sub*)section{TITLE}
  texCmdEnv            texCmd       \BEGIN; \END
  texEnvArgName        PreCondit    \begin{ENVNAME}
  texCmdRef            texCmd       \CITE; \LABEL
  texRefArg            Special      \cite{REFERENCE}; \label{REF}
  texE3Func            texCmdType   \STR_NEW:N
  texE3Var             texCmd       \G_MYFILE_NAME_STR

Table 3: A list of math mode groups.~
>
  GROUP                    DEFAULT        EXAMPLE
  ----------------------------------------------------------------------------
  texMathZone              Special        \( HERE \); \[ HERE \]
  texMathZoneEnv           texMathZone    \begin{menv}  HERE \end{menv}
  texMathZoneEnvStarred    texMathZone    \begin{menv*} HERE \end{menv*}
  texMathZoneX             texMathZone    $ HERE $
  texMathZoneXX            texMathZone    $$ HERE $$
  texMathZoneEnsured       texMathZone    \ensuremath{HERE}
  texCmdMathEnv            texCmdEnv      \BEGIN; \END (for math environments)
  texMathEnvArgName        Delimiter      \begin{EQUATION}
  texCmdMath               texCmd         \ENSUREMATH
  texMathDelim             Type           \LVERT
  texMathDelimMod          texMathDelim   \LEFT\lvert \RIGHT\rvert
  texMathOper              Operator       Basic operators: +-=/
  texMathSuperSub          texMathOper    Sub and super operators (^, _)
  texMathError             texError       Unmatched region endings

Table 4: A list of other important groups.~
>
  GROUP                DEFAULT         EXAMPLE
  ----------------------------------------------------------------------------
  texLength            Number          Length units, e.g. "4 cm". Only when
                                       contained e.g. in option groups.
  texLigature          texSymbol       --; ---; ``; ''; ,,
  texCmdAccent         texCmd          \"{a}
  texCmdLigature       texSpecialChar  \ss; \ae
  texCmdSpaceCodeChar  Special         Catcodes. For more info, see:
                                       https://en.wikibooks.org/wiki/TeX/catcode
  texCmdTodo           Todo            \TODOSOMETHING
  texCmdVerb           texCmd          \VERB
  texVerbZoneInline    texZone         \verb+VERB TEXT+
  texVerbZone          texZone         \begin{verbatim} VERB TEXT \end{verbatim}
  texCmdDef            texCmdNew       \DEF
  texDefArgName        texArgNew       \def\NAME
  texDefParm           texParm         \def\name #1
  texCmdItem           texCmd          \item

==============================================================================
NAVIGATION                                                  *vimtex-navigation*

Vim already has a lot of useful navigation related features, such as
|tags-and-searches| and |include-search|. VimTeX improves the latter feature
by setting the 'include' and 'includeexpr' options, see |vimtex-includeexpr|.

VimTeX also provides a separate table-of-content feature. This works by
parsing the LaTeX project and displaying a table of contents in a separate
window. For more info, see |vimtex-toc|.

The "engine" for collecting the table-of-content entries may also be used as
a backend for external plugins. There are sources for |denite.nvim|, |unite.vim|
and |fzf.vim| that should work well. The source code may be used as inspiration
to write custom sources or sources for other, similar plugins.

------------------------------------------------------------------------------
INCLUDE EXPRESSION                                         *vimtex-includeexpr*

VimTeX provides an advanced |includeexpr| that makes it possible to open
source files for e.g. packages and documentclasses with the |gf| command. The
implementation relies on `kpsewhich` to find the source files. Consider the
following example: >

  \documentclass{article}
  \usepackage{MyLocalPackage}
  \usepackage{SomeOtherPackage,YetAnotherPackage}
  ...

With the cursor on the documentclass name `article` or one of the package
names, |gf| will take you to the TeX source files (typically `.cls` file for
documentclass and `.sty` files for packages).

------------------------------------------------------------------------------
TABLE OF CONTENTS                                                  *vimtex-toc*

|vimtex-toc| displays a table of contents (ToC) for the current LaTeX document.
The ToC entries may be activated/jumped to with <cr> or <space>. There are
currently four different "layers" of entries:

* content  This is the main part and the "real" ToC
* todo     This shows TODOs from comments and `\todo{...}` commands
* label    This shows `\label{...}` commands
* include  This shows included files

The ToC is configured with |g:vimtex_toc_config|. One may change things from
where the ToC window is positioned to which layers to show and more. Please
read the option help for details.

The ToC parser uses a list of matchers to parse the LaTeX project for the ToC
entries. One may add custom matchers through the |g:vimtex_toc_custom_matchers|
option. The syntax of a custom matcher is specified here:
|toc_matcher_specification|.

Note: By setting the `mode` configuration key to > 2, the separate ToC window
is not opened and most of the features mentioned here will be irrelevant.

One may force file input entries of the "include" type into the ToC through
comments with the following syntax: >

  % vimtex-include: /path/to/file

The path may be absolute or relative. In the latter case, it will be relative
to the current root (as printed by |:VimtexInfo|). This will add an entry in
the ToC which makes it easy to open any file. Any file opened through the ToC
that was included in this manner will be linked to the current VimTeX project,
and thus the ToC and similar commands will be available, even if the file is
not a LaTeX file.

                                                       *vimtex-toc-custom-maps*
Some people may want to have separate mappings for different ToC contents,
e.g. one mapping to open a table of labels and todos and a different mapping
to open a table of include files. This may be easily added with custom
mappings: >

  augroup vimtex_customization
    autocmd!
    autocmd FileType tex call CreateTocs()
  augroup END

  function CreateTocs()
    let g:custom_toc1 = vimtex#toc#new({
        \ 'layers' : ['label', 'todo'],
        \ 'todo_sorted' : 0,
        \ 'show_help' : 0,
        \ 'show_numbers' : 0,
        \ 'mode' : 4,
        \})
    nnoremap <silent> \ly :call g:custom_toc1.open()<cr>

    let g:custom_toc2 = vimtex#toc#new({
        \ 'layers' : ['include'],
        \ 'show_help' : 0,
        \})
    nnoremap <silent> \lY :call g:custom_toc2.open()<cr>
  endfunction

The `vimtex#toc#new` function takes a dictionary argument that may be used to
override the one main configuration (i.e. the combination of the default
values and |g:vimtex_toc_config|).

Associated settings:
* |g:vimtex_toc_enabled|
* |g:vimtex_toc_custom_matchers|
* |g:vimtex_toc_todo_labels|
* |g:vimtex_toc_show_preamble|
* |g:vimtex_toc_config|

------------------------------------------------------------------------------
DENITE AND UNITE SOURCES                                        *vimtex-denite*
                                                                 *vimtex-unite*

                                        https://github.com/Shougo/denite.nvim
                                          https://github.com/Shougo/unite.vim
|denite.nvim| is is a popular interface for many things, including outlines.
Although VimTeX includes a simple interface for a tables of contents, it also
makes sense to provide these as a source to |denite.nvim|. The source name is
simply `vimtex`.

|unite.vim| is the predecessor to |denite.nvim|. As for denite, there is a source
called `vimtex`.

If one prefers the |denite.nvim| or |unite.vim| source to the VimTeX interface,
one may override the default mapping, e.g.: >

  nnoremap <localleader>lt :<c-u>Denite vimtex<cr>
  nnoremap <localleader>lt :<c-u>Unite vimtex<cr>

------------------------------------------------------------------------------
FZF INTEGRATION                                                   *vimtex-fzf*

                                           https://github.com/junegunn/fzf.vim
                                               https://github.com/junegunn/fzf
|fzf.vim| integrates the general-purpose command-line fuzzy finder |fzf| into vim
and neovim. Similar to the |denite.vim| and |unite.vim| source it may be used to
quickly navigate VimTeX's built-in ToC feature. To use it, just define a
mapping to `vimtex#fzf#run()` in your .vimrc, e.g.: >

  nnoremap <localleader>lt :call vimtex#fzf#run()<cr>

You can also choose to only show certain entry "layers", according to this
table (see |vimtex-toc| for detailed explanation of the "layers"):

  `c`:  content
  `t`:  todo
  `l`:  label
  `i`:  include

The default behavior is to show all layers, i.e. 'ctli'. To only show
`content` and `label`s use: >

  :call vimtex#fzf#run('cl')

On Windows the python package Colorama is required for colored output.
For Linux and MacOS colors should work out-of-the-box, even without Colorama.

A second argument can be passed to this function to customize the FZF options.
It should be an object containing the parameters passed to `fzf#run()`. For
example, if you've defined `g:fzf_layout`, then those options can be passed to
`vimtex#fzf#run`: >

    :call vimtex#fzf#run('ctli', g:fzf_layout)

==============================================================================
COMPILER                                                      *vimtex-compiler*

VimTeX provides an interface to the following LaTeX compilers/compiler
backends:

* |vimtex-latexmk|   http://users.phys.psu.edu/~collins/software/latexmk-jcc
* |vimtex-latexrun|  https://github.com/aclements/latexrun
* |vimtex-tectonic|  https://tectonic-typesetting.github.io/
* |vimtex-arara|     https://github.com/cereda/arara
* |vimtex-generic-compiler|

The interface is implemented in a general way, which makes it relatively easy
to add new compilers.

Compilation is started and stopped with |:VimtexCompile| and |:VimtexStop|.
Although, |:VimtexStop| stopping is only relevant for continuous compilations,
and in this case, |:VimtexCompile| itself works as a toggle.  Single shot
compilation is always available through |:VimtexCompileSS|.  The default
mappings for these commands are listed here: |vimtex-default-mappings|.

It is also possible to compile a selection of the file. To do this, one may
either use the mapping, |<plug>(vimtex-compile-selected)|, or the command
|:VimtexCompileSelected|.

The compilers should respect the TeX program directive as described here:
|vimtex-tex-program|, except for |vimtex-arara|, which uses its own set of
directives and rules.

Associated commands:
* |:VimtexCompile|
* |:VimtexCompileSS|
* |:VimtexCompileSS!|
* |:VimtexCompileSelected|
* |:VimtexCompileOutput|
* |:VimtexStatus|
* |:VimtexStatus!|
* |:VimtexStop|
* |:VimtexStopAll|
* |:VimtexErrors|
* |:VimtexErrors|
* |:VimtexClean|
* |:VimtexClean!|
* |:VimtexErrors|

Associated settings:
* |g:vimtex_compiler_enabled|
* |g:vimtex_compiler_method|
* |g:vimtex_compiler_latexmk|
* |g:vimtex_compiler_latexmk_engines|
* |g:vimtex_compiler_latexrun|
* |g:vimtex_compiler_latexrun_engines|
* |g:vimtex_compiler_tectonic|
* |g:vimtex_compiler_arara|
* |g:vimtex_compiler_generic|
* |g:vimtex_compiler_progname|
* |$VIMTEX_OUTPUT_DIRECTORY|

Associated events:
* |VimtexEventCompileStarted|
* |VimtexEventCompileStopped|
* |VimtexEventCompileSuccess|
* |VimtexEventCompileFailed|

------------------------------------------------------------------------------
LATEXMK                                                        *vimtex-latexmk*

                      http://users.phys.psu.edu/~collins/software/latexmk-jcc
> latexmk is a perl script for running LaTeX the correct number of times to
> resolve cross references, etc; it also runs auxiliary programs (bibtex,
> makeindex if necessary, and dvips and/or a previewer as requested).  It has
> a number of other useful capabilities, for example to start a previewer and
> then run latex whenever the source files are updated, so that the previewer
> gives an up-to-date view of the document. The script runs on both UNIX and
> MS-WINDOWS (XP, etc).

`latexmk` is a compiler backend that handles recompilation of LaTeX documents
when source files have been changed.  VimTeX uses the continuous mode by
default, but `latexmk` also allows single shot compilations.  The compiler may
be configured through the |g:vimtex_compiler_latexmk| option.

If the `callback` key is enabled (it is by default), then compilation errors
will be parsed automatically.  This is done by utilizing the tricks explained
below. Note: This only works for continuous compilation mode.

As stated, one may customize the `latexmk` options through
|g:vimtex_compiler_latexmk|.  However, one may also configure `latexmk`
explicitly through a global `~/.latexmkrc` file, or a project specific
`.latexmkrc` file. It is important to know that command line arguments have
priority, so one may want to use custom options if one wants to specify
particular things in a configuration file.

A particular set of options are very convenient for a good coupling between
`latexmk` and Vim: `$compiling_cmd`, `$success_cmd`, and `$failure_cmd`. These
options can be used to specify commands that are run by `latexmk` before and
after compilation. This is used by VimTeX to achieve callbacks after
compilation has finished through |vimtex#compiler#callback| with something
like this: >

  $success_cmd = "gvim --remote-expr 'vimtex#compiler#callback(1)'";
  $failure_cmd = "gvim --remote-expr 'vimtex#compiler#callback(0)'";

Another neat way to use this is to use `xdotool` to change the window title of
the viewer to indicate the compilation status: >

  $compiling_cmd = "xdotool search --name \"%D\" " .
                   "set_window --name \"%D compiling...\"";
  $success_cmd   = "xdotool search --name \"%D\" " .
                   "set_window --name \"%D OK\"";
  $failure_cmd   = "xdotool search --name \"%D\" " .
                   "set_window --name \"%D FAILURE\"";

Note: If you define these options similar to the above `xdotool` trick and
      still want to enable the VimTeX callbacks, then one must include
      a semicolon at the end of the `cmd` strings so that VimTeX may append
      safely to the options.

Note: More info on `xdotool` here: https://www.semicomplete.com/projects/xdotool.

------------------------------------------------------------------------------
LATEXRUN                                                      *vimtex-latexrun*

                                        https://github.com/aclements/latexrun
> See LaTeX run. Run latexrun.
>
> latexrun fits LaTeX into a modern build environment. It hides LaTeX's
> circular dependencies, surfaces errors in a standard and user-friendly
> format, and generally enables other tools to do what they do best.

`latexrun` is a compiler backend that handles recompilation of LaTeX documents
when source files have been changed.  However, it is a much simpler backend,
and does not support e.g. continuous mode and automatic starting of viewers.
The latter is supported by VimTeX, though, through the callback.  See
|g:vimtex_view_automatic|.

The compiler may be configured through the |g:vimtex_compiler_latexrun| option.

------------------------------------------------------------------------------
TECTONIC                                                      *vimtex-tectonic*

                                      https://tectonic-typesetting.github.io/
> Tectonic is a modernized, complete, self-contained TeX/LaTeX engine, powered
> by XeTeX and TeXLive.

`tectonic` is a compiler backend that features automatic support file
downloading along with reproduceable builds and full Unicode and OpenType
fonts support thanks to the power of XeTeX. It does not support continuous
compilation, like |vimtex-latexmk| and so the only relevant commands are
|:VimtexCompile| to start (single shot) compilation, and |:VimtexCompileOutput|
to see the compilation output. As for |vimtex-latexrun| and |vimtex-arara|,
the viewer can be started automatically with |g:vimtex_view_automatic|.

`tectonic` cleans up intermediate files like `.aux` and log files by default.
However, VimTeX's backend invoke it with the flags `--keep-logs` and
`--keep-synctex` which enables us to see the errors on the quickfix and it
gives us synctex support. Therefor, by default, |<plug>(vimtex-clean)|
and |:VimtexClean| clean these files.

The compiler may be configured through the |g:vimtex_compiler_tectonic| option.

------------------------------------------------------------------------------
ARARA                                                            *vimtex-arara*

                                        https://github.com/cereda/arara
> arara is a TeX automation tool based on rules and directives. It gives you
> subsidies to enhance your TeX experience.

`arara` is a TeX automation tool that uses rules and directives that are
defined in the preamble of a LaTeX project. The user manual can be found here:
https://ctan.uib.no/support/arara/doc/arara-manual.pdf

`arara` does not do continuous compilation, and so the only relevant commands
are |:VimtexCompile| to start (single shot) compilation, and
|:VimtexCompileOutput| to see the compilation output. As for |vimtex-latexrun|
and |vimtex-tectonic|, the viewer can be started automatically with
|g:vimtex_view_automatic|.

The compiler may be configured through the |g:vimtex_compiler_arara| option.

Note: It is not possible to directly specify an output directory from VimTeX.
      This is a restriction caused by the design of arara. However, since one
      may still want to specify custom output directories, VimTeX allows to
      customize the output directory through the environment variable
      |$VIMTEX_OUTPUT_DIRECTORY|.

------------------------------------------------------------------------------
GENERIC COMPILER                                      *vimtex-generic-compiler*

There are a lot of various compiler backends for LaTeX, and it is also
possible to simply use things like a Makefile. The generic backend allows to
use mostly whatever you want. However, since it is a generic implementation,
it will not be as well integrated as e.g. |vimtex-latexmk|.

Some examples of build tools that can be used with the generic backend:

* Light LaTeX Make (llmk)
  https://ctan.org/pkg/light-latex-make

  > This program is yet another build tool specific for LaTeX documents. Its
  > aim is to provide a simple way to specify a workflow of processing LaTeX
  > documents and encourage people to always explicitly show the right
  > workflow for each document.

* spix (Yet another TeX compilation tool: simple, human readable, no option,
  no magic)
  https://ctan.org/pkg/spix

  > SpiX offers a way to store information about the compilation process for
  > a tex file inside the tex file itself. Just write the commands as comments
  > in the tex files, and SpiX will extract and run those commands.
  >   Everything is stored in the tex file (so that you are not missing some
  > piece of information that is located somewhere else), in a human-readable
  > format (no need to know SpiX to understand it).

TODO: More documentation here. Examples of configuration.

==============================================================================
SYNTAX CHECKING (LINTING)                                       *vimtex-lint*

VimTeX provides syntax checking (linting) for TeX and BibTeX files through
three compilers: `lacheck` [1], `chktex` [2], and `biber` [3]. These may be
activated with the |:compiler| command, see |compiler-select|. A selected
compiler may then be used e.g. with |:make| or |:lmake|. See the following
text for some tips on how one may use this feature.

It is possible to use more automatic linting through dedicated plugins. For
more information, see |vimtex-nf-linting|.

------------------------------------------------------------------------------

A common workflow is to utilize the |location-list| with |:lmake|:

  - To lint the currently open TeX file with `lacheck`, run
    `:compiler lacheck|lmake`
  - To lint the currently open TeX file with `chktex`, run
    `:compiler chktex|lmake`
  - To lint the currently open BibTeX file with `biber`, run
    `:compiler bibertool|lmake`

After linting, the compiler or linter messages are added to the location list.
This list may be displayed in the location-list window with |:lwindow|, and
one may jump between the entries with |:lN| and |:lp|. To automatically open
the location-list window after linting is finished, one may add the following
to one's |vimrc|: >

  augroup VimTeX
    autocmd!
    autocmd QuickFixCmdPost lmake lwindow
  augroup END

For convenience, one may also define a command for linting for each file type
and add an autocmd to automatically lint on save. The following gives an
example for `bibertool` and BibTeX, but one may of course do the same with
`lacheck` and/or `chktex` for TeX files as well. First, add the following to
`~/.vim/after/ftplugin/bib.vim`: >

  command! -buffer -bang Lint compiler bibertool | lmake<bang>

Then, add to `~/.vim/after/ftplugin/bib.vim`: >

  augroup VimTeX
    autocmd!
    autocmd BufWrite <buffer=abuf> compiler bibertool | lmake!
  augroup END

If one minds that Vim becomes unresponsive while linting, then one may utilize
plugins like |vim-dispatch| [4] or |AsyncRun| [5]. With `vim-dispatch`, one
may simply replace the `:lmake` call with `:Make`. For `AsyncRun`, one may
define a `:Make` command such as: >

  command! -bang -nargs=* -complete=file Make
          \ AsyncRun<bang> -auto=make -program=make

The quickfix window that lists the linter errors and warnings can then be
opened by |:cwindow| and they can be jumped to by |:cN| respectively |:cp|.

Often, a syntax error in a BibTeX file is due to a missing comma after an
entry. One may define a command to automatically add such missing commas, e.g.
by adding the following lines in `~/.vim/after/ftplugin/bib.vim`: >

  command! -buffer -range=% -bar AddMissingCommas keeppatterns
        \ <line1>,<line2>substitute:\v([}"])(\s*\n)+(\s*\a+\s*\=):\1,\2\3:giep

To call this automatically after saving a BibTeX file, add the following
autocommand inside a proper autocommand group (e.g. `augroup VimTeX` as
suggested above) in `~/.vim/after/ftplugin/bib.vim`: >

  autocmd BufWrite <buffer> exe
        \ 'normal! m`' | silent AddMissingCommas | silent! exe 'normal! g``'

Finally, for more full-fledged linting in Vim, see the plug-ins mentioned in
|vimtex-non-features|.

[1] https://ctan.org/pkg/lacheck
[2] https://www.nongnu.org/chktex/
[3] https://github.com/plk/biber
[4] https://github.com/tpope/vim-dispatch
[5] https://github.com/skywind3000/asyncrun.vim

==============================================================================
GRAMMAR CHECKING                                               *vimtex-grammar*

VimTeX provides several compilers for grammar checking TeX files through the
|compiler-select| feature in Vim:

  style-check~
    http://www.cs.umd.edu/~nspring/software/style-check-readme.html

  textidote~
    See more details here: |vimtex-grammar-textidote|

  vlty~
    See more details here: |vimtex-grammar-vlty|

A compiler may be activated with the |:compiler| command. The selected compiler
may then be used e.g. with |:make| or |:lmake|. As an example, one may do the
following to use the |location-list| with a given checker: >

    :compiler {checker}|lmake

See |vimtex-lint| above for some tips on how to use this feature. The
following is a list of the available checkers:

The language of the Tex file is determined by the option |'spelllang'|. This
option can be specified in ones vimrc file, but it can also be specified in
a |modeline| (see also the user manual section |21.6| for a gentle
introduction to the use of modelines).

------------------------------------------------------------------------------
TEXTIDOTE                                            *vimtex-grammar-textidote*

The `textidote` compiler is a VimTeX wrapper over TeXtidote [1]. TeXtidote is
a correction tool for LaTeX documents to check grammar, style, and perform
spell checking.

Configuration of the wrapper is controlled by the Vim dictionary
|g:vimtex_grammar_textidote|. In particular, it is important to specify the
`jar` key to the path of the executable jar file `textidote.jar`. Please note
that if one installs `textidote` with a package manager e.g. in some common
Linux distributions, the `.jar` file might be missing. If so, it should be
possible to download it manually from [1]. However, before one does that, it
can be smart to check the top lines of the installed executable, as it may be
a simple Bash script wrapper.

[1]: https://sylvainhalle.github.io/textidote/

------------------------------------------------------------------------------
VLTY                                                      *vimtex-grammar-vlty*

The `vlty` compiler uses the Python package `YaLafi` [1] for extracting the
plain text and combines this with the proofreading software `LanguageTool` [2].

In order to use `vlty`, you need local installations of both components. An
archive of `LanguageTool` can be downloaded from [3]. After uncompressing at
a suitable place, the path to it is specified as shown below. On a system like
`Arch Linux`, `LanguageTool` may also be installed with: >

  sudo pacman -S languagetool

`YaLafi` itself can be installed with: >

  pip install --user yalafi

Configuration is controlled by the Vim dictionary |g:vimtex_grammar_vlty|.
As a minimal example, one could write in |vimrc|: >

  let g:vimtex_grammar_vlty = {'lt_directory': 'path/to/LanguageTool'}
  set spelllang=en_gb

The given directory has to contain the `LanguageTool` software, including for
instance the file `languagetool-server.jar`. If instead `LanguageTool` is
installed through a package manager as mentioned above, one could write: >

  let g:vimtex_grammar_vlty = {'lt_command': 'languagetool'}
  set spelllang=en_gb

Calling `:compiler vlty` will raise an error message if some component cannot
be found.

Note: Spell checking with `LanguageTool` is only enabled if a country code is
      specified in |'spelllang'|.

[1] https://github.com/matze-dd/YaLafi
[2] https://www.languagetool.org
[3] https://www.languagetool.org/download/

==============================================================================
VIEW                                                              *vimtex-view*

VimTeX provides the command |:VimtexView| to open the desired viewer.  The
command is mapped to '<localleader>lv' by default.  The list of supported
viewers are given in the description of |g:vimtex_view_method|.

For supported viewers, |:VimtexView| will also perform forward search when the
viewer is opened.

Associated settings:
* |g:vimtex_view_enabled|
* |g:vimtex_view_automatic|
* |g:vimtex_view_method|
* |g:vimtex_view_use_temp_files|
* |g:vimtex_view_general_options|
* |g:vimtex_view_general_viewer|
* |g:vimtex_view_mupdf_options|
* |g:vimtex_view_mupdf_send_keys|
* |g:vimtex_view_skim_activate|
* |g:vimtex_view_skim_reading_bar|
* |g:vimtex_view_zathura_options|

Associated events:
* |VimtexEventView|

------------------------------------------------------------------------------
SYNCTEX SUPPORT                                                *vimtex-synctex*

Synctex is a tool that enables synchronization of the text editor position and
the pdf viewer position.  The tool may be used to add mappings in vim to go to
the current position in the compiled pdf document (forward search), and also
to go from a specific position in the pdf file to the corresponding position
in vim (inverse/backward search).

To make synctex work, it must be enabled. VimTeX enables this by default by
passing `-synctex=1` on the command line, unless the user overrides the
option (see the `option` key for |g:vimtex_compiler_latexmk| or
|g:vimtex_compiler_latexrun|).

Alternatively, for |vimtex-latexmk|, one can put this in ones `~/.latexmkrc` file: >

  $pdflatex = 'pdflatex -synctex=1 %O %S';

Note: For |neovim| users, one must use `neovim-remote` for backward search. See
      |vimtex-faq-neovim| for more info.

------------------------------------------------------------------------------
FORWARD SEARCH                                  *vimtex-synctex-forward-search*

For supported viewers, |:VimtexView| (<localleader>lv) will issue a forward
search if the viewer is already opened.  The forward search will take you to
the page or position in the viewer that corresponds to the current line in
your vim session.  See |g:vimtex_view_method| for a list of supported viewers.

------------------------------------------------------------------------------
BACKWARD SEARCH                                *vimtex-synctex-backward-search*
                                                *vimtex-synctex-inverse-search*

In supported viewers one may set up backward or inverse search.  When
correctly set up, this allows one to go directly from a selected line in the
viewer (typically by double clicking with the mouse or something similar) to
the corresponding line inside the Vim instance.

Backward search is typically set up inside the specific viewer through an
option named something like "inverse search command-line".  A standard value
for the option is: >

  gvim --remote-silent +%l "%f"

Note: Inverse search relies on the |clientserver| functionality of vim.  Each
      instance of vim runs its own server.  The above mentioned standard value
      implies the default server name, which might not be the actual name of
      the server for the vim instance you are using. For more info, see
      |vimtex-clientserver|.

Note: For backward search to work on windows, one must ensure that the folder
      that contains `gVim.exe` is in your `%PATH%` environment variable.

==============================================================================
LATEX DOCUMENTATION                                           *vimtex-latexdoc*

VimTeX provides the command |:VimtexDocPackage| to open documentation for
packages and documentclasses. The command is mapped to `K` by default, and by
default package documentation is looked up through http://texdoc.net/. This
can be customized through |g:vimtex_doc_handlers|.

In the following, I list some alternative and relevant options for access to
LaTeX documentation, both online and offline.

------------------------------------------------------------------------------
ONLINE                                                 *vimtex-latexdoc-online*

I recommend the LaTeX Wikibook [0] as a good source of documentation for
LaTeX. One should also know about the Comprehensive TeX Archive Network, or
CTAN [1], which is the central place for all kinds of material around TeX.
The long-existing unofficial LaTeX(2e) reference manual (latexref) can be
found online at [2].

[0]: https://en.wikibooks.org/wiki/LaTeX
[1]: https://ctan.org/
[2]: https://latexref.xyz/

------------------------------------------------------------------------------
OFFLINE                                               *vimtex-latexdoc-offline*

One may use a more dedicated offline documentation system. On macOS, Dash [0]
is a non-free but high-quality system. On Linux, one may use Zeal [1] or dasht
[2], both of which access the Dash documentation sets. Zeal should also work
well on Windows.

The above systems may be accessed from vim through dash.vim [3], zeavim.vim
[4] or vim-dasht [5], respectively. Other alternative vim plugins include
investigate.vim [6].

A different option is to rely on texdoc [7]. If you specify e.g. in your
`~/.vim/after/ftplugin/tex.vim` to use `setlocal keywordprg=texdoc`, then
press |K| on a package name in `\usepackage{name}`, this will open the
documentation pdf of this package. Note, though, that this assumes that the
documentation is available offline, which it might not be (e.g. on Arch Linux
it is not available through the texlive packages).

The unofficial LaTeX(2e) reference manual (latexref) should also be mentioned,
since it may be easily downloaded in various formats from [8].

[0]: https://kapeli.com/dash
[1]: https://zealdocs.org/
[2]: https://github.com/sunaku/dasht
[3]: https://github.com/rizzatti/dash.vim
[4]: https://github.com/sunaku/vim-dasht
[5]: https://github.com/KabbAmine/zeavim.vim
[6]: https://github.com/keith/investigate.vim
[7]: https://www.tug.org/texdoc/doc/texdoc.pdf
[8]: https://latexref.xyz/dev/

==============================================================================
CONTEXT MENU                                              *vimtex-context-menu*

VimTeX provides the command |:VimtexContextMenu| to open a context menu for
the item below the cursor. The menu allows various actions relevant to the
current context. It is mapped by default to `<localleader>la`.

The available contexts are listed below.

Associated settings:
* |g:vimtex_context_pdf_viewer|

------------------------------------------------------------------------------
CITATION CONTEXT                                      *vimtex-context-citation*

When the cursor is over a citations, e.g. `\textcite{myRef}`, then the context
menu will show choices relevant to the current citation entry. This works by
parsing the relevant `bib` file for metadata and providing menu actions
depending on the available metadata. The actions are only displayed when they
are relevant.

Possible actions:

  Edit entry~
    Go to the entry location in the relevant bib file.

  Show entry~
    Show the registered data for the current entry.

  Open PDF~
    Open associated PDF file from the `file` key of the bib entry.

  Open DOI~
    Open associated DOI url from the `doi` key of the bib entry.

  Open URL~
    Open associated URL from the `url` key of the bib entry.

==============================================================================
CODE STRUCTURE                                                    *vimtex-code*

The VimTeX code is based on the |autoload| feature of vim. For each new
latex buffer, the function *vimtex#init* initializes a state variable as well
as buffer local mappings and commands, all based on the desired options (see
|vimtex-options|).

The main init function calls `vimtex#mymodule#init_buffer` for each submodule,
if it exists. This function should take care of defining buffer local
mappings, commands, and autocommands.

The state variable is a |Dictionary| that contains data that is specific to
a single LaTeX project. Such a project may consist of several buffers for
different files if the project is a multi-file project (see
|vimtex-multi-file|). A submodule may add to the state during initialization
with `vimtex#mymodule#init_state`, which takes the state object as a single
argument.

The command |:VimtexInfo| (mapped to <localleader>li by default) will show the
(relevant) contents of the local state, as well as some auxiliary information
that may be useful for debugging purposes.

See also the supplementary high-level code documentation [0] for more detailed
information about the VimTeX code.

[0]: https://github.com/lervag/vimtex/blob/master/DOCUMENTATION.md

------------------------------------------------------------------------------
API REFERENCE                                                 *vimtex-code-api*

This is an API reference of the most useful VimTeX functions available to
users for customization.

Note: This API is currently a work in progress!

*vimtex#syntax#in_mathzone(...)*
  Returns 1 if the position is inside a math zone. If called without
  arguments, the position refers to the cursor position. Else must be called
  with two arguments: the line number and colun number.

*vimtex#compiler#is_running()*
  Function returns 0 if a compiler is not running, 1 if it is running, or -1
  if the compiler backend is not available (e.g. for non VimTeX buffers).

*vimtex#compiler#callback(status)*
  Utility function to be used as a compiler callback function. The argument is
  the compiler status: 0 or |v:false| means compilation failed and 1 or
  |v:true| means compilation was successful. The function does several useful
  things based on the status, such as running the |VimtexEventCompileFailed|
  and |VimtexEventCompileSuccess| events.

==============================================================================
FAQ                                                                *vimtex-faq*

This is a section of some frequently asked questions whose answers may be of
help to users.

Contents:
* |vimtex-faq-slow-matchparen|
* |vimtex-faq-skimviewer|
* |vimtex-faq-surround|
* |vimtex-faq-isfname|
* |vimtex-faq-neovim|
* |vimtex-faq-tags|
* |vimtex-faq-tags-bibtex|
* |vimtex-faq-texmfhome|
* |vimtex-faq-windows|
* |vimtex-faq-wsl|
* |vimtex-faq-zathura-macos|

------------------------------------------------------------------------------
                                                   *vimtex-faq-slow-matchparen*
Q: Why is matching parens so slow?
A: Because it is complicated and requires some expensive searches for matching
   parantheses. It uses the syntax information to skip commented delimiters,
   which is expensive. You can tune the timeout and stopline parameters for
   the searches with |g:vimtex_delim_timeout| and |g:vimtex_delim_stopline|,
   which may help. If it is still too slow, you can also try to use
   vim-matchup [0].

   [0]: https://github.com/andymass/vim-matchup

------------------------------------------------------------------------------
                                                        *vimtex-faq-skimviewer*
Q: How do I properly set up VimTeX with Skim?
A: Set |g:vimtex_view_method| to `skim` (and read |vimtex_viewer_skim| if you
   did not already do so). Forward search should just work. Backward search
   requires configuration in Skim that depends on which version of Vim you are
   using. Open the settings panel in Skim, go to the `Sync` tab and set the
   options according to your desired version of Vim:

     * For `MacVim`, select the `MacVim` preset.
     * For `neovim`, select the `Custom` preset from the drop-down list and set:
         Command: nvr~
         Args: --remote +"%line" "%file"~
       Please ensure that you have the `nvr` (neovim-remote) utility and the
       `pynvim` Python module available, see |vimtex-faq-neovim|.

   Some related information may be found here:
   https://sourceforge.net/p/skim-app/wiki/TeX_and_PDF_Synchronization
   https://jdhao.github.io/2021/02/20/inverse_search_setup_neovim_vimtex

------------------------------------------------------------------------------
                                                        *vimtex-faq-sumatrapdf*
Q: How do I properly set up VimTeX with SumatraPDF?
A: First, see and follow the guidelines in |vimtex_viewer_sumatrapdf|. Forward
   search should work after this. Backward search requires configuration in
   SumatraPDF that depends on which version of Vim you are using. The
   following advice is for `neovim`; things should be simpler for Vim.

   1. First, ensure that `neovim-remote` is installed (e.g. `pip install
      neovim-remote`).

   2. Add some configuration to your vimrc file to detect the servername: >

        function! SetServerName()
          let nvim_server_file = has('win32')
                \ ? $TEMP . "/curnvimserver.txt"
                \ : "/tmp/curnvimserver.txt"
          call system(printf("echo %s > %s", v:servername, nvim_server_file))
        endfunction

        augroup vimtex_common
            autocmd!
            autocmd FileType tex call SetServerName()
        augroup END
<
   3. Open `Settings --> Options` in SumatraPDF. Find the section
      `Set inverse search command-line` in the bottom part and insert the
      following long command there: >

        cmd /c for /F %i in ('type C:\Users\ADMINI~1\AppData\Local\Temp\curnvimserver.txt') do nvr --servername %i -c "normal! zzzv" +"%l" "%f"
<
      You may need to change the exact file path above for your Windows
      system. You can use the command `:echo $TEMP` to check the temp folder
      on your Windows.

   See the following blog posts for more related information:

     https://jdhao.github.io/2021/02/20/inverse_search_setup_neovim_vimtex/
     https://jdhao.github.io/2019/03/26/nvim_latex_write_preview/#inverse-search-for-sumatra-pdf-on-windows

   It is also possible to specify the backward search options from Vim,
   although it requires a relatively complex and nasty expression. Something
   like this: >

      let g:vimtex_view_general_options
          \ = '-reuse-instance -forward-search @tex @line @pdf'
          \ . ' -inverse-search "' . exepath(v:progpath)
          \ . ' --servername ' . v:servername
          \ . ' --remote-send \"^<C-\^>^<C-n^>'
          \ . ':execute ''drop '' . fnameescape(''\%f'')^<CR^>'
          \ . ':\%l^<CR^>:normal\! zzzv^<CR^>'
          \ . ':call remote_foreground('''.v:servername.''')^<CR^>^<CR^>\""'
<
   Note: The expected behavior for the multi-line setting above is to refresh
         the `InverseSearchCmdLine` setting in SumatraPDF. It may fail if the
         Vim/gVim process is not running as Administrator on Windows 10.
         A workaround is to ensure to launch Vim as Administrator when editing
         tex files.

------------------------------------------------------------------------------
                                                          *vimtex-faq-surround*
Q: VimTeX provides `dse`, `dsc`, `cse`, and `csc`.  These seem to be inspired by
   |surround.vim|.  Does VimTeX also provide the corresponding `yse` and `ysc`?
A: The mentioned mappings are indeed inspired by |surround.vim|.  However,
   VimTeX does not provide `ys<text-object>e` and `ys<text-object>c`.  If you use
   |surround.vim|, then the asked for mappings may be easily added if one adds
   the following lines to `~/.vim/after/ftplugin/tex.vim` or any other
   `ftplugin/tex.vim` in your |runtimepath|: >

  let b:surround_{char2nr('e')}
      \ = "\\begin{\1environment: \1}\n\t\r\n\\end{\1\1}"
  let b:surround_{char2nr('c')} = "\\\1command: \1{\r}"
<
   Remark also that, by default, |surround.vim| already provides the mapping
   `ys<text-object>l` for encapsulating a text object in a LaTeX environment.

   Note: Please also read the section |vimtex-nf-surround|!

   Note: An alternative is to use `vim-sandwich` (see |sandwich.txt| or
         https://github.com/machakann/vim-sandwich), which has built-in
         support for LaTeX-specific surroundings.

------------------------------------------------------------------------------
                                                           *vimtex-faq-isfname*
Q: Vim throws error when jumping to file with |gf|.
A: This might be due to the |isfname| setting, which by default contains `{,}`
   on windows.  |isfname| is a global option, and can therefore not be set by
   VimTeX.  Suggested solution is to remove `{,}` from |isfname| by: >

  set isfname-={,}
<
------------------------------------------------------------------------------
                                                            *vimtex-faq-neovim*
Q: Does VimTeX work with neovim?
A: Yes, but backward sync requires the `neovim-remote` utility. It may be
   installed and used by VimTeX as follows:

     1. Install the `pynvim` and `neovim-remote` modules for python3 (e.g.,
        using `pip3 install --user pynvim neovim-remote`; if `python3 -c
        "import pynvim"` returns without error and `nvr` starts neovim from
        the command line, everything should be good to go).

     2. Configure your viewer to use `nvr --remote +"%line" "%file"` for
        backward sync.

   See https://github.com/mhinz/neovim-remote for more information on `nvr`.

------------------------------------------------------------------------------
                                                              *vimtex-faq-tags*
Q: How can I jump from a `\ref{label}` to the corresponding label?
A: This is not a feature provided by VimTeX itself, but vim has very good
   support for tag navigation, see |tags-and-searches|. It is worth mentioning
   that the |ctags| support for LaTeX is somewhat lacking. This can be amended
   by adding some lines to your `~/.ctags` configuration file (or
   `.ctags.d/default.ctags` if you use Universal ctags), e.g.: >

    --langdef=tex2
    --langmap=tex2:.tex
    --regex-tex2=/\\label[ \t]*\*?\{[ \t]*([^}]*)\}/\1/l,label/

<   See [0,1] for references. I also find |gutentags| [2] to be very convenient
   for automatically generating and updating tag files.

   [0]: http://stackoverflow.com/q/8119405/51634
   [1]: https://github.com/lervag/vimtex/issues/348
   [2]: https://github.com/ludovicchabant/vim-gutentags

------------------------------------------------------------------------------
                                                       *vimtex-faq-tags-bibtex*
Q: How can I jump from a `\cite{key}` to the corresponding bibtex entry?
A: This is not a feature provided by VimTeX itself. Similar to
   |vimtex-faq-tags|, the feature is available through |tags-and-searches|.
   The following `~/.ctags` configuration will be useful (or
   `.ctags.d/default.ctags` if you use Universal ctags): >

    --langdef=bib
    --langmap=bib:.bib
    --regex-bib=/^@[A-Za-z]+\{([^,]+),/\1/e,BibTeX-Entries/i
    --regex-bib=/^@string\{([^ "#%')(,=}{]+)/\1/s,BibTeX-Strings/i
    --regex-bib=/author[[:space:]]*=[[:space:]]*("([^"]+)"|\{([^\}]+)\})[[:space:]]*,?[[:space:]]*$/\2\3/a,BibTeX-Authors/i

<   See [0] for references.

   [0]: https://github.com/lervag/vimtex/issues/564

------------------------------------------------------------------------------
                                                         *vimtex-faq-texmfhome*
Q: How can I change `TEXMFHOME`?
A: If you change `TEXMFHOME` in your `.bashrc` or `.zshrc` or similar and use `gvim`
   invoked from the desktop environment (from menus, hotkeys, etc.), gvim does
   not know about the new value of `TEXMFHOME`. The reason for this is that
   `vim` invokes shells (e.g. with `!` or `system()`) as non-interactive and
   non-login shell, which means `.bashrc` or `.zshrc` are not read.  If you
   start `gvim` from an interactive shell which has read `.bashrc` or `.zshrc,
   `gvim` inherits these values and therefore they are consistent.

   One can make the invoked shells interactive by setting |shellcmdflag| to
   "-ic".  If you want to keep them non-interactive, you can create an
   additional shell startup file where you keep your environment variables:

   1. If bash is your default shell, create e.g. the file `.bashenv` containing
      your customized `TEXMFHOME` variable and add `$BASH_ENV=$HOME/.bashenv` to
      `$MYVIMRC` and `source $HOME/.bashenv` to `.bashrc` [0].

   2. If zsh is your default shell, use `.zshenv` for customizing `TEXMFHOME`.
      This file is always read by zsh. Nothing has to be added to `$MYVIMRC` [1].

   For more information on how to correctly set environment variables, see e.g.
   the SO answer by @Rmano [2].

   [0]: https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html
   [1]: http://zsh.sourceforge.net/Intro/intro_3.html
   [2]: http://askubuntu.com/a/356973/16395

------------------------------------------------------------------------------
                                                           *vimtex-faq-windows*
Q: Does VimTeX support Windows?
A: Yes and no.  I personally don't use Windows, and as such, it is difficult
   to make every feature work perfectly.  However, I think most features
   should work.  Here are some things that might not work quite as expected,
   with some workarounds.

   * The full executable path for `gvim.exe` might include spaces, which might
     lead to problems, see e.g. [0].  A workaround is to put the default
     installation path of Vim (or neovim) to your %PATH% variable and set
     |g:vimtex_compiler_progname| to |v:progname|. See [3] for a convenient
     tool to adapt %PATH%.

   * VimTeX does not work well with the 'shell' setting set to Windows
     PowerShell. It is therefore recommended to use the default 'shell'
     settings. See [4] for more information.

   Also, see [1-2] for some relevant issues that might be of interest.

   [0]: https://github.com/lervag/vimtex/issues/966
   [1]: https://github.com/lervag/vimtex/issues/736
   [2]: https://github.com/lervag/vimtex/issues/882
   [3]: https://www.rapidee.com/en/path-variable
   [4]: https://github.com/lervag/vimtex/issues/1507

------------------------------------------------------------------------------
                                                               *vimtex-faq-wsl*
Q: Does VimTeX support WSL (Windows Subsystem for Linux)?
A: For the moment, rudimentarily, as follows: To set up the viewer, install
   mupdf [0] or SumatraPDF [1], add the executable to %PATH%, say by Rapidee
   [2]. In your vimrc, the lines
>
   if has('win32') || (has('unix') && exists('$WSLENV'))
     if executable('mupdf.exe')
       let g:vimtex_view_general_viewer = 'mupdf.exe'
     elseif executable('SumatraPDF.exe')
       let g:vimtex_view_general_viewer = 'SumatraPDF.exe'
     endif
   endif
<
   make |:VimtexView| work under Windows, and also under WSL, provided that at
   least Windows 10 version 1903 [3] of WSL is installed, the current work dir
   and the compiled file is contained in the Linux home directory $HOME (as
   opposed to %USERPROFILE% in Windows).

   However, client-server capabilities seem to be disabled (perhaps because
   WSL does not have built-in support for X11) and therefore backward search
   does not work. Neither does forward search work: While SumatraPDF opens
   fine the PDF file in \\wsl$\<DistroName>\..., the forward search in
   SumatraPDF itself does not find the corresponding source file in
   \\wsl$\<DistroName>\....

   To set up a LaTeX distribution, while reusing that of Windows as proposed
   at [4] seems efficient, in practice accessing files on mounted NTFS drives
   from WSL is slow, even more so under WSL2 [5]. Therefore a full TeXLive
   installation is recommended.

   If only basic functionality is required, then a minimal TeXLive
   installation, such as TinyTeX [6] or a minimal set of packages to compile
   LaTeX as provided by your distribution, is an option, as discussed at [7].
   For example, under openSUSE, it suffices to install the packages
   texlive-scheme-basic, texlive-latexmk, texlive-collection-fontsrecommended.

   [0]: https://chocolatey.org/packages/mupdf
   [1]: https://chocolatey.org/packages/sumatrapdf
   [2]: https://www.rapidee.com/en/about
   [3]: https://devblogs.microsoft.com/commandline/whats-new-for-wsl-in-windows-10-version-1903/
   [4]: https://github.com/lervag/vimtex/issues/1380
   [5]: https://vxlabs.com/2019/12/06/wsl2-io-measurements/
   [6]: https://yihui.org/tinytex/
   [7]: https://tex.stackexchange.com/questions/397174/minimal-texlive-installation

------------------------------------------------------------------------------
                                                     *vimtex-faq-zathura-macos*
Q: Does Zathura + VimTeX work on macOS?
A: Yes, it should work.  The following recipe has been reported to work [0].
   The steps assume the user has installed and knows how to use Homebrew [1].

   1. Zathura needs `dbus` to work properly. Install it with the following:
      `brew install dbus`, or, if it is already installed, reinstall (this
      seems necessary for some unknown reason): `brew reinstall dbus`

   2. Add this to your `.bashrc` or `.zshrc` file (or similar): >

      export DBUS_SESSION_BUS_ADDRESS="unix:path=$DBUS_LAUNCHD_SESSION_BUS_SOCKET"
<
   3. Changed the value of `<auth><\auth>` in
      `/usr/local/opt/dbus/share/dbus-1/session.conf` from `EXTERNAL` to
      `DBUS_COOKIE_SHA1`.

   4. Run `brew services start dbus`

   5. Now install Zathura (most recean version, aka HEAD): >

      brew tap zegervdv/zathura
      brew install girara --HEAD
      brew install zathura --HEAD --with-synctex
      brew install zathura-pdf-poppler
      mkdir -p $(brew --prefix zathura)/lib/zathura
      ln -s $(brew --prefix zathura-pdf-poppler)/libpdf-poppler.dylib $(brew --prefix zathura)/lib/zathura/libpdf-poppler.dylib
<
   6. Reboot and enjoy.

   Note: If you already had Zathura and girara installed and things don't
         work, then first uninstall and unlink them and try to follow the
         above steps from step 1.

   [0]: https://github.com/lervag/vimtex/issues/1737#issuecomment-759953886
   [1]: https://brew.sh

==============================================================================
TROUBLESHOOTING                                       *vimtex-troubleshooting*

Here are some pitfalls that one may experience if one of these assumptions are
broken:

- Completion may not work properly for exotic file encodings, such as for
  UTF-16LE (see https://github.com/lervag/vimtex/issues/615)

With different operating systems and different plugin configurations, there
are a few things that must be considered for system interoperability. A number
of common problems and suggested solutions are included in the following
troubleshooting section.

Problem: Continuous compilation seems to hang~

Upon starting continuous compilation the status bar indicates "VimTeX:
Compiler started in continuous mode", but the compilation never terminates and
the quickfix window does not load.

Tips:
1. Ensure that a latexmk process and a Perl process have started. If they have
   not been started, then these two programs may not accessible given your
   operating system's PATH environment variable.
2. On Windows, some releases of Perl have been known to not trigger callbacks
   upon successful/failed compilation. It is highly suggested to install a
   dedicated Perl distribution (e.g. Strawberry Perl). See
   https://github.com/lervag/vimtex/issues/378 for more information.
3. Ensure that the option `-interaction=nonstopmode` is provided to latexmk.
   This is done by default by VimTeX, unless the user provides custom options
   through |g:vimtex_compiler_latexmk| (see the `option` key). In the latter
   case, the user must ensure that the said option is also provided.

Problem: Text objects on Windows~

In Windows, environment text object commands, like `vae` and `vie`, do not
select the entire body of the environment. More specifically, given: >

    \begin{someenv}
      some content
    \end{someenv}

The command `dae` results in: >

    }

and `die` results in: >

    \begin{someenv}
      t
    \end{someenv}

Solution: It seems that vim for Windows comes with some options set by default
in the vimrc file. One of these has been reported to be `:behave mswin` (see
|:behave|) which, among other things, sets the 'selection' option to
"exclusive". This can be ameliorated by pursuing one of two options:

  1) Add `:behave xterm` to your vimrc file.
  2) Add `:set selection=inclusive` to your vimrc file.

See also: https://github.com/lervag/vimtex/issues/408

Problem: Typing <Tab> or <C-n> causes Vim to hang before making a completion~

VimTeX may be scanning included files with `kpsewhich` while collecting
completion candidates for keyword completion. Try disabling this feature by
setting |g:vimtex_include_search_enabled| to 0 in your |vimrc|: >

    let g:vimtex_include_search_enabled = 0

Note: Plugins like |supertab| [0], which often maps the |i_<Tab>| key, will
      typically use keyword completion "behind the scenes" to gather
      completion candidates.

      [0]: https://github.com/ervandew/supertab

==============================================================================
CREDITS                                                        *vimtex-credits*

VimTeX is developed by Karl Yngve Lervåg <karl.yngve@gmail.com>, and is
distributed under the MIT license.  The project is available as a Git
repository: https://github.com/lervag/vimtex.

VimTeX was developed from scratch, but much of the code has been based on
LaTeX-Box: https://github.com/LaTeX-Box-Team/LaTeX-Box.  LaTeX-suite was also
an inspiration: http://vim-latex.sourceforge.net/.

I do accept donations through PayPal (see link below [0]). As there are no
expenses related to VimTeX (except time), any money I receive would be spent
on coffee, beer or chocolate. These things make me happy. However, I will also
be happy if one should choose to donate to a charity instead, as there are
a lot of people in more need of money than me! Examples of charities may be
|ICCF| (the organisation that Vim specifically supports) or Medicins sans
Frontieres [1]. Feel free to let me know if you should donate to a charity due
to VimTeX, as I would be happy to hear of it.

[0]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5N4MFVXN7U8NW
[1]: https://www.msf.org/

==============================================================================
CHANGELOG                                                    *vimtex-changelog*

The following changelog only logs particularly important changes, such as
changes that break backwards compatibility.  See the git log for the detailed
changelog.

2020-11-16: More flexible package syntax options~
Deprecate *g:vimtex_syntax_autoload_packages* in favor of
|g:vimtex_syntax_packages|, which allows more fine grained control over each
package.

2020-09-24: More consise grammar options~
Deprecate *g:vimtex_textidote_jar* in favor of |g:vimtex_grammar_textidote|.

2020-08-11: Remove g:vimtex_quickfix_latexlog~
The option *g:vimtex_quickfix_latexlog* was deprecated in favor of the more
general mechanism provided by |g:vimtex_quickfix_ignore_filters|.

2020-07-31: Use events for callback hooks~
The events |VimtexEventCompileSuccess|, |VimtexEventCompileFailed|, and
|VimtexEventView| have been added to make it easier to hook personal
customizations. This deprecates the following options:
* *g:vimtex_compiler_callback_hooks*
* *g:vimtex_view_general_callback*
* *g:vimtex_view_general_hook_callback*
* *g:vimtex_view_general_hook_view*
* *g:vimtex_view_mupdf_hook_callback*
* *g:vimtex_view_mupdf_hook_view*
* *g:vimtex_view_skim_hook_callback*
* *g:vimtex_view_skim_hook_view*
* *g:vimtex_view_zathura_hook_callback*
* *g:vimtex_view_zathura_hook_view*

2020-07-19: Released version 1.0~
Version 1.0 (and earlier) works on Vim 7.4 and with neovim 0.1.7. Later
versions require Vim 8.0 or neovim 0.4.3.

2018-08-15: Refactored the ToC interface~
I've made a large update to the code for the ToC window in order to simplify
and unify the interface. In the new version, |g:vimtex_toc_config| replaces
all of the following options:
* *g:vimtex_index_split_width*
* *g:vimtex_index_split_pos*
* *g:vimtex_index_show_help*
* *g:vimtex_index_resize*
* *g:vimtex_index_hide_line_numbers*
* *g:vimtex_index_mode*
* *g:vimtex_toc_layers*
* *g:vimtex_toc_fold*
* *g:vimtex_toc_fold_level_start*
* *g:vimtex_toc_hotkeys*
* *g:vimtex_toc_refresh_always*
* *g:vimtex_toc_show_numbers*
* *g:vimtex_toc_tocdepth*

2017-07-27: Major refactoring of the folding feature~
I've made a large update to the code for folding. The configuration of the
various folded elements is now done through a single option:
|g:vimtex_fold_types|.

Deprecated options:
* *g:vimtex_fold_comments*
* *g:vimtex_fold_preamble*
* *g:vimtex_fold_envs*
* *g:vimtex_fold_env_blacklist*
* *g:vimtex_fold_env_whitelist*
* *g:vimtex_fold_markers*
* *g:vimtex_fold_parts*
* *g:vimtex_fold_sections*
* *g:vimtex_fold_commands*
* *g:vimtex_fold_commands_default*
                                                               *vimtex-lacheck*
2017-06-05: Removed Lacheck support~
Removed support for using `lacheck` for checking LaTeX syntax. The reason is
that there exist several (good) external plugins for syntax checking files.
These are general purpose plugins that work for multiple file types. For more
info, see |vimtex-non-features|.

2017-05-20: Updated TOC options~
There's been a few updates to the TOC. During this work, I removed some
unecessary options.

Deprecated options:
* *g:vimtex_toc_fold_levels*  (was not necessary)
* *g:vimtex_toc_number_width*  (see |g:vimtex_toc_tocdepth|)

2017-03-31: Refactored quickfix related features~
I've added a more general layer for handling different error parsers.
Currently there are few or now changes from the user point of view, but this
should make it possible to add other methods for showing errors in a LaTeX
project than the current one that parses the `.log` file directly.

Deprecated options:
* *g:vimtex_quickfix_warnings*  (see |g:vimtex_quickfix_latexlog|)

2017-03-28: Major refactoring of initialization~
Added a general compiler interface, see |vimtex-compiler|.  To configure the
`latexmk` compiler, see |g:vimtex_compiler_latexmk|.

Deprecated options:
* *g:vimtex_latexmk_enabled* (use |g:vimtex_compiler_enabled|)
* *g:vimtex_latexmk_progname* (use |g:vimtex_compiler_progname|)
* *g:vimtex_latexmk_callback_hooks* (use |g:vimtex_compiler_callback_hooks|)
* *g:vimtex_latexmk_callback*
* *g:vimtex_latexmk_autojump*
* *g:vimtex_latexmk_continuous*
* *g:vimtex_latexmk_background*
* *g:vimtex_latexmk_options*

Deprecated commands:
* *VimtexCompileToggle* (use |:VimtexCompile|)

2017-03-28: Major refactoring of initialization~
The initialization has been refactored in order to provide a more consistent
separation of buffer initialization and state initialization. This has no
major consequence for users, but it makes maintenance and further development
easier.

2017-03-02: Changed how to set ignored warnings~
I'm updating the changelog to notify of a change to the quickfix settings.

Deprecated options:
* *g:vimtex_quickfix_ignore_all_warnings*
* *g:vimtex_quickfix_ignored_warnings*

See instead:
  |g:vimtex_quickfix_warnings|

2016-05-31: A lot of things have updated~
I know that people would like to see a simple list of changes. Unfortunately,
I am bad at keeping this changelog updated. All details are available in the
git log, though. The reason I added this entry is to note that I have removed
an option:

* *g:vimtex_env_complete_list* --- It is no longer necessary. Completion
                                 candidates are instead parsed from the
                                 project.

2016-02-06: Large refactoring of delimiter parsing~
I've refactored a lot of the code in order to make the parsing of delimiters
and features that rely on delimiter detection and similar more consistent.
This results in some changes in option names and similar, but it should make
it easier to provide improved and more robust features.

There is one feature change: The delimiter toggle now consistently toggles the
modifier, not the delimiter itself, and it toggles between a range of
modifiers by default. For customization, see |g:vimtex_delim_toggle_mod_list|.

The following options have changed names:
* *g:vimtex_change_set_formatexpr* ---> |g:vimtex_format_enabled|
* *g:vimtex_change_complete_envs*  ---> |g:vimtex_env_complete_list|
* *g:vimtex_change_toggled_delims* ---> |g:vimtex_delim_toggle_mod_list|

The following options have been removed:
* *g:vimtex_change_ignored_delims_pattern* --- It was no longer necessary

The following mappings have been renamed:
* *<plug>(vimtex-delete-env)*   ---> |<plug>(vimtex-env-delete)|
* *<plug>(vimtex-delete-cmd)*   ---> |<plug>(vimtex-cmd-delete)|
* *<plug>(vimtex-change-env)*   ---> |<plug>(vimtex-env-change)|
* *<plug>(vimtex-change-cmd)*   ---> |<plug>(vimtex-cmd-change)|
* *<plug>(vimtex-toggle-star)*  ---> |<plug>(vimtex-env-toggle-star)|
* *<plug>(vimtex-toggle-delim)* ---> |<plug>(vimtex-delim-toggle-modifier)|
* *<plug>(vimtex-create-cmd)*   ---> |<plug>(vimtex-cmd-create)|
* *<plug>(vimtex-close-env)*    ---> |<plug>(vimtex-delim-close)|

2015-10-19: Added convenient insert mode mappings~
I've merged the `math_mappings` branch (see #172 and #251). It adds the
feature that is explained in |vimtex-imaps|.

2015-06-06: Minor but convenient restructuring (++)~
I've changed a lot of the code structure in relatively small ways.  For
instance, instead of referring to the particular data blobs through the global
array, I instead linked a buffer variable to the correct global array element.

One particular change is that all modules are now initialized in three steps:

  1. Initialize module options
  2. Initialize script variables and single execution functionalities
  3. Initialize buffer options

Finally, I've cleaned up a lot of the code by removing some deprecation
warnings and similar.

2015-03-21: Implemented index buffers, deprecated vimtex_toc filetype~
The system for displaying the table of content relied on a dedicated filetype
plugin.  This was inherited from LaTeX-Box, and worked quite well.  However,
I intend to implement more functionality that uses the same kind of buffer to
display similar things, such as a list of labels.  I realized I wanted the ToC
window to be more adaptable, so I implemented the `index` interface for such
buffers.  The `index` in itself may be used to create ToC-like buffers with
simple actions.  The |vimtex-toc| uses and expands the `index` in such a way
that the changes should barely be noticeable from the user perspective.  Note
however the following variable name changes:

* *g:vimtex_toc_numbers_width*     ---> |g:vimtex_toc_number_width|
* *g:vimtex_toc_hide_preamble*     ---> |g:vimtex_toc_show_preamble|
* *g:vimtex_toc_numbers*           ---> |g:vimtex_toc_show_numbers|

* *g:vimtex_toc_hide_line_numbers* ---> |g:vimtex_index_hide_line_numbers|
* *g:vimtex_toc_resize*            ---> |g:vimtex_index_resize|
* *g:vimtex_toc_hide_help*         ---> |g:vimtex_index_show_help|
* *g:vimtex_toc_split_pos*         ---> |g:vimtex_index_split|
* *g:vimtex_toc_width*             -/

                                                         *vim-latex-namechange*
2015-03-08: Changed the name to VimTeX~
The old name `vim-latex` was already used by LaTeX-Suite.  I was not aware of
the name clash in the beginning.  Due to the rising popularity of this plugin,
it has become clear that such a name clash is very inconvenient.  The present
change is therefore very much needed.

The name change is reflected throughout the plugin in the names of commands,
mappings, functions, and options.  People should update their `vimrc` settings
accordingly.  For instance, every option name should be changed from >

  g:latex_... = ...

to >

  g:vimtex_... = ...

2014-12-07: Added more general view functionality~
Added new module for view functionality.  This allows more complex view
functions (and commands), for instance to do forward (and possibly backwards)
searching through `synctex`.  In the first version, I added forward search for
mupdf by use of the `synctex` command and `xdotools`.

The `g:latex_viewer` option has now been deprecated.  Instead one should use
|g:vimtex_view_method| and |g:vimtex_view_general_viewer|.

Deprecated option:
* *g:latex_viewer*

2014-06-13: Changed some option names~
Some VimTeX option names were changed in an attempt to make the names
more consistent.  These options are listed here for reference:
* *g:latex_errorformat_ignore_warnings*
* *g:latex_errorformat_show_warnings*
* *g:latex_latexmk_autojump*
* *g:latex_latexmk_quickfix*

The new names are, respectively:
* |g:vimtex_quickfix_ignored_warnings|
* |g:vimtex_quickfix_ignore_all_warnings|
* |g:vimtex_quickfix_autojump|
* |g:vimtex_quickfix_mode|

2013-10-05: First public release~
VimTeX was first released on github on this date. The initial version was
named vim-latex, which conflicted with Vim LaTeX-Suite which is also known as
vim-latex.

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: