7 Introduction

Nikolas Vanderhoof edited this page 2016-05-23 12:07:09 -04:00

Table of Contents

• Feature Overview
• Requirements
• Latexmk
• Clientserver
• Support for Multi-File Projects
• Recursive search
• File .latexmain specifier
• TeX root specifier
• Buffer variable
• Comment on internal tex plugin

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

• Document compilation with latexmk
• Support for several PDF viewers with forward search
  • MuPDF
  • Zathura
  • Okular
  • qpdfview
  • SumatraPDF
  • Other viewers are supported through a general interface
• Completion of citations, labels, glossary entries and filenames
• Document navigation through
  • table of content
  • table of labels
• Word count (through texcount)
• Motions
  • Move between sections with [[, [], ][, ]]
  • Move between matching delimiters with %
• Text objects
  • ic ac Commands
  • id ad Delimiters
  • ie ae LaTeX environments
  • i$ a$ Inline math structures
• Other mappings
  • Delete the surrounding command or environment with dsc/dse/ds$
  • Change the surrounding command or environment with csc/cse/cs$
  • Toggle starred environment with tse
  • Toggle between e.g. () and \left(\right) with tsd
  • Close the current environment/delimiter in insert mode with ]]
  • Insert new command with <F7>
  • Convenient insert mode mappings for faster typing of e.g. maths
• Folding
• Indentation
• Improved syntax highlighting
  • Highlight matching delimiters
  • Support for biblatex/natbib package
  • Support for cleveref package
  • Support for listings package
  • Support for minted package
  • Support for dot2tex with nested syntax highlighting
• Support for multi-file project packages
  • import
  • subfiles

Requirements

Latexmk

Vimtex uses latexmk to compile LaTeX documents.

According to the official latexmk website, 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)."

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 the vim wiki.

Support for Multi-File Projects

Vimtex supports most multi-file documents. It uses a recursive search algorithm that should find the main LaTeX file in most cases. For special cases, there are several alternative methods for specifying the main file, see below. The priority of the methods are as follows:

1. Buffer variable
2. TeX root specifier
3. Subfiles package
4. File .latexmain specifier
5. Recursive search

Vimtex also supports the import and subfiles packages that can be used to make it easier to work with multi-file projects. If one uses the subfiles package, the VimtexToggleMain command is particularly useful.

Recursive search

The recursive search detects the main LaTeX file by searching for a file in the current and parent directories that includes the present file and that has the \documentclass line.

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

path1/main.tex
path2/chapter.tex

That is, the main file detection will not work for the file chapter.tex, because the main file does not live in the same folder or a parent folder.

File .latexmain specifier

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

path/file.tex
path/file.tex.latexmain
path/sections/file1.tex
path/sections/file2.tex

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

TeX root specifier

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 = /path/to/my-main.tex.

Note that this method should work for the case where the recursive search does not work.

Buffer variable

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

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

When Vimtex is active, it will be used as the main filetype plugin. 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 Vim's default TeX syntax. Vimtex also provides its own indentation plugin.

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'.