*latex.txt* LaTeX plugin for Vim version 7.3 (and above) *vim-latex* *latex* Author: Karl Yngve Lervåg 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| 10. View ................................. |vim-latex-view| synctex .............................. |vim-latex-synctex| 11. Motion ............................... |vim-latex-motion| 12. Change ............................... |vim-latex-change| 13. Table of contents .................... |vim-latex-toc| 14. Utility functions .................... |vim-latex-util| 15. Function reference ................... |vim-latex-functions| 16. FAQ .................................. |vim-latex-faq| 17. Credits .............................. |vim-latex-credits| 18. 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#help| lists all `vim-latex` mappings defined for the current buffer, by default mapped to '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 '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 'li'. Functions: |latex#info| |latex#help| |latex#reinit| ------------------------------------------------------------------------------ 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 '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() v % *@:call latex#motion#find_matching_pair(1) o % *@:normal v% v a$ *@:call latex#motion#select_inline_math() v i$ *@:call latex#motion#select_inline_math(1) o a$ *@:normal va$ o i$ *@:normal vi$ v ae *@:call latex#motion#select_environment() v ie *@:call latex#motion#select_environment(1) o ae *@:normal vae o ie *@:normal vie v ad *@:call latex#motion#select_delimiter() v id *@:call latex#motion#select_delimiter(1) o ad *@:normal va( o id *@:normal vi( n [[ *@:call latex#motion#next_sec(0,1,0) n [] *@:call latex#motion#next_sec(1,1,0) n ][ *@:call latex#motion#next_sec(1,0,0) n ]] *@:call latex#motion#next_sec(0,0,0) v [[ *@:call latex#motion#next_sec(0,1,1) v [] *@:call latex#motion#next_sec(1,1,1) v ][ *@:call latex#motion#next_sec(1,0,1) v ]] *@:call latex#motion#next_sec(0,0,1) o [[ *@:normal v[[ o [] *@:normal v[] o ][ *@:normal v][ o ]] *@:normal v]] n li *@:call latex#info() n lh *@:call latex#help() n lR *@:call latex#reinit() n lt *@:call latex#toc#open() n lT *@:call latex#toc#toggle() n ll *@:call latex#latexmk#toggle() n lk *@:call latex#latexmk#stop(1) n lK *@:call latex#latexmk#stop_all() n le *@:call latex#latexmk#errors(1) n lo *@:call latex#latexmk#output() n lg *@:call latex#latexmk#status() n lG *@:call latex#latexmk#status(1) n lc *@:call latex#latexmk#clean() n lC *@:call latex#latexmk#clean(1) n lv *@:call latex#view#view() n lr *@:call latex#view#rsearch() n zx *@:call latex#fold#refresh() n dse *@:call latex#change#env('') n cse *@:call latex#change#env_prompt() n dsc @ds}dF\ n csc *@:call latex#change#command() n tse *@:call latex#change#toggle_env_star() n tsd *@:call latex#change#toggle_delim() n *@:call latex#change#to_command()i i *@:call latex#change#to_command() i ]] *@:call latex#change#close_environment() ============================================================================== 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(0) *VimLatexClean!* call latex#latexmk#clean(1) *VimLatexCompile* call latex#latexmk#compile() *VimLatexCompileSS* call latex#latexmk#compile_singleshot(0) *VimLatexCompileSS!* call latex#latexmk#compile_singleshot(1) *VimLatexCompileToggle* call latex#latexmk#toggle() *VimLatexErrors* call latex#latexmk#errors(1) *VimLatexErrors!* call latex#latexmk#errors(0) *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(0) *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#view() *VimLatexRSearch* call latex#view#rsearch() ============================================================================== 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_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_build_dir| |g:latex_latexmk_callback| |g:latex_latexmk_enabled| |g:latex_latexmk_continuous| |g:latex_latexmk_background| |g:latex_latexmk_options| |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_hide_preamble| |g:latex_toc_hide_line_numbers| |g:latex_toc_numbers| |g:latex_toc_numbers_width| |g:latex_toc_resize| |g:latex_toc_secnumdepth| |g:latex_toc_split_pos| |g:latex_toc_width| |g:latex_view_enabled| |g:latex_view_general_viewer| |g:latex_view_general_options| |g:latex_view_method| |g:latex_view_mupdf_options| |g:latex_view_okular_options| |g:latex_view_sumatrapdf_options| ------------------------------------------------------------------------------ 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_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_build_dir* Set this variable in case a dedicated build dir is used with `latexmk`/`latex` compilations. > let g:latex_latexmk_build_dir = '.' < *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_background* If continuous mode is disabled, then this option may be used to set whether single compilations should be run in the foreground or the background. > let g:latex_latexmk_background = 0 < *g:latex_latexmk_continuous* If enabled, `latexmk` will run in continuous mode. This means that the document is compiled every time a document file has been changed. Set to 0 to disable. Note that the callback functions only work if continuous mode is enabled. > let g:latex_latexmk_continuous = 1 < *g:latex_latexmk_options* Set desired options for `latexmk` compilation. Note that options may also be specified indirectly through a `.latexmkrc` file. > let g:latex_latexmk_options = '-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, the list is empty, thus no warnings are 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: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_hide_preamble* If enabled, the start of the preamble is not shown in the TOC. > let g:latex_toc_hide_preamble = 0 < *g:latex_toc_hide_line_numbers* If enabled, line numbers will be hidden in the TOC window. That is, |nonumber| and |norelativenumber| will be set locally for the TOC window. > let g:latex_toc_hide_line_numbers = 1 < *g:latex_toc_numbers* Toggle display of numbers in TOC. The numbers may also be toggled inside the TOC window with the `s` keybinding. > let g:latex_toc_numbers = 1 < *g:latex_toc_numbers_width* Set display width of numbers in TOC. If 0, the width is set based on the section depth. > let g:latex_toc_numbers_width = 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_pos* Define where the TOC window is opened. > let g:latex_toc_split_pos = 'vert leftabove' < *g:latex_toc_width* Set width of TOC window. > let g:latex_toc_width = 30 < *g:latex_view_enabled* Enable interface for view functionality. > let g:latex_view_enabled = 1 < *g:latex_view_general_viewer* Set general viewer. > let g:latex_view_general_viewer = 'xdg-open' < *g:latex_view_method* Set viewer method. If not set or set to `general`, it uses the general viewer, see |g:latex_view_general_viewer|. > let g:latex_view_method = '' The currently available choices are: > general mupdf okular sumatrapdf < *g:latex_view_general_options* *g:latex_view_mupdf_options* *g:latex_view_okular_options* *g:latex_view_sumatrapdf_options* Set custom options for the given viewer. > let g:latex_view_general_options = '' let g:latex_view_mupdf_options = '' let g:latex_view_okular_options = '' let g:latex_view_sumatrapdf_options = '' < *g:latex_view_mupdf_send_keys* String of keys sent to MuPDF after the PDF file has been opened. The keys are sent by the function |latex#view#mupdf_poststart|. > let g:latex_view_mupdf_send_keys = '' < ============================================================================== 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: offers a list of all matching labels, with their associated value and page number. The label completion matches: 1. labels: > \ref{sec: < 2. numbers: > \eqref{2 < 3. labels and numbers together (separated by whitespace): > \eqref{eq 2 ------------------------------------------------------------------------------ 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 \cite{algo \cite{Don.*Knuth 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 compilation. The interface may be disabled with |g:latex_latexmk_enabled|. The default mappings are: > nnoremap ll :call latex#latexmk#toggle() nnoremap lk :call latex#latexmk#stop() nnoremap lK :call latex#latexmk#stop_all() nnoremap le :call latex#latexmk#errors(1) nnoremap lo :call latex#latexmk#output() nnoremap lg :call latex#latexmk#status(0) nnoremap lG :call latex#latexmk#status(1) nnoremap lc :call latex#latexmk#clean(0) nnoremap lC :call latex#latexmk#clean(1) Compilation is started with |latex#latexmk#compile| or may be toggled by |latex#latexmk#toggle|. The default behaviour uses preview continuous mode of `latexmk`, which may be disabled with |g:latex_latexmk_continuous|. If it is disabled, then the option |g:latex_latexmk_background| may be used to decide if single shot compilation should run in the foreground or the background. Single shot compilation may always be issued with the function |latex#latexmk#compile_singleshot|. This function ignores the |g:latex_latexmk_background|` setting, though, and will by default hide the output from the `latexmk` command. The function is available through the command |VimLatexCompileSS|, and if desired one may create a custom mapping such as > nnoremap ls :VimLatexCompileSS A banged version of the command also exists, which will provide a more verbose output. 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|. Note however that this only works for continuous compilation mode. 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_continuous| |g:latex_latexmk_background| |g:latex_latexmk_options| Functions: |latex#latexmk#clean| |latex#latexmk#compile| |latex#latexmk#compile_singleshot| |latex#latexmk#errors| |latex#latexmk#output| |latex#latexmk#status| |latex#latexmk#stop| |latex#latexmk#stop_all| |latex#latexmk#toggle| ------------------------------------------------------------------------------ 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. ============================================================================== VIEW *vim-latex-view* |vim-latex| provides functions for viewing the compiled documents. A command and a mapping is defined for the multipurpose `view` function, which calls the chosen view method defined by |g:latex_view_method|. Associated settings: |g:latex_view_enabled| |g:latex_view_general_viewer| |g:latex_view_general_options| |g:latex_view_method| |g:latex_view_mupdf_options| |g:latex_view_okular_options| |g:latex_view_sumatrapdf_options| Functions: |latex#view#general| |latex#view#mupdf| |latex#view#mupdf_rsearch| |latex#view#okular| |latex#view#sumatrapdf| ------------------------------------------------------------------------------ SYNCTEX SUPPORT *vim-latex-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~ |vim-latex| currently supports forward search for a limited set of viewers. The functionality is enabled by choosing the desired viewer with the |g:latex_view_method| option. The currently supported viewers are: * MuPDF * SumatraPDF * Okular More viewers and functionality will be implemented in the future. Backward search~ Backward or inverse 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" Backward search is unfortunately not supported by all pdf viewers. The following is a list of viewers that to my knowledge should support backward search: * Okular * SumatraPDF * Evince (since version 2.91.3) 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. MuPDF does not support inverse search. However, by the use of some semi ugly hacks, we have implemented a command inside vim that simulates the functionality. The command is |VimLatexRSearch|, and is by default mapped to `lr` if MuPDF is chosen as the viewer. The command will go to the line in the tex project that corresponds to the FIRST line on the page that is open in MuPDF. For SumatraPDF one may set the inverse search setting from vim directly by adding some command line options as shown below. The advantage of doing this is that one may specify the vim server name explicitly, which means that the backward search will also work as expected if one has several vim instances running. To enable this, use the general viewer and: > let g:latex_view_general_viewer='SumatraPDF ' \ . '-reuse-instance -inverse-search ' \ . '"gvim --servername '.v:servername.' --remote-send \"^^' \ . ':drop \%f^:\%l^:normal\! zzzv^' \ . ':execute ''drop ''.fnameescape(''\%f'')^' \ . ':\%l^:normal\! zzzv^' \ . ':call remote_foreground('''.v:servername.''')^\""' ============================================================================== 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| provides mappings that are inspired by `surround.vim` (https://github.com/tpope/vim-surround). These mappings are: `cse` - change surrounding environment `dse` - delete surrounding environment `csc` - change surrounding command `dsc` - delete surrounding command Note: This mappings is only available if `surround.vim` is also available. `tsd` - toggle delimiters (add/remove `\left` and `\right`) `tse` - toggle starred environment An environment that has been opened but not closed may be closed by the mapping `]]`. In addition, some functionality is provided to wrap the current selection. This is not mapped to anything by default. Functions: |latex#change#command| |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 '' 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_hide_preamble| |g:latex_toc_hide_line_numbers| |g:latex_toc_numbers| |g:latex_toc_numbers_width| |g:latex_toc_resize| |g:latex_toc_secnumdepth| |g:latex_toc_split_pos| |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#command| |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#compile_singleshot| |latex#latexmk#errors| |latex#latexmk#options| |latex#latexmk#status| |latex#latexmk#stop| |latex#latexmk#stop_all| |latex#latexmk#toggle| |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#general| |latex#view#mupdf| |latex#view#mupdf_poststart| |latex#view#mupdf_rsearch| |latex#view#okular| |latex#view#sumatrapdf| ------------------------------------------------------------------------------ Detailed descriptions:~ *latex#change#command* Change the current command name to one typed at a prompt. *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#compile_singleshot* Starts a single shot compile with `latexmk ...` 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#latexmk#toggle* Toggle compilation. Calls |latex#latexmk#compile| if `latexmk` is not running for the current file. Else it calls |latex#latexmk#stop|. *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#general* Open the output file with the viewer that is specified with the option |g:latex_view_general_viewer|. *latex#view#mupdf* *latex#view#okular* *latex#view#sumatrapdf* First open the output file if it is not open with MuPDF/Okular/SumatraPDF. Then perform a forward search. *latex#view#mupdf_poststart* Function that is called after the MuPDF window has been opened. The function is used to run `xdotool` commands, for instance to return focus to vim and to possibly send some keys to MuPDF as specified in |g:latex_view_mupdf_send_keys|. *latex#view#mupdf_rsearch* Perform a reverse search by use of `xdotool` and `synctex`. ============================================================================== FAQ *vim-latex-faq* 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 `vim-latex`. Suggested solution is to remove `{,}` from |isfname| by: > set isfname-={,} ============================================================================== CREDITS *vim-latex-credits* |vim-latex| is developed by Karl Yngve Lervåg , 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-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:latex_view_method| and |g:latex_view_general_viewer|. Deprecated option: *g:latex_viewer* 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: