Abstract
Latex-Suite attempts to provide a comprehensive set of tools to view, edit and compile LaTeX documents in Vim. Together, they provide tools starting from macros to speed up editing LaTeX documents to functions for forward searching .dvi documents. Latex-Suite has been possible because of the contributions of many people. Please see latex-suite-credits for a list of people who have helped.
Latex-Suite is released under the Vim charityware license. For license and conditions of use look at |copyright|. Replace all occurrences of ``Vim'' with ``Latex-Suite''. The current copyright holders of Latex-Suite are Srinath Avadhanula and Mikolaj Machowski.
Homepage: http://vim-latex.sourceforge.net
Table of Contents
If you are reading this, it most probably means that you have already installed Latex-Suite and the help files. If this is not the case, follow the detailed instructions on Latex-Suite's download page.
Make sure that you create a few necessary settings in your
~/.vimrc.
" REQUIRED. This makes vim invoke Latex-Suite when you open a tex file. filetype plugin on " IMPORTANT: win32 users will need to have 'shellslash' set so that latex " can be called correctly. set shellslash " OPTIONAL: This enables automatic indentation as you type. filetype indent on " OPTIONAL: Starting with Vim 7, the filetype of empty .tex files defaults to " 'plaintex' instead of 'tex', which results in vim-latex not being loaded. " The following changes the default filetype back to 'tex': let g:tex_flavor='latex'
In addition, the following settings could go in your ~/.vim/ftplugin/tex.vim file:
" this is mostly a matter of taste. but LaTeX looks good with just a bit " of indentation. set sw=2 " TIP: if you write your \label's as \label{fig:something}, then if you " type in \ref{fig: and press <C-n> you will automatically cycle through " all the figure labels. Very useful! set iskeyword+=:
In the unlikely case that Latex-Suite is installed, but you do not want to use it (e.g., if it is installed system-wide and you use some other package to deal with tex files), you can suppress the loading of Latex-Suite by setting
let b:suppress_latex_suite = 1
in your ~/.vim/ftplugin/tex.vim.
This functionality is available via the TeX-Suite >
Templates
menu.
This module provides a way to insert custom templates at the beginning of the
current file.
When Latex-Suite first starts up, it scans the template directory and creates menu items based on the files found there. When you select a template from this menu, the file will be read in above the first line of the current file.
A template file can utilize placeholders for initializing the cursor position when the template is read in and subsequent movement. In addition, template files can contain dynamic elements such as the time of creation of a file etc, by using vim expressions.
You can place your own templates in the template directory in order for them to be available via the menu.
Templates are also accessible for non-gui users with the command
|:TTemplate
|. The argument should be name of
the corresponding template file. If the command is called
without arguments (preferred usage), then a list of available
templates is displayed and the user is asked to choose one of
them.
Latex-Suite ships with a very comprehensive set of insert mode and |visual-mode| mappings and menu items to typeset most of the LaTeX elements.
These mappings are are not standard mappings in the sense that
only the last character is mapped. See plugin/imaps.vim for
further documentation. For example, in the case of the mapping
EFI
provided by Latex-Suite you can press the characters
'E
', 'F
' and 'I
'
as slowly as you wish (unlike the normal imap
command
where timeout
issues are involved). The characters are
visible as you type them (unlike normal imap
s) and you
can use the movement or backspace key to correct yourself unlike normal
mappings.
Almost all macros provided in Latex-Suite implement Stephen Riem's bracketing
system and Gergely Kontra's JumpFunc()
for handling
place-holders. This consists of using "place-holders" to mark off
locations where the next relevant editing has to be done. As an example,
when you type EFI
in |insert-mode|, you will get the
following:
\begin{figure}[<+htpb+>] \centering \includegraphics{<+file+>} \caption{<+caption text+>} \label{fig:<+label+>} \end{figure}<++>
The text <+htpb+>
will be selected and
you will be left in |select-mode| so that you can continue typing
straight away. After having typed in the placement specifier, you can press
<Ctrl-J>
(while still in insert-mode). This will
take you directly to the next "place-holder". i.e, <+file+>
will be visually selected with Vim in select mode
again for typing in the file name. This saves on a lot of key presses.
If you wish to change these macros from their default values, for
example, if you wish to change `w
to expand to
\omega
instead of its default expansion to
\wedge
, you should use the IMAP
function as described in the Using
IMAP() section.
An important thing to note is that if you wish to over-ride macros
created by Latex-Suite rather than merely create new macros, you should place
the IMAP()
calls in a script which gets sourced
after the files in Latex-Suite. A good place typically is as a file-type
plugin file in the
~/.vim/after/ftplugin/
directory. (Use
~/vimfiles
if you are using
WINDOWS
). For example to over-ride
`w
to \omega
instead of
\wedge
, place the following line in (say)
~/.vim/after/ftplugin/tex_macros.vim
:
call IMAP('`w', '\omega', 'tex')
To delete a mapping, you can use
call IUNMAP('FEM', 'tex')
in ~/.vim/after/ftplugin/tex_macros.vim
.
It is important to use a file-name which will get sourced on a
FileType
event. Therefore you must use a file-name
which conforms to the standards as described in
|ftplugin-name|
.
If you wish to temporarily suspend the imaps functionality, then you
can set the Imap_FreezeImap
to 1. If you set
g:Imap_FreezeImap
to 1, then it will be a
system-wide setting. Setting b:Imap_FreezeImap
will
affect only the current buffer.
The following sections describe the various editing macros provided by Latex-Suite.
\begin{...} ... \end{...}
pairs.
There are several possibilities for the customization of the inserted environments, see the section about customizations.
Latex-Suite provides the following ways to insert environments
If you press <F5>
in the insert or normal
mode while on an empty line, Latex-Suite prompts you with a list of
environments you might want to insert. You can either choose one
from the list or type in a new environment name. If you press
<F5>
on a line which already has a word,
then that word is used instead of prompting.
See Tex_Env_name for a description of how Latex-Suite uses the word to form the expansion and how to modify Latex-Suite's behavior.
The list of environments which Latex-Suite prompts you with (when
<F5>
is pressed on an empty line) is formed
from the Tex_PromptedEnvironments
setting.
In addition to this setting, Latex-Suite also lists environments found in custom packages as described in the section Package actions.
The shifted function keys, <S-F1>
to
<S-F4>
can be mapped to insert very commonly
used environments. The environments mapped to each key can be
customized via the g:Tex_HotKeyMappings setting.
Environments can also be inserted by pressing a 3 capital letter
sequence starting with an E
. The sequence of 3
letters generally tries to follow the following rules:
E
flushleft (_f_lush + _l_eft) ---> EFL flushright (_f_lush + _r_ight) ---> EFR minipage (_m_ini + _p_age) ---> EMPIf on the other hand, the environment name cannot be broken up into 2 distinct words, then the next 2 letters are the first 2 letters of the name of the environment. Example:
equation (_eq_uation) ---> EEQ
Unfortunately there are some environments that cannot be split in two words and first two letters in name are identical. In this case shortcut is created from E, first and last letter. Example:
quote (_q_uot_e_) ---> EQE quotation (_q_uotatio_n_) ---> EQN
Of course, not every last one of the environments can follow this rule because of ambiguities. In case of doubt, pull down the Tex-Environments menu. The menu item should give the hint for the map.
Latex-Suite provides visual-mode mappings which enclose visually selected portions of text in environments. There are two ways provided to do this.
You can also select a portion of text visually and press
<F5>
while still in visual mode. This will
prompt you with a list of environments. (This list can be customized
via the g:Tex_PromptedEnvironments
setting). You can either choose from this list or type in a new
environment name. Once the selection is done, Latex-Suite encloses the
visually selected portion in the chosen environment.
You can also select text visually and press a sequence of three
characters beginning with ,
(the single comma
character) and the selected text will be enclosed in the chosen
environment. The three letter sequence follows directly from the
three letter sequence used to insert environments as described here. The following
example describes the rule used:
If ECE
inserts a
\begin{center}...\end{center}
environment, then to
enclose a block of selected text in
\begin{center}...\end{center}
, simply select the
text and press ,ce
. The rule simply says that the
leading E
is converted to ,
and
the next 2 letters are small case.
Some of the visual mode mappings are sensitive to whether you
choose line-wise or character-wise. For example, if you choose a
word and press ,ce
, then you get
{\centering word}
, whereas if you press
,ce
on a line-wise selection, you get:
\begin{center} line \end{center}
Pressing <S-F5>
in normal mode detects which
environment the cursor is presently located in and prompts you to
replace it with a new one. The innermost environment is detected. For
example, in the following source:
\begin{equation} \begin{array}{ccc} 2 & 3 & 4 \end{array} \end{equation}
if you are located in the middle "2 & 3 & 4" line, then pressing
<S-F5>
will prompt you to change the array
environment, not the equation environment. In addition, Latex-Suite will also
try to change lines within the environment to be consistent with the
new environment. For example, if the original environment was an
equation
environment with a
\label
command, then changing it to an
equation*
environment will delete the
\label
.
Pressing <F5>
in normal mode has the same
effect as pressing <F5>
in insert-mode,
namely you will be prompted to choose an environment to insert.
Pressing <F7>
in insert or normal mode while
the cursor is touching a word will insert a command formed from the
word touching the cursor.
For certain common commands, Latex-Suite will expand them to include
additional arguments as needed. For example, frac
becomes \frac{<++>}{<++>}<++>
. Otherwise, it will
simply change the word under the cursor as follows
word --> \word{<++>}<++>
You can define custom expansions
of commands using the Tex_Com_{name}
setting as
described in here.
If <F7>
is pressed when the cursor is on
white-space, then Latex-Suite will prompt you to choose a command and insert
that instead.The list of commands is constructed from the g:Tex_PromptedCommands
setting and also from commands which Latex-Suite finds while scanning custom
packages which Latex-Suite finds. See the Package actions section for details
on which files are scanned etc.
You can select a portion of text visually and press
<F7>
while still in visual mode. This will
prompt you with a list of commands. (This list can be customized
via the g:Tex_PromptedCommands
setting). You can either choose from this list or type in a new
command name. Once the selection is done, Latex-Suite encloses the
visually selected portion in the chosen command.
These mappings insert font descriptions such as:
\textsf{<++>}<++>
with the cursor left in place of the first placeholder (the <++> characters).
Mnemonic:
Example: Typing FEM
in insert-mode expands to
\emph{<++>}<++>
.
Just like environment mappings, you can visually select an area and press
`sf
to have it enclosed in:
\textsf{word}
or
{\sffamily line }
depending on character-wise or line-wise selection.
These maps insert LaTeX sections such as:
\section{<++>}<++>
etc. Just as in the case of environments and fonts, can be enclosed with a visual selection. The enclosing is not sensitive to character or line-wise selection.
Mnemonic: (make your own!)
SPA for part SCH for chapter SSE for section SSS for subsection SS2 for subsubsection SPG for paragraph SSP for subparagraph
Example: SSE in insert mode inserts
\section{<++>}<++>
If you select a word or line and press ,se
, then you
get
\section{section name}
The menu item in Tex-Environments.Sections have a sub-menu called 'Advanced'. Choosing an item from this sub-menu asks a couple of questions (whether you want to include the section in the table of contents, whether there is a shorter name for the table of contents) and then creates a more intelligent template.
Lower case
`a
through `z
expand to
\alpha
through \zeta
.
Upper case:
`D = \Delta `F = \Phi `G = \Gamma `Q = \Theta `L = \Lambda `X = \Xi `Y = \Psi `S = \Sigma `U = \Upsilon `W = \Omega
LaTeX does not support upper case for all greek alphabets.
Just like other Latex-Suite mappings, these mappings are not created using
the standard imap
command. Thus you can type slowly,
correct using <BS>
etc.
These are simple 2 key expansions for some very commonly used LaTeX elements:
`^ Expands To \Hat{<++>}<++> `_ expands to \bar{<++>}<++> `6 expands to \partial `8 expands to \infty `/ expands to \frac{<++>}{<++>}<++> `% expands to \frac{<++>}{<++>}<++> `@ expands to \circ `0 expands to ^\circ `= expands to \equiv `\ expands to \setminus `. expands to \cdot `* expands to \times `& expands to \wedge `- expands to \bigcap `+ expands to \bigcup `( expands to \subset `) expands to \supset `< expands to \le `> expands to \ge `, expands to \nonumber `~ expands to \tilde{<++>}<++> `; expands to \dot{<++>}<++> `: expands to \ddot{<++>}<++> `2 expands to \sqrt{<++>}<++> `| expands to \Big| `I expands to \int_{<++>}^{<++>}<++>
(again, notice the convenient place-holders)
In addition the visual mode macros are provided:
`( encloses selection in \left( and \right) `[ encloses selection in \left[ and \right] `{ encloses selection in \left\{ and \right\} `$ encloses selection in $$ or \[ \] depending on characterwise or linewise selection
These mappings speed up typing European languages which contain diacritic characters such as a-umlaut etc.
+<l> expands to \v{<l>} =<l> expands to \'{<l>}
where <l>
is an alphabet.
+} expands to \"{a} +: expands to \^{o}
Latex-Suite also ships with smart backspacing functionality which provides another convenience while editing languages with diacritics.
Diacritics are disabled by default in Latex-Suite because they can sometimes be a little too intrusive. Moreover, most European users can nowadays use font encodings which display diacritic characters directly instead of having to rely on Latex-Suite's method of displaying diacritics.
Set the g:Tex_Diacritics variable to enable diacritics.
Latex-Suite provides an easy way of entering bibliographic entries. Four
insert-mode mappings: BBB
, BBL
,
BBH
and BBX
are provided, all of
which essentially act in the same manner. When you type any of these in
insert-mode, you will get a prompt asking you to choose a entry type
for the bibliographic entry.
When you choose an entry type, a bibliographic entry template will be
inserted. For example, if you choose the option
'book'
via the map BBB
, then
the following template will be inserted:
@BOOK{<+key+>, author = {<++>}, editor = {<++>}, title = {<++>}, publisher = {<++>}, year = {<++>}, otherinfo = {<++>} }<++>
<+key+>
will be highlighted in select-mode and
you can type in the bib-key. After that you can use
<Ctrl-J>
to navigate to successive locations
in the template and enter new values.
BBB
inserts a template with only the fields
mandatorily required for a given entry type. BBL
inserts a template with commonly used extra options.
BBH
inserts a template with more options which are
not as commonly used. BBX
inserts a template with
all the fields which the entry type supports.
B
for Bibliographic entry, L
for Large entry, H
for Huge entry, and
X
stands for all eXtras.
If you wish the BBB
command to insert a few
additional fields in addition to the fields it creates, then you will
need to define global variables of the form
g:Bib_{type}_options
in you $VIM/ftplugin/bib.vim
file, where
{type}
is a string like
'article'
, 'book'
etc. This
variable should contain one of the letters defined in the following
table
Character | Field Type |
---|---|
w | address |
a | author |
b | booktitle |
c | chapter |
d | edition |
e | editor |
h | howpublished |
i | institution |
k | isbn |
j | journal |
m | month |
z | note |
n | number |
o | organization |
p | pages |
q | publisher |
r | school |
s | series |
t | title |
u | type |
v | volume |
y | year |
For example, by default, choosing 'article'
via
BBB
inserts the following template by default
@ARTICLE{<+key+>, author = {<++>}, title = {<++>}, journal = {<++>}, year = {<++>}, otherinfo = {<++>} }<++>
However, if g:Bib_article_options
is defined as
'mnp'
, then 'article'
will
insert the following template
@ARTICLE{<+key+>, author = {<++>}, title = {<++>}, journal = {<++>}, year = {<++>}, month = {<++>}, number = {<++>}, pages = {<++>}, otherinfo = {<++>} }<++>
If you have some other fields you wish to associate with an article
which are not listed above, then you will have to use the
Bib_{type}_extrafields
option. This is a newline
separated string of complete field names which will be included in the
template. For example, if you define
let g:Bib_article_extrafields = "crossref\nabstract"
then the article template will include the lines
crossref = {<++>}, abstract = {<++>},
You will need to define Bib_*
settings in your
$VIMRUNTIME/ftplugin/bib.vim
file.
Latex-Suite ships with the following smart keys:
Smart Backspace.
Pressing <BS>
in insert mode checks to see
whether we are just after something like \'{a}
and
if so, deletes all of it. i.e, diacritics are treated as single
characters for backspacing.
You might want to disable this feature, if you are editing
Chinese, Japanese or Korean text.
Smart Quotes.
Pressing "
(English double quote) will insert
``
or ''
by making an
intelligent guess about whether we intended to open or close a quote.
Smart Space.
Latex-Suite maps the <space>
key in such a
way that $ characters are not broken across lines. It does this by
first setting tw=0
so that Vim will not
automatically break lines and then maps the
<space>
key to insert newlines keeping
$$
's on the same line.
Smart Dots.
Pressing ...
(3 dots) results in
\ldots
outside math mode and
\cdots
in math mode.
Latex-Suite utilizes a set of macros originally created by Carl Mueller in
auctex.vim to make inserting all the \left ... \right
stuff very easy and to also make some use of the heavily under-utilized
<Alt>
key.
By default, the mappings involving the <Alt>
key
are turned off for compatibility with inserting non-ASCII characters. It
can be enabled by setting
let g:Tex_AdvancedMath = 1
in your $VIM/ftplugin/tex.vim
.
By default, typing Alt-<key>
in Vim takes
focus to the menu bar if a menu with the hotkey
<key>
exists. If in your case, there are
conflicts due to this behavior, you will need to set
set winaltkeys=no
in your $VIM/ftplugin/tex.vim
in order to use these
maps.
If for some reason, you wish to not map the
<Alt>
keys, (some European users need to use
the <Alt>
key to enter diacritics), you can
change these maps to other keys as described in the section Customizing Alt-key maps.
This is a polymorphic insert-mode mapping which expands to one of the following depending on the character just before the cursor location.
Character before cursor | Expansion |
---|---|
( | \left( <++> \right) |
[ | \left[ <++> \right] |
| | \left| <++> \right| |
{ | \left\{ <++> \right\} |
< | \langle <++> \rangle |
q | \lefteqn{<++>}<++> |
If the character before the cursor is none of the above, then it will
simply insert a \label{<++>}<++>
.
In insert mode, this key is polymorphic as follows:
\mathcal{}
.
\cite{}
.
In visual mode, it will simply enclose the selection in
\mathcal{}
This mapping inserts an \item
command at the
current cursor location depending on which environment the cursor is
enclosed in. The style of the \item
command is
dependent on the enclosing environment. By default,
<Alt-I>
has styles defined forthe following
environments:
Environment | Style |
---|---|
itemize | \item |
enumerate | \item |
theindex | \item |
thebibliography | \item[<+biblabel+>]{<+bibkey+>} <++> |
description | \item[<+label+>] <++> |
<Alt-I>
is intelligent enough to
account for nested environments. For example,
\begin{itemize} \item first item \item second item \begin{description} \item[label1] first desc \item[label2] second % <Alt-I> will insert "\item[<+label+>] <++>" if % used here \end{description} \item third item % <Alt-I> will insert "\item " when if used here. \end{itemize} % <Alt-I> will insert nothing ("") if used here
The style used by <Alt-I>
can be customized
using the g:Tex_ItemStyle_environment
variable.
This functionality available via the TeX-Suite.Macros menu, provides a way of inserting customized macros into the current file via the menu.
When Latex-Suite starts up, it scans the
$VIM/ftplugin/latex-suite/macros/
directory and
creates a menu from the files found there. Each file is considered as
a single macro. You can place your own macros in this directory,
using placeholders if wanted.
When you choose a macro from the menu, the corresponding file is read into the current buffer after the current cursor position. In non-gui mode, you can use the |TMacro| command instead of choosing from the menu. This command takes the macro file name as an argument. When called without arguments (preferred usage), then a list of available macro files is displayed and the user is prompted to choose one of them).
There are some other tools provided in this menu, namely:
{New} | Creates a new (unnamed) buffer in the latex-suite/macros/ directory. Use the command :TexMacroNew in non-gui mode. |
{Edit} | Opens up the corresponding macro file for editing. Use |:TexMacroEdit| in non-gui mode. When you try to edit {macro} not from local directory Latex-Suite will copy it to your local directory with suffix "-local". If local copy already exists Latex-Suite prompt for overwriting it. |
{Delete} | Deletes the corresponding macro. Use the prefixed numbers for fast navigation of menus. Use |:TexMacroDelete| in non-gui mode. When you choose to delete {macro} which is not in your local directory Latex-Suite will refuse to delete it. |
{Redraw} | Rescans the macros/ directories and refreshes the macros list. |
If you find the need to create your own macros, then you can use the
IMAP()
function provided with Latex-Suite. See Why use IMAP()
for a short
explanation of why you might prefer IMAP()
over
Vim's standard :imap
command. An example best
explains the usage:
:call IMAP('NOM', '\nomenclature{<++>}<++>', 'tex')
This will create a Latex-Suite-style mapping, where if you type
NOM
in insert mode, you will get
\nomenclature{<++>}<++>
with the cursor left in
place of the first <++>
characters. See IMAP() syntax for
a detailed explanation of the IMAP()
command.
For maps which are triggered for a given filetype, the
IMAP()
command above should be put in the filetype
plugin script for that file. For example, for tex-specific mappings,
the IMAP()
calls should go in
$VIM/ftplugin/tex.vim
. For globally visible maps,
you will need to use the following in either your
~/.vimrc
or a file in your
$VIM/plugin
directory.
augroup MyIMAPs au! au VimEnter * call IMAP('Foo', 'foo', '') augroup END
IMAP
mappings can be removed by
IUNMAP
, e.g.,
call IUNMAP('FEM','tex')
Using IMAP
instead of Vim's built-in
:imap
command has a couple of advantages:
:imap
. if you type
the left hand side too slowly, then the mapping will not be
activated.
Formally, the syntax which is used for the IMAP
function is:
call IMAP (lhs, rhs, ft [, phs, phe])
Argument | Explanation |
---|---|
lhs |
This is the "left-hand-side" of the mapping. When you use
If you have two mappings which end in a common
call IMAP('BarFoo', 'something', 'tex') call IMAP('Foo', 'something else', 'tex')
Then typing
Also, the nature of call IMAP('foo', 'something', 'tex') call IMAP('foobar', 'something else', 'tex')
Then you will never be able to trigger |
rhs |
The "right-hand-side" of the mapping. This is the expansion you
will get when you type
This string can also contain special characters such as
:call IMAP('EFE', "\\begin{figure}\<CR><++>\\end{figure}<++>", 'tex')
With this, typing You can also set up a Latex-Suite style mapping which calls a custom function as follows: :call IMAP('FOO', "\<C-r>=MyFoonction()\<CR>", 'tex')
where call IMAP('FOO', "\<C-r>=AskVimFunc()\<CR>", 'vim') " Askvimfunc: Asks For Function Name And Sets Up Template " Description: function! AskVimFunc() let name = input('Name of the function : ') if name == '' let name = "<+Function Name+>" end let islocal = input('Is this function scriptlocal ? [y]/n : ', 'y') if islocal == 'y' let sidstr = '<SID>' else let sidstr = '' endif return IMAP_PutTextWithMovement( \ "\" ".name.": <+short description+> \<cr>" . \ "Description: <+long description+>\<cr>" . \ "\<C-u>function! ".name."(<+arguments+>)<++>\<cr>" . \ "<+function body+>\<cr>" . \ "endfunction \" " \ ) endfunction
|
ft |
The file type for which this mapping is active. When this string is left empty, the mapping applies for all file-types. A filetype specific mapping will always take precedence. |
phs, phe |
If you prefer to write the
Note that the |
Latex-Suite has a lot of functionality written to ease working with packages.
Packages here refers to files which you include into the LaTeX
document using the \usepackage
command.
When you first invoke Latex-Suite, it scans the
$VIM/ftplugin/latex-suite/packages
directory for
package script files and creates a menu from all the files found there.
This menu is created under TeX-Suite > Packages >
Supported
. This menu contains a list of packages "supported"
by Latex-Suite. When you choose one of the packages from this menu (for example
the amsmath
package), then a line of
the form
\usepackage[<++>]{amsmath}<++>
will be inserted into the current file.
The \usepackage
line can also be inserted in an easy
manner in the current file by pressing <F5>
while in the preamble of the current document. This will set up a prompt
from the supported packages and ask you to choose from one of them. If
you do not find the package you want to insert in the list, you can type
in a package-name and it will use that. Pressing
<F5>
in the preamble on a line containing a
single word will construct a \usepackage
line from
that word.
You can also use the TPackage
to insert the
\usepackage
line.
Once you have inserted a \usepackage
line, for
supported packages, you can use the Options and Commands menus
described in the next section.
Latex-Suite takes the following actions for packages detected when a file is
loaded, or a new \usepackage
line is inserted using
one of the methods described in the previous section.
If you are using the GUI and you have g:Tex_Menus set to 1, Latex-Suite will create the following sub-menus
TeX-Suite > Packages > <package> Options |
TeX-Suite > Packages > <package> Commands |
where <package>
is the package you just
inserted (or was detected). You can use these menus to insert commands,
environments and options which Latex-Suite recognizes as belonging to this
package.
While inserting an option, you need to position yourself in the
appropriate place in the document, most commonly inside the square
braces in the \usepackage[]{packname}
command. Latex-Suite
will not navigate to that location.
In addition to creating these sub-menus, Latex-Suite will also scan the
$VIM/ftplugin/latex-suite/dictionaries
directory and
if a dictionary file corresponding to the package file is found, then
it will add the file to the 'dict'
setting in Vim
so you can use the <C-X><C-K>
command to
complete words from that file.
For example, the SIUnits
package has a custom
dictionary.
If a package detected at startup is found by Latex-Suite in the current
directory or in a location specified by the g:Tex_TEXINPUTS variable, Latex-Suite will
scan the package for \newenvironment
and
newcommand
lines and also append any commands and
environments found to the list of commands and environments which you
are prompted with when you press <F5>
or <F7>
in insert
mode.
In addition, the TeX-Suite > Packages
menu also
contains the following submenus
Update. This command is to be invoked with the cursor placed on the package name. If the corresponding package is found, then a sub-menu with the supported commands and options is created.
Update All.
This function reads the preamble of the document for
\usepackage
lines and if Latex-Suite supports the detected
packages, then sub-menus containing the package options and commands
are created.
Whenever Latex-Suite begins editing a new LaTeX file, it scans it for
\usepackage{name}
lines, and if a supported package
is found, then it will create sub-menus and add to the
'dict'
setting as described above.
If a master-file has been specified, then it will scan that file instead of the current file. See the section Custom Packages to see which files Latex-Suite will scan in more detail.
For all the packages detected in this manner, Latex-Suite will take certain actions as described in the section package support..
Often times, the preamble can become too long, and some people prefer
to put most of their personalization in a custom package and include
that using a \usepackage
line. Latex-Suite tries to search
such customs package for other \usepackage
lines, so
that supported packages included in this indirect manner can also be
used to create sub-menus, extend the 'dict'
setting
etc. The most obvious place to place such custom packages is in the
same directory as the edited file. In addition, LaTeX also supports
placing custom packages in places pointed to by the
$TEXINPUTS
environment variable.
If you use the $TEXINPUTS
variable in LaTeX, and
you wish Latex-Suite to search these custom packages for
\usepackage
lines, then you need to initialize the
g:Tex_TEXINPUTS
variable.
The g:Tex_TEXINPUTS
variable needs to be set in the
same format which Vim uses for the 'path'
setting.
This format is explained in detail if you do
:help file-searching
from within Vim.
Therefore the value of g:Tex_TEXINPUTS
will most
probably be different from $TEXINPUTS
which your
native LaTeX distribution uses.
Example:
let g:Tex_TEXINPUTS = '~/texmf/mypackages/**,./**'
The **
indicates that all directories below the
directory ~/texmf/mypackages
and
./
are to be scanned for custom packages.
The present directory '.'
is always searched. You
need not include that in g:Tex_TEXINPUTS
.
Supporting a package is easy and consists of writing a vim script with
the same name as the package and placing it in the
$VIM/ftplugin/latex-suite/packages
directory. A
package script should define two variables as described in the next two
sections. In addition to these two variables, you can also define any
functions, environment definitions etc. in this file.
This setting is a string containing a comma separated list of options supported by this package.
Example:
g:Tex_package_option_mypack = 'opt1,opt2=,sbr:group1,opt3,opt4'
The =
suffix means that the option takes a value.
Use sbr:group name
to separate options into
sub-menus. All successive options will be clubbed into the
group1
sub-menu till the next
sbr:
option is encountered.
g:TeX_package_<package> = "pre:Command,pre:Command1" More detailed example is in latex-suite/packages/exmpl file (slightly outdated). Here is short summary of prefixes which can be used in package files: (x - place with cursor, <++> - |placeholder|) {env:command} Environment: creates simple environment template \begin{command} x \end{command}<++> {eno:command} Environment with option: \begin[x]{command} <++> \end{command}<++> {ens:command[<<option>>]...} Environment special: \begin[<<option>>]...{command} <++> \end{command}<++> {bra:command} Brackets: \command{x}<++> {brd:command} Brackets double: \command{x}{<++>}<++> {brs:command[<<option>>]...} Brackets special (as environment special: \command[<+x+>]{<++>}{<++>}<++> {nor:command} Normal: \command<Space {noo:command} Normal with option: \command[x]<++> {nob:command} Normal with option and brackets: \command[x]{<++>}<++> {pla:command} Plain: command<Space {spe:command} Special: command <-literal insertion of command {sep:command} creates separator. Good for aesthetics and usability :) {sbr:command} Breaks menu into submenus. <command> will be title of submenu. Can be used also in package variable. Command can be also given without prefix:. The result is \command
Latex-Suite provides an easy way to insert references to labels and
bibliographic entries and also provide filename arguments to commands
such as \includegraphics
. Although the completion
capabilities are very diverse, Latex-Suite only uses a single key
(<F9>
by default) to do all of it. Pressing the
<F9>
key does different things based on where
you are located. Latex-Suite tries to guess what you might be trying to
complete at the location where you pressed
<F9>
. For example, pressing
<F9>
when you are within a
\ref
command will try to list the
\label
's in the present directory. Pressing it when
you are in a \cite
command will list bibliography
keys. Latex-Suite also recognizes commands which need a file name argument and
will put up an explorer window for you to choose a filename.
Most of Latex-Suite's completion capabilities depend on the python interface of vim. Both python2 and python3 are supported. Hence,
python print "Hello."
or
python3 print("Hello.")
should work.
Pressing <F9>
when you are within a partially
completed \ref
command will split open a window
(named __OUTLINE__
) which contains a nicely
formatted list of all the \label
s found in the
present project. The \label
s are heirarchically
arranged according to which \section
,
\subsection
etc of the overall document structure
they are present in. For example, when you first press
<F9>
after typing \ref{
,
you should see something like:
+-- 54 lines: 2. Kinematics-------------------------------- +-- 98 lines: 3. Aerodynamics of the MFI thorax------------ +-- 40 lines: 4. Jump Resonance in Fourbar Mechanisms------ +-- 28 lines: 5. Design and Fabrication Issues-------------
Each chapter is |fold|ed away so that you can quickly jump to the correct section/subsection in which the relevant equation is defined. This makes inserting references significantly faster for large projects with hundreds of equations. You can then open some of the folds to see for example:
+-- 54 lines: 2. Kinematics-------------------------------- 3. Aerodynamics of the MFI thorax 3.1. Aerodynamic modeling of the MFI wing forces 3.1.1. Geometric Specification eqn:wingnormal-pos \nhat = T_z(\theta_2) T_y(\theta_y)T_x(\theta_x)\nhat_0, eqn:T-1 T_1(\theta_2) &= T_z(\theta_2)
The <Tab>
key is mapped in this window to
toggle folds so that you can quickly open/close folds in order to
navigate the heirarchy faster. Once you are positioned on a
label, press <Enter>
. This closes the
__OUTLINE__
window, returns to the window in which
you pressed <F9>
and inserts the reference
at the current cursor position.
You can press <F9>
after typing part of the
\label
. In this case, Latex-Suite only presents
\label
s which begin with the already filled
characters. You can use this to choose between equations, figures,
tables etc. if you consistently label equations to begin with
eqn:
, figures to begin with fig:
etc. For example, with this scheme, pressing
<F9>
after typing
\ref{eqn:
will only list equations.
Latex-Suite works the same way if you press <F9>
after any command which contains the letters ref
.
Thus you can complete \eqref
in exactly the same
manner.
This method of preseting the \label
s depends on Vim
being compiled with python[3] support. To check if you have this, see the
output of the :ver
command. If you see something
like +python
or +python3
, you are all set. Failing this, you
will need to have python
somewhere in your
$PATH
.
Latex-Suite provides an easy way to insert references to bibliographic
entries. Pressing <F9>
when the cursor is
placed inside a partially completed \cite
command
will split open a new window (named __OUTLINE__
)
which contains a formatted and syntax highlighted list of all bibtex
entries found. For example, pressing <F9>
after typing \ref{
should present you with a window
which looks something like this:
Article [dickinson:science:99] "Wing rotation and aerodynamic basis of insect flight" M. H. Dickinson and F-O. Lehman and S. P. Sane In Science, 1999 Article [ellington:84:part1] "The Aerodynamics of Hovering Insect Flight. I. The Quasi-Steady Analysis" Ellington, C P In Philosophical Transactions of the Royal Society of London. Series B, Biological Sciences, 1984 Article [ellington:84:part2] "The Aerodynamics of Hovering Insect Flight. II. Morphological Parameters" Ellington, C P In Philosophical Transactions of the Royal Society of London. Series B, Biological Sciences, 1984
You can easily jump from one entry to another using the
'n'
and 'p'
keys (to go to the
next / previous entry respectively).
You can also filter out a subset of the bibtex entries by pressing
'f'
while in this window. Doing this presents the
following prompt:
Field acronyms: (`:let g:Tex_EchoBibFields = 0` to avoid this message) [t] title [a] author [b] booktitle [j] journal [y] year [p] bibtype (you can also enter the complete field name) Enter filter criterion [field<space>value]:
At the prompt, type
a ellington
Notice that the letter a is an acronym for author
according to the prompt above. Therefore this filter only shows those
bibtex entries whose author field contains the text
ellington
. You can keep narrowing your selection by
repeatedly filtering the results. If you would like to remove all the
filters and see all entries again, press 'a', which removes
all the filters.
You can also sort the bibtex entries based on a field. To do this, press 's'. This will present you with a prompt like in the case of the filter and you are asked to choose a field. In this case, you would type in a single character. This sorts the entries according to that field.
<F9>
will also work in a similar way after any
command which contains the word cite
in it. For
example, pressing <F9>
will also work with
\citenum
etc.
The following logic is applied to find out which bibliographic entries are included in the completion.
Firstly, if the present file has a master-file defined for it, then Latex-Suite will perform the following steps on that file instead of on the current file.
First, the file is scanned for a \bibliography
command or a \addbibresource
command.
To explain better, assume that a command
\bibliography{file1,file2}
is found
in the present file. For each bibliography file, say
file1
, Latex-Suite first tries to see if a
.bib
file, file1.bib
can be
found. If so, it will scan it for bib-keys of the form
@BOOK{
etc., and add these searches to the
completion list. If a .bib
file cannot be found,
then it will try to see if file1.bbl
can be found.
If so, Latex-Suite will search it for bib-keys of the form
\bibitem
and add these to the completion list.
You can set the location where Latex-Suite will search for
.bib
and .bbl
files using the
|Tex_BIBINPUTS|
variable.
If a \bibliography
command is not found, then Latex-Suite
tries to scan the present file for a
\begin{thebibliography}
environment. If found,
Latex-Suite searches the present file for bib-keys of the form
\bibitem
.
When you press <F9>
at a location where Latex-Suite
guesses a filename needs to be typed, then a new explorer window will
open up with the list of files. You can use this window to change
directories etc. Pressing <enter>
on a filename
in the explorer window will automatically close the explorer window,
return to the location where you pressed <F9>
from and insert the filename into that position.
Latex-Suite also tries to guess what kinds of files you might not want to
insert and hides those accordingly. For example, if you press
<F9>
when you are located at
\includegraphics{
, then Latex-Suite knows that you will not
want to insert .tex
files. Therefore, the explorer
window will automatically hide these files.
As of now, Latex-Suite recognizes the following commands for filename completion. Along with the commands, this table also lists the files which Latex-Suite will not show for completing each command.
command | hide pattern |
---|---|
\bibliography | '^\.,\.[^b]..$' |
\include \includeonly | '^\.,\.[^t]..$' |
\includegraphics | '^\.,\.tex$,\.bib$,\.bbl$,\.zip$,\.gz$' |
\input | '' |
Latex-Suite also recognizes certain commonly used LaTeX commands for the
<F9>
key. At the moment, the
\bibliographystyle
, \addtocontents
and the \addcontentsline
commands are recognized,
although more will be added in the future. When you press the
<F9>
after such a command, Latex-Suite will prompt
you with a list of arguments which make sense for the command.
This functionality is available for commands for which a global
variable of the form
g:Tex_completion_{<command>}
is defined where
<command>
is the command name. This variable
is a comma separated list of values which this command takes. For
example, the argument to the \bibliographystyle
command is commonly one of abbr,alpha,plain,unsrt
.
Therefore, Latex-Suite defines
let g:Tex_completion_bibliographystyle = 'abbr,alpha,plain,unsrt'
You can define your own completion variables in a similar manner for commands which you might use.
This functionality, available via the TeX-Suite menu, provides various tools to compile and debug LaTeX files from within Vim.
If you are using commonly used LaTeX tools, then you should be all set
as soon as you download and install Latex-Suite. In order to compile a
LaTeX file, simply press \ll
while editing the file.
This runs latex on the current file and displays the errors in a
|quickfix-window| below the file being edited. You can then scroll
through the errors and press <enter>
to be
taken to the location of the corresponding error. Along with the errors
being listed in the quickfix window, the corresponding log file is also
opened in |preview| mode beneath the quickfix window. It is scrolled
automatically to keep in sync with the error being viewed in the
quickfix window. You will be automatically taken to the location of the
first error/warning unless you set the g:Tex_GotoError variable to 0.
Latex-Suite also supports compiling LaTeX into formats other than DVI. By
default, Latex-Suite supports PDF and PS formats. In order to choose a format
other than DVI, use the TTarget
command or the
TeX-Suite > Target Format
menu item. This will ask you
to type in the name of the target format you want to compile to. If a rule
has been defined for the format (as described in the next
section), then Latex-Suite will switch to
that format.
Trying to choose a format for which no rule has been defined will result in Latex-Suite displaying a warning message without taking any action.
If you are using a multiple file project and need to compile a master file while editing other files, then Latex-Suite provides a way to specify the file to be compiled as described in latex-master-file.
In order to compile LaTeX files into various formats, Latex-Suite needs to know which external programs to call and in which way they need to be called. This information is provided to Latex-Suite via a number of "rules". For each format you want to compile to, you need to specify a rule. A rule is specified by defining a variable of the form:
g:Tex_CompileRule_<format>
where <format>
is a string like
"pdf"
, "dvi"
etc.
Example: By default, Latex-Suite uses the following rule for compiling LaTeX documents into DVI.
g:Tex_CompileRule_dvi = 'latex --interaction=nonstopmode $*'
Default values are also provided for ps and pdf formats. You might want to change these rules in texrc according to your local tex environment.
For win32 users user MikTeX, sometimes the latex compiler's output has a
bug where a single number is split across different lines. In this case,
put the included vim-latex
file distributed with Latex-Suite.
Latex-Suite also handles compiling dependencies automatically via certain rules which specify the "dependency chain" for each target format. For example, if in your case, you use
.tex -> .dvi -> .ps -> .pdf
to generate pdf
files from dvi
files, then you will need to specify the following setting in your
Latex-Suite configuration (see customizing Latex-Suite for where
these settings should go):
let g:Tex_FormatDependency_pdf = 'dvi,ps,pdf'
This is a comma separated string of formats specifying the order in
which the formats to be compiled into should be chosen. With this
setting, if you set the target format to pdf
, then
the next time you compile via the \ll
shortcut, Latex-Suite
will first generate a dvi
file, then use that to
generate the ps
file and finally create the
pdf
file from that.
If any of the intermediate formats is listed in the
g:Tex_MultipleCompileFormats
setting as described
in the section Compiling multiple
times, then Latex-Suite might make multiple calls to the compiler to
generate the output file of that format.
Along with the g:Tex_FormatDependency_{format}
setting, you should ofcourse specify the rule for compiling to each of
the formats as described in the previous
section. For example, with the setting above, you could use:
let g:Tex_CompileRule_dvi = 'latex --interaction=nonstopmode $*' let g:Tex_CompileRule_ps = 'dvips -Ppdf -o $*.ps $*.dvi' let g:Tex_CompileRule_pdf = 'ps2pdf $*.ps'
By default, Latex-Suite does not specify any compiler dependencies. Each target format for which a rule has been derived will be compiled independently.
Most LaTeX compilers need to be re-run several times in several
commonly occurring situations in order to get a final camera ready copy.
For example, when \label
's change, when new
\cite
commands are added etc. If the target format
you are compiling to requires multiple compilations, then you will
need to include the format in the
g:Tex_MultipleCompileFormats
setting. This is a
comma separated string of formats which need multiple compilations to
be generated correctly.
By default, this setting contains just the dvi
format. If you use the pdflatex
compiler to generate
pdf
files, then you might want to also include
pdf
into the above setting.
For every format included in the
g:Tex_MultipleCompileFormats
setting described
above, Latex-Suite will use the following logic to generate the file. Note
that although the following description uses latex
to refer to the compiler, it could be some other compiler such as
pdflatex
for generating pdf
output.
.idx
file, then remember
its contents.latex
..idx
file changed due to the latex
compiler, then run makeindex
to redo the
.ind
file and then remember to rerun latex.
If the .aux
file generated by the latex
compiler contains a \bibdata
line, then it
means that we are using a .bib
file. Therefore,
run bibtex
.
This means that we will always run bibtex
whenever we use the \bibliography
command
whether or not we actually need to. At this time, Latex-Suite does not
parse the .aux
file before and after the latex
compiler to see if we are required to rerun
bibtex
.
.bbl
file changes because of this, then
remember to rerun latex again.
makeindex
or
bibtex
again.
The LaTeX file is compiled atmost 5 times using this logic. These steps will ensure that on most platforms/environments, you will get a clean output with all the cross-references, citations etc correctly labelled and ordered.
Most LaTeX compilers produce a very large amount of output during compilation, most of which is not relevant to debugging type-setting errors. The compiler plugin provided with Latex-Suite (which is an enhanced version of the standard compiler plugin maintained by Artem Chuprina), provides a way to filter the compiler output so that the actual errors/warnings can be presented much more concisely.
The compiler plugin is set up by default to function in a "non-verbose",
"ignore-common-warnings" mode, which means that irrelevant lines from the
compiler output will be ignored and some very common warnings are also
ignored.
Latex-Suite does this via the global variable g:Tex_IgnoredWarnings
.
This is a list of patterns, which can be used to filter out (or ignore)
some or the warnings and errors reported by the compiler. See the link
above for its default value.
Latex-Suite uses the g:Tex_IgnoreLevel
setting to set a default ignore level. For example, for the default
value of 4, Latex-Suite ignores warnings and errors matching the first 4
patterns in g:Tex_IgnoredWarnings
.
In addition to setting a default value of the ignore level, Latex-Suite
provides the ability to set the level dynamically, using the
TCLevel
command. For example, if you issue the
command:
TCLevel 3
from within Vim, then the next time you compile the document, Latex-Suite will
ignore warnings and errors which match the first three patterns in
g:Tex_IgnoredWarnings
.
When TCLevel is called with the unquoted string strict as follows:
TClevel strict
then Latex-Suite switches to a "verbose", "no-lines-ignored" mode which is useful when you want to make final checks of your document and want to be careful not to let things slip by.
See the explanation of the settings g:Tex_IgnoredWarnings and g:Tex_IgnoreLevel to find out how to customize the filtering done by Latex-Suite
Latex-Suite also provides a way to compile a fragment of a document. This can be very useful while debugging a complex equation or one chapter in a book, etc.
To do this, visually select a portion of the text and press
\ll
while in visual mode. The visually selected portion
will be saved to a temporary file with the preamble from the current
document prepended. Latex-Suite will then switch focus to this temporary file and
compile it. Continue to debug this file as required and then replace the
portion of the original file with this one.
Pressing \lv
while viewing the temporary file will
view the output file generated from the temporary file, not the original
file
Two commands |TPartComp| and |TPartView| are provided to be able to get this functionality via the command line.
From release 1.6 onwards of Latex-Suite, the temporary file created for part compilation will reside in the same directory as the file from which the fragment is being created. This ensures that any relative path-names defined in the fragment will still work. Latex-Suite will attempt to clean the temporary file(s) created when Vim exits.
If you do not use Latex-Suite, but an external program or script to compile your tex documents, you can use
:cg | copen
to load (and parse) the .log
file.
If you use vim to compile your documents, you might want to use
:let $max_print_line=1024
such that latex will not wrap the filenames. Otherwise, you could use it as an environment variable or simply use
max_print_line=1024 pdflatex ...
in your terminal. If you are using latexmk, you should set
$ENV{'max_print_line'} = '1024'; $log_wrap = $ENV{'max_print_line'};
in your ~/.latexmkrc
.
In order to view the output files created by compiling the source
files, you need to specify which external program Latex-Suite should call. You
can specify the external program using one of two settings
Tex_ViewRule_format or Tex_ViewRuleComplete_format.
By default, Latex-Suite has default settings for viewing various common output
formats via the Tex_ViewRule_format
settings, so
that if you are using commonly used programs, you should be all set to
view compiled files from within Vim by simply pressing
\lv
.
The viewing function also takes the *.latexmain
file
into account to decide which file to show.
If pressing \lv
does not work, then it most probably
has to do with incorrect settings of the g:Tex_ViewRule_<format>
where <format>
is the format you are
attempting to view. See the link above for how to set this according to
your system.
On Windows and OS/X, you can leave the view rule empty to open the document
with the default viewer on your system. On Linux/UNIX systems, you can use
the xdg-open
command to open the document with the default
viewer.
In addition to viewing the files, Latex-Suite also supports forward and inverse searching for certain common tools for viewing documents. See the next few sections for details on forward and inverse searching, including an overview of viewers.
Forward searching refers to making a viewer display a given document at a given location from within Vim. At present, these viewers are known to support forward searching, but viewers that are not listed here may work, too:
Viewer | OS | Supported documents | Comment |
---|---|---|---|
Skim | Apple / OS X Tiger | Supports also inverse searching | |
PDFView | Apple / OS X | No longer in development, supports also inverse searching | |
TeXniscope | Apple | PDF, DVI | |
YAP | Windows | DVI, PS | ships with MikTex |
Sumatra PDF | Windows | ||
kdvi | Linux/UNIX | DVI | |
okular | Linux/UNIX | DVI, PDF, PS and many more | Included in KDE 4 |
xdvi | Linux/UNIX | DVI | |
xdvik | Linux/UNIX | DVI |
Pressing \ls
from within Vim
should make the viewer display the portion of the document where your
cursor is placed.
OS/X users need to set the g:Tex_TreatMacViewerAsUNIX
flag
to 1
and provide a UNIX-like viewrule, that expects as
arguments the document, the linenumber and the sourcefile in this order.
Most DVI viewers need "source-special" information in order to do
forward (and inverse) searching. This information is embedded in the
dvi
file if the LaTeX source is compiled with the
--src-specials
option. By default, Latex-Suite does not
supply this argument to the compiler. See the section on
g:Tex_CompileRule_dvi
to find out how this option can be set.
Pdf viewers usually use a synctex(.gz) file. This can be enabled with the compiler flag
-synctex=1
for pdflatex.
Within this suite it is however enabled by default, unless you change
g:Tex_CompileRule_pdf
.
Inverse searching refers to a viewer (either pdf
or dvi
)
telling Vim to display the LaTeX source file at a given location.
Usually this happens with double-clicking or clicking while pressing the shift/control button
in the viewer window. The actual method depends on the viewer application.
You will need to enable searching in order to use this functionality.
You will also need to specify certain settings to the viewer conveying the syntax which it needs to use to tell Vim how to display the source file.
In windows you need to supply the following command in the apporpriate setting of your viewer:
"C:\Program Files\vim\vim74\gvim" -c ":RemoteOpen +%l %f"
Or if you have (g)Vim added to your $PATH
simply:
gvim -c ":RemoteOpen +%l %f"
The command :RemoteOpen
is supplied when you install
Latex-Suite. In YAP
, you can set this option under
View > Options > Inverse Search
in the Command Line field.
And in SumatraPdf
you can set this option under
Settings > Options > Set inverse search command-line
.
On *nix machines, Latex-Suite attempts to call the DVI viewer in such a way
that it already knows how to communicate with Vim. If this does not
seem to be working, you can use the RemoteOpen
command described above.
Latex-Suite ships with the plugin SyntaxFolds.vim which is a plugin for creating "fake" syntax folds on the fly. The fold method is actually manual but the folding is based on LaTeX syntax. This offers a speed increase over regular syntax folding. Ofcourse it has the disadvantage that the folds are not dynamic, i.e newly created syntax items are not automatically folded up. (This is a compromise between speed and convenience).
When you open up a LaTeX file, all the portions will be automatically folded
up. However, no new folds will be created until you press
\rf
. (rf
stands for "refresh folds").
The fold-text is set to the first line of the folded text unless the fold is a table, figure etc. (an environment). In this case, if a \caption and/or a label is found in the folded region, then those are used to make a more meaningful fold-text, otherwise the second line of the environment is displayed along with the name of the environment. In other words, the following
\begin{figure}[h] \centering \includegraphics[height=6cm]{slidercrank.pdf} \caption{The Slider Crank Mechanism.} \label{fig:slidercrank} \end{figure} % a LaTeX comment. \begin{equation} \sin(\pi) = 0 \end{equation}
will be shown as:
+--- 5 lines: figure (fig:slidercrank) : The Slider Crank Mechanism. ----- % a LaTeX comment. +--- 3 lines: equation () : \sin(\pi) = 0 --------------------------------
By default, Latex-Suite creates folds in the following manner:
\part %%fakepart \chapter %%fakechapter \section %%fakesection \subsection %%fakesubsection \subsubsection %%fakesubsubsection \paragraph %%fakeparagraph \item \equation \align \figure \table \footnote
The indentation shows the "nestedness" of the folding scheme. See the next section to see how you can change this scheme.
From version 1.6 onwards, the folding in Latex-Suite can be controlled to a large extent via a number of global variables.
This entry defines which sections will be folded. This setting is a comma separated list of section names. The default value is:
part,chapter,section,subsection,subsubsection,paragraph
Each of the entries in the list will fold up a section of the
corresponding name and the corresponding %%fakesection
.
The %%fakesection
section is
provided as a means for the user to group lines into "fake" sections.
In particular, it is useful to fold the introduction of a section
that is not part of a subsection
:
\section{Latex-Suite} %%fakesubsection Introduction A short introduction of the features of Latex-Suite. \subsection{Installation} Installation instructions.
Without the %%fakesubsection
the introduction would not be folded separately from the section.
It is also possible, to add section names at the same level of hierarchy. These have to be separated by "|". This is, e.g., useful for the KOMA classes, which add "\addcap":
" let g:Tex_FoldedSections = 'part|addpart,chapter|addchap,section|addsec,subsection,subsubsection,paragraph,subparagraph'
See also advanced fold settings.
This entry defines which environments will be folded. It is a comma separated string of words each of which defines a single environment. The default setting is
verbatim,comment,eq,gather, align,figure,table,thebibliography, keywords,abstract,titlepage
The words need not be standard Latex environments. You can
add any word you like. Also, each word will fold up all
environments whose name begins with that word. For example, in
the setting above, the word "align"
folds up the
\begin{align}
,
\begin{align*}
,
\begin{aligned}
environments. To avoid
this, you can replace the word "align"
with
"align}"
.
See also advanced fold settings.
This entry defines which commands will be folded. It is a comma separated string of words each of which defines a single command. The default setting is empty, i.e no commands are folded. The words need not be standard Latex commands. You can use whatever words you like. Each word will fold all commands whose name begins with that word as in the case of the Tex_FoldedEnvironments variable.
It is very difficult to fold commands reliably because it is very difficult to create a regexp which will match a line containing unmatched parentheses (or curly brackets), but will not match a line containing matched parentheses.
Just to make things safer, only lines which start a command but do
not contain additional curly braces after the command has started are
folded. In other words, if you wanted to fold the the command
"mycommand"
, then the lines
\mycommand{This is a line and some more text on the next line }
will be folded, but the lines
\mycommand{This is a \textbf{line} and some more text }
will not be folded. This is a bug which is very difficult to fix.
See also advanced fold settings.
This entry defines fold syntax for certain items which do not naturally fit into the section, environment of command lists. It is a comma separated list of words. The default value is:
item,preamble,<<<
Unlike the other Tex_FoldedXXXX variables, the words in this setting are limited to take values from the following list:
Value | Meaning |
---|---|
comments | Folds up contiguous blocks of comments |
item | Folds up the \item s within list
environments |
preamble | Folds up the preamble of a document. (The part between
the \documentclass command and the
\begin{document} environment) |
<<< | Folds defined manually by the user using the
<<< and
>>> strings as fold-markers. |
Any other words in the Tex_FoldedMisc
setting
are silently ignored.
See also advanced fold settings.
The order of the words in the Tex_FoldedXXXX
variables is important. The order defines the
order in which the folds are nested. For example, the value
"subsection,section"
for the
Tex_FoldedSections
variable will not fold any
subsections at all. This is because the folds are created in the
reverse order in which they occur in the
Tex_FoldedSections
setting and also, once a fold is
created, the interior of the fold is not examined for creating
additional folds. In the above case, this means that a
\section
is folded first and then its interior is
not examined further. The correct value should have been
"section,subsection"
Each of the fold setting variables
Tex_FoldedSections
,
Tex_FoldedEnvironments
etc., as explained previously
is a comma separated string of variables. However, to make it easier
to add to the default settings without having to
repeat the whole default setting again, Latex-Suite uses the following logic
in forming the complete setting string from the
Tex_FoldedXXXX
variables. If the variable starts with
a comma, then Tex_FoldedXXXX
is added to the end of
the default string rather than replacing it. Similarly, if it ends
with a comma, then it will be prepended to the beginning of the
default setting rather than replacing it.
For example, if Tex_FoldedEnvironments
is set to the
string "myenv"
, then only an environment of the
form \begin{myenv}
will be folded. However, if the
Tex_FoldedEnvironments
setting is
",myenv"
, then the \begin{myenv}
environment will be folded after all other environments in the default
setting have been folded. On the other hand if
Tex_FoldedEnvironments
is of the form
"myenv,"
, the \begin{myenv}
environment will be folded before the rest of the environments in the
default setting.
Many LaTeX projects contain multiple source files which are
\include
d from a master file. A typical example of
this situation is a directory layout such as the following
thesis/ main.tex abstract.tex intro/ intro.tex figures/ fig1.eps fig2.eps chapter1/ chap1.tex figures/ fig1.eps conclusion/ conclusion.tex figures/
In the above case, main.tex
will typically look like
% file: main.tex \documentclass{report} \begin{document} \input{abstract.tex} \input{intro/intro.tex} \input{chapter1/chap1.tex} \input{conclusion/conclusion.tex} \end{document}
In such situations, you will
need to convey to Latex-Suite that main.tex
is the main file
which \input
s the other files. This is done by creating
an empty file called main.tex.latexmain
in the same
directory in which main.tex
resides. This file is called
the master file in this manual. See Tex_MainFileExpression for an
alternative way of specifying the master file.
Here main.tex.latexmain
is (obviously) a different
file from main.tex
itself.
main.tex
need not be renamed. This ofcourse
restricts each directory to have a single master file.
Each time Latex-Suite opens a new LaTeX file, it will try to see if it is
part of a multiple file project by searching upwards (to the root of
the file-system) from the current file's directory to see if it finds a
file of the form *.latexmain
. If such a file is
found, then it is considered that the current file is part of a larger
project. The name of the LaTeX master file is inferred directly from
the first part of the *.latexmain
file as described
in the example above.
If a master file is found,
then Latex-Suite :source
s the file. Thus this file needs to
contain valid Vim commands. This file is typically used to store
project specific settings.
Some typical per-project settings which are best put in the master file are
Tex_ProjectSourceFiles |
In the example described previously, if you are editing
intro/intro.tex
and press \ll
,
then you still want Latex-Suite to compile main.tex
,
because intro/intro.tex
is merely a fragment which
is \input
'ed into main.tex
. If
the master file is already specified using the
*.latexmain
convention described previously, then Latex-Suite will automatically
compile the master file when you are editing any of its
\input
'ed fragments. Thus pressing
\ll
while editing intro/intro.tex
will compile main.tex
.
If you wish to use some different logic to specify the main file name,
you can specify a custom expression via the
Tex_MainFileExpression
variable. This is a string
containing a valid vim expression. In addition, you can use a variable
modifier
which is in the format used for
|filename-modifiers|
, for example,
':p:h'
. You should utilize this variable to modify
the filename of the main file.
let g:Tex_MainFileExpression = 'MainFile(modifier)' function! MainFile(fmod) if glob('*.latexmain') != '' return fnamemodify(glob('*.latexmain'), a:fmod) else return '' endif endif
This section describes the maps and commands used in Latex-Suite. It also describes a way to change the map sequences according to your preference.
Most of the mappings used in Latex-Suite can be mapped to a different key
combination to suit your particular needs. An example best explains the
procedure for doing this. Suppose you want to remap the
<C-j>
key which Latex-Suite (actually imaps.vim) uses
to jump to the next placeholder. To do this, you first need to find out
which <Plug>
mapping
<C-j>
is derived from. You will need to look
at the relevant section of this manual to do this. For example, the
section IMAP mappings has
the information that the <C-j>
key is derived
from <Plug>IMAP_JumpForward
. Therefore to
remap the <C-j>
key to say
<C-space>
, you will need to put a
statement like the following in your ~/.vimrc
.
imap <C-space> <Plug>IMAP_JumpForward
To change the IMAP
mappings which affect jumping
between placeholders, the map
statement above has
to be placed in your ~/.vimrc
. For other mappings
you can place the map
statement in your
$VIM/ftplugin/tex.vim
file. The reason for this is
that the <C-j>
maps are created in
plugin/imaps.vim
, which is sourced as soon as Vim
starts before sourcing any ftplugin files.
These mappings are utilized for jumping between placeholders as described here. See the parent section to find out how to use this information to change the default maps.
Plug map | Default Key |
---|---|
<Plug>IMAP_JumpForward | <C-j> |
<Plug>IMAP_JumpBack | (none) |
<Plug>IMAP_DeleteAndJumpForward | (none) |
<Plug>IMAP_DeleteAndJumpBack | (none) |
<Plug>IMAP_JumpForward
takes you to the
location of the next place-holder.
<Plug>IMAP_JumpBack
takes you to the previous
place-holder.
<Plug>IMAP_DeleteAndJumpForward
deletes the
presently selected place-holder and jumps to the next place-holder
irrespective of whether the present placeholder is empty or not and
ignoring the value of place-holder settings like g:Imap_DeleteEmptyPlaceHolders
and g:Imap_StickyPlaceHolders
<Plug>IMAP_DeleteAndJumpBack
deletes the
presently selected place-holder and jumps to the previous place-holder
irrespective of whether the present placeholder is empty or not and
ignoring the value of place-holder settings like g:Imap_DeleteEmptyPlaceHolders
and g:Imap_StickyPlaceHolders
These mappings are are described in the section Alt key macros. See the parent section to see how to use the following information to remap keys.
Plug Mapping | Default Key |
---|---|
<Plug>Tex_MathBF | <Alt-B> |
<Plug>Tex_MathCal | <Alt-C> |
<Plug>Tex_LeftRight | <Alt-L> |
<Plug>Tex_InsertItemOnThisLine | <Alt-I> |
When used without any arguments lists all available macros defined in runtime ftplugin/latex-suite/macros/ directories and prompts you to choose one of them. With one argument |:read| this macro under cursor position. With more than one argument it will not work :) In Vim >= 6.2 works completion of names of macros (see 'wildmenu', 'wildmode' for more about command-line completion).
Splits window for editing {macro}. When used without any arguments lists all available macros defined in runtime ftplugin/latex-suite/macros/ directories and prompt you to choose one of them. When you try to edit {macro} not from local directory Latex-Suite will copy it to your local directory with suffix "-local". If local copy already exists Latex-Suite prompt for overwriting it. In Vim >= 6.2 works completion of names of macros (see 'wildmenu', 'wildmode' for more about command-line completion).
Splits window to write new macro. Directory in new buffer is locally changed to Latex-Suite/macros/.
Delets {macro} from your local ftplugin/latex-suite/macros/ directory. When used without any arguments lists all available macros defined in Latex-Suite/macros/ directory and prompt you to choose one of them. When you choose to delete {macro} which is not in your local directory Latex-Suite will refuse to delete it. In Vim >= 6.2 works completion of names of macros (see 'wildmenu', 'wildmode' for more about command-line completion)
When used without any arguments lists name of the packages for
which support is available. If you are using Vim GUI and have
Tex_Menus
set to 1, then it will list all files
found in the $VIM/ftplugin/latex-suite/packages
directory. Otherwise, Latex-Suite will list files found in the
$VIM/ftplugin/latex-suite/dictionaries
directory.
Choosing a file from the list will insert a
\usepackage[<++>]{<packname>}
line into the
buffer at the current cursor location. For Vim 6.2 and above, you
can use command-line completion to choose a package file. You can also
call TPackage
with one or more package names
separated with spaces in which case, Latex-Suite will insert
\usepackage
lines for each of them in turn.
After inserting the \usepackage
line(s), Latex-Suite will
support it (them) in various ways as described in the section Actions taken for supported
packages.
This command `reads' name of package under cursor and turns on possible support.
After issuing this command latexSuite scans the file in looking for not declared packages, removing not needed entries from Packages menu and turning off not necessary packages' dictionaries.
When used without any arguments lists all available templates from latex-suite/templates/ directory and prompts to choose one of them. With one argument :0|read| {template} file. With more than one argument it will not work :) In Vim >= 6.2 works completion of names of macros (see 'wildmenu', 'wildmode' for more about command-line completion)
Used without any arguments inserts last section type (|latex-sectioning|). Accepts arguments: n> inserts section name in <n> logical level. Levels are:
0 | part |
1 | chapter |
2 | section |
3 | subsection |
4 | subsubsection |
5 | paragraph |
6 | subparagraph |
+<n> | inserts section name <n> logical levels above the last used comand |
-<n> | inserts section name <n> logical levels below the last used comand |
+ | inserts section name one logical level below the last used command (equal to +1). |
++ | inserts section name two logical levels below the last used command (equal to +2). |
- | inserts section name one logical level over the last used command (equal to -1). |
-- | inserts section name two logical levels over the last used command (equal to -2). |
Command accepts also latexSuite mappings (|latex-macros|) without preceding S and in lowercase:
:TSection pa
will result in \part{}
. It is possible to use full names of
sections: :TSection part
Accepts the same arguments as |TSection| but leads to a couple of questions (whether you want to include the section in the table of contents, whether there is a shorter name for the table of contents) and then creates a more intelligent template.
Accepts one argument. Will look through .tex files in directory of edited file for argument. It can be regexp. You don't have to enclose argument in "". <cr> takes you to location. Other keys work as described in |latex-viewer|. Note: TLook uses :grep command and is using 'grepprg'. Its regular expressions can be different from those of Vim.
Accepts one argument. Will look through .bib files in directory of edited file for argument. It can be regexp. You don't have to enclose argument in "". <cr> takes you to location. Other keys work as described in |latex-viewer|.
TLookBib uses :grep command and is using 'grepprg'. Its regular expressions can be different from those of Vim.
Accepts one argument. Will look through all files in directory of edited file for argument. It can be regexp. You don't have to enclose argument in "". <cr> takes you to location. Other keys work as described in |latex-viewer|. Note: TLook uses :grep command and is using 'grepprg'. Its regular expressions can be different from those of Vim.
No argument allowed but accepts range in all formats. Define fragment of interest with :'a,'b, :/a/,/b/, :'<,'> or :20,30. All other rules of compilation apply.
Customizing Latex-Suite is done by defining certain global variables in
$VIM/ftplugin/tex.vim
, where
$VIM
corresponds to ~/.vim
for *nix
machines and ~/vimfiles
for windows machines. This file
is not part of the Latex-Suite distribution. You will need to create this file
yourself (or modify it if it exists) if
you need to change any default settings. Since this file is not
included as part of the Latex-Suite distribution, it will not be over-written in
subsequent updates.
The default settings in Latex-Suite are defined in
$VIM/ftplugin/latex-suite/texrc
. Please take a look at
this file if you find this documentation incomplete or confusing. That file
is also well documented.
This chapter describes the various settings which effect Latex-Suite and their default values. The settings are broken up into sections according to the behavior which they influence.
Type | boolean |
Default Value | 0 |
If set to 1, then Latex-Suite will create certain global debug statements which can be printed by doing
:call Tex_PrintDebug()
Type | boolean |
Default Value | 1 |
If Latex-Suite detects that your vim is python enabled (using
has('python')
and has('python3')
), then it tries to use python in
certain places to speed things up. If this misbehaves, you can set
this to zero, in which case, Latex-Suite will use vimscript to accomplish
the same.
Latex-Suite uses place-holders to minimize using the movement keys while typing. The following settings affect how place-holders are used.
These setting need to be set in your ~/.vimrc
, not
$VIM/ftplugin/tex.vim
because these settings affect
the behavior of imaps.vim
, which is a global plugin,
not a file-type plugin.
Type | Boolean |
Default Value | 1 |
Setting this to zero completely disables using place-holders.
Setting | Type | Value |
---|---|---|
Imap_PlaceHolderStart | String | '<+' |
Imap_PlaceHolderEnd | String | '+>' |
These settings affect the strings displayed at the beginning and end of the place-holder string. Set these strings to a value different than a commonly occurring sequence of characters.
If you use the latin1
encoding and do not type in
french, then you can set these strings to the \xab
and \xbb
characters (the french quotation marks).
Type | Boolean |
Default Value | 1 |
When set to one, non-descriptive or empty place-holders are deleted on
pressing <Ctrl-J>
.
Type | Boolean |
Default Value | 1 |
When set to 1, in visual mode, <Ctrl-J>
takes
you to the next placeholder without deleting the current placeholder.
If you wish to wish to expand certain environments differently from
the way Latex-Suite does it, you can define custom expansions using global
variables of the form Tex_Env_{name}
where
name
corresponds to the environment.
For example, if you press <F5>
after typing
theorem
, Latex-Suite will by default expand it to
\begin{theorem} \label{<++>}<++> \end{theorem}<++>
However, if you wish change this to
\begin{theorem} <++> \end{theorem}<++>
then define the following variable
let g:Tex_Env_theorem = "\\begin{theorem}\<CR><++>\<CR>\\end{theorem}"
If the expansion uses special keys such as carriage return etc, then
use double-quotes and use the "\<key>"
notation for special keys. Backslashes have to be doubled.
You could even use strings returned by functions as the expansion by using the IMAP_PutTextWithMovement() function.
If the name of the environment contains special characters (for
example, the align*
environment), then use the
following form:
let g:Tex_Env_{'align*'} = \ "\\begin{align*}\<CR><++> &= <++>\<CR>\\end{align*}<++>"
This will make pressing <F5>
after
align*
expand to
\begin{align*} <++> &= <++> \end{align*}<++>
By default, Latex-Suite inserts labels without prefixes.
The setting Tex_EnvLabelprefix_{name}
, where name
corresponds to the environment, is used to create labels with prefixes automatically.
For instance, if you use
let g:Tex_EnvLabelprefix_equation = "eq:"
the prefix eq:
is inserted in all labels in generated equations:
\begin{equation} <++> \label{eq:<++>} \end{equation}<++>
This setting works for the environments
figure
,
table
,
theorem
,
definition
,
lemma
,
proposition
,
corollary
,
assumption
,
remark
,
equation
,
align
and
multline
.
Type | Boolean |
Default Value | 0 |
If Tex_EnvEndWithCR
is set to 1
, a carriage return (i.e., line break)
is inserted between \end{environment}
and the last placeholder:
\begin{equation} <++> \label{<++>} \end{equation} <++>
Type | Boolean |
Default Value | 0 |
If Tex_ItemsWithCR
is set to 1
, a carriage return (i.e., line break)
is inserted after \item
and the placeholder, e.g., itemize<F5>
is expanded to
\begin{itemize} \item <++> \end{itemize}
Type | Boolean |
Default Value | 1 |
If Tex_LabelAfterContent
is set to 0
, the label is placed before the content of the environment:
\begin{equation} \label{<++>} <++> \end{equation}<++>
Type | Boolean |
Default Value | 0 |
If this variable is set to 1, then when an environment is chosen from the menu then for selected environments, Latex-Suite asks a series of questions on the command line and inserts a template with the corresponding fields already filled in. Setting this to zero will insert a template with place-holders marking off the places where fields need to be filled.
Type | String |
Default Value | 'equation,equation*,align,align*,enumerate,itemize,figure,table' |
This string represents a comma separated list of fields corresponding to
environments. Pressing <F5>
in insert-mode in
the body of the document asks you to choose from one of these
environments to insert.
Leaving this string empty will leave the <F5>
key unmapped
Type | String |
Default Value | 'equation*,equation,bmatrix' |
This string represents a comma separated list of environments which are
mapped to <Shift-F-1>
through
<Shift-F-4>
. For example, pressing
<Shift-F-2>
with this setting inserts the
equation
environment.
Leaving this string empty will leave <Shift-F-1>
through
<Shift-F-4>
unmapped.
Only the first four fields of this list are used. The rest are silently ignored.
If you wish to define new expansions for fast command insertion as
described here, or redefine
expansions from the default values in Latex-Suite, you will need to define
variables of the form g:Tex_Com_{name}
where
name
is a command name. For example, with the
setting
let g:Tex_Com_frac = "\\frac{<++>}{<++>}<++>"
pressing <F7>
after typing
frac
will change it to \frac{<++>}{<++>}<++>
See Tex_Env_name for additional details on how to create this setting in various special circumstances.
Type | String |
Default Value |
'footnote,cite,pageref,label'
|
This string represents a comma separated list of LaTeX commands
which Latex-Suite uses for the <F7>
and
<S-F7>
maps as described here.
Leaving this string empty will leave the <F7>
key unmapped.
This setting affects the style which Latex-Suite uses to insert an
\item
when <Alt-I>
is
pressed as described here. By default
Latex-Suite defines styles for the following environments:
Environment | Style |
---|---|
itemize | \item |
enumerate | \item |
theindex | \item |
thebibliography | \item[<+biblabel+>]{<+bibkey+>} <++> |
description | \item[<+label+>] <++> |
Each style is defined by a variable of the form
g:Tex_ItemStyle_{envname}
where
envname
is the name of the environment for which
the style is defined. For example, by default
g:Tex_ItemStyle_description = '\item[<+label+>] <++>'
Redefining the style for a particular environment or defining a style for an entirely new environment is simply a matter of setting the value of a variable of the corresponding name.
The following variables disable various parts of the macro functionality of Latex-Suite. See the links to the relevant sections to see what functionality setting each of the variables to zero will take away.
Setting | Link to relevant section | Default Value |
---|---|---|
g:Tex_EnvironmentMaps
| Environment Mappings | 1 |
g:Tex_EnvironmentMenus | 1 | |
g:Tex_FontMaps | Font Mappings | 1 |
g:Tex_FontMenus | 1 | |
g:Tex_SectionMaps | Section Mappings | 1 |
g:Tex_SectionMenus | 1 |
Type | boolean |
Default Value | 0 |
This option when set to 1, temporarily freezes Latex-Suite's macro expansion. It might be useful when you are using some other keymap which is causing excessive macro expansion. Use a buffer-local variable of the same name if you wish to affect just the present buffer.
Type | Boolean |
Default Value | 1 |
With so many visual maps, its helpful to have a way of catching typing
errors made in visual mode. What this does is to prompt you to correct
your visual mode mapping if you start out with g:Tex_Leader
and then type some
illegal keys. It basically maps just the g:Tex_Leader
character to a function.
Type | String |
Default Value | '`' |
The mappings in Latex-Suite are by default prefixed with the back-tick
character. For example, `/
inserts
\frac{<++>}{<++>}<++>
etc. You can change the
prefix with the following setting.
','
, '/'
,
'`'
are preferred values. ''
or
'\'
will lead to a lot of
trouble.
g:Tex_Leader is also used for visual mode mappings for fonts.
Type | String |
Default Value | ',' |
In order to avoid clashes between the large number of visual mode macros
provided, the visual mode
macros for environments and sections start with a character
different from g:Tex_Leader
.
These settings affect the smart key functionality as described here.
Type | Boolean |
Default Value | 1 |
Whether or not the smart quotes functionality is available.
If enabled, the quote characters can be customized by setting the following variables:
Setting | Value |
---|---|
g:Tex_SmartQuoteOpen | "``" |
g:Tex_SmartQuoteClose | "''" |
Non-English users will want to change these settings to their locale.
These global variables will be ignored if there are buffer-local
variables (with the same name), which may be set in the language specific
package files, such as
$VIM/ftplugin/latex-suite/packages/german
.
The following settings affect the completion functionality in Latex-Suite.
These three settings affect the aesthetics of the completion functionality.
Setting | Explanation | Default Value |
---|---|---|
g:Tex_ViewerCwindowHeight | The height of the cwindow which displays the
list of \label s etc. | 5 |
g:Tex_ViewerPreviewHeight | The height of the preview window which shows the context of a
\label etc. | 10 |
g:Tex_ExplorerHeight | The height of the explorer window which lists the files from which to choose an image file. | 10 |
g:Tex_ImageDir | The directory to scan for images | '' |
Type | string |
Default Value | '' |
This string describes the directories which are scanned while trying
to search for .bib
and .bbl
files. See the cite completion
section for more details.
This string should be set in the syntax accepted by Vim's native
'path'
setting. Do not include the present
directory '.'
. While searching for
bibliography
files, the present directory will be
prepended to this variable.
When set to 1 (default),
Latex-Suite searches for \label
s in all
.tex
files of your project,
starting with the
main file
when <F9> is pressed. See \ref completion for details.
When set to 1 and if Tex_UseOutlineCompletion
is 0,
Latex-Suite searches for \label
s in all
.tex
files in the directory containing the file
being edited when <F9> is pressed. See \ref completion for details.
Type | String |
Default Value | '' |
This setting is meant to be initialized on a per-project basis using
the Latex-Suite master file as
described in Latex-Suite Project
section. It is a list of source files which are used in the project.
If defined, then instead of using the logic described in
Tex_UseSimpleLabelSearch to
search for files in which to search for \label
s, we
simply search for \label
s in this list. This
significantly reduces the time it takes to generate the list of
possible completions for large projects.
The list is specified as a whitespace separated list of filenames relative to the location of the main file.
When set to 1 (default), Latex-Suite uses python to parse your bib-file. See \cite completion for details.
The following settings affect Latex-Suite's compilation functionality
Type | String |
Default Value | dvi for windows/*nix and
pdf for mac |
Use this setting to choose the default target format. For example,
setting this to pdf
makes Latex-Suite compile a pdf file
when you press \ll
and fire up the
pdf
viewer on pressing \lv
. Make
sure that a rules for compiling and viewing have been defined for this
target format as described here and here.
Here <format>
refers to the target format for
which this rule is defined. Latex-Suite supports compiling into
dvi
, ps
and pdf
by default. All these rules are strings defined by default as follows:
g:Tex_CompileRule_dvi | 'latex -interaction=nonstopmode $*' |
g:Tex_CompileRule_ps | 'ps2pdf $*' |
g:Tex_CompileRule_pdf | 'pdflatex -interaction=nonstopmode $*' |
If you desire forward and inverse searching via Latex-Suite, you will need to
change g:Tex_CompileRule_dvi
to include
-src-specials
. However, this has been known to cause
problems with the output file. Therefore, use this with care.
Type | string |
Default Value | '' |
By default, there are no format dependencies defined. Each definition
is of the form above where <format>
is a
string such as 'dvi'
etc.
The value of each string is a comma separated string such as 'dvi,ps'. See the Compiler dependency section to see how to use/specify this setting
Type | string |
Default Value | 'dvi' |
This is a comma separated string of formats for which the compiler needs to be called multiple times in order to get cross-references, citations etc right. See the Compiling multiple times section for details.
Type | String |
Default Value | a new-line separated list of patterns as described
below |
The default value of this setting is
\"Underfull\n". \"Overfull\n". \"specifier changed to\n". \"You have requested\n". \"Missing number, treated as zero.\n". \"There were undefined references\n" \"Citation %.%# undefined"
This setting defines a set of patterns which will be filtered out when displaying the output from the latex compiler. This is to aid in filtering out very common warnings/errors.
Remember to check the value of g:Tex_IgnoreLevel
when you change this setting. For example, if you append a new pattern
which you would like to ignore by default, increase the value of
g:Tex_IgnoreLevel
.
Type | Integer |
Default Value | 7 |
This setting defines a "filter level" or an "ignore level". A value of 7
for instance means that any warning/error matching with any of the first
7 fields of g:Tex_IgnoredWarnings
will be ignored. Setting this value to zero will mean that no
error/warning is ignored. However, even with a value of zero, Latex-Suite will
filter out most of the text which a LaTeX compiler typically produces.
Use
TCLevel strict
from within Vim in order to see all the lines from the compiler's output.
Type | boolean |
Default Value | 1 |
When set to 1, then if a makefile
or
Makefile
is present in the current directory, then
Latex-Suite sets the makeprg
option to just
"make <target>"
, where
<target>
is the target format chosen using
the TCTarget
or TTarget
commands.
When set to 0, then Latex-Suite will set the makeprg
setting to whatever is defined by the g:Tex_CompileRule_target
setting.
The following settings affect how Latex-Suite will display compiled files.
Here <format>
refers to a format such as
dvi
, ps
, etc. This variable defines
the program which will be called to display a file of that format.
By default, Latex-Suite defines viewer programs for viewing DVI, PS and PDF formats as follows:
Windows | Unix | |
---|---|---|
g:Tex_ViewRule_dvi | 'yap -1' | 'xdvi' |
g:Tex_ViewRule_ps | 'gsview32' | 'ghostview' |
g:Tex_ViewRule_pdf | 'AcroRd32' | 'xpdf' |
For Macintosh systems, these strings are left empty by default. This lets the system pick the program for each format. If you define these variables for Mac, the system choice will be over-ridden.
Latex-Suite appends file.format
to the above settings
while calling the external programs. For example, with
let g:Tex_ViewRule_dvi = 'yap -1'
yap
is called as
!start yap -1 file.dvi
from within
Vim. (The initial start
is used on
Windows
platforms is to make yap
start as a separate process.) If you find the way Latex-Suite constructs the
command line too restrictive, you can use the Tex_ViewRuleComplete_format
setting for more complete control on how the command line is
constructed while calling the external program for viewing.
For windows, you will need to set the $PATH
variable
to include the paths to yap
,
AcroRd32
, gsview32
and any other
programs. See your system documentation for how to do this.
To change the default format for viewing files, set the g:Tex_DefaultTargetFormat variable.
Here <format>
refers to the extension of a
output format such as dvi
, html
etc.
Tex_ViewRuleComplete_format
takes precedence over
Tex_ViewRule_format
if both are specified. By
default, Latex-Suite does not define values for
Tex_ViewRuleComplete_format
for any
format
. Unlike in the case of
Tex_ViewRule_format
, Latex-Suite does not modify
Tex_ViewRuleComplete_format
at all in constructing
the command line. The only modification is to substitute
'$*'
everywhere in the string with the name of the
file being viewed (without the extension).
Make sure you make the process go into the background otherwise vim will wait for the viewer to terminate before letting you edit the file again.
To make a process go into the background on a *nix
platform, use a trailing &
in the setting. On
Windows
, use start
at the
beginning of the setting. Example: Suppose you have a latex->html
converter which converts a file say foo.tex to a file foo/index.html.
Then you would use:
" On *nix platform let g:Tex_ViewRuleComplete_html = 'MozillaFirebird $*/index.html &' " On windows platform let g:Tex_ViewRuleComplete_html = 'start MozillaFirebird $*/index.html'
In addition to using the variables defined in this section to affect
the menu-layout permanently (i.e, the layout Latex-Suite will start with), you
can also use the TeX-Suite > Configure Menu
menu to
dynamically configure the menu layout after Latex-Suite has started.
Type | Boolean |
Default Value | 1 |
If set to 0, Latex-Suite will suppress showing all menus. Useful if you mostly work in terminals.
Type | number |
Default Value | 80 |
This setting decides the location of the first top-level Latex-Suite menu. You can for example shift all the menus created by Latex-Suite to the very end by setting this value to a large number like 990.
Type | Boolean |
Default Value | 1 |
The Tex-Math
menu consists of hundreds of mathematical
symbols used in LaTeX. This menu comprises about 75% of the menus.
Type | Boolean |
Default Value | 1 |
This setting controls the "compactness" of the menus. If set to 1, then the
Font, Counter and Dimensioning menus are collected together in a single
menu called Tex-Elements
, otherwise, they will each get
a separate menu.
Type | Boolean |
Default Value | 1 |
Setting this to zero will stop Latex-Suite from automatically creating the
TeX-Suite > Packages > Supported
menu at startup. You
can still create the menu after startup by going to
TeX-Suite > Configure Menu
.
Type | Boolean |
Default Value | 1 |
If this option is set, Latex-Suite creates the packages option within the TeX-Suite menu. Otherwise, it is a top-level menu entry.
Type | String |
Default Value | 'TeX-' |
This string is the prefix added to all the menus created by Latex-Suite. If you
define this variable with a dot ('.'
) as the last
character, then all the menus created by Latex-Suite will be nested under a
single master menu. For example, set this to
'&LaTeX-Suite.'
to nest all menus under a menu
called &LaTeX-Suite
.
Type | Boolean |
Default Value | 0 |
This setting controls whether Latex-Suite uses utf-8 symbols to display some of
the mathematical symbols in the TeX-Math
menu. It is
necessary for your system/GUI to support utf-8. Setting this to 1 has the
side-effect of setting the 'encoding'
option of Vim
to 'utf-8'.
The following settings control the folding functionality of Latex-Suite, see also Customizing what to fold.
Type | Boolean |
Default Value | 1 |
Setting this to zero completely disables Latex-Suite's folding functionality.
However, the TexFoldTextFunction()
is still available
in case you want to use another folding scheme but still want to continue
using the fold text function.
These settings affect the custom packages functionality in Latex-Suite
Type | string |
Default Value | '' |
This setting describes the directories scanned by Latex-Suite while searching for custom user packages as described in the custom packages section. Do not include the present directory in this setting. The present directory is always scanned for custom packages.
This string should be set in the syntax accepted by Vim's native
'path'
setting.
This setting describes the directories scanned by Latex-Suite to search for templates.
And finally, the credits:
Artur R. Czechowski | maintains the BSD package of Latex-Suite. Lots of valuable feedback. |
Lubomir Host | provided the diacritics and also helped in development. |
Alexander Wagner | valuable suggestions during development. |
Luc Hermitte | his variation of Stephen Riehm's bracketing system is used in Latex-Suite. |
Gergely Kontra | the clever little JumpFunc() in imaps.vim is due to him. The implementation of the templates also borrows from mu-template.vim by him. |
Dimitri Antoniou | author of ltags and also provided the nice tip about forward / reverse search on DVI documents. |
Stephen Riehm | the extremely helpful bracketing system is from him. |
Alan Schmitt | provided macros/folding elements. Continued feedback, bug-reports/fixes. |
Hari Krishna Dara | for ExecMap(), the clever little function which makes typing visual mode mappings so much easier and error-free. |
Alan G Isac | for the comprehensive BibT() function for entering bibtex entries. |
Gontran Baerts | for libList.vim |
Peter Heslin | useful discussion and also a lot of bug fixes. the %%fakesection in folding.vim. |
Zhang Lin-bo | lots of very useful additions to folding. The code for customizing the folding scheme is due to him. |
A large number of functions in Latex-Suite come from various other people. Some of those people might have been missed here. Each function should however have the author's name/e-mail above it. Thats the more authoritative place to check out who has done what.
The current maintainer(s) of Latex-Suite is(are)
Srinath Avadhanula <srinath@fastmail.fm> |
Mikolaj Machowski <mikmach@wp.pl> |
Benji Fisher <benji@member.AMS.org> |