vimtex/doc/latex.txt

*latex.txt*    LaTeX plugin for Vim version 7.3 (and above)
*vim-latex* *latex*

Author:  Karl Yngve Lervåg <karl.yngve@gmail.com>
License: MIT license {{{
  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                                                  *vim-latex-contents*

    1. Intro ................................ |vim-latex-intro|
    2. Main interface ....................... |vim-latex-main|
    3. Default mappings ..................... |vim-latex-mappings|
    4. Commands ............................. |vim-latex-commands|
    5. Options .............................. |vim-latex-options|
    6. Omni completion ...................... |vim-latex-completion|
    7. Folding .............................. |vim-latex-folding|
    8. Indentation .......................... |vim-latex-indent|
    9. Latexmk .............................. |vim-latex-latexmk|
       Latexmk tricks ....................... |vim-latex-latexmk-tricks|
       Latexmk synctex ...................... |vim-latex-latexmk-synctex|
   10. Motion ............................... |vim-latex-motion|
   11. Change ............................... |vim-latex-change|
   12. Table of contents .................... |vim-latex-toc|
   13. Utility functions .................... |vim-latex-util|
   14. Function reference ................... |vim-latex-functions|
   15. Credits .............................. |vim-latex-credits|
   16. Changelog ............................ |vim-latex-changelog|

==============================================================================
INTRO                                                        *vim-latex-intro*

This vim plugin provides some convenience functionality for editing LaTeX
documents.  The goal has been to create a minimalistic and functional plugin
that is easy to customize and evolve.  Most of the functionality provided is
turned on by default, but the user may turn off features that are not desired.
The plugin will hereafter be referred to as |vim-latex|.

                                                      *vim-latex-requirements*
Some of the functionalities of |vim-latex| has certain requirements:

  |vim-latex-latexmk|
    Requires that the user has installed both `latexmk` and `pgrep`.  If these
    are not available, then the functionalities provided by
    |vim-latex-latexmk| will not be available.

  |vim-latex-completion|
    The function |latex#complete#bibtex| requires `bibtex` and `kpsewhich` to
    parse bib files for bibliography completion.

==============================================================================
MAIN INTERFACE                                                *vim-latex-main*

The |vim-latex| interface is based on the |autoload| feature of vim.  For each
new latex buffer, the function *latex#init* initializes the variables and
functionalities based on the desired options |vim-latex-options|.  The first
run performs some global initialization, which is mainly to define
autocommands.  Other functionality is provided by additional autoloaded
scripts, such as |vim-latex-latexmk|.  Every additional script should have an
initialization script that sets default mappings, creates autocommands and
performs other necessary initialization.  This initialization script is then
called from |latex#init|.

The main interface provides some basic functionality.  |latex#view|, by
default mapped to '<localleader>lv', opens the current output file in
a viewer.  |latex#help| lists all mappings that are defined specifically for
the current buffer, by default mapped to '<localleader>lh'.  If the default
mappings are used, |latex#help| will display them.  |latex#info| echoes the
contents of |g:latex#data| and |b:latex|.  This is useful mainly for
debugging.  Finally, |latex#reinit| clears the current data in |g:latex#data|
and |b:latex|, stops running `latexmk` processes |latex#latexmk#stop_all|,  and
then performs a new initialization with |latex#init|.

For each latex project that is opened, a |Dictionary| is created and added to
the list |g:latex#data|.  The dictionary is initialized with information tied
to the current project, mainly the different associated file names.  In
addition, a dictionary is created for every buffer |b:latex|.  This contains
data that is specific to the current buffer, most importantly it contains the
ID of the main latex project.  This combination of local and global data
enables |vim-latex| to work properly for multi-file latex projects.  It also
allows the editing of different latex projects simultaneously in different
buffers.

                                                                *g:latex#data*
A |List| of |Dictionaries|, each containing data specific to a given latex
project.  The ID of a latex project is the index of its dictionary in the list.
An example of a dictionary is given here: >

  {
    'pid': 0,
    'name': 'main',
    'base': 'main.tex',
    'root': '/some/path',
    'tex': '/some/path/main.tex',
    'aux': function('202'),
    'log': function('203'),
    'out': function('204'),
  }

Which entries are present in a given dictionary depends on the current
settings.  For example, the entry `pid` is only available if
|vim-latex-latexmk| is enabled |g:latex_latexmk_enabled|.  Note that some of
the file entries are functions.  The functions are used to find the files when
necessary, in case they do not exist when the latex file is opened.  All
defined dictionaries can be printed with the function |latex#info|, by default
mapped to '<localleader>li'.

                                                                     *b:latex*
For each buffer, |vim-latex| defines a |Dictionary| that contains buffer local
information.  An example of such a dictionary is: >

  {
    'id': 0,
    'fold_sections': [],
  }

The most important entry is `id`, which is the index of the corresponding
entry in the list of latex projects |g:latex#data|.  Other entries may also be
exist, such as `fold_sections`.  The dictionary can be printed with the
function |latex#info|, by default mapped to '<localleader>li'.

Functions:
        |latex#info|
        |latex#help|
        |latex#reinit|
        |latex#view|

------------------------------------------------------------------------------
Support for multi-file projects:~
                                                        *vim-latex-multi-file*
                                                                    *tex-root*

|vim-latex| supports multi-file documents in the sense that the plugin
automatically detects the root file of the project.  This detection is based
on a recursive search for files that include the current tex file, until
a main file is recognized.  A file is assumed to be the main file if it has
the `\begin{document}` line.  Files are assumed to live in the same folder or
a parent folder of the current file.  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.

It is also possible to specify the main TeX file with a comment in one of the
first five lines of the current file similar to this: >

  %! TEX root = my-main.tex

==============================================================================
DEFAULT MAPPINGS                                          *vim-latex-mappings*

The default mappings for |vim-latex| are given below.  See 'map-listing' for
an explanation of the format.  The function |latex#help| is provided for
convenience to list all the defined mappings, and it is by default mapped to
'<localleader>lh'.  The default mappings may be disabled with the option
|g:latex_mappings_enabled|, if the user wishes to create his/her own mappings.

n  %                *@:call latex#motion#find_matching_pair()<cr>
v  %                *@:<c-u>call latex#motion#find_matching_pair(1)<cr>
o  %                *@:normal v%<cr>

v  a$               *@:<c-u>call latex#motion#select_inline_math()<cr>
v  i$               *@:<c-u>call latex#motion#select_inline_math(1)<cr>
o  a$               *@:normal va$<cr>
o  i$               *@:normal vi$<cr>

v  ae               *@:<c-u>call latex#motion#select_environment()<cr>
v  ie               *@:<c-u>call latex#motion#select_environment(1)<cr>
o  ae               *@:normal vae<cr>
o  ie               *@:normal vie<cr>

v  ad               *@:<c-u>call latex#motion#select_delimiter()<cr>
v  id               *@:<c-u>call latex#motion#select_delimiter(1)<cr>
o  ad               *@:normal va(<cr>
o  id               *@:normal vi(<cr>

n  [[               *@:call latex#motion#next_sec(0,1,0)<cr>
n  []               *@:call latex#motion#next_sec(1,1,0)<cr>
n  ][               *@:call latex#motion#next_sec(1,0,0)<cr>
n  ]]               *@:call latex#motion#next_sec(0,0,0)<cr>
v  [[               *@:<c-u>call latex#motion#next_sec(0,1,1)<cr>
v  []               *@:<c-u>call latex#motion#next_sec(1,1,1)<cr>
v  ][               *@:<c-u>call latex#motion#next_sec(1,0,1)<cr>
v  ]]               *@:<c-u>call latex#motion#next_sec(0,0,1)<cr>
o  [[               *@:normal v[[<cr>
o  []               *@:normal v[]<cr>
o  ][               *@:normal v][<cr>
o  ]]               *@:normal v]]<cr>

n  <localleader>li  *@:call latex#info()<cr>
n  <localleader>lh  *@:call latex#help()<cr>
n  <localleader>lv  *@:call latex#view()<cr>
n  <localleader>lR  *@:call latex#reinit()<cr>
n  <localleader>lt  *@:call latex#toc#open()<cr>
n  <localleader>lT  *@:call latex#toc#toggle()<cr>
n  <localleader>ll  *@:call latex#latexmk#compile()<cr>
n  <localleader>lk  *@:call latex#latexmk#stop(1)<cr>
n  <localleader>lK  *@:call latex#latexmk#stop_all()<cr>
n  <localleader>le  *@:call latex#latexmk#errors(1)<cr>
n  <localleader>lo  *@:call latex#latexmk#output()<cr>
n  <localleader>lg  *@:call latex#latexmk#status()<cr>
n  <localleader>lG  *@:call latex#latexmk#status(1)<cr>
n  <localleader>lc  *@:call latex#latexmk#clean()<cr>
n  <localleader>lC  *@:call latex#latexmk#clean(1)<cr>

n  zx               *@:call latex#fold#refresh()<cr>
n  dse              *@:call latex#change#env('')<cr>
n  cse              *@:call latex#change#env_prompt()<cr>
n  tse              *@:call latex#change#toggle_env_star()<cr>
n  tsd              *@:call latex#change#toggle_delim()<cr>
n  <F7>             *@:call latex#change#to_command()<cr>i
i  <F7>             *@:call latex#change#to_command()<cr>
i  ]]               *@:call latex#change#close_environment()<cr>

==============================================================================
COMMANDS                                                  *vim-latex-commands*

|vim-latex| is mainly based on a function API as described in the section
|vim-latex-functions|.  However, commands are also defined for convenience.
Below the commands are listed in alphabetical order.

VimLatexClean                call latex#latexmk#clean()
VimLatexClean!               call latex#latexmk#clean(1)
VimLatexCompile              call latex#latexmk#compile()
VimLatexErrors               call latex#latexmk#errors(1)
VimLatexHelp                 call latex#help()
VimLatexInfo                 call latex#info()
VimLatexOutput               call latex#latexmk#output()
VimLatexRefreshFolds         call latex#fold#refresh()
VimLatexReinitialize         call latex#reinit()
VimLatexStatus               call latex#latexmk#status()
VimLatexStatus!              call latex#latexmk#status(1)
VimLatexStop                 call latex#latexmk#stop()
VimLatexStopAll              call latex#latexmk#stop_all()
VimLatexTocOpen              call latex#toc#open()
VimLatexTocToggle            call latex#toc#toggle()
VimLatexView                 call latex#view()

==============================================================================
OPTIONS                                                    *vim-latex-options*

This section describes the options for |vim-latex|.  The options are first
listed in alphabetical order, before they are described in more detail.  The
descriptions also list the default values.

Overview:~

  |g:latex_enabled|
  |g:latex_build_dir|
  |g:latex_complete_close_braces|
  |g:latex_complete_enabled|
  |g:latex_complete_recursive_bib|
  |g:latex_complete_patterns|
  |g:latex_fold_enabled|
  |g:latex_fold_automatic|
  |g:latex_fold_envs|
  |g:latex_fold_parts|
  |g:latex_fold_preamble|
  |g:latex_fold_sections|
  |g:latex_indent_enabled|
  |g:latex_latexmk_callback|
  |g:latex_latexmk_enabled|
  |g:latex_latexmk_options|
  |g:latex_latexmk_output|
  |g:latex_mappings_enabled|
  |g:latex_motion_enabled|
  |g:latex_motion_matchparen|
  |g:latex_quickfix_autojump|
  |g:latex_quickfix_ignored_warnings|
  |g:latex_quickfix_ignore_all_warnings|
  |g:latex_quickfix_mode|
  |g:latex_toc_enabled|
  |g:latex_toc_fold_levels|
  |g:latex_toc_fold|
  |g:latex_toc_hide_help|
  |g:latex_toc_resize|
  |g:latex_toc_secnumdepth|
  |g:latex_toc_split_side|
  |g:latex_toc_width|
  |g:latex_viewer|

------------------------------------------------------------------------------
Detailed descriptions and default values:~

                                                             *g:latex_enabled*
If this variable exists and is 0, then |vim-latex| is completely disabled.  By
default, it is not defined.

                                                           *g:latex_build_dir*
Set this variable in case a dedicated build dir is used with `latexmk`/`latex`
compilations. >
  let g:latex_build_dir = '.'
<
                                               *g:latex_complete_close_braces*
When a label or a cite has been completed, this option controls whether it
will be followed by a closing brace. >
  let g:latex_complete_close_braces = 0
<
                                                    *g:latex_complete_enabled*
Use this option to prevent the plugin from setting the 'omnifunc': >
  let g:latex_complete_enabled = 1
<
                                              *g:latex_complete_recursive_bib*
This option toggles recursive searching for bibliography files.  Note that this
option may lead to a significant slowdown for large projects if enabled. >
  let g:latex_complete_recursive_bib = 0
<
                                                   *g:latex_complete_patterns*
Define patterns that control when the label and citation completion is
triggered. >
  let g:latex_complete_patterns = {
      \ 'ref' : '\C\\v\?\(eq\|page\|[cC]\)\?ref\*\?\_\s*{[^{}]*',
      \ 'bib' : '\C\\\a*cite\a*\*\?\(\[[^\]]*\]\)*\_\s*{[^{}]*',
      \ })
<
                                                        *g:latex_fold_enabled*
Use this option to disable/enable folding. >
  let g:latex_fold_enabled = 1
<
                                                      *g:latex_fold_automatic*
Set manual or automatic updating of fold levels.  For manual mode, one must
use the |zx| mapping to update the foldlevels when desired.  For automatic
mode, the fold levels will be updated automatically.  Beware that this may
lead to some minor lags for large files. >
  let g:latex_fold_automatic = 1
<
                                                           *g:latex_fold_envs*
Decide whether environments should be folded or not. >
  let g:latex_fold_envs = 1
<
                                                          *g:latex_fold_parts*
List of parts that should be folded. >
  let g:latex_fold_parts = [
        \ "appendix",
        \ "frontmatter",
        \ "mainmatter",
        \ "backmatter",
      \ ]
<
                                                       *g:latex_fold_preamble*
Decide whether preamble should be folded or not. >
  let g:latex_fold_preamble = 1
<
                                                       *g:latex_fold_sections*
List of section constructs that should be folded. >
  let g:latex_fold_sections = [
        \ "part",
        \ "chapter",
        \ "section",
        \ "subsection",
        \ "subsubsection",
      \ ]
<
                                                      *g:latex_indent_enabled*
Use |vim-latex| indentation function.  Not as customizable as the official
indentation function, but imho it is better. >
  let g:latex_indent_enabled = 1
<
                                                    *g:latex_latexmk_callback*
If enabled, this option tells `latexmk` to run |latex#latexmk#errors| after
compilation is finished.  Note that this feature only works if vim is compiled
with the |+clientserver| option. >
  let g:latex_latexmk_callback = 1
<
                                                     *g:latex_latexmk_enabled*
Whether to enable the `latexmk` interface or not.  Note that even if it is not
enabled, the autoload functions will be available.  However, the
necessary variables and autocommands will not be defined, and the mappings
will not be created. >
  let g:latex_latexmk_enabled = 1
<
                                                     *g:latex_latexmk_options*
Set extra options for `latexmk` compilation. >
  let g:latex_latexmk_options = ''
<
                                                      *g:latex_latexmk_output*
Set desired output for `latexmk` compilation. >
  let g:latex_latexmk_output = 'pdf'
<
                                                   *g:latex_quickfix_autojump*
Whether to automatically jump to the first error whenever the |quickfix| window
is opened. >
  let g:latex_latexmk_autojump = 0
<
                                        *g:latex_quickfix_ignore_all_warnings*
If enabled, all LaTeX warnings are ignored and will not be listed in the
quickfix window.  LaTeX errors will of course still be listed. >
  let g:latex_quickfix_ignore_all_warnings = 0
<
                                           *g:latex_quickfix_ignored_warnings*
List of warning messages that should be ignored. By default, no warnings are
ignored. To ignore some common LaTeX warnings, try the following setting: >
  let g:latex_quickfix_ignored_warnings = [
        \ 'Underfull',
        \ 'Overfull',
        \ 'specifier changed to',
      \ ]
<
                                                       *g:latex_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 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.

The default value is: >
  let g:latex_quickfix_mode = 2
<
                                            *g:latex_quickfix_open_on_warning*
If it is 0, then the quickfix window will only be opened on errors or when
it is forced open. >
  let g:latex_quickfix_open_on_warning = 1
<
                                                    *g:latex_mappings_enabled*
Whether to load the default mappings.  If this is set to 0, then no mappings
will be defined.  Since all of the functionality is available as functions,
this allows the user to define his or her own mappings. >
  let g:latex_mappings_enabled= 1
<
                                                      *g:latex_motion_enabled*
Whether to enable the motion interface.  If it is disabled, then neither the
default mappings nor the autocommands that enable highlighting of matching
parens will be defined. >
  let g:latex_motion_enabled = 1
<
                                                   *g:latex_motion_matchparen*
Enable highlighting of matching parens.  This gives better support for LaTeX,
but disables the builtin |matchparen|. >
  let g:latex_motion_matchparen = 1
<
                                                         *g:latex_toc_enabled*
Enable interface for TOC.  If it is disabled, then mappings for the TOC will
not be created. >
  let g:latex_toc_enabled = 1
<
                                                     *g:latex_toc_fold_levels*
If TOC entries are folded, this option controls the number of fold levels that
will be used. >
  let g:latex_toc_fold_levels = 0
<
                                                            *g:latex_toc_fold*
Turn on folding of TOC entries. >
  let g:latex_toc_fold = 0
<
                                                       *g:latex_toc_hide_help*
Allow the TOC help text to be hidden. >
  let g:latex_toc_hide_help = 0
<
                                                          *g:latex_toc_resize*
Automatically resize vim when the TOC window is opened. >
  let g:latex_toc_resize = 1
<
                                                     *g:latex_toc_secnumdepth*
Define number of section levels to display.  Set level corresponding to the
desired latex variable `secnumdepth`.  Note that the variable may be updated
directly through the TOC window.  For more info on `secnumdepth` see e.g.
http://en.wikibooks.org/w/index.php?title=LaTeX/Document_Structure >
  let g:latex_toc_secnumdepth = 3
<
                                                      *g:latex_toc_split_side*
Define where the TOC window is opened. >
  let g:latex_toc_split_side = 'leftabove'
<
                                                           *g:latex_toc_width*
Set width of TOC window. >
  let g:latex_toc_width = 30
<
                                                              *g:latex_viewer*
Set default viewer application. >
  let g:latex_viewer = 'xdg-open'
<
==============================================================================
OMNI COMPLETION                                         *vim-latex-completion*

|vim-latex| provides an 'omnifunc' for omni completion, see |compl-omni| and
|latex#complete#omnifunc|.  The function is enabled by default, but may be
disabled with |g:latex_complete_enabled|.  Omni completion is accessible with
|i_CTRL-X_CTRL-O|.

The omni function completes labels and citations.  The completion candidates
are gathered with the functions |latex#complete#labels| and
|latex#complete#bibtex|.  If |g:latex_complete_close_braces| is set to 1, then
the completion includes closing braces.

Associated settings:
        |g:latex_complete_enabled|
        |g:latex_complete_patterns.ref|
        |g:latex_complete_patterns.bib|
        |g:latex_complete_close_braces|
        |g:latex_complete_recursive_bib|       

Functions:
        |latex#complete#omnifunc|
        |latex#complete#labels|
        |latex#complete#bibtex|

------------------------------------------------------------------------------
Complete labels~

Label completion is triggered by '\ref{' commands as defined with
|g:latex_complete_patterns.ref|.  The completion parses every relevant aux
file to gather the completion candidates.  This is important to note, 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 their associated value and page
number.  The label completion matches:

    1. labels: >
        \ref{sec:<CTRL-X><CTRL-O>
<    2. numbers: >
        \eqref{2<CTRL-X><CTRL-O>
<    3. labels and numbers together (separated by whitespace): >
        \eqref{eq 2<CTRL-X><CTRL-O>

------------------------------------------------------------------------------
Complete citations~

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

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.

==============================================================================
FOLDING                                                    *vim-latex-folding*

|vim-latex| can fold texts according to LaTeX structure (part, chapter, section
and subsection).  Folding is turned on by default, but it can be disabled if
desired |g:latex_fold_enabled|.

When folding is turned on and a latex document is opened, the document is
parsed once in order to define the highest fold level based on which parts
(such as frontmatter, backmatter, and appendix) and section types (chapter,
section, etc.) are present.  If the document has been edited and a new fold
level is required (or has become redundant), then |latex#fold#refresh| can be
used to refresh the fold level settings.  This function is mapped by default
to 'zx'.

Associated settings:
    |g:latex_fold_enabled|
    |g:latex_fold_automatic|
    |g:latex_fold_preamble|
    |g:latex_fold_parts|
    |g:latex_fold_sections|
    |g:latex_fold_envs|

Functions:
    |latex#fold#level|
    |latex#fold#text|
    |latex#fold#refresh|

==============================================================================
INDENTATION                                                 *vim-latex-indent*

The official indentation function is pretty good and allows for some
customization.  However, I am not quite satisfied, so I wrote my own
indentation function that is not customizable at all (at least for now), but
that I think is better.  It is enabled by default, but may be disabled if
desired |g:latex_indent_enabled|.

Associated settings:
    |g:latex_indent_enabled|

==============================================================================
LATEXMK                                                    *vim-latex-latexmk*

|vim-latex| provides a basic interface to `latexmk` for background
compilation.  The interface may be disabled with |g:latex_latexmk_enabled|.
The default mappings are: >

  nnoremap <localleader>ll :call latex#latexmk#compile()<cr>
  nnoremap <localleader>lk :call latex#latexmk#stop(1)<cr>
  nnoremap <localleader>lK :call latex#latexmk#stop_all()<cr>
  nnoremap <localleader>le :call latex#latexmk#errors(1)<cr>
  nnoremap <localleader>lo :call latex#latexmk#output()<cr>
  nnoremap <localleader>lg :call latex#latexmk#status(0)<cr>
  nnoremap <localleader>lG :call latex#latexmk#status(1)<cr>
  nnoremap <localleader>lc :call latex#latexmk#clean(0)<cr>
  nnoremap <localleader>lC :call latex#latexmk#clean(1)<cr>

The background compilation is started with |latex#latexmk#compile|.  It relies
on the preview continuous mode of `latexmk`.  If vim is compiled with the
|+clientserver| option and if |g:latex_latexmk_callback| is enabled, then
compilation errors are parsed automatically.  This is done by utilizing the
tricks explained in |vim-latex-latexmk-tricks|.

To check for and view errors in the quickfix window, use
|latex#latexmk#errors|.  To check if background compilation is running, use
|latex#latexmk#status|.

Associated settings:
    |g:latex_latexmk_enabled|
    |g:latex_latexmk_callback|
    |g:latex_latexmk_autojump|
    |g:latex_latexmk_options|
    |g:latex_latexmk_output|

Functions:
    |latex#latexmk#clean|
    |latex#latexmk#compile|
    |latex#latexmk#errors|
    |latex#latexmk#output|
    |latex#latexmk#status|
    |latex#latexmk#stop|
    |latex#latexmk#stop_all|

------------------------------------------------------------------------------
Latexmk tricks:~                                    *vim-latex-latexmk-tricks*

`latexmk` allows to set options through a configuration file
`$HOME/.latexmkrc`.  A particular set of options are very convenient for
a good coupling between |vim-latex| and `latexmk`: `$..._cmd`, where `...`
refers to either `compiling`, `success`, or `failure`.  These options can be
used to specify commands that are run by `latexmk` before and after
a compilation run.  For instance, one may use these options: >

$compiling_cmd = "xdotool search --name \"%D\" " .
                 "set_window --name \"%D compiling...\"";
$success_cmd = "xdotool search --name \"%D\" " .
               "set_window --name \"%D OK\"; " .
               "gvim --remote-expr 'latex#latexmk#errors(0)'";
$failure_cmd = "xdotool search --name \"%D\" " .
               "set_window --name \"%D FAILURE\"; " .
               "gvim --remote-expr 'latex#latexmk#errors(0)'";
<
Here `xdotool` (http://www.semicomplete.com/projects/xdotool/) is used to
change the title of the pdf viewer during and after compilation.  In addition,
|latex#latexmk#errors| is called through the |clientserver| after each run to
either open the quickfix window when there are errors/warnings, or to close the
quickfix window in case all errors/warnings are gone.

The latter trick is utilized in |vim-latex| to automatically run the callback
commands if vim has the option |+clientserver|, and if the option
|g:latex_latexmk_callback| is enabled.  The command that is used by `latexmk`
is then on the following form: >

  gvim --servername v:servername --remote-expr 'latex#latexmk#errors(0)'

This command is then appended to the existing `$success_cmd` and
`$failure_cmd`.  Note that if the existing commands are not empty, then they
must end with a semicolon in order to allow |vim-latex| to append safely.

------------------------------------------------------------------------------
Latexmk synctex:~                                  *vim-latex-latexmk-synctex*
                                                           *vim-latex-synctex*

|vim-latex| does not include automatic support for synctex.  However, the view
command does accept arguments, which makes it easy to add a forward search
mapping, such as this for the popular viewer Okular: >

  let g:latex_viewer = 'okular'
  function! SyncTexForward()
    call latex#view('--unique '
      \ . g:latex#data[b:latex.id].out()
      \ . '\#src:' . line(".") . expand('%:p'))
  endfunction
  nmap <leader>ls :call SyncTexForward()<cr>

Backward search is generally set up inside the specific viewers, and how to do
this depends on the viewer.  Please read the specific manuals or search the
web to find out how to do it.

==============================================================================
MOTION                                                      *vim-latex-motion*

|vim-latex| provides some functions that can be used to give improved motions
and text objects.  For instance, |vim-latex-motion| enables highlighting of
matching parens or tags (such as begin/end structures).  The functionality is
enabled by default, but may be disabled if desired.

Associated settings:
    |g:latex_motion_enabled|
    |g:latex_motion_matchparen|

Functions:
    |latex#motion#find_matching_pair|
    |latex#motion#next_section|
    |latex#motion#sel_delimiter|
    |latex#motion#sel_environment|
    |latex#motion#sel_inline_math|

==============================================================================
CHANGE                                                      *vim-latex-change*

|vim-latex| has a nice functionality that enables quick toggling of stars in
environments or toggling of `\left` and `\right` pairs of delimiters.
Functions are also provided to change or close the current environment and to
wrap the selected text.

Functions:
    |latex#change#close_environment|
    |latex#change#env|
    |latex#change#env_prompt|
    |latex#change#to_command|
    |latex#change#toggle_delim|
    |latex#change#toggle_env_star|
    |latex#change#wrap_selection|
    |latex#change#wrap_selection_prompt|

==============================================================================
UTILITY FUNCTIONS                                             *vim-latex-util*

Several utility functions are available.  Many of these are used as building
blocks for other functionalities, but are also available for users to add
additional functionality.

Functions:
    |latex#util#convert_back|
    |latex#util#get_delim|
    |latex#util#get_env|
    |latex#util#has_syntax|
    |latex#util#in_comment|
    |latex#util#kpsewhich|
    |latex#util#tex2tree|
    |latex#util#tree2tex|

==============================================================================
TABLE OF CONTENTS                                              *vim-latex-toc*

|vim-latex| provides a table of contents (TOC) window that can be opened
|latex#toc#open|  or toggled |latex#toc#toggle|.  In the TOC, one can use
'<CR>' on a selected entry to navigate.

Associated settings:
    |g:latex_toc_enabled|
    |g:latex_toc_fold_levels|
    |g:latex_toc_fold|
    |g:latex_toc_hide_help|
    |g:latex_toc_resize|
    |g:latex_toc_split_side|
    |g:latex_toc_width|

Functions:
    |latex#toc#open|
    |latex#toc#toggle|

==============================================================================
FUNCTION REFERENCE                                       *vim-latex-functions*

The following is a reference of the available functions, sorted
alphabetically.  First a short overview is given, then more detailed
descriptions follow.

Overview:~

  |latex#change#close_environment|
  |latex#change#env|
  |latex#change#env_prompt|
  |latex#change#to_command|
  |latex#change#toggle_delim|
  |latex#change#toggle_env_star|
  |latex#change#wrap_selection|
  |latex#change#wrap_selection_prompt|
  |latex#complete#omnifunc|
  |latex#complete#labels|
  |latex#complete#bibtex|
  |latex#fold#level|
  |latex#fold#text|
  |latex#fold#refresh|
  |latex#help|
  |latex#info|
  |latex#latexmk#clean|
  |latex#latexmk#compile|
  |latex#latexmk#errors|
  |latex#latexmk#output|
  |latex#latexmk#status|
  |latex#latexmk#stop|
  |latex#latexmk#stop_all|
  |latex#motion#find_matching_pair|
  |latex#motion#next_sec|
  |latex#motion#sel_delimiter|
  |latex#motion#sel_environment|
  |latex#motion#sel_inline_math|
  |latex#reinit|
  |latex#toc#open|
  |latex#toc#toggle|
  |latex#util#convert_back|
  |latex#util#get_delim|
  |latex#util#get_env|
  |latex#util#has_syntax|
  |latex#util#in_comment|
  |latex#util#kpsewhich|
  |latex#util#tex2tree|
  |latex#util#tree2tex|
  |latex#view|

------------------------------------------------------------------------------
Detailed descriptions:~

                                               *latex#change#close_environment*
Closes current delimiter or environment command.  The function is only useful
when used as an insert mode command, since it returns the closing part of the
delimiter or environment.

                                                             *latex#change#env*
Change the current environment name to the one passed as an argument.

                                                      *latex#change#env_prompt*
Change the current environment name to one typed at a prompt.

                                                      *latex#change#to_command*
Turn word under cursor into command.  This essentially prepends a backslash
and adds an opening brace.  The function may be used both in an insert mode
mapping and in a normal mode mapping.

                                                    *latex#change#toggle_delim*
Toggle delimiters between `(` `)` and `\left(` `\right)` (and similar).

                                                 *latex#change#toggle_env_star*
Toggle star for the current environment.

                                                  *latex#change#wrap_selection*
Wrap the current selection within a supplied command.

                                           *latex#change#wrap_selection_prompt*
Wrap the current selection within a command given at a prompt.

                                                     *latex#complete#omnifunc*
An 'omnifunc' for label and citation completion, see |vim-latex-completion|.

                                                       *latex#complete#labels*
Parses aux files to gather label candidates for completion.

                                                       *latex#complete#bibtex*
Parses included bibliography files and `thebibliography` environments to
gather candidates for completion.

                                                            *latex#fold#level*
Sets fold level for each line. 'foldexpr' |fold-expr|

                                                             *latex#fold#text*
Sets fold title text. 'foldtext'

                                                          *latex#fold#refresh*
Refreshes fold levels based on which parts and sections used in the current
file buffer.  Also issues a |zx| call to update folds.

                                                                  *latex#help*
Lists all mappings that are defined specifically for the current buffer.  If
the default mappings are used, then |latex#help| will display them.

                                                                  *latex#info*
Echoes the contents of |g:latex#data| and |b:latex|.  This is useful mainly
for debugging.

                                                         *latex#latexmk#clean*
Clean up temporary files with `latexmk -c`.  An optional argument may be
supplied to indicate that the `-C` flag should be used, which also cleans
output files.  This will only be run if `latexmk` is not already running.

                                                       *latex#latexmk#compile*
Starts `latexmk -pvc ...` for the given buffer, if it is not already running.

                                                        *latex#latexmk#errors*
Parse the log file for errors and warnings.  If any errors or warnings are
found, they are displayed in the quickfix window.  The exact behaviour is
controlled through the different quickfix specific option:

  |g:latex_quickfix_autojump|
  |g:latex_quickfix_ignore_all_warnings|
  |g:latex_quickfix_ignored_warnings|
  |g:latex_quickfix_mode|

Note: The function takes one argument, which if nonzero will force open the
quickfix window if any errors are present.  This is used in the normal mode
mapping.

                                                        *latex#latexmk#output*
Opens a new buffer that show the output from the `latexmk` command.  To close
the buffer, one may simply type `q`.

                                                        *latex#latexmk#status*
Show if `latexmk` has been started for the current buffer.  An optional
argument may be supplied, in which case the status for all buffers is shown.

                                                          *latex#latexmk#stop*
Stop the `latexmk` process running for the current buffer.  An optional
argument may be given, in which case the function becomes verbose.

                                                      *latex#latexmk#stop_all*
Stops all running `latexmk` processes.

                                             *latex#motion#find_matching_pair*
Finds a matching pair of parentheses or begin-end-tags.  The functions is used
to find the pair closest to the current cursor position.

                                                       *latex#motion#next_sec*
A motion command function that moves to the next section.  Used to redefine
the mappings for ']]', '[[', and similar.

                                                  *latex#motion#sel_delimiter*
A function that is used to create text objects for text contained within a set
of delimiters.

                                                *latex#motion#sel_environment*
A function that is used to create text objects for environments.

                                                *latex#motion#sel_inline_math*
A function that is used to create text objects for inline math structures.

                                                                *latex#reinit*
Clears the current global and local data in |g:latex#data| and |b:latex|,
stops running `latexmk` processes |latex#latexmk#stop_all|,  and then performs
a new initialization.

                                                              *latex#toc#open*
Open the TOC window.  If it is already open, then simply move the cursor to
the TOC window.

                                                            *latex#toc#toggle*
Toggle TOC window: If TOC window is open, then close it.  If it is closed,
then open it (but do not move the cursor to the window).

                                                     *latex#util#convert_back*
Convert from stuff like `\IeC{\"u}` to corresponding unicode symbols.

                                                        *latex#util#get_delim*
Get surrounding delimiters (with position).

                                                          *latex#util#get_env*
Get surrounding environment.  If optional argument supplied, the function also
returns the position (line and column number) of the begin and end structure.

                                                       *latex#util#has_syntax*
Checks if the given position (or current position) is within the given syntax
structure.

                                                       *latex#util#in_comment*
Checks if the given position (or current position) is within a comment.

                                                        *latex#util#kpsewhich*
Parse file with `kpsewhich`.

                                                         *latex#util#tex2tree*
Turn tex structure to a tree composed of lists.  E.g. >
  { testing { tex2tree { } } } => [ "testing" , [ "tex2tree", []]]
<
                                                         *latex#util#tree2tex*
Turns a tree composed of lists into tex structure.  E.g. >
  [ "testing" , [ "tex2tree", []]] => { testing { tex2tree { } } }
<
                                                                  *latex#view*
Open the output file (specified with |g:latex_latexmk_output|) with the
default viewer |g:latex_viewer|.

==============================================================================
CREDITS                                                    *vim-latex-credits*

|vim-latex| 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/vim-latex.

|vim-latex| 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/.

The documentation of |vim-latex| is structured with inspiration from CtrlP
(https://github.com/kien/ctrlp.vim), simply because CtrlP has a very good
documentation.

==============================================================================
CHANGELOG                                                *vim-latex-changelog*

The following changelog only logs important changes, such as changes that
break backwards compatibility.  See the git log for the detailed changelog.

2014-06-13: Changed some option names~
Some |vim-latex| 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:latex_quickfix_ignored_warnings|
  |g:latex_quickfix_ignore_all_warnings|
  |g:latex_quickfix_autojump|
  |g:latex_quickfix_mode|

2013-10-05: First public release~

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: