vim/vimtex
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
e74fc287ed
vimtex/doc/vimtex.txt
Karl Yngve Lervåg e74fc287ed Improved support for subfiles package (#155) 
Added parsing of main file from `\documentclass[main.tex]{subfiles}`.
2015-04-29 15:40:08 +02:00

1292 lines
52 KiB
Plaintext
Raw Blame History

*vimtex.txt* A modern vim plugin for editing LaTeX files.
*vimtex*
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 *vimtex-contents*
Introduction |vimtex-introduction|
Feature overview |vimtex-features|
Requirements |vimtex-requirements|
Support for multi-file projects |vimtex-multi-file|
Comment on internal tex plugin |vimtex-comment-internal|
Usage |vimtex-usage|
Default mappings |vimtex-default-mappings|
Options |vimtex-options|
Commands |vimtex-commands|
Map definitions |vimtex-mappings|
Completion |vimtex-completion|
Complete labels |vimtex-complete-labels|
Complete citations |vimtex-complete-cites|
Autocomplete |vimtex-complete-auto|
Neocomplete |vimtex-complete-neocomplete|
YouCompleteMe |vimtex-complete-youcompleteme|
Folding |vimtex-folding|
Indentation |vimtex-indent|
Syntax highlighting |vimtex-syntax|
Navigation |vimtex-navigation|
Table of contents |vimtex-toc|
Table of labels |vimtex-labels|
Latexmk |vimtex-latexmk|
Latexmk tricks |vimtex-latexmk-tricks|
Lacheck |vimtex-latexmk-lacheck|
View |vimtex-view|
Synctex |vimtex-synctex|
Forward search |vimtex-synctex-forward-search|
Backward search |vimtex-synctex-backward-search|
Code structure |vimtex-code|
FAQ |vimtex-faq|
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.
-----------------------------------------------------------------------------
Feature overview~
*vimtex-features*
- Document compilation with `latexmk`
- Forward search with several PDF viewers
- Completion of citations and labels
- Document navigation through
- table of content
- table of labels
- Motions
- Move between sections with `[[`, `[]`, `][`, `]]`
- Move between matching delimiters with `%`
- Text objects
- `ie` `ae` LaTeX environments
- `i$` `a$` Inline math structures
- `id` `ad` Delimiters
- Other mappings
- Delete the surrounding command or environment with `dse`/`dsc`
- Change the surrounding command or environment with `csd`/`cse`
- Toggle starred environment with `tse`
- Toggle between e.g. `()` and `\left(\right)` with `tsd`
- Close the current environment in insert mode with `]]`
- Insert new command with `<F7>`
- Folding
- Indentation
- Improved syntax highlighting
- Highlight matching delimiters
- Support for `biblatex`/`natbib` package
- Support for `cleveref` package
- Support for `listings` package
- Support for `dot2tex` with nested syntax highlighting
------------------------------------------------------------------------------
Requirements~
*vimtex-requirements*
`latexmk` http://users.phys.psu.edu/~collins/software/latexmk-jcc
|vimtex| uses `latexmk` to compile the LaTeX document. `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)." [Copied from the latexmk page.] For more info, see
|vimtex-latexmk|.
|clientserver|
|vimtex| requires the |clientserver| for the callback functionality to
work. The callbacks are used to provide feedback when compilation is
finished, as well as to parse the log for errors and warnings and to open
the |quickfix| window when necessary.
If you use Vim under a terminal in Linux or OSX, then Vim must be
started as a command server with the command line option `--servername`,
e.g. `vim --servername VIM`. For different ways of ensuring this, see:
http://vim.wikia.com/wiki/Enable_servername_capability_in_vim/xterm
------------------------------------------------------------------------------
Support for multi-file projects~
*vimtex-multi-file*
|vimtex| 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
< *vimtex-subfiles*
Further, |vimtex| supports the `subfiles` package. That is, the main file is
parsed from the `\documentclass` line whenever it has the following format: >
\documentclass[main.tex]{subfiles}
< *b:vimtex_main*
Finally, the main file may be specified through the buffer variable
`b:vimtex_main`. If one uses project specific |vimrc| files, one may then use
an |autocmd| to specify the main file through this buffer variable with >
autocmd FileType tex let b:vimtex_main = 'main.tex'
------------------------------------------------------------------------------
Comment on internal tex plugin~
*vimtex-comment-internal*
Vim ships with some LaTeX support out of the box. In particular, it provides
good syntax highlighting (|ft-tex-syntax|), indentation (see the source file
$VIMRUNTIME/indent/tex.vim for the documentation), and some sensible options
(|ft-tex-plugin|).
When |vimtex| is active, it will be used as the main |ftplugin|. It will
define the same set of sensible settings as the internal plugin. However,
|vimtex| does not provide its own syntax, instead it adds a few minor
improvements to |ft-tex-syntax|, see |vimtex-syntax|. |vimtex| also provides its
own indentation plugin, see |vimtex-indent|.
Vim will generally autodetect filetypes automatically. In most cases this
works as expected, however, in some cases it will detect a file with the `tex`
suffix as a |plaintex|. To prevent this, one may set the option
|g:tex_flavor| in ones `vimrc` file, that is: >
let g:tex_flavor = 'latex'
==============================================================================
USAGE *vimtex-usage*
Default mappings |vimtex-default-mappings|
Options |vimtex-options|
Commands |vimtex-commands|
Mappings |vimtex-user-mappings|
------------------------------------------------------------------------------
Default mappings~
*vimtex-default-mappings*
|vimtex| is designed to be controlled by a selection of mappings. The default
mappings are listed below. Most of the mappings are also available as
commands, see |vimtex-commands|.
If one prefers, one may disable the default mappings through the option
|g:vimtex_mappings_enabled|. One can then define custom mappings 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.
-----------------------------------------------------------~
LHS RHS MODE~
-----------------------------------------------------------~
<localleader>li |<plug>(vimtex-info)| `n`
<localleader>lt |<plug>(vimtex-toc-open)| `n`
<localleader>lT |<plug>(vimtex-toc-toggle)| `n`
<localleader>ly |<plug>(vimtex-labels-open)| `n`
<localleader>lY |<plug>(vimtex-labels-toggle)| `n`
<localleader>lv |<plug>(vimtex-view)| `n`
<localleader>lr |<plug>(vimtex-reverse-search)| `n`
<localleader>ll |<plug>(vimtex-compile-toggle)| `n`
<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-full)| `n`
<localleader>lc |<plug>(vimtex-clean)| `n`
<localleader>lC |<plug>(vimtex-clean-full)| `n`
dse |<plug>(vimtex-delete-env)| `n`
dsc |<plug>(vimtex-delete-cmd)| `n`
cse |<plug>(vimtex-change-env)| `n`
csc |<plug>(vimtex-change-cmd)| `n`
tse |<plug>(vimtex-toggle-star)| `n`
tsd |<plug>(vimtex-toggle-delim)| `n`
<F7> |<plug>(vimtex-create-cmd)| `ni`
]] |<plug>(vimtex-close-env)| `i`
a$ |<plug>(vimtex-a$)| `nxo`
i$ |<plug>(vimtex-i$)| `nxo`
ae |<plug>(vimtex-ae)| `nxo`
ie |<plug>(vimtex-ie)| `nxo`
ad |<plug>(vimtex-ad)| `nxo`
id |<plug>(vimtex-id)| `nxo`
% |<plug>(vimtex-%)| `nxo`
]] |<plug>(vimtex-]])| `nxo`
][ |<plug>(vimtex-][)| `nxo`
[] |<plug>(vimtex-[])| `nxo`
[[ |<plug>(vimtex-[[)| `nxo`
-----------------------------------------------------------~
------------------------------------------------------------------------------
Options~
*vimtex-options*
*g:vimtex_enabled*
Set to 0 to disable |vimtex|.
Default value: Undefined.
*g:vimtex_complete_enabled*
Use this option to disable/enable |vimtex| completion.
Default value: 1
*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_complete_recursive_bib*
This option toggles recursive searching for bibliography files.
Note: This feature may lead to a significant lag for large projects.
Default value: 0
*g:vimtex_complete_patterns*
Define patterns that control when the label and citation completion is
triggered.
Default value: >
let g:vimtex_complete_patterns = {
\ 'ref' : '\C\\v\?\(eq\|page\|[cC]\)\?ref\*\?\_\s*{[^{}]*',
\ 'bib' : '\C\\\a*cite\a*\*\?\(\[[^\]]*\]\)*\_\s*{[^{}]*',
\ })
<
*g:vimtex_fold_enabled*
Use this option to disable/enable folding.
Default value: 1
*g:vimtex_fold_automatic*
Turn on/off automatic updating of fold levels. If it is off, one must use
the |zx| mapping to update the foldlevels when desired.
Note: Automatic updating of fold levels may lead to some lags for large
files.
Default value: 0
*g:vimtex_fold_envs*
Control whether or not to fold environments.
Default value: 1
*g:vimtex_fold_parts*
List of document parts that should be folded.
Default value: >
let g:vimtex_fold_parts = [
\ "appendix",
\ "frontmatter",
\ "mainmatter",
\ "backmatter",
\ ]
<
*g:vimtex_fold_preamble*
Control whether or not to fold the preamble.
Default value: 1
*g:vimtex_fold_sections*
List of section constructs that should be folded.
Default value: >
let g:vimtex_fold_sections = [
\ "part",
\ "chapter",
\ "section",
\ "subsection",
\ "subsubsection",
\ ]
<
*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_index_hide_line_numbers*
If enabled, then line numbers will be hidden in the index windows. That is,
|nonumber| and |norelativenumber| will be set locally.
Default value: 1
*g:vimtex_index_resize*
Whether or not to automatically resize vim when index windows are opened.
Note: This option makes sense if the index window is vertically split.
Default value: 0
*g:vimtex_index_show_help*
Whether to display the index help text.
Default value: 1
*g:vimtex_index_split_pos*
Define where index windows should be opened.
Default value: 'vert leftabove'
*g:vimtex_index_split_width*
For vertically split windows: Set width of index window.
Default value: 30
*g:vimtex_labels_enabled*
Use this option to disable/enable table of labels.
Default value: 1
*g:vimtex_toc_enabled*
Use this option to disable/enable table of contents (ToC).
Default value: 1
*g:vimtex_toc_fold*
Turn on folding of ToC entries.
Default value: 0
*g:vimtex_toc_fold_levels*
This option controls the number of fold levels that will be used if the
folding of the ToC is enabled.
Default value: 1
*g:vimtex_toc_show_preamble*
Whether to include the preamble in the ToC.
Default value: 1
*g:vimtex_toc_show_numbers*
Set whether or not to show section numbers in ToC.
Note: The numbers may also be toggled inside the ToC window with the `s`
keybinding.
Default value: 1
*g:vimtex_toc_number_width*
Set the display width of numbers in the ToC. If it is set to 0, then the
width is set based on the section depth, see |g:vimtex_toc_secnumdepth|.
Default value: 0
*g:vimtex_toc_secnumdepth*
Define the number of section levels to display. Set level corresponding to
the desired latex variable `secnumdepth`. For more info on `secnumdepth`,
see http://en.wikibooks.org/w/index.php?title=LaTeX/Document_Structure.
Note: The variable may be updated inside the ToC window with the mappings
`+` and `-`.
Default value: 3
*g:vimtex_mappings_enabled*
Control whether or not to load the default mappings.
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_motion_matchparen*
Enable highlighting of matching delimiters.
Note: This will override the builtin |matchparen|.
Default value: 1
*g:vimtex_latexmk_enabled*
Use this option to disable/enable the `latexmk` interface |vimtex-latexmk|.
Default value: 1
*g:vimtex_latexmk_build_dir*
This option sets the compilation build directory. It corresponds to the
`-output-directory` option in `latexmk`.
Default value: '.'
*g:vimtex_latexmk_callback*
If enabled, this option tells `latexmk` to run |vimtex#latexmk#callback| after
compilation is finished.
Note 1: This feature requires |clientserver|.
Note 2: Callbacks are only possible when continuous mode is active, see
|g:vimtex_latexmk_continuous|.
Default value: 1
*g:vimtex_latexmk_continuous*
If enabled, `latexmk` will run in continuous mode, i.e. with the `-pvc`
argument. This means that the document is compiled every time a document
file has been changed.
If disabled, `latexmk` will run single shot compilations.
Default value: 1
*g:vimtex_latexmk_background*
If continuous mode is disabled, then this option may be used to set
whether single shot compilations should be run in the foreground or the
background.
Default value: 0
*g:vimtex_latexmk_options*
A string of options that will be passed on to `latexmk`.
Note: Options may also be specified indirectly to `latexmk` through
both a global and a project specific `.latexmkrc` file.
Default value: '-pdf'
*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_all_warnings*
This option controls whether or not LaTeX warnings should be included in the
|quickfix| window. LaTeX errors will always be included.
Default value: 0
*g:vimtex_quickfix_ignored_warnings*
A list of warning messages that should be ignored. The list is a list of
strings. Any LaTeX warning that contains a string in the list will be
ignored.
To ignore some common LaTeX warnings, try the following setting: >
let g:vimtex_quickfix_ignored_warnings = [
\ 'Underfull',
\ 'Overfull',
\ 'specifier changed to',
\ ]
<
Note: This option is only relevant if |g:vimtex_quickfix_ignore_all_warnings|
is disabled.
Default value: []
*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 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 both the
continuous mode and the callbacks are active, see
|g:vimtex_latexmk_continuous| and |g:vimtex_latexmk_callback|.
Default value: 2
*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.
Note: The quickfix window will only be opened automatically if both the
continuous mode and the callbacks are active, see
|g:vimtex_latexmk_continuous| and |g:vimtex_latexmk_callback|.
Default value: 1
*g:vimtex_view_enabled*
Use this option to disable/enable the |vimtex| viewer interface.
Default value: 1
*g:vimtex_view_method*
Set the viewer method. The supported viewers are listed below. Please see
|vimtex-synctex| for explanations of the terms 'forward search' and
'backward search'.
general~
This is a basic interface where the viewer can be specified through
|g:vimtex_view_general_viewer|.
mupdf~
http://www.mupdf.com/
A very minimalistic and quick PDF viewer. Supports forward and backward
search. Backward search is available with |VimtexRSearch|, 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.
okular~
https://okular.kde.org/
A very feature rich PDF viewer. Supports forward search. Backward
search must be set up from the viewer.
qpdfview~
https://launchpad.net/qpdfview
A tabbed document viewer. Supports forward search. Backward search
must be set up from the viewer.
sumatrapdf~
http://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. Backward search
must be set up from the viewer.
Note: It is possible to set up inverse search for SumatraPDF through the
command line. This can be utilized to improve the current
implementation in order to set the correct |servername| for
inverse search. At the moment, this is not implemented. However,
one can achieve the functionality by using the general viewer with
the following setting: >
let g:vimtex_view_general_viewer = 'SumatraPDF -reuse-instance '
\ . '-inverse-search "gvim --servername ' . v:servername
\ . ' --remote-send \"^<C-\^>^<C-n^>'
\ . ':drop \%f^<CR^>:\%l^<CR^>:normal\! zzzv^<CR^>'
\ . ':execute ''drop '' . fnameescape(''\%f'')^<CR^>'
\ . ':\%l^<CR^>:normal\! zzzv^<CR^>'
\ . ':call remote_foreground('''.v:servername.''')^<CR^>\""'
<
zathura~
https://pwmt.org/projects/zathura/
Zathura is like MuPDF a very fast and minimalistic viewer, but it allows
a more user configuration. Supports forward search and backward search.
If one chooses a method that is not the default method, then the viewer will
support forward search, see |vimtex-synctex-forward-search|.
Default value: 'general'
*g:vimtex_view_general_viewer*
Use a general viewer.
Default value:
Linux: `xdg-open`
Mac: `open`
*g:vimtex_view_<viewer>_options*
Set custom options for the given viewer. See |g:vimtex_view_method| for
a list of possible viewers.
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: ''
------------------------------------------------------------------------------
Commands~
*vimtex-commands*
*VimtexInfo*
*<plug>(vimtex-info)*
:VimtexInfo Show information stored for all projects (available
mostly for debug purposes).
*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.
*VimtexLabelsOpen*
*<plug>(vimtex-labels-open)*
:VimtexLabelsOpen Open table of labels.
*VimtexLabelsToggle*
*<plug>(vimtex-labels-toggle)*
:VimtexLabelsToggle Toggle table of labels.
*VimtexCompile*
*<plug>(vimtex-compile)*
:VimtexCompile Starts compilation, either in continuous mode or in
single shot mode, depending on the value of
|g:vimtex_latexmk_continuous|.
*VimtexCompileToggle*
*<plug>(vimtex-compile-toggle)*
:VimtexCompileToggle Toggles compilation. Only useful when continuous
mode is enabled (|g:vimtex_latexmk_continuous|).
*VimtexCompileSS*
*<plug>(vimtex-compile-ss)*
:VimtexCompileSS Start single shot compilation in background.
*VimtexCompileSS!*
:VimtexCompileSS! Like |VimtexCompileSS|, but in foreground.
*VimtexOutput*
*<plug>(vimtex-compile-output)*
:VimtexOutput Open file where `latexmk` 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 auxilliary files
*VimtexClean!*
*<plug>(vimtex-clean-full)*
:VimtexClean! Clean auxilliary files, include output files
*VimtexErrors*
*<plug>(vimtex-errors)*
:VimtexErrors Open |quickfix| window if there are errors or
warnings.
*VimtexLacheck*
*<plug>(vimtex-lacheck)*
:VimtexLacheck Run `lacheck` to check document for errors.
*VimtexView*
*<plug>(vimtex-view)*
:VimtexView View `pdf` for current project, perform forward
search if available.
*VimtexRSearch*
*<plug>(vimtex-reverse-search)*
:VimtexRSearch Do reverse search (only available for MuPDF viewer).
------------------------------------------------------------------------------
Map definitions~
*vimtex-mappings*
*vimtex-zx*
When |vimtex| folding is enabled, then |vimtex| remaps |zx| and |zX| in such
that the folds are refreshed appropriately.
*<plug>(vimtex-delete-env)*
*<plug>(vimtex-change-env)*
Delete/Change surrounding environment.
*<plug>(vimtex-delete-cmd)*
*<plug>(vimtex-change-cmd)*
Delete/Change surrounding command. Note: <plug>(vimtex-delete-cmd) depends
on |surround.vim| (https://github.com/tpope/vim-surround).
*<plug>(vimtex-toggle-star)*
Toggle starred environment.
*<plug>(vimtex-toggle-delim)*
Toggle delimiters, for instance between `(...)` and `\left(...\right)`.
*<plug>(vimtex-create-cmd)*
Convert current word into a command. This works in both normal and insert
mode.
*<plug>(vimtex-close-env)*
Close the current environment (insert mode).
*<plug>(vimtex-a$)*
Text object for inline math (inclusive).
*<plug>(vimtex-i$)*
Text object for inline math (exclusive).
*<plug>(vimtex-ae)*
Text object for environments (inclusive).
*<plug>(vimtex-ie)*
Text object for environments (exclusive).
*<plug>(vimtex-ad)*
Text object for delimiters (inclusive).
*<plug>(vimtex-id)*
Text object for delimiters (exclusive).
*<plug>(vimtex-%)*
Find matching pair.
*<plug>(vimtex-]])*
Section forward (inclusive).
*<plug>(vimtex-][)*
Section forward (exclusive).
*<plug>(vimtex-[])*
Section backward (inclusive).
*<plug>(vimtex-[[)*
Section backward (exclusive).
==============================================================================
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 both labels and citations. If desired, one may
set |g:vimtex_complete_close_braces|, which makes the completion include
closing braces.
Associated settings:
|g:vimtex_complete_enabled|
|g:vimtex_complete_patterns.ref|
|g:vimtex_complete_patterns.bib|
|g:vimtex_complete_close_braces|
|g:vimtex_complete_recursive_bib|
------------------------------------------------------------------------------
Complete labels~
*vimtex-complete-labels*
Label completion is triggered by '\ref{' commands as defined with
|g:vimtex_complete_patterns.ref|. 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 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~
*vimtex-complete-cites*
Citation completion is triggered by '\cite{' commands as defined with
|g:vimtex_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.
------------------------------------------------------------------------------
Autocomplete~
*vimtex-complete-auto*
Vim does not provide automatic completion by itself, but there exist at least
two good plugins that provide this: |neocomplete| and |youcompleteme|. See below
for descriptions on how to setup these with |vimtex|.
neocomplete~
*vimtex-complete-neocomplete*
|neocomplete| is my preferred choice for an automatic completion engine in vim.
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 =
\ '\v\\\a*(ref|cite)\a*([^]]*\])?\{([^}]*,)*[^}]*'
<
YouCompleteMe~
*vimtex-complete-youcompleteme*
|youcompleteme| is probably the most popular code-completion engine for Vim. The
github repository is here: https://github.com/Valloric/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
let g:ycm_semantic_triggers.tex = [
\ 're!\\[A-Za-z]*(ref|cite)[A-Za-z]*([^]]*])?{([^}]*, ?)*'
\ ]
==============================================================================
FOLDING *vimtex-folding*
|vimtex| can fold documents according to the LaTeX structure (part, chapter,
section and subsection). Folding is turned on by default, but it can be
disabled if desired (|g:vimtex_fold_enabled|).
When folding is enabled 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 the mapping `zx` can be used to
refresh the fold level settings (see |vimtex-zx|).
In order to get slightly cleaner fold text, I recommend setting the global
'fillchars' option. To preserve the default vertical separator and only
change the fold filler, use e.g.: >
set fillchars=vert:|,fold:\
Associated settings:
|g:vimtex_fold_enabled|
|g:vimtex_fold_automatic|
|g:vimtex_fold_preamble|
|g:vimtex_fold_parts|
|g:vimtex_fold_sections|
|g:vimtex_fold_envs|
==============================================================================
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|
==============================================================================
SYNTAX HIGHLIGHTING *vimtex-syntax*
Vim ships with syntax hightlighting for LaTeX documents out of the box, please
see ||ft-tex-syntax|. |vimtex| therefore does not provide its own syntax
highlighting. However, |vimtex| does add some minor improvements:
- Support for `biblatex` and `natbib` package
- Support for `cleveref` package
- Support for `listings` package
- Nested syntax highlighting for `dot2tex`
==============================================================================
NAVIGATION *vimtex-navigation*
*vimtex-index*
The |vimtex-index| is an interface that is used to display lists and indexes
in vertically or horizontally split windows. It supports custom keybindings
inside the index window, including actions on the list elements. The position
of the window is controlled by |g:vimtex_index_split_pos|. By default, the
top of the buffer will display help text to explain the local keybindings.
This may be turned off with |g:vimtex_index_show_help|.
The |vimtex-index| interface is used by the table of contents |vimtex-toc| and
the table of labels |vimtex-labels|.
Associated settings:
|g:vimtex_index_hide_line_numbers|
|g:vimtex_index_resize|
|g:vimtex_index_show_help|
|g:vimtex_index_split_pos|
|g:vimtex_index_split_width|
------------------------------------------------------------------------------
Table of contents~
*vimtex-toc*
|vimtex-toc| shows a table of contents (ToC) for the current LaTeX document.
The ToC entries may be activated/jumped to with <cr> or <space>. The local
keybindings are described if |g:vimtex_index_show_help| is enabled.
Associated settings:
|g:vimtex_toc_enabled|
|g:vimtex_toc_fold|
|g:vimtex_toc_fold_levels|
|g:vimtex_toc_number_width|
|g:vimtex_toc_show_preamble|
|g:vimtex_toc_show_numbers|
|g:vimtex_toc_secnumdepth|
------------------------------------------------------------------------------
Table of labels~
*vimtex-labels*
|vimtex-labels| shows a table of labels similar to the ToC. The table entries
may be filtered with the `f` keybinding. Filters may be removed with the `c`
keybinding.
Associated settings:
|g:vimtex_labels_enabled|
==============================================================================
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).
|vimtex| uses `latexmk` to compile the LaTeX document. It utilizes by default
the preview continuous mode. This means that after the compilation is turned
on, `latexmk` will automatically recompile when any LaTeX project file is
changed.
If one prefers to have single shot compilations, one may disable the
continuous mode with |g:vimtex_latexmk_continuous|. If it is disabled, then
the option |g:vimtex_latexmk_background| may be used to decide if single shot
compilation should run in the foreground or the background.
Regardless of the |g:vimtex_latexmk_continuous| option, single shot
compilation may always be issued with |VimtexCompileSS|.
If vim is compiled with the |+clientserver| option and if
|g:vimtex_latexmk_callback| is enabled (which it is by default), then
compilation errors will be parsed automatically. This is done by utilizing
the tricks explained in |vimtex-latexmk-tricks|. Note that this only works
for continuous compilation mode. One can always check for compilation erors
with |VimtexErrors|.
Associated settings:
|g:vimtex_latexmk_enabled|
|g:vimtex_latexmk_callback|
|g:vimtex_latexmk_autojump|
|g:vimtex_latexmk_continuous|
|g:vimtex_latexmk_background|
|g:vimtex_latexmk_options|
------------------------------------------------------------------------------
Latexmk tricks~
*vimtex-latexmk-tricks*
One may parse options to `latexmk` through |g:vimtex_latexmk_options|.
However, one may also configure `latexmk` explicitly through a global
`~/.latexmkrc` file, or a project specific `.latexmkrc` 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 with something like this: >
$success_cmd = "gvim --remote-expr 'vimtex#latexmk#callback(1)'";
$failure_cmd = "gvim --remote-expr 'vimtex#latexmk#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: http://www.semicomplete.com/projects/xdotool.
------------------------------------------------------------------------------
Lacheck~
*vimtex-latexmk-lacheck*
After compilation of a LaTeX document, the log file will contain errors that
are parsed by |vimtex| as explained above. However, there are syntax checkers
for LaTeX. |vimtex| provides a simple interface to `lacheck` for checking
LaTeX manuscripts for errors. This is available through |VimtexLacheck|.
==============================================================================
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_method|
|g:vimtex_view_general_viewer|
|g:vimtex_view_<viewer>_options|
------------------------------------------------------------------------------
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, one must enable synctex manually by adding the line >
$pdflatex = 'pdflatex -synctex=1 %O %S';
to `~/.latexmkrc`.
------------------------------------------------------------------------------
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 dobbel clicking with the mouse or something similar) to
the corresponding line inside the Vim instance.
Backward search is typially 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.
Note: For backward search to work on windows, one must ensure that the folder
that contains `gVim.exe` is in your `%PATH%` environment variable.
==============================================================================
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 the variables and
functionalities based on the desired options |vimtex-options|. The first run
performs some global initialization, which is mainly to define autocommands.
Other functionality is provided by additional autoloaded scripts. Every
additional script should have an initialization script that sets default
commands and mappings, creates autocommands and performs other necessary
initialization. This initialization script is then called from 'vimtex#init'.
For each LaTeX project that is opened, a |Dictionary| is created and added to
the list 'g:vimtex#data'. The dictionary is initialized with data tied to the
current project. In addition, a dictionary is created for every buffer
'b:vimtex'. This contains data that is specific to the current buffer, most
importantly it contains the ID of the corresponding main LaTeX project. The
command |VimtexInfo| (mapped to <localleader>li by default) will show the
contents of the buffer and global vimtex variables. This combination of local
and global data enables |vimtex| to work properly for multi-file latex
projects. It also allows the editing of different latex projects
simultaneously in different buffers.
==============================================================================
FAQ *vimtex-faq*
*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 `yse` and `ysc`. If you use |surround.vim|, then
the asked for mappings may be easily added if one adds the following lines
to ones `vimrc` file: >
augroup latexSurround
autocmd!
autocmd FileType tex call s:latexSurround()
augroup END
function! s:latexSurround()
let b:surround_{char2nr("e")}
\ = "\\begin{\1environment: \1}\n\t\r\n\\end{\1\1}"
let b:surround_{char2nr("c")} = "\\\1command: \1{\r}"
endfunction
<
*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-={,}
==============================================================================
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/.
==============================================================================
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.
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 noticable 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~
==============================================================================
vim:tw=78:ts=8:ft=help:norl:
Reference in New Issue View Git Blame Copy Permalink