1030 lines
44 KiB
Plaintext
1030 lines
44 KiB
Plaintext
*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:
|