Fetching contributors…
Cannot retrieve contributors at this time
5756 lines (4925 sloc) 229 KB
*automatic-tex-plugin.txt* LaTeX filetype plugin Last change: 26 September 2012
An Introduction to AUTOMATIC (La)TeX PLUGIN (ver. 12.1)
by Marcin Szamotulski
mszamot [AT] gmail [DOT] com
If you found this plugin useful or you have any kind of problems with running
it or some ideas to share, you are cordially invited to write to me: Voting at Vim site is also welcome ;) .
This is a filetype plugin for Vim to comfortably write [TeX], [LaTeX],
[PdfLaTeX],... documents, which provides functionality not met in other
plugins. It makes you [FREE] from compiling procedure, making this process
automatic using autocommands. It also provides useful mappings and other
many other commands: to analyse your .log file, to see the table contents, to
search for a label, to search in bib files or to find a macro definition
matching a pattern, or even to find and preview fonts in your tex
distribution. The features include a multi-functional tab completion for:
commands, environment names, packages, input files, bib files, bst files,
colours, closing brackets and environments (preserves nesting),... etc. To
have full functionality you need: python (with nonstandard psutil library, see
|atp-requirements-python| how to get it), pdffonts available in the package
'app-text/poppler' (at least in Gentoo). Another good tool is texdoc, which
is a part of TexLive - these days standard TeX distribution for Linux, and
MikTeX on Windows.
* background compilation, debugging modes, progress bar
* command to make the document (cross references, references, index, tables
of contents) |atp-:MakeLatex|,
* completion for commands, closing environments (even nested), package names,
citations and labels. Support for some latex packages,
see |atp-completion|,
* forward/inverse searching:
see |atp-:SyncTex|, |atp_inverse_search|,
* table of contents which allows to switch between different sections, files,
but also to delete and paste sections:
see |atp-:TOC|, |atp-toc-window|,
* list of labels which allows to see the context of a label:
see |atp-:Labels|,
* a command to get bib data from the AMSRef web page
see |atp-:AMSRef|,
* a powerful function to search in bibliographic files (bib files):
see |atp-bibsearch|,
* a command to list ToDo lines:
see |atp-:ToDo|,
* a command to search for a macro definition (multi-line support):
see |atp-:Dsearch|,
* a command to search and PREVIEW fonts in your latex distribution:
see |atp-:FontSearch|, and |atp-:FontPreview|,
* indentation.
SOURCEFORGE *atp-sourceforge*
- The project is hosted on SourceForge:
SUPPORT *atp-support*
You can [DONATE] for this project through your [PayPal] account (my email
is <mszamot [AT] gmail [dot] com>). This will be highly appreciated.
I have a problem with my hardware now, and the donations will help to
solve it. This is quite_an_issue for me now so thanks a lot for you
Thank You. ~
You can use this link:
- There is a mailing list which will serve for: feature requests, bug
reports, suggestions. You can subscribe at:
- There is also a new wiki page: (as for now it only includes features of
ATP - it looks nice :)
- For detailed list of changes you can look at:;a=log
- Project news can be tracked through sourceforge watch feature (you need
sourecforge account)
- SourceForge hosts stable releases (also available on Vim web page) but
also snapshots of unstable developed new version. The snapshots might
contains fixes and new features which might not yet work well, or might
change (commands, maps, etc ...).
|atp-news| News.
|atp-installation| Installation.
|atp-commands| Functions and commands:
some most important commands: ~
compile ~
viewer ~
|atp-:SyncTex| forward searching,
diff ~
motion ~
|atp-:Tags| make tags file,
search ~
|atp-:Dsearch| definition search,
|atp-:S| search in projects.
|atp-toc-window| Commands/maps defined in Table of Contents window
and Labels window. Includes folding from toc.
|atp-folding| Folding.
|atp-bibtex| File type plugin for bibtex.
|atp-bibsearch| Searching in bib files.
|atp-completion| How to use and configure completion
|atp-configure| How to configure to your needs.
|atp-ProjectFiles| A note how to write project files within ATP.
|atp-ProjectScript| A script executing project specific settings.
|atp-mappings| Mappings.
|atp-abbreviations| Abbreviations.
|atp-errors| Debugging ATP.
|atp-editing| Editing tools.
|atp-requirements| Requirements.
|atp-viewers| Note about viewers,
with [reverse_searching] for Okular, Xpdf and Skim
|atp-tips| Some tex oriented tips.
|atp-highlight| Colours and syntax files.
|atp-remarks| Final remarks.
|atp-copy-rights| Copy Rights.
Note on usage: type :help atpCTRL-d to see all the helptags. To see help tags
for all the defined functions :help atp*()CTRL-d, mappings: :help atp-mapCTRL-d
NEWS *atp-news*
Changes in version 12.1
You can help me get new hardware, since my laptop is dying ...
This is quite important issue for me these days so if you can donate just a few
pennies ...
Thanks for your support,
Marcin Szamotulski
|g:atp_HighlightMatchingPair| to turn on/off higlighting of matching pairs
(begin/end which might be slow on a slow computer).
If you set |g:atp_SelectInlineMath_withSpace|=1 |atp-im| will select the
space just after/before \(:\).
A few reported bug were fixed.
Changes in version 12
The default values of |g:atp_map_forward_motion_leader| has changed to "]"
and |g:atp_map_backward_motion_leader| to "[".
New |atp-gD| normal command.
The maps >E and <E are now |atp-]e| and |atp-[e|, and the previus >e and <e
maps are |atp-]]| and |atp-[[|. The accept a count. There are also [] and ][
maps (the count for them is not yet implemented).
|atp-:Texdoc| and |atp-:Texdef| instead of |atp-:TexDoc|, |atp-:TexDef|.
|atp-:Texdef| defined only if |g:atp_developer| is 1.
|g:atp_diacritics| variable: switched the values, now 2 (for diacritics: a''
-> accented a) and 1 (normal imaps).
If you don't want the ruler in the ATP status set the vim option |'noruler'|
and use the command |atp-:Status| (or |atp-:ATPStatus|).
|atp-:TEXL| and the \\l map supports count.
There are two maps to |atp-:SyncTexL|: \\f (like \\l) and \F.
completion: if you use subfiles packages the completion for \ref{} and
\eqref{} also looks inside the subfile .aux file.
If subfiles packge is used, the local aux file is searched for labels
If you don't like the maps associated to a given leader (g:atp_imap_leader_1,
...) put define the variable to be an empty string in your |vimrc| or |atprc|
The motions { and } are adding entries to the jump list, by setting the
` mark. This is the default behaviour in vim (see |jump-motions|) The same
aplies to the |atp-:S| command.
Read this note: |atp-completion-new-packages|.
Changes in version 11.1
I have put ATP on fundageek - a rais funding platform:
I am forced to do that, since my laptop is not working properly and I need
a replacement. Please share the link among people who would like to
support this project.
Best regards,
Note: ~/.vim/ftplugin/ATP_files/ was moved to
~/.vim/ftplugin/ATP_files/ You might need to udpat the
config file of your browser (Okular, Xpdf, etc.)
gf - works faster if vim is compiled with |+python| interface.
C-XC-O - closing brackets: a small bug fixed.
vip - better support for "\begin{...}[...]\label{...}".
MakeLatex! - with the bang "!" the commands writes (using |update| command)
all the loaded project buffers.
Changes in version 11
NOTE: You should remove the file:
Then ATP completion will work better, since ATP can now scan package and
documentclass files (.sty, .cls) for commands and options.
NOTE: I change the name of the script at to AutomaticLaTeXPlugin
(with capital X), if you install ATP via Vim-Addon-Manager (or other vim
plugin manager) this might affect path were the script is
located. In this case you might need to adjust the setting of reverse search
in your viewer (Okular, Xpdf, ...).
NOTE: It was found that 'relativenumber' option slows down vim when edditing
tex files (at least for some users).
You can download a quick reference guide for ATP from:
It should be easier now to go through ATP features.
If you set |g:atp_ParseLog| and |g:atp_Compiler|="python", then ATP will
rewrite the log file so that the output is readable for vim |quickfix| using
|errorformat|. The advantage is for project files, where it is important to
correctly read the file position of the error. In addition there is one more
|atp-:ShowErrors| flag 'O' which shows 'overfull \hbox' messages. Also note
that the flag 'w' (for warnings) excludes font warning messages.
NOTE: See also |atp-:Cgetfile| (!!! This command is only defined for vim version
< 7.3.468, my patch 468 introduces a new autocommand which is used to rewrite
the log file, so check out the latest vim version !!!).
|atp-:ErrorFormat| accepts "+{+flag}-{-flag}" as an argument.
|g:atp_Signs|=0 by default.
|g:atp_indent|=1 by default, then LatexBox indentation file is used.
|atp-gf| works well with \bibliography{} command.
See ':help atp-omap-<C-d>' for the defined operator maps.
|atp-vi(|, ... , |atp-va}| maps.
Support for subfiles.sty package:~
Compilation of parts of a project (using subfiles package).
|atp-:TEXL|, |atp-:ViewL|, |atp-:SyncTexL|, see also |b:atp_autex| (when set
to 2 automatic compilations of subfiles is turned on).
|atp-:S| command has additional flag 'x', when used the
|v:searchforward| value will not be changed.
|atp-:TOC| was rewritten in python so that it works well with project files.
If your vim is compiled without python the old ToC will be used.
TOC and Labels windows are clicable: acts like <space> = go to section and
leave TOC/Labels window open.
See also |atp-:RemoveFromToC| command.
See |atp-autosilent|, |atp-autodebug| and |atp-autoDebug| debug modes.
Previously, by default QuickFix window was closed when there was no error.
Now this behaviour is reserved only for |atp-autosilent|, |atp-autodebug|,
and |atp-autoDebug| modes.
omap \w and vmap \w to repeat last wrapping command (like \it, \sf, \em, ...)
(see |atp-omap-\w| and |atp-omap-WrapSelection|)
See |g:atp_diacritics| (used instead of g:atp_imap_diacritics_inteligent).
|atp-:ErrorFormat| and |atp-:ShowErrors| have a flag 'h' instead of 'O' which
shows both 'Underfull \hbox' and 'Overfull \hbox' messages'.
Local project script (.project.vim file) may contain |:set|/|:setl|
statements which will be executed after |vimrc| and |atprc| files.
These statements are executed only once (per project file).
As suggested by F.Heiderich: #< and #> are now maps for \langle and \rangle.
New commands: |atp-:Texdef|, |atp-:KpsewhichEdit|. They are defined in
plugin/tex_atp.vim script, so you can use them not only inside tex files.
Changes in version 10.6.4
ATP normal r map is working better, that is |.| works well with |atp-r| map.
|g:atp_OpenAndSyncSleepTime| = "500m" -- sleep time between the time when
ATP finds the viewer working and syncing (forward searching) for the command
|atp-:View|! (with bang) (this is time left for the viewer to open the file).
Plus some new package files for completion: showidx, makeidx, syntonly and
a better completion for the \includeonly{} command (which removes items from
completion menu which are already included).
Count added to |atp-]%| and |atp-[%|.
|atp-:TexAlign| works with smallmatrix environment.
Completion scans package and documentclass files for options (if vim is
compiled with |+python|).
Changes in version 10.6.3
A small bug fixed when opening a new tex buffer.
Omni completion changed:
(Expert Mode) Tab Completion is mapped to <C-X><C-O>
(Non Expert Mode) Tab Completion is mapped to <C-X>o
This is the default, if you want to use <Tab> and <S-Tab> keys set
|g:atp_tab_map| to 1 in your |vimrc| or |atprc| file.
For some reasons it is better to map completion to <C-X><C-O> than to use
'omnicomplete' option (as it was done in 10.6.2). Using the option sometimes
issues errors (when modifying text) also setting cursor position to the right
place is impossible (in more advanced completions, like closing
Note also that g:atp_no_tab_map has changed to |g:atp_tab_map|.
Changes in version 10.6.2
Omni completion -- ATP Tab completion now works as Omni Completion, see
|compl-omni|, the non expert mode completion is
mapped to <F7> key. The <Tab> key is not mapped. If
you want to use <Tab> and <S-Tab> for completion,
as it was done before, just put 'let
|g:atp_tab_map|=0' in your |vimrc| or |atprc|
Note that omni completion might give the 'Pattern
not found' error, when closing environments or
brackets - you can ignore this message (it is not
possible to turn it off, and working it around will
take to much time).
completion -- memoir document class completion: document class options,
and some commands,
-- bibref package added.
% motion -- changes the jump list (this is vim compatible
behaviour (see |jump-motions|)
-- omap % added. Now to delete an environment just put
the cursor over \begin or \end command and use 'd%'.
The same will work if you want to delete (:), [:],
{:} or $:$ pairs.
{ and } normal motions -- also work in visual mode (see |}| and |{|).
|atp-:Yank| and |atp-:Paste| (inside bib search) changed. Also yanking in
toc (the section key) is in more vim style.
|atp-:PasteSection| with bang "!" puts section before rather than after.
At the end of |atp-tips| I show how to make w b and aw work slightly better
(this is experimental code).
|atp-:ChangeLabel| -- a new command for changing labels across the
|atp-:WordCount| -- range added, if the file type is 'tex' also
doesn't count the preambule.
|atp-:View| -- instead of :ViewOutput command.
Changes in version 10.6.1
In the |atp-:BibSearch| window:
:BibChoose is now split into two commands:
|atp-:Yank| and |atp-:Paste|, the maps 'y', 'c' and 'p', 'P' can be invoked
with a count. |atp-:Yank| by default uses the " register.
|atp-:SyncTex| is now mapped to |atp-\f|, instead of t, which was not
compatible with |t| vim command. It is easy to remember |atp-\f| = like forward
search ;)
New normal mode wrapping operator maps: see |atp-nmap-fonts| and
Commands to find maps:
:Map[!] {pattern} |atp-:Map|
:Nmap[!] {pattern} |atp-:Nmap|
:Imap[!] {pattern} |atp-:Imap|
:Smap[!] {pattern} |atp-:Smap|
:Vmap[!] {pattern} |atp-:Vmap|
:Omap[!] {pattern} |atp-:Omap|
:Lmap[!] {pattern} |atp-:Lmap|
There is another plugin: MapFinder
which defines them. The only Imap differs, here it is more specific to ATP,
since ATP defines and deletes some imaps on the fly not all of them are
visible with :imap command.
Changes in version 10.6
The command |atp-:View| with bang (also <F3> map) opens and makes forward search.
Reverse search (atplib#FindAndOpen() function) sets the "'" mark before
changing text position.
Folding: ~
See |atp-folding| - thanks to Johannes Zellner for the simple (and fast)
folding script.
Imaps: ~
->, <- in tikz picture environment (but not in math) puts \draw[->] or \draw[<-].
They are also disabled inside [:].
Vmaps: ~
'o, 'u instead of 'ov and 'uv (\overline, \underline). This is compatible
with imaps 'o and 'u.
Some bug fixes. For example the algorithm for closing brackets is more
reliable (should work in 100% cases ;).
Cmap: ~
<space> cmap for \_s\+, if |\v| is included (very magic) in the pattern (any where) then
\_s+ is used as rhs.
Changes in version 10.5
Thanks for all the vim karma points: if you look at all ftplugin scripts ATP has 8th
rate and among ten most rated plugins it has 2nd best average rate: 3.71, while the
first one has 3.73. If you find something in ATP which is not convenient, or
you think it might be done in a more friendly way, let me know, I'm open for
discussions :)
Here are the recent changes (excluding bug fixes):
Signs -- see |atp-signs| (and |signs|).
:Unwrap -- see |atp-:Unwrap| command (nmap <LocalLeader>u).
See added note below |g:atp_texinputs|.
The package variable names are changed, see |atp-completion-packages|.
Changes in version 10.2
Skim (MacOS) -- support for "Skim" added (forward search)
[thanks to Florian Heiderich].
Read the necessary steps in |atp-Viewers-Skim|.
Xpdf -- support for inverse searching added (Xpdf -> vim)
thus both inverse and forward searching
works for Xpdf (and Okular). See
|atp-Viewers-Xpdf| how to set it.
:MakeLatex [mode] -- mode is one of silent/debug/Debug. Will
also show bibtex/biber/makeidx error
code/debug info.
:Dictionary {word} -- an interface to
see |atp-:Dictionary| (with map =d
using |<cword>| under the cursor).
|atp-:Edit| -- instead of :EditInputFile
:ShowErrors e -- fixed (finally!)
:TexAlign -- can manage table environments and also
join lines which do not end with \\, see
|g:atp_TexAlign_join_lines| how to set this.
'iskeyword' -- is set using g:tex_isk variable. This is
compatible with the standard tex syntax
:TexAlign! -- bang added+some fixes, see |atp-:TexAlign|.
Replace() -- if |g:atp_VimCompatible| is 0 then the
normal |r| will be overwritten with another
function with the following feature:
if you do |atp-r| over one of the brackets:
(:), {:}, [:] then r(, r{, r[ (and r), r},
r]) will change both: the opening and the
closing bracket. Otherwise, i.e. over any
other character, or rc where c is other
than opening bracket at opening position or
closing bracket at closing position,
|atp-r| will work the same as |r|.
New imaps:
l*, L* \wedge, \bigwedge (l = lattice theoretic, meet)
l+, L+ \vee, \bigvee (join)
wedge is also under #& but #ve (for \vee) and #V (for \bigvee) are removed,
since they were interfering with #ve for \varepsilon.
Greek Letter Maps: are disabled when the previous character is '\'. So you
can type '\#a' with the default value of |g:atp_imap_leader_1| and it will
not transform into '\\alpha'.
map _ -- set section: focus main window on the
section under cursor and jump back to TOC.
map & vmap zc -- fold sections/chapters/... . Has one
limitation: cannot fold subsection if
section in which it sits is folded.
You can fold several sections at once using
visual mode (subsections will not be
folded in right way though).
Changes in version 10
If you use <Shift-Tab> (i.e. non-expert mode for completion) to close
a bracket, it will be put after the cursor, allowing you to write inside
brackets. This doesn't work with \(:\) and other math pairs and closing
Closing brackets with <Tab> is much faster now.
cmap <M-c> ^\%([^%]\|\\%\)* - useful when searching for sth which
is not in a commented out.
Both vmap and imap for \overline and \underline are using
The value of |g:atp_MapSelectComment| is now |=c| (it used to be _c)
You can also use v|ip| over commented lines to select them.
New math imaps: (|atp-imaps-math|)
|- \vdash
-| \dashv
++ \sum (it is disabled now when typing X_++ or X^++)
The command :Align (and thus also :TexAlign) are using ATP_strlen function to
measure the string length. ATP sets g:Align_xstrlen="ATP_strlen" if
'conceallevel' option is >0. If 'conceallevel' is reset to 0 ATP_strlen
behaves like g:Align_xstrlen=2. (This needs Align plugin version higher than
36, available at: .
|atp-:TOC| and |atp-:Labels| commands when open together will be in one
column with table of contents at the top.
]*, ]%, [*, [% - skip comment maps, all works now in the same way. If
|g:atp_VimCompatible| is 1 they go to where comment starts/ends, if it is
0 they go one line above/below.
cmap <M-c> will insert a pattern which match lines which are not a comment.
INSTALLATION *atp-installation*
If you have .vmb (or .vba) file just open it in vim and source it (:so %<CR>).
You can also install ATP using Vim Addon Manager (VAM):
or GetLatestVimScipt plugin:
Third option is to clone the git repository with the command: >
git clone ssh:// ./atp
If you use VAM you can clone into your vim-addon directory
(~/.vim/vim-addons/AutomaticLaTexPlugin) and VAM will update it using git
pull. In this way you will have always the most recent version of ATP.
Note: If you use Pathogen or VAM you need to restart all your vim servers if
you want revesre search to work, or at least use in each running server
pathogen#infect('addons'), or similar command with VAM (:ActivateAddons
Necessary vim settings:
|:filetype-indent-on| (if you want to have automatic indentation for TeX files)
|:syntax-enable| (several features will not work properly without this option)
If you do not like colours you can still set syntax on but clear the highlight
colours (you should make a simple function which clears all the highlight
groups, because ':hi clear' will not give you what you want).
See |atp-requirements| for other ATP requirements or better go to: web page.
To get updates it is enough to use this command:
With bang update ATP to latest {UNSTABLE} snapshot, without to latest
stable release. It makes a check if your version is the latest one.
If you have installed {UNSTABLE} snapshot and then you run :UpdateATP
without a bang "!", then ATP will ask you if you want to DOWNGRADE to
the last stable release.
{UNSTABLE} snapshots contain small fixes, and rarely, major changes
of important parts of ATP (what can produce new bugs).
|atp-:UpdateATP| works well with pathogen vim plugin.
Requires python (consult the |feature-list|).
This command prints version information of ATP and the time stamp when
this version was build. The time stamp is in format 'dd-mm-yy_HH-MM'.
ATP AND OTHER PLUGINS *atp-and-other-plugins*
EasyMotion and ATP ~
If you want to use EasyMotion vim plugin (which is quite handy):
You can set |g:atp_Compare|="". Alternatively, if you want to use the
fastest comparing method of ATP, you can add to last line of
s:EasyMotion() function (i.e. just above the |:endfunction| vimL keyword) in
let b:atp_changedtick = b:changedtick
< In older version of EasyMotion this function used to be inside
plugin/EasyMotion.vim file.
You might want to change g:EasyMotion_leader_key (see |easymotion-leader-key|),
because some maps of ATP are interfering with EasyMotion. For example "-"
might be a good choice. You can also try to change |maplocalleader| which
is heavily used by ATP.
COMMANDS *atp-commands* *atp-:*
The main function is not seen by the user (it is called s:compiler, for those
who want to read the plugin). It executes tex compiler specified by the
variable |b:atp_TexCompiler|. It is executed as an autocommand by the line: >
au! CursorHold $HOME*.tex silent call 's:auTeX()'
< where s:auTeX() is a simple function which calls s:compiler if the file
written on the disk and the buffer differ. There are two comparing mechanism,
the default one is using |b:changedtick-variable| , the seconds compares the
buffer with the on-disk version:
The default value is "changedtick". Then the |b:changedtick-variable|
is used to find if there buffer differs and to run latex. With any other
value a compare function will be used (which compares the buffer and
the written file on the disk) - this method is much slower but has
additional features: by default differences in comments are skipped
(if you set |g:atp_compare_embedded_comments|=0 (the default is 1)
then also the comments which do not start right at the beginning of
line will be skipped). The second feature is to not see differences in
amount of blank lines: two or more blank lines is the same as one
blank line, for this set |g:atp_compare_double_empty_lines|=0, which
is the default.
As you can see it will run if a key is not pressed during time defined by
option |'updatetime'| (see |CursorHold|) in the normal mode. If you type in
insert mode the file won't be compiled (and that's all right as you can be in the
middle of your very long formula). The value of |'updatetime'| which works
fine is around 1000ms (|'updatetime'| is set in milliseconds). Instead of
setting |'updatetime'| options directly you should set the variables
|b:atp_updatetime_insert| and |b:atp_updatetime_normal|. Here's an important
note on using CTRL-C (|i_CTRL-C|) in Vim:
In vim the key combination CTRL-C (|i_CTRL-C|) in insert mode exists to
normal without triggering the InsertLeave autocommands. In this way it
doesn't changes the |'updatetime'| from |b:atp_updatetime_insert| to
|b:atp_updatetime_normal|. If |g:atp_IMapCC|=1 then |_CTRL-C| is mapped to
|i_CTRL-[| so the InsertLeave autocommands are parsed. However, it is
a good habit to use |i_CTRL-C| while you are writing/editing and |i_CTRL-[| or
|i_ESC| when you wish to see what you wrote (then TeX will be run
quicker). If you follow this you can even set
|b:atp_updatetime_normal|=1 (if you set it to 0 then the file will not
be processed while Vim is in normal mode).
b:atp_updatetime_insert = 4000
b:atp_updatetime_normal = 2000
< - These variables sets the value of |'updatetime'| vim option.
Separate settings are for normal and insert mode. You can make
|b:atp_updatetime_normal| even smaller so that the file is processed
whenever you go out from insert mode to normal mode. These values will
overwrite the original value of |'updatetime'| (unless you set both
variables to 0) so you should adjust them in order for the change to have
an effect.
If you set |b:atp_updatetime_insert|=0 the TeX compiler will not be called
while Vim is in the insert mode.
If you set |b:atp_updatetime_normal|=0 the TeX compiler will not be called
while Vim is in the normal mode.
b:atp_MaxProcesses = 3
When |g:atp_Compiler|="python" this variable will control the maximal
number of simultaneous LaTeX processes in the background. If new process
comes old and the number of processes is |b:atp_MaxProcesses| or bigger
one appropriate number of processes is killed to have not more than
|b:atp_MaxProcesses|. If you set it to 0 ATP will not control the number
of running instances of LaTeX compiler. There is one more variable:
b:atp_KillYoungest = 0
When set to 0 (the default) oldest processes are killed, when set to
1 youngest ones. If your file is big it might be better to kill youngest
Coming back to compilation ... ~
Tex compiler is run with one options:
which points to a unique temporary file in a temporary directory |b:atp_TempDir|
You can switch off/on the function s:auTeX by pressing <S-F5> or by letting
the local to buffer variable |b:atp_autex|=1 (on) |b:atp_autex|=0 (off). It is
useful in some situations turn automatic compiling off.
Note: if you set |b:atp_autex|=2 the the automatic compilation will
compile the currently edited subfile of your project (for this you need to
use the subfiles package).
The key <S-F5> calls the command |atp-:ToggleAuTeX| which sets the variable
|b:atp_autex| and issue a message. You can also set this variable to 0 for
some files that are not supposed to be processed, for example:
au BufRead texmf/*.tex let b:atp_autex=0
On start up |b:atp_autex| is set to 1 if the path of opened file is not under any
tex directory ('kpsewhich -show-path tex', except the current dir). For example,
files located under your local texmf tree will have b:atp_autex=0. Also for
files with other extension than the standard "tex" it will be set to 0.
:ToggleAuTeX {arg}
The {arg} is one of off/on/local. It sets b:atp_autex to 0/1/2
respecively. If {arg} is omitted it changes: local->off (2->0),
on->off (1->0) and off->on (0->1).
The second important variable |b:atp_TexCompiler| configures if you use TeX,
PdfTeX, LaTeX, PdfLaTeX and it should point to the program name so please do
not use capital letters.
Next variable to set is |b:atp_OutDir|. It configures where TeX
will put the output and where viewer and log analysing tools can find
appropriate files.
The last top most important variable is |g:atp_keep| which is a list of extensions,
by default it is
let g:atp_keep = [ "log", "aux", "toc", "bbl", "ind", "idx", "synctex.gz",
\ "blg", "loa", "toc", "lot", "lof", "thm", "out" ]
Files with this extension will be copied from |b:atp_OutDir| to the temporary
directory with appropriate name to be used when (La)TeX is compiling. (log file
will be only copied after it is created, other files will be copied back and
forth between you |b:atp_OutDir| and the temporary directory)
There are two function compile which can compile your tex file: one written in
python (for portability reasons) and old one in bash. They work almost the
same with one small difference. The python code has some vim enhancements (for
example the progres bar).
The python code has a debug file compile.log under |g:atp_TempDir| will
contain all the errors issued by python, and ''
- debugging info printed by the || script.
If for some reason you'd like to use the old 'bash' style script there is
a variable: >
g:atp_Compiler = "python"
< just switch its value to "bash" (you don't need to restart vim). OK, so
what is the difference: the python script uses psutil python library (probably
you need to install it, at least I had to.) It is for two purposes: to
determine if xpdf is running and secondly, more importantly to check if latex
is running.
The python script || sends PID numbers of latex processes to vim
variable |b:atp_LatexPIDs|. Then the function which makes the status line for
ATP has a python code to check if the latex PIDs are still valid processes.
This is more accurate than the method used with bash compiler (before running
latex increase variable |b:atp_running| and decrease after getting signal that
latex has ended). In many situations this was failing. The new method works
better, however it shows that latex is running after slightly longer period of
time (not that first python must run the script and then run latex).
The variable |b:atp_TexReturnCode| stores the return code of compilation.
See |atp-requirements-python| for python libraries that are used by ATP.
By default the call back mechanism is turned on (g:atp_callback=1)
When call back mechanism is set, which is by default if you run gui
version, if you invoke 'vim' from command line you need to add
'servername' variable, it might be desirable to alias Vim to to >
vim --servername VIM
< you have additional functionalities:
* if you set |g:atp_signs| to 1 (the default is 0) call back and
|atp-:ShowErrors| will use |signs| to mark errors and warnings.
* Status Line Notification: status line can show if tex is running >
let g:atp_statusNotif = 1
< If unset you will get a message when compiler ends. If set the
number next to the name of your compiler indicates how many
instances are currently running. If |g:atp_ProgressBar|=1 then also
progress information of TeX compiler will be shown.
It can also show if other programs such as bibtex, biber or makeidx
are curently running.
* The log file will be automatically read after compilation (|:cgetfile|).
The command |:cgetfile| will be run when you open new files, this
nicely works with |:edit| command but not |:split| if you want to keep
the old log file in QuickFix window. If this is the case set >
let g:atp_cgetfile = 0
< The default value is 1.
* Debug mode is set by the value of |t:atp_DebugMode|, you can set or
see its value using |atp-:DebugMode| command (with completion for
debug modes).
*atp-debug-mode-silent* *atp-debug-mode-autosilent*
*atp-silent* *atp-autosilent*
* if |t:atp_DebugMode| = 'silent' or 'autosilent'
:DebugMode silent
nmap <LocalLeader><LocalLeader>s
You will not get any message from compilation.
In 'autosilent' mode the quick fix window will be automatically
closed if there are no more errors (this depend on error
*atp-debug-mode-debug* *atp-debug-mode-autodebug'
*atp-debug* *atp-autodebug*
* if |t:atp_DebugMode| = 'debug' or 'autodebug'
:DebugMode debug
nmap <LocalLeader><LocalLeader>d
After the end of compilation (invoked by the user or
autocommand) you will get a message with the return status of
the compilation. If the exit code is non zero it will be
highlighted with |hl-ErrorMsg|.
If you open the error window with |:copen| or with the menu
option ToggleDebugMode then it will be automatically closed
after first compilation with no errors. Quick fix window is
closed in both 'silent' and 'debug' debug modes. This depends
on |errorformat| which you can set with |atp-:ErrorFormat|
and |atp-:ShowErrors|:
ATP test for 'no errors' is 'len(|getqflist()|)'. If the
debug mode was 'debug' |t:atp_DebugMode| will fall back to
|g:atp_DefaultDebugMode| (by default it is the 'silent'
The 'autodebug' works similar to 'autosilent' mode.
*atp-debug-mode-Debug* *atp-debug-mode-autoDebug*
*atp-Debug* *atp-autoDebug*
* if |t:atp_DebugMode| = 'Debug' or 'autoDebug'
:DebugMode Debug
nmap <LocalLeader><LocalLeader>D
This mode is the same as 'debug' + after compilation ATP jumps
to first error.
The 'autoDebug' works similar to 'autosilent' mode.
* if |t:atp_DebugMode| = 'verbose'
Every compilation which is invoked by the user will be run in
verbose mode (this mode is mapped to <F5> key). In this mode
latex '-interaction=' switch is set from the variable
|b:atp_VerboseLatexInteractionMode| (the default value is
Note: the 'verbose' mode in 'Vim' (in the console) needs to be run,
when there is no other latex instance running. Now you get a message
to wait until compilation ends. In future releases, a better solution
will be worked out. Gui version 'gvim' works better (as it doesn't
suspend the editor).
The background compilation is always done in |g:atp_DefaultDebugMode|.
Unless it is set to 'verbose' in which case 'debug' mode is used.
See also |atp-:copen|.
g:atp_ProgressBar = 1
< By default, when using the python compiler you will get progress
message in your status line. The number indicates the last page number
compiled by LaTeX. If by some reason, you want to switch this off, set
g:atp_ProgressBar to 0 (use |let|).
You need |g:atp_statusNotif|=1 and |g:atp_statusline|=1 for this
feature to work (see also |laststatus| on how to activate status line
in Vim).
If there are many background processes the number which is shown
belongs to the oldest process. (|g:atp_ProgressBarValues| is a dictionary
{ 'pid' : 'pagenr' } - status line shows max of pagenr's).
Note: the time between you start to compile and when [1] appears in
the status line is mostly the time when LaTeX is reading all the
packages loaded in the preamble.
Limitations ~
Progress Bar doesn't like when you switch windows while the
compilation takes time. You might need to use |atp-:Kill| command.
< This is a dictionary of dictionaries:
{ 'bufnr' : {dict}, ... }
Every buffer gets its entry (by |bufnr()|). The {dict} is a dictionary
which is an empty dictionary {} if compilation is not going on, and
while compilation it contains the dictionary of PID number and page
number where the compilator actually is doining its job.
Note: If you compile and the progress bar starts at page > 1, you can
use 'let |g:atp_ProgressBarValues|={}' to reset the progress bar. You
should check if there is any LaTeX process running in the system.
You can also use the |atp-:Kill| command which will reset the
progress bar and kill the corresponding processes.
g:atp_DebugModeQuickFixHeight = 8
< This is the maximal height of |quickfix| window when opened by ATP.
You can invoke compiler in the 'debug' mode with '|<LocalLeader>|d',
'|<LocalLeader>|D' for 'Debug' mode (jump to first error),
'|<LocalLeader>|l' uses the default mode.
let g:atp_DefaultDebugMode = 'silent'
< This is the default debug mode in which background compilation will
run. It can be set to 'debug', setting it to 'verbose' will have the
same effect as setting it to 'debug'. ATP will come back to this debug
mode if compilation ends with exit status 0.
When compilations ends without errors (i.e. when quick fix list is
empty for the current error format) |t:atp_DebugMode| falls back to
g:atp_DebugModeCmdHeight = &cmdheight
< the default cmd height (see |cmdheight|) for the debug mode.
ATP will switch to it back and forth if needed. By default it is set
to |cmdheigh| value (thus unless you set it to sth else you will not
see the difference).
When going out of debug/Debug modes cmdheight is set to
|g:atp_cmdheight| value (with default value set from 'cmdheight'
option on startup).
Note: if you change |cmdheight| you should also change
|g:atp_DefaultCmdHeight|, unfortunately vim has not autocommand group
event to do that automatically.
:DebugMode [debug-mode] *atp-:DebugMode*
Command which help to set |t:atp_DebugMode| variable (has completion).
[debug-mode] is one of "silent", "debug", "Debug", "verbose" (they can
be suppressed to 's', 'd', 'D' or 'v' (or "si"/"sil"/"sile"/... etc).
If no argument is given it shows the current debug mode.
:DebugMode[!] s[ilent]
nmap <LocalLeader><LocalLeader>s
:DebugMode[!] autos[ilent]
It will load error file (|cgetfile|) with bang "!" it will
open |quickfix| window if there are errors (|cwindow|). If
|quickfix| window was opened it will be closed.
Sets |t:atp_DebugMode|='silent' ('autosilent').
:DebugMode d[ebug]
nmap <LocalLeader><LocalLeader>d
:DebugMode[!] autod[ebug]
It will load error file (|cgetfile|) and open |quickfix|
window with |:copen|.
Sets |t:atp_DebugMode|='debug' ('autodebug')
:DebugMode D[ebug]
nmap <LocalLeader><LocalLeader>D
:DebugMode[!] autoD[ebug]
It will load error file (|cgetfile|) and open |quickfix|
window with |:copen|.
Sets |t:atp_DebugMode|='Debug' ('autoDebug')
:DebugMode v[erbose]
Sets |t:atp_DebugMode|='verbose'
The height of the |quickfix| window will be one more than the length
of quick fix list (|getqflist()|) but nor more than
:copen *atp-:copen*
Works slightly different than |:copen|. The [height] argument will not
take effect. Use |:resize| instead. ATP computes the height of the
QuickFix window, and uses the variable |g:atp_DebugModeQuickFixHeight|
as an upper bound for QuickFix window height.
The variable b:atp_ReloadOnError if set to 1 (which is the default) reload the
file even when the exit status of compiler was non zero. If set to 0, then the
file will not be reloaded [actually for viewers other than Xpdf it will not be
copied from the temporary directory, for Xpdf it will be copied but not
There is also a variable which stores the last command which executed
your tex compiler, see |g:atp_TexCommand|.
:[count]TEX[!] [debug_mode] *atp-:TEX*
map [count]<LocalLeader>l, map [runs]<LocalLeader>d
If anyway you want to run TeX yourself but you do not want to see the
output this is the right tool. This runs TeX in 'nonstopmode'. You can
specify an argument [count] which tells how many consecutive runs of
TeX you need (this is important if you want to compile Table of
Contents, or index, or the bibliography (see |atp-:Bibtex|)
With bang it saves (using the |update| command) all loaded project
If b:atp_OpenViewer=1 and there current viewer (b:Viewer) is not
running on the output file then this function will open a viewer. By
default b:atp_OpenViewer=0 and this feature is disabled.
The command :2TEX will call the compiler two times.
It is useful when you want to make the outline (using hyperref
package) of your article in pdf files, the tex file has to be
'sourced' twice. To make the bibliography you can use |atp-:Bibtex|.
If {runs} > 5 it will be reduced to 5, to avoid running tex for hundreds
(or event thousands) of times (what could happen otherwise by
a mistake giving the range of the command to be the current line
The optional argument [debug_mode] has possible values: '', 'silent',
'debug', 'Debug', 'verbose'. When '' the current debug mode is used
(|t:atp_DebugMode|). ( [debug_mode] can be suppressed to 's', 'd',
'D', 'v' or "si"/"sil"/"sile"/... etc.) See the description of
\d is mapped to :TEX debug and \l to :TEX (thus it uses your default
debug mode).
:[count]TEXL [debug_mode] *atp-:TEXL*
map [count]<LocalLeader>k
This command compiles the current subfile (L - comes from "local") of
the project (you have to use subfiles package).
This commands also sets 'errorfile' option (using |atp-:TEX| will set
it back to the main log file).
Note that ATP is coping the project aux file (if present) and using it
for compilation of subfiles. In this way you get all the labels and
references. If you add new labels to the subfile then ATP will copy
the corresponding entries from the subfile aux file to the main aux
file. However, it will not work if the label (its value) was changed
or removed. Then you need to compile the project with |atp-:TEX|
Note: the advantage of using subfiles package is that you
can use |atp-:SyncTexL| command for forward searching in the local
:[count]DTEX *atp-:DTEX*
map [count]<LocalLeader>d
This is equivalent to ':TEX debug'.
:MakeLatex[!] *atp-:MakeLatex*
With one command you can make your whole document: cross references,
bibliography (with or without bibtex), index, table of contents, table
of figures, table of theorems ([ntheorem package]), table of
With bang it saves (using the |update| command) all loaded project
If aux or log files are loaded in a buffer then they will be deleted
- this is a requirement of vimgrep internal grep command (other wise
vimgrep will search in the buffer not the hard disk version and they
may differ).
Returns with an error message if log contains '! Emergency stop.'
If |g:atp_Compiler| = 'python' it uses the python script to compile
document, if |g:atp_Compiler| = 'bash' it uses a bash command (UNIX
:Bibtex[!] [debug_mode] *atp-:Bibtex*
map <LocalLeader>b
With BANG "!":
This function will call bibtex to produce the bibliography file
(.bbl). If in |b:atp_OutDir| there is no 'aux' file it first calls tex
compiler. After the 'bbl' file is produced two consecutive runs of tex
compiler are called to make the bibliography.
If you specify any value to the [debug_mode] option (for the values
see |atp-:TEX|) In verbose mode (only the last time tex compiler will
run in errorstop mode and echoed to the console). This gives you the
chance to see the output of bibtex command (it will be also printed
when latex ends).
If bibtex returns with non zero exit code, latex will not be run
Without BANG "!"
If you want to just run bibtex use :Bibtex without
The command |atp-:Bibtex| will :call Bibtex(), while :Bibtex v
(and :Bibtex [debug_mode]) will :call Bibtex(1)
The bang "!" is used in the same way as for |atp-:TEX| command.
For the description of optional argument [debug_mode] see |atp-:TEX|.
Tex is looking for the date base files in the path: `kpsewhich -show-path
bib`. The variable g:atp_bibinputs contains these directories separated by
commas. If atp cannot find your bib file, tex also won't be able.
Similarly this variable stores all of path reported by `kpsewhich
-show-path tex`.
This is a list of directories as g:atp_raw_bibinputs with appended '**'
see ':h file-searching'.
This is a list of directories as g:atp_raw_texinputs with appended '**'
see ':h file-searching'.
Note: The above four variables might be added to
|g:atp_ProjectGlobalVariables|. ATP will start faster, but remember to
unlet them and restart vim when you change your TeX distribution, so that
ATP will rebuild them.
Kill python scripts running (b:atp_PythonPIDs) and all pids in
|b:atp_LatexPIDs|. This only works with |g:atp_Compiler|="python".
:PID *atp-:PID*
Prints PIDs of all running instances of |b:atp_TexCompiler|.
:Compiler {compiler-program} *atp-:Compiler*
Command which help to set |b:atp_TexCompiler| variable (with
This is a command which sets the |b:atp_OutDir| variable and the
|'errorfile'| option. See |b:atp_OutDir| for the default value.
Compile with latexmk in background.
With bang "!": Force compilation with latexmk in background.
See |g:LatexBox_latexmk_options|.
Clean temporary output from LaTeX.
With bang "!": Clean temporary output from LaTeX.
Stop latexmk if it is running.
Show the running status of latexmk for the current buffer.
With bang "!": show the running status of latexmk for all buffers with
process group ID's.
:ShowErrors[!] [flag] *atp-:ShowErrors*
nmap <LocalLeader>e /for other maps see |atp-:ShowErrors-maps|/
This command shows error/warning messages. It sets the |'errorformat'|
variable accordingly to the optional [flag] argument (if bang is used
the change is permanent, if not |errorformat| will be restored at the
end), which is a word made of letters:
e - include errors
w - include all warning messages
(with g:atp_ParseLog, font warning messages are excluded)
r - include all reference warnings
c - include all citations warnings
f - include all font warnings
fi - include font info massages
F - show files listed in the log
(messages which start with 'File: ')
shows the files loaded by tex
for example fd files that LaTeX is using
p - show package info messages (g:atp_ParseLog only)
P - show packages loaded by tex
(messages which start with 'Package: ')
h - show 'Overfull \hbox' and 'Underfull \hbox' messages (g:atp_ParseLog only)
o - open the log file in a new buffer (split).
all - all excluding f,fi,F,p,P
All - with g:atp_ParseLog: show all the above,
with !g:atp_ParseLog: show whole log file.
If none flag is given |g:atp_DefaultErrorFormat| value is used. If
'o' flag is used the split buffer with log message has a map 'q' to
':bd'. Example: >
:ShowErrors rc
< will show all reference and citation warnings.
Note: this command works in quickfix window. It will change
errorformat but will not reload quickfix list. Use |atp-:ErrorFormat|
This works like |:cgetfile| command, but also filters errors from
quick fix list which are not recognised by |errorformat| (it is done
by |atp-:ShowErrors|). This is only useful with |g:atp_ParseLog|=1 and
when vim is not compiled with the patch 468, see |has-patch|
(otherwise the command is not provided). If you use cmdalias plugin
(vimscript 746) you can alias this command to cg (|:cg|) in |atprc|
g:atp_ParseLog = 1
If |g:atp_ParseLog| is 1 (|g:atp_Compiler|="python"), then ATP will
parse the log file. So that |quickfix| will show you corrent file
names for the errors. This is particullary usefull for project
files. The new log file is written with an extension '_log'.
g:atp_DefaultErrorFormat = 'erc'
The value is the same as argument to |atp-:ShowErrors| and
|atp-:ErrorFormat|. This is the default argument for these commands when
they are used without any argument. Also corresponding 'errorformat' is
set up at startup.
b:atp_ErrorFormat = 'ecw'
This variable stores the current format of errors. It is a word with
letters given in [flag] argument to |atp-:ShowErrors|. You can set it
with |atp-:ErrorFormat| command. It is used by serveral ATP functions,
for example call back feature checks if there are errors looking into
Quick Fix list (with |getqflist()|), which will depend on the variable
ShowErrors maps: *atp-:ShowErrors-maps*
<LocalLeader>e view errors with current |b:atp_ErrorFormat| (:ShowErrors)
<F6>+e to see all errors (:ShowErrors e)
<F6>+w to see all warnings (:ShowErrors w)
<F6>+r to see warnings coming (:ShowErrors rc)
from references or citations
<F6>+f to see font warnings (:ShowErrors f)
This is not a texloganalyzer mapping but it is a good place to mention it:
<F6>+l to open log file in a new split window
this is a mapping to the |atp-:OpenLog|.
:ErrorFormat {flag} *atp-:ErrorFormat*
This command has the same syntax as |atp-:ShowErrors|. It sets the
|b:atp_ErrorFormat| variable and vim option |'erroformat'|, and the
rereads the log file with |cgetfile|. If {flag} is not given it only
shows the current value of |b:atp_ErrorFormat|. The variable
|b:atp_ErrorFormat| is also set when you use the command
As an argument you may use +{flag} and -{flag} then {flag} will be
added/removed from |b:atp_ErrorFormat|, example: >
:ErrorFormat +w
:ErrorFormat +w-f
:ErrorFormat -F+e
< will add 'w' to |b:atp_ErrorFormat|.
Note: this command works in quickfix window as well.
If you change |b:atp_OutDir| variable and you want to update the
|'errorfile'| option use this command. It will show you the value to
which |'errorfile'| was set.
:ShowErrors o *atp-:OpenLog*
:OpenLog, map <F6>l, imap <F6>l
Opens log file in a new split window with two options (which are set
locally): 'ruler', 'nospell', and a map 'q' to ':bd'.
You can also use the command ':Explore' to see log, aux, ... files
(which is a part of 'netrw' Vim plugin).
In the log file there are some special tools to syncronize the tex source file
and the Viewer (currently only Xpdf is supported) with log file:
|atp-:SyncTex| and |atp-:SyncXpdfLog|) These tools can sync tex file/Xpdf
automatically using autocommand group |CursorMoved|.
:SyncTex[!] (inside log file)
:nmap <LocalLeader>f, nmap <Enter>
If you open log file with ':ShowErrors o' command then you can use
this command to move to the place in the source code where the error
occurs. It works with project files and also can go to error which
appear in a declared package. It will go to the first error line
declared in the log file below the cursor position (more precisely, to
first line which matches '^l\.\d\+\|on input line\|at lines' will be used).
With bang [!] it opens new window if the file with error is not shown
in the current tab page. Without bang it opens the file in the window
where ':ShowErrors o' was used.
If you set |g:atp_LogSync|=1 (the default value is 0) then the source
file will be syncronize with the log file via autocommand (with
|CursorMoved|). This sets 'cursorline' option to indicate the
corresponding line in the source file. When the log buffer becomes
hidden this option should be unset.
To set |g:atp_LogSync| you can use |atp-:Sync| command. |atp-:Sync|
will toggle the value, ':Sync on' will set it to 1 and ':Sync off'
will set it
to 0.
If you set g:atp_SyncXpdfLog = 1 (the default value is 0) and you use
Xpdf as a viewer it will be synchronised with the log file (with
autocommand group |CursorMoved|). You can also use the command
:SyncXpdf or :Xpdf in the log buffer which does the same.
:View[!] *atp-:View*
map <LocalLeader>v, map <F3>, imap <F3>
You would like to see what you are editing use this function. It will
use the program defined in the variable b:atp_Viewer. See |b:atp_Viewer|,
|g:atp_XpdfServer|, |atp-xpdfOptions|. When there is no output file it will run
TeX and open the file. Read more about particular viewers
(inverse/reverse searching) in |atp-viewers|.
With bang (and <F3> maps) opens viewer at the cursor position in vim
(forward search). This will only work for viewers that support forward
searching (xpdf, xdvi, okular, skim).
let |g:atp_OpenAndSyncSleepTime|="500m"
Give 500 milliseconds for the viewer to read the file, before
|atp-:View|! and |atp-:ViewL|! commands will do a forward search.
:ViewL[!] *atp-:ViewL*
map <LocalLeader>V, map <S-F3>, imap <S-F3>
With this command you can view the subfile comiled by |atp-:TEXL|
command (or with |b:atp_autex|=2). "L" comes from "local".
Bang and [i]map <S-F3> works as in |atp-:View|! command (and its <F3>
:SyncTex[!] *atp-:SyncTex* *atp-\f*
map <LocalLeader>f, map <S-LeftMouse>
Which makes an forward search (vim->Viewer). As for now ATP supports Okular,
Xpdf and Xdvi with this feature (Evince is not yet supported).
With bang |atp-:SyncTex| will not check if the viewer is running.
Note: you can also set reverse search for Okular and Xdvi, see
|atp-Viewers-Okular| and |atp-Viewers-Xdvi| for an instruction how to
do that. Xpdf doesn't support reverse searching.
Note: there is a bug in Xpdf, one cannot sent commands to Xpdf to
quickly. If the |atp-:SyncTex| command only updates the page, but
doesn't shift it then you can try to set g:atp_XpdfSleepTime variable
to something higher than the default 0.1 (this is sleep time between
sending commands to Xpdf in seconds)
When the output file or the synctex file (.synctex.gz) doesn't exists
then first it will be generated. It can also open the document if it
is not yet opened.
Read |atp-:SyncTex_with_Okular| if you use Okular.
:SyncTexL[!] *atp-:SyncTexL* *atp-\\f* *atp-\F*
map <LocalLeader>F
map <LocalLeader><LocalLeader>f
Forward search from the subfile to its output (as compiled with
|atp-:TEXL| or |b:atp_autex|=2).
With bang |atp-:SyncTexL| will not check if the viewer is running.
:Viewer {viewer-program} *atp-:Viewer*
Command which help to set b:atp_Viewer variable (with nice completion).
:SetXdvi *atp-:SetXdvi*
This command sets the options for xdvi viewer, which enables inverse
and reverse searching. You can use the command |atp-:SyncTex| for
forward searches (Vim->Xdvi) >
:SyncTex (although dvi is using srcspecials rather than synctex)
map <LocalLeader>f
nmap <S-LeftMouse>
< For inverse searching hold CTRL and press click left mouse button on
the text in xdvi viewer. It sets: >
let b:atp_TexOptions="-src-specials"
< and also other variable to enable reverse searching (Xdvi->Vim) see
more |atp-viewers-Xdvi|.
This command sets |g:atp_xdviOptions| variable, but do not overrides
your settings if you defined '-editor' and '-watchfile' switches (it
defines only these two, watch file makes xdvi reload the file every
given interval)
:SetXpdf *atp-:SetXpdf*
:SetOkular *atp-SetOkular*
This command sets options for Xpdf viewer. Xpdf supports forward
searching (vim->Xpdf) with command: |atp-:SyncTex|. It sets >
let b:atp_TexOptions="-synctex=1"
< Thus it enables the forward searching (the above is the default
value for ATP, but it will change when you use |atp-:SetXdvi| which
uses "-src-specials".
It reads the Xpdf viewer options from the variables
|b:atp_xpdfOptions| and g:atp_xpdfOptions. Similarly for Okular.
nmap <F6>g
Runs external program pdffonts on pdf output file.
:BibSearch /{pattern}/ [flag] see |atp-:BibSearch|
This function finds bib entries in bib files defined in your tex file
and in the variable |b:atp_BibFiles|, which match the
[pattern] (a Vim regular expression). The output is configurable by
the [flag] argument, see |atp-bibflags|. By default the pattern is
case insensitive.
:AMSRef[!] {bibdata}
A command to get bib data from AMSRef:
The bib data will be appended to bibliography of the current document. If
there are many bib files will get a choice which one to use. This command
is also available in bib files. Without bang, i.e. "!", it writes and
closes the bib buffer with it will leave you in unsaved bib file buffer.
You will be also asked for the bib key, the default choice is to use the
AMS bib key.
This command also works when you use \begin{bibliography} environment. But
the default is to use a bib file. The obtained bibliographic reference is
copied to the register |g:atp_bibrefRegister| (the default is "0" so you can
paste it using Vim command 'p'). In addition, it is stored in the variable
:BibYank see |atp-:BibYank|, |atp-:BibPaste|
map [count]c, [count]y,
map [count]p, [count]P
This commands are defined in the buffer with results of
|atp-:BibSearch| command. It is mapped to '[count]y', '[count]c',
'[count]p' and '[count]P' and let you copy the bib entry key to
a register (see |atp-:BibYank|) or directly to the last opened buffer.
:FindBibFiles *atp-:FindBibFiles*
This updates the variables s:bibfiles, s:allbibfiles,
s:notreadablebibfiles. Finds all bib files defined in all
'\bibliography' commands. For more about the above variables read
|atp-variables-bib|. The command |atp-:FindBibFiles| finds bib
files in the current buffer.
If a readable bib file was not found under one of path listed in of
g:atp_bibinputs variable (see |g:atp_bibinputs|) it is classified
as not readable.
:GotoFile[!] *atp-:GotoFile*
:Edit[!] *atp-:Edit* *atp-gf*
nmap gf
This command finds input files under b:atp_MainFile (it is recursive).
The nmap 'gf' checks first if there is a file under the cursor. If
there is no file under the cursor it list all input files. Input file
is one introduced in the source file with \input{<file>}, \input
<file> \include{<file>}. The current file is now shown with highlight
group: |hl-WarningMsg|.
This command uses kpsewhich to find in which path to find input files.
Actually the path variables: |g:atp_texinputs| for input files and
|g:atp_bibinputs| for bib files are used.
The bibliographic declared are also listed. The command searches for
them in any directory listed in g:atp_bibinputs (see
If |g:atp_developer| = 1 (default 0) then the map 'gf' can also open
package files and document class files, but only when using 'gf' over
\usepackage, \documentclass, and \RequirePackage commands.
With bang "!" this command regenerates tree of files (this is
important only in files with input lines), without it uses cached
values (if they exist).
The current file is now shown with highlight group: |hl-WarningMsg|.
:KpsewhichEdit {file} *atp-:KpsewhichEdit*
Find {file} using kpsewhich and edit it. For example >
:KpsewhichEdit amsmath.sty
map <F1>, imap <F1>
Then you have to type what you are looking for and press enter. The
option 'keywordprg' is set to 'texdoc -m', i.e when your cursor is
over a package name and you press 'K' key then you should see the
package document file (if it is named after the package).
Without any argument it will open "g:atp_TeXdocDefault", by default it
is equal to "-a lshort", i.e. "The not so short introduction to LaTeX
2e" by Tobias Oetiker. You can change the default for something that
you use more often, for example you can set it to "-a faq", i.e. 'The
UK TeX FAQ' (or even to "-a lshort faq" if you want them both :).
:Texdef[!] {args}
This command is an interface to the texdef program. Use ':Texdef --help'
to see the help message. |atp-:Texdef| command automatically sets the
--tex switch (using |filetype|). If run with bang [!] a comma
separeted list of packages of the current tex file will be appended to
the texdef command (using --package switch).
Note: this command is defined only if |g:atp_developer| is set to 1 on
startup. See |g:atp_developer| for details.
List input files of the current project. It also updates the
|b:ListOfFiles| and |b:TreeOfFiles| variables to the current values.
The variable *g:atp_inputfile_pattern* is used as a pattern to find
input files. If you use 'biblatex' you do not need to put any pattern
matching bibliographies (\addbibresource, \bibliography, ...), ATP has
special way of dealing with them which is faster. If you use 'subfile'
package ATP will add \\subfile pattern.
:Open[!] [pattern]
If you configure g:atp_LibraryPath, this function will find files
matching [pattern] under g:atp_LibraryPath and let them open with
a program defined in >
< The g:atp_LibraryPath is a comma-separated list of directory names.
You should use wild cards '**' and '*' as in |globpath()|, if you want
to include subdirectories, etc. For example >
let g:atp_LibraryPath=$HOME."/**"
< will search for files under your $HOME directory. The default value of
g:atp_OpenTypeDict is: >
let g:atp_OpenTypeDict = {
\ "pdf" : "xpdf", "ps" : "evince",
\ "djvu" : "djview", "txt" : "split" ,
\ "tex" : "edit", "dvi" : "xdvi -s 5" }
< The values of g:atp_OpenTypeDict should be a program to open the file,
or one of 'tabe', 'split', 'edit', (if 'vim' is specified, then 'tabe'
will be used). The cat program is also supported.
Found files (all not just matching ones) are stored in the variable
g:atp_Library. It is set by |globpath()| on g:atp_LibraryPath and then
filtered, only files which extensions are given in g:atp_OpenTypeDict
will be stored. This variable is restored by the global project script.
You can use {bang} "!" to regenerate the library if it has changed.
This is particularly useful as by default ATP remembers g:atp_Library in
the common project script (see |atp-ProjectScript|).
:Dictionary {word}
map =d
This is an interface to Type a [word]
and you will get quotes from mathematical articles or books written by
native speakers of English. The command has a completion for words
List of words is hard coded in ATP (it is too slow to get it), since the
dictionary evolves it might contain new entries (note: if this is the
case, please inform me).
The map takes the |<cword>| under the cursor as an argument.
:Delete[!] *atp-:Delete*
map <F6>d
Deletes all files which extension belongs to g:atp_tex_extensions in
the directory |b:atp_OutDir|. By default |g:atp_tex_extensions| does
not contain 'tex', 'pdf', 'dvi' so none of your important files will
be deleted. When the command is used without bang the extensions
from |g:atp_DeleteWithBang| are removed from |g:atp_tex_extensions|.
The default value of |g:atp_DeleteWithBang| contains for example
'synctex.gz' extensions, thus it won't be removed by :Delete (without
bang "!").
If you set |g:atp_delete_output|=1 the function will delete also the
current output file (but not any other!) and 'synctex.gz' file.
g:atp_DeleteWithBang = ['synctex.gz', 'tex.project.vim']
< This is list of extensions which will not be removed when
|atp-:Delete| is run without bang. You do not need to add "pdf" or
"dvi", extensions.
:SshPrint [lpr_options]
It will run 'lpr' command and append to it the options defined in the
variable 'g:printeroptions' + options given in the second argument. It
prints the pdf or dvi depending on the value of |b:atp_TexCompiler|.
If you specify the variable 'g:atp_ssh=<user>@<host>' it will print
via ssh on the <host> using the [lpr_options] passed to the lpr
command. The command ':SshPrint' has a completion set for the printers
available on your local system or in the host. You do not have to
escape white spaces.
The command has completion for the names of printers (also remote
printers) and also other lpr options and its values, press <Tab> to
cycle through printers, or type first letters of the printers name and
press <Tab> to complete it.
:Lpr [lpr_options]
It prints using the lpr command on a local printer. The syntax and
completion are the same as for |atp-:SshPrint|.
Sends "lpstat -l" remotely (using the |g:atp_ssh| value) or locally and
echoes the output.
List printers available on the host |g:atp_ssh|.
:Wrap [beginWrapper] [endWrapper] [cursor_pos] [new_lines]
Puts selected text between [beginWrapper] and [endWrapper]. Also sets
the cursor position according to the [cursor_pos]. Possible values
are: a number -- indicates the character offset from beginning of
[beginWrapper]; or 'end' put the cursor at the end of [endWrapper] or
'begin' leave the cursor at the beginning (to be precise at the end of
the starting wrapper). The default [beginWrapper] is '{' and
[endWrapper] is '}'. The last argument [new_lines] has two values 0/1
(default is 0): if 1 then the [beginWrapper] and [endWrapper] are put
in separate lines (the begin line and end line are split), this is
useful for putting text into an environment \begin{}:\end{}.
See |<f-args>| to know how to pass arguments. (They are separated with
spaces, white spaces in arguments should be escaped with backslash
For the predefined maps which use WrapSelection see below
|atp-maps-WrapSelection| or use |atp-:HelpVMaps|.
nmap <LocalLeader>u
If cursor is standing over a bracket it will remove both matching
brackets together with \left:\right, \bigl:\bigr, ... sizes. This
works for: (:), {:}, [:], \{:\}, \[:\] and \(:\).
:IWrap {mathWrapperPair}, {textWrapperPair}, [cursor_pos], [new_lines]
Puts the selected text inside {mathWrapperPair} if the cursor stands
in mathematics otherwise inside {textWrapperPair}. {mathWrapperPair}
{textWrapperPair} are Vim lists of length at least 1, the first
wrapper is the opening and the second is the closing one (if not given
the default '}' is used. The other arguments are as for
|atp-:Wrap|. If the opening leader in is not given then this
command is not wrapping the text (see below for the suggested map
The command arguments should be separated with commas and quoted
separately (see |<args>|).
For the predefined maps which use |atp-:Wrap| see below
|atp-maps-InteligentWrapSelection| or use |atp-:HelpVMaps|.
See section |atp-vmap-WrapSelection| on predefined set of vmaps.
You can also use a wrapper which was yanked into register 'a': >
:Wrap @a
< This will work not only in visual mode. It will operate on last
selected text. So if you accidentally lost the selection you can still
use this command (but not the maps)!
map <LocalLeader>a
This is a wrapper around Align command of the great AutoAlign Vim plugin:
This command sets correct align options and aligns the environment.
The following LaTeX environments are supported: >
equation, align, alignat, flalign, displaymath and tabular
< Equation, align, alignat, flalign and displaymath are checked using
syntax, tabular environment is checked using searchpair() function,
the |g:atp_completion_limits|[2] applies.
The command :Align (and thus also :TexAlign) are using ATP_strlen
function to measure the string length. ATP sets
g:Align_xstrlen="ATP_strlen" if 'conceallevel' option is >0. If
'conceallevel' is reset to 0 ATP_strlen behaves like
With bang "!", |atp-:TexAlign| will join lines which do not ends with
'\\'. If *g:atp_TexAlign_join_lines* =1 then the map <LocalLeader>a
will use the bang.
Make a tag file with a python script included in ATP. It also scans aux
file for associated numbers to labels which then are used as tags. If you
declare hyperref package in the preambule also \hyperref{}{} commands are
matched for tags as well.
|atp-:Tags| command will be defined only if you do not define it yourself.
Natbib as well as biblatex commands are supported (with exception of
\cites, ... biblatex commands).
With bang the bibtags for \cite commands are not made. If you use more
than one bibliography file searching to which of them it belongs might
take some time. If this is the case and you do not want this kind of tags
you can make the tag file faster.
Note: you might need to adjust 'iskeyword' Vim option. ATP is adding
|g:atp_separator| to 'iskeyword' if |g:atp_no_separator| is 0.
Note!:In Vim 'iskeyword' by default contains '_'. It is disabled by the
standard tex syntax file (you do not want to include _ from _{} LaTeX
construct into 'w' motion). So it is better to avoid it in label names, so
that |CTRL-]| works well. If you need to add it use:
au FileType set iskeyword+=_
(this will not work with setlocal).
Note: the python script is sourced in the background. When the script
finishes it will let you know. The tag file is not accessible until the
script finishes.
Check out |tag-and-searches| how to use tags.
:LatexTags command is only defined if there was :Tags command defined.
:TOC[!] *atp-:TOC*
nmap <LocalLeader>t
Shows Table of Contents of your document. It do not yet support the
starred version of chapter, section,... .
The optional argument bang controls if the table of contents data base
must be generated: by default map <LocalLeader>t doesn't regenerate
the toc data base (unless if it doesn't exist), :TOC command
regenerate the data base, :TOC! not.
See |atp-toc-window| for commands and maps defined in the toc window.
|atp-:TOC| supports many edited files. The variable t:atp_toc_buflist
is a list of project names (|b:atp_MainFile|) which are shown in ToC.
Use |atp-:RemoveFromToC| to remove a project from ToC.
If you have in your buffer list two files a.tex and b.tex this command
will produce table of contents of both of them. If you have just one
opened window (excluding the ToC window) then pressing <space>,
<enter>, p and _ will take you to the right buffer (which will be read
if is unloaded or hidden). If you split a window then <space>,
<enter>, p, _ will take you to the window from which you are coming.
However, if you have two windows with two different buffers loaded
they will act on the window with the matching buffer name.
The variable t:toc_window_width sets the width of table of contents
window. By default t:toc_window_width=30. You can set a global
variable g:toc_window_width to override the default value.
:RemoveFromToC {name}
Remove the project with main file {name} from ToC. There is
a completion for {name}s.
This function returns the name of the currently edited chapter/
section/subsection/subsubsection. Use ':echo CTOC()' or just ':CTOC' to
see the returned value. If you added a section unit the function will
not update the database, run ':TOC' to do that (map <LocalLeader>t).
:Labels[!] *atp-:Labels*
map <LocalLeader>L
Shows labels defined in your file. You can also use the commands and
mappings described in |atp-toc-window|.
If you forget what are these mappings, write ':map <buffer>' in the
TOC or LABELS window, or move to the end of the LABELS window to see
a short help message.
The key 's' shows the context of the label under the cursor (your
current window splits).
The variable t:labels_window_width sets the width of labels window. By
default t:labels_window_width=30. You can set a global
variable g:labels_window_width to override the default value.
Without bang "!" the labels data base will not be generated.
Difference of \t and \L is that \L regenerates the database (which is
quite fast).
Note: in memoir class you will not see labels type (in square
:GotoLabel[!] {pattern}
The command does the obvious thing. The {pattern} matches against the
label or label value (as appears in output file). When matching the
label value '^' is added at the beginning of pattern. With bang it
doesn't regenerate the labels dictionary. It works with project files.
It has completion. If pattern matches many labels they all are listed
with some useful info: label value, label and the file where it was
defined (only in projects). Examples: >
:GotoLabel 1.2
:GotoLabel ^thm:
< Note: there is |atp-:Tags| command which makes the tag file, and you
can use vim |tags| commands.
Note: You can also use a tag file and vim |tags| commands, see
{only in Xpdf}
:GotoNamedDest <destination_name>
Using '\hypertarget{<destination_name>}{<text>}' from hyperref package
you can insert into PDF named destinations. This command will set the
position of PDF file in Xpdf to this destination. There is
a completion for destination names. This command solely works with
Xpdf. Using: >
< you can turned labels into named destinations.
*atp-:F* *atp-]]*
:[count]F {arg}
nmap [count]]]
Go (forward) to {arg}, {arg} might be: part, section, subsection,
subsubsection, defined environment name. You can use command
completion which uses all the locally defined environments.
*atp-:B* *atp-[[*
:[count]B {arg}
nmap [count][[
Go backward to {arg}, like above |atp-:F|.
*atp-[m* *atp-[M*
*atp-]m* *atp-]M*
nmap [count]]m [count]]M
nmap [count][m [count][M
Got to next/previous math environment, with the captial M go to
displayed math environment.
If g:atp_mapNn is set to one (see |atp-:ToggleNn|) then this command
is using |atp-:S|.
nmap %
Jump to the matching pair (:), {:}, [:], \begin:\end.
*atp-]e* *atp-[e*
nmap [count]]e
nmap [count][e
There are two more nice maps: ]e which is something like %]], i.e. jump
over the current environment and go to next one. The reverse <e is
also implemented, thought it is not simply [[%. They do not support
count (yet), and actually count breaks them. If you want to add |zz|,
(|zt| or |zb|) after ]e you can put this in your |atprc| file:
map <buffer> <silent> ]e <Plug>JumptoNextEnvironmentzz
map <buffer> <silent> [e <Plug>JumptoPreviousEnvironmentzz
*atp-]f* *atp-[f*
*atp-]F* *atp-[F*
nmap [count]]f [count]]F
nmap [count][f [count][F
These two maps are only valid in beamer. They goto next/previous
frame. ]F and [F are using |zt| command.
*atp-:NPart* *atp-]p*
*atp-:NChap* *atp-]c*
*atp-:NSec* *atp-]s*
*atp-:NSSec* *atp-]S*
:NPart[!], :NChap[!], :NSec[!], :NSSec[!], :NSSSec[!] [title_pattern]
[count]:F {section}
map ]p, map ]c, map ]s, map ]S
vmap ]p, vmap ]c, vmap ]s, vmap ]S
Go to next part/chapter/section/subsection/subsubsection which title
matches optionally given [title_pattern]. With bang "!" the command
doesn't skip commented sections. Maps skip them. The search will wrap
around the end of a file if 'wrapscan' is set.
The {section} argument for :F is one off:
Map Command Meaning
]p :NPart go to next part
]c :NChap go to next chapter
]s :NSec go to next section
]S :NSSec go to next subsection
You can set the leader ']' using |g:atp_map_forward_motion_leader|
Note: If you set |g:atp_forward_motion_leader| to '>' then ATP remaps
|>>| to >> and also |v_>| to >>. |>| is working and is not touched by
ATP. If you have |'timeout'| set then the map is executed faster, if
you use |'notimeout'| this workaround it makes these operators work.
Note: If you set |g:atp_forward_motion_leader|="}" then ATP remaps |}|
operator to }}
Note: the maps work in visual mode and operator pending mode ('d\ns'
will delete till the end of the section). You can use |n| and |N| Vim
normal commands (also in visual mode) to go further.
In visual mode these maps go to end of current section or, if already
at the end of section, end of next section.
[title_pattern] is the pattern which will match for the pattern, it
should start with '.*' when you want to match somewhere in a middle of
the title.
These commands (and maps) use Vim |search()| function or |atp-:S| command
depending on the value of |g:atp_mapNn| (see |atp-:ToggleNn|, when
g:atp_mapNn=1 the |atp-:S| command is used). You can set the value
of |g:atp_mapNn| using the command |atp-:ToggleNn|. If 'wrapscan' is
set and g:atp_mapNn=1 the search will wrap around the end of the
project (not the end of the current buffer).
You can unmap these keys and use <Plug>GotoNextSubSection,
<Plug>GotoNextSection, <Plug>GotoNextChapter, <Plug>GotoNextPart to
define new maps.
*atp-:PPart* *atp-[p*
*atp-:PChap* *atp-[c*
*atp-:PSec* *atp-[s*
*atp-:PSSec* *atp-[S*
:PPart[!], :PChap[!], :PSec[!], :PSSec[!], :PSSSec[!] [title_pattern]
[count]:B {section}
map [p, map [c, map [s, map [S
vmap [p, vmap [c, vmap [s, vmap [S
Go to previous part/chapter/section/subsection/subsubsection which
title matches [title_pattern] (an optional argument). With bang "!"
the command doesn't skip commented sections. Maps skip them. The
search will wrap around the beginning of a file if 'wrapscan' is set.
You can set the leader '[' using |g:atp_map_backward_motion_leader|
The {section} argument for :B is one off:
For description of arguments read |atp-:NextSection| just above.
Map Command Meaning
[p :PPart go to previous part
[c :PChap go to previous chapter
[s :PSec go to previous section
[S :PSSec go to previous subsection
These commands (and maps) use Vim |search()| function or |atp-:S|
command depending on the value of |g:atp_mapNn| (see |atp-:ToggleNn|,
when g:atp_mapNn=1 the |atp-:S| command is used). If 'wrapscan' is
set and g:atp_mapNn=1 the search will wrap around the beginning of
the project (not the beginning of the current buffer).
You can unmap these keys and use <Plug>GotoPreviousSubSection,
<Plug>GotoPreviousSection, <Plug>GotoPreviousChapter,
<Plug>GotoPreviousPart to define new maps.
Note: If you set |g:atp_backward_motion_leader| as '<' then ATP remaps
|<<| to << and also |v_<| to <<. |<| is working and is not touched by
ATP. If you have |'timeout'| set then the map is executed faster, if
you use |'notimeout'| this workaround it makes these operators work.
Note: If you set |g:atp_backward_motion_leader|="{" then ATP remaps |}|
operator to {{.
Previous commands where using relative position - goto next/previous
section/chapter. The following commands/maps will go to section/chapter as
counted from first one.
*atp-:SSec* *atp--S*
*atp-:Sec* *atp--s*
*atp-:Chap* *atp--c*
*atp-:Part* *atp--p*
nmap -S
nmap -s
nmap -c
nmap -p
Go to subsection/section/chapter/part [count] from begin of the
section/chapter/document, i.e. 3]s will jump to section 3 in current
chapter. Mark ' is preserved.
Note: if you are in a section which has no subsections :SSec and -S
will go to next section, the same applies to other section types.
You can set the leader for maps with *g:atp_goto_section_leader* .
*atp-]star* *atp-]%* *atp-gc*
nmap [count]]* [count]]% [count]gc
Go to end of current/next comment group. Do this [count] times. The
default [count] is 1.
Note: if |g:atp_VimCompatible|=1 (the default) it goes one line below
the last commented line, if it is 0 it goes to the end of the comment.
Note: This commands wraps around the begining/end of the file. The
'wrapscan' option applies.
*atp-[star* *atp-[%* *atp-gC*
nmap [* p% gC
Go to beginning of current/previous comment group
Note: if |g:atp_VimCompatible|=1 (the default) it goes one line above
the last commented line, if it is 0 it goes to the begin of the comment.
map |<LocalLeader>|s
Add/removes a star from the current environment (if it is not one
belonging to the list: >
< See |b:atp_StarEnvDefault| and |b:atp_StarMathEnvDefault|.
:InsertEnv[!] {envname}
This command inserts environment {envname} and puts the cursor at the
end of \begin{{envname}} statement. To open new line below use |o|.
If used with bang the environment is inserted in line.
map <S-F4>
mapped to <F4> and <S-F4>, switches environment name. See
(i.e. echo ) g:atp_toggle_environments_1...7 (you can change or add
your own variables, just add numbers - they must be consecutive).
Read |g:atp_toggle_labels| below how it handles the prefixes of
nmap <F4>
This does the same as the above command but asks for environment name
Read |g:atp_toggle_labels| below how it handles the prefixes of
The commands |atp-:ToggleEnv| and |atp-:ChangeEnv| changes the
prefixes of labels (if there is one, which belongs to
g:atp_shortnames_dict) and all ref's (\ref, \eqref and \pageref). You
have to turn on this feature by putting g:atp_toggle_labels=1 (by
default it is 0). If there is a label (\label{...}) to which it wants
to change it doesn't change labels and issue a Warning Message but as
this changes your file it is turned off by default. It will still
change the labels if there is a reference \(\ref{...}, \eqref{...},
etc) (with undefined label).
In project files this is done in all files belonging to the project.
Changes are not saved by default (ATP uses |'hidden'| option, so when
you use q! or qa! all changes will be lost).
This command changes label in the current line and all its occurrences
inside \ref{}, \pageref{}, \eqref{} commands.
In project files this is done in all files belonging to the project.
Changes are not saved by default (ATP uses |'hidden'| option, so when
you use q! or qa! all changes will be lost).
:WrapEnvironment {environment}
vmap <F4>
Mark part of the text and wrap it into environment given as the
argument, the map will let you choose the environment name.
:Wdiff {old-file} {new-file}
This is diff using the GNU wdiff. This command will split the view and
show the wdiff output. You can use ]s and [s to go to next previous
change. The deleted parts of {old-file} are marked embraced into
{=...=} and highlighted with |hl-DiffDelete|. The added parts of
{new-file} are embraced with {+...+} and highlighted with
|hl-DiffAdd|. If the preambles differ you will be asked which one to
use in the diff file.
This is an alternative for latexdiff program, but is much faster.
The diff file might not compile well (thus the b:atp_autex is set to
0 by default), this is mainly because the math environments can be
break and the output might contain: \( a {= =c\)=} {+ !=c\)+} Other
things which are not taken into account are changes of environment
names, changes of coordinates in tikz. It would be nice to tell to
wdiff to not diff them, but this is not implemented.
After you resolve such conflicts the file should compile nicely
(though I didn't do many tests). After that you can change {=...=} and
{+...+} for something better. For example you can change {= and =} for
\textcolor{red}{=} and {+, +} for \textcolor{blue}{+}. If you resolved
syntactic conflicts in a very nice way you can change whole {=<old>=}
for \textcolor{red}{<old>} and {+<new>+} for \textcolor{blue}{<new>}.
For this you can use the following Vim command:
(which also remaps ]s and [s and keeps the highlighted areas).
The :NiceDiff command, although I tried, is not changing all the regions,
I will try to fix this in next releases. (Thus not all parts of the output
file might be highlighted).
*atp-[d* *atp-[D*
:Dsearch[!] [/]{pattern}[/]
nmap [d, [D
The {pattern} argument is optional. It is any vim pattern. Finds all
definitions which matches the pattern. It looks in the main file (only
in the preamble, unless the optional bang '!' is used) and all the
input files (except bib files). This command respects the options:
'ignorecase' and 'smartcase'. You can override them with '\C' (match
case what follows) and '\c' (ignore case in what follows).
The maps |atp-[d| and |atp-[D| are reading the keyword under the
cursors (in the same way as |atp-gD| does), |atp-[D| uses the bang
option of |atp-:Dsearch|.
It works likes |[d|, |[D| but handles multi line definitions. The also
jump back to the current buffer, while the command leaves in the
preview buffer.
Recommendation: you can make command alias to |:ds| with cmdalias plugin
(vimscript 746) in your |atprc| file.
nmap gD
This works like |gD| (with the difference that it searches in include
files as well): it finds the first global definition of the command
under the cursor. It start from the first line of the main project
file (|b:atp_MainFile|) and goes down visiting all included files on
the way. It finds definitions of commands, environments and colors.
You can use |CTRL-O| to return.
To get the keyword under the cursor, he 'iskeyword' is set to the
value of |g:atp_iskeyword| variable. By default it will only match
[a-zA-Z] and the backslash. At the end your 'iksyeword' setting will
be restored.
Note: to find environment the cursor have to be over the environment
name rather than the '\begin' command. If you want to go to the
reference definition (\label) use |CTRL-]|, see |atp-:Tags|.
Only available if vim is compiled with |+python| interface.
*g:atp_DsearchMaxWindowHeight* = 15
You can set the maximal height of the window which shows the results of
|atp-:Dsearch| (default is 15).
:FontSearch[!] [pattern]
For example:
:FontSearch ^t1
will list all the fd files in your tex distribution which
names starts with t1 (i.e. which describes fonts in encoding
:FontSearch! bookman
will list all fd files which full path matches 'bookman'.
In the opened window there are several mappings defined:
<Enter> open the fd file under the cursor
<Tab> list fonts defined in the fd file (shows the command
that you can use in your tex file to use this font)
p preview the fonts defined in the fd file under the
cursor, do not shows the latex source.
P preview fonts and show the latex source
(then you can see the errors why the preview was not
produced; in many cases there are no encoding files or
fonts themselves for which you have to look in CTAN
archive yourself; or YOU CAN just SEE HOW TO USE
FONTS :) )
q close the window (actually, delete the buffer using
:bd, it will be still in the list if you type ":ls!",
so even then you can reload previous searches.)
In addition to 'p' and 'P' maps there is a :Preview command.
Note: the maps 'p' and 'P' work in both normal and visual mode.
You can select a part of the text and use this maps or the command
:Preview to make one preview file for all the font files.
The same mappings are defined in the window with fd file opened
(except <Enter>, <Tab>).
Additionally, read |font-lowlevelcommands| to learn how to use
|\usefont|, |\fontsize|, |\selectfont| and other such commands.
The 'Latex 2e font selection' by 'LeTeX3 Project Team' might be very
useful. It is available on the net (you probably have it in your tex
distribution if it is installed with the documentation, if not check
the CTAN archive).
ATP also has a very nice completion for various font declaration
commands, see |atp-completion-fontdeclaration|.
Hopefully, this will help your documents to become beautiful :)
:FontPreview[!] {fdFile} [encoding] [keep_tex]
Previews all fonts defined in fd file matching the pattern <fd_file>
with encoding [encoding] (optional). If [keep_tex] is 1 (default is 0)
it will keep the latex source file for debugging purposes.
Without [!] it matches just the name of the fd files, with [!] the
pattern {fdFile} matches for full path.
It returns a list of fonts which fd files matches the {fdFile} pattern in
[encoding]. You will be asked to chose for which files make a preview,
possible answers are: >
< which is equivalent to >
< you can also mix this notation: >
< As in FontSearch command the [keep_tex] variable specifies if
the source file will be shown (for debugging purposes, or just to look how
to use the font :).
:Status[!] *atp-:Status*
(:ATPStatus[!]) *atp-:ATPStatus*
This command sets the status line, which include: the name of currently
edited chapter (or section) the value of |b:atp_OutDir| (unless used
with bang "!") and it will warn you if |b:atp_OutDir| variable is not
set. Note: this command will set the variable |g:atp_statusOutDir|.
The status line will also contain the information about processing
compilation: see |atp-status-line-notification|, |g:atp_ProgressBar|.
This function is called at startup unless the variable
'|g:atp_statusline|=0' is set. The status is set by the autocommand: >
au BufWinEnter,BufWinEnter,TabEnter *.tex :call ATPStatus(0,b:atp_StatusCurSection)
< In this way every opened window with a '*.tex' file will get the correct
status line.
If |g:atp_StatusCurSection| is set to 1 (the default) the current section will be
put in the status line. Some times it is slow though.
The command respects the |'ruler'| vim option.
If there was a command with name 'Status', atp is not overwriting it,
it uses ATPStatus name.
Note: if you set g:atp_statusOutDir=0 (the default is 1) then the
output directory will be not seen in the statusline. This variable
only controls the status line at startup. If you want to remove/add
output directory rather use |atp-:Status| command.
ToDo({keyword}, {stop}, [bufname]) *atp-function-ToDo*
:ToDo[!] [bufname] *atp-:ToDo*
:Note[!] [bufname] *atp-:Note*
The function list all the lines of the buffer [bufname] which match
for the pattern '^\s*%.*{keyword}'. The {stop} argument is the pattern to
before which to stop. The optional argument is the buffer name
(the buffer name completion is set on). If not given the current
buffer is assumed. You can set highlighting for this command by:
highlight atp-Todo ctermfg=... guifg=...
The command :ToDo sets keyword='^\s*%\s*$\|^\s*%\c.*\<note\>' and
stop='^\s*%.*\c\<note\>', and the command :Note sets
keyword='\c\<note\>' and stop='^\s*%\s*$\|^\s*%\c.*\<to\s*do\>'. This
prevent from listing ToDo lines with Notes and vice versa and stops at
lines which contains only '%'. With bang "!" the '^\s*' is not
prepended to the patterns.
The command to compute the number of words. With bang [!] it will show
the word count of each input file. It uses 'detex' program (which is
present in 'texlive') to remove the latex markups prior to word
counting (done by the external 'wc' program). Note: This command will
first save the file.
If [range] is not given (or is the current line) it counts words in
whole file, otherwise counts words in the given range.
If |g:atp_babel| variable is set on start up to 1 (however, the default
value is 0, you can use |vimrc| or |atprc| file to switch it on) then
ATP will set the |'keymap'| option according to the default babel
language (which is the last language passed to babel as optional
argument [lang_list] in \usepackage[lang_list]{babel}).
If |g:atp_babel| is set to 1 the keymap name is shown in the status
line (if you use the |atp-status-line|.
The |g:atp_kemaps| variable is used to translate babel language name
to 'keymap' value. The default is something like: >
let g:atp_keymaps = {
\ 'british' : 'ignore', 'english' : 'ignore',
\ 'USenglish' : 'ignore', 'UKenglish' : 'ignore',
\ 'american' : 'ignore',
\ 'bulgarian' : 'bulgarian-bds', 'croatian' : 'croatian',
\ 'czech' : 'czech', 'greek' : 'greek',
\ 'plutonikogreek': 'greek', 'hebrew' : 'hebrew',
\ 'russian' : 'russian-jcuken', 'serbian' : 'serbian',
\ 'slovak' : 'slovak', 'ukrainian' : 'ukrainian-jcuken',
\ 'polish' : 'polish-slash' }
< When the value is <ignore> then the function <SID>Babel() (or the
command |atp-:Babel|) will ignore setting keymap option for this
language. Using the above syntax you can set this variable in |vimrc|
or |atprc| file.
This is useful if you in day to day work use one language, but some
times you write a tex file in some other language.
:ShowOptions[!] [pattern]
This will show values of variables that are currently set.
With bang it also shows global variables defined in
'ftplugin/ATP_files/options.vim' (that means almost all global
variables). Completion lists are filtered out by default.
The optional argument [pattern] is used to filter variables names with
the given pattern.
TIP: if you are looking for a variable you can use this command to
find it.
These commands list valid mappings defined by ATP (unless g:no_plugin_maps or
g:no_atp_maps are defined).
:Map[!] {pattern} *atp-:Map*
:Nmap[!] {pattern} *atp-:Nmap*
:Imap[!] {pattern} *atp-:Imap*
:Smap[!] {pattern} *atp-:Smap*
:Vmap[!] {pattern} *atp-:Vmap*
:Omap[!] {pattern} *atp-:Omap*
:Lmap[!] {pattern} *atp-:Lmap*
The {pattern} is matched against the right hand side of a map as shown
by the corresponding |:map| command. If |<bang>| is added the pattern
is matched against output of [nisvol]map commands with only first
column removed (which indicates the map mode).
The Imap can also find imaps which are not defined in normal mode
(there are such maps in ATP), and thus are invisible while looking at
the output of |:imap| command).
:ShowPackages lists LaTeX packages defined in the preamble.
:Preamble echoes the preamble to vim pager.
Reloads ATP plugin: variables, functions, and maps. Note that maps are not
Compilation ~
*atp-g:vim_program* Default: autodetected
Vim program to use on command line for callbacks.
If autodetect fails, defaults to >
'/Applications/ -g'
< on MacVim, or to |v:progname| on other systems.
*atp-g:LatexBox_latexmk_options* Default: ""
Additional options to pass to latexmk during compilation, e.g, "-d".
*atp-g:LatexBox_output_type* Default: "pdf"
Extension of the output file. One of "pdf", "dvi" or "ps".
*atp-g:LatexBox_autojump* Default: 0
Automatically jump to first error after calling latexmk.
For the table of contents command and maps read |atp-:TOC|.
The Table of Contents window is used by both |atp-:TOC| and |atp-:Labels|
In the Table of Contents window there are the following nmaps:
'e' to echo the line from your tex file
'y' or 'c' to yank the label of the chapter under the cursor
to a register, if it exists,
'p' to paste it directly to your tex file (just after the
current cursor position),
'[N]s' it splits the window with your tex source file and
sets the current line to the beginning of the
chapter/section or label under the cursor.
If [N] fiven the new window will be that heigh
(like with |:split| command). In ToC window |zt| is
also used.
'q' to quit,
<Enter> to go to the section under the cursor and close ToC.
<space>, <LeftMouse> to go to the section under the cursor but
leave ToC open.
'_' to go to the section under the cursor and return to
ToC afterwards.
'zc' to fold section/chapter/... . You can mark several
lines in visual mode and use 'zc' to fold them at
Limitation: ~
It cannot fold subsections in a right way when the
section is folded. In particular, this applies when
folding several sections with subsections in visual
There are also commands: ':C' and ':P', which do the same as 'c' and
'p' mappings. They all call the function 'Yank(<where>)', the argument
<where> can be one of: '@<register name>' or 'p'.
You can also delete and paste sections using the Table of Contents
These commands are available in table of contents. They act on
:YankSection [register]
< Yank the section under the cursor (in table of contents) to the given
register. If the register is not specified use the unnamed register
The other commands do not use registers but an internal stack.
< Using ':DeleteSection' you can delete the section under cursor together
with all its subsections. /Section can be one of: part, chapter,
section, subsection, subsubsection, or bibliography/. Deleted section
will be added to a stack which can be shown using the command
':SectionStack' There is a command to paste the section from section
stack ':PasteSection'. By default it pastes the most recent element in
the stack. Passing a number will paste that element of the stack
/bear in mind that then numbers of sections in the stack will change/.
':PasteSection' puts the section just after where current section
ends (section under the cursor in the ToC buffer). With bang "!" it
puts before.
Note: If you use bibtex commands to make bibliography ATP finds the
line which contains '\bibliography' command. And then searches
backward for the first line which is a blank line. The next line is
assumed to be the first line of bibliography. Thus to move the last
section before bibliography or the bibliography itself its better you
put a blank line before bibliography commands. The same applies for
bibliographies put in the middle of document (end of a chapter, part,
etc.) The end of bibliography is found in the same way as the end of
subsubsection. If you use
\begin{thebibliography}:\end{thebibliography} there is no such
a problem.
If you want to paste a section before the first section, use the line
with the file name.
nnoremap u, nnoremap U, nnoremap g-, nnoremap g+
< You can use undo. The :Undo command will undo in the buffer under
the cursor (it switches to the correct window, using the Vim undo
function, and runs :TOC command - so after all your back in ToC.). The
':Undo' command has one argument - the Vim undo command to use, it is
one of: 'u/U/g-/g+' (the default is 'u'). They are mapped to 'u','U',
'g-' and 'g+'. (only in the ToC buffer). Note: ':Undo' command
doesn't changes the Section Stack.
There is one more level of security: There is a global variable which
stores all the deleted sections together with some information about
them: >
< it is a Vim list (see |List|). Each entry is a list of the following format: >
[ <title>, <type>, <deleted_section>, <section_nr>, <file> ]
< where <title> is the section title, <type> is one of: part, chapter,
section, subsection, subsubsection bibliography or abstract. Deleted
section is a list of deleted lines, <section_nr> is the number of the
section that it had before delete, <file> is the full path to the
file which it comes from. If you need to use it, you can use the Vim
function |append()| to put the <deleted_section> in the right place.
You may want to have a map: >
:au FileType toc_atp nnoremap dd :DeleteSection<CR>
< this can be put in your '$HOME/.atp.vim' configuration file.
:Fold, :'<,'>Fold
< Fold section[s], works in the same way as 'zc' (as above) with the same
FOLDING *atp-folding*
I found a nice folding file (written by Johannes Zellner, added with his
permission) there are two options:
g:atp_folding = 0 *g:atp_folding*
enables/disables folding. you should set in your |vimrc| or |atprc|
files. if you reset the value on the fly you need to issue
'|:filetype| detect' command in order for changes to take place.
g:atp_fold_environments = 0 *g:atp_fold_environments*
enables/disables folding of environments. By default folding is
disabled since it slows down vim.
SEARCHING IN BIB FILES *atp-bibsearch*
Table of Contents: ~
Naming Conventions: ~
@article{<label>, \
author = { .... }, <-- bib entry |
title = { .... }, > bib field
journal= " .... ", |
} /
article <-- bib field keyword
author,title,... <-- bib entry label
<label> <-- bib field label
One more function is provided which searches the bib files for bib fields,
and for the bib field labels for the latex command \cite{}.
:BibSearch /{pattern}/ [flag] *atp-:BibSearch*
which do what you expect. The arguments should not be quoted and
separated by a white spaces (if you want to include a white space use
'\ '), for more see |f-args|. If you do not provide any argument then
all entries of all bib files will be shown.
Note: {pattern} should be a PYTHON regular expression not vim regular
expression (they are similar to very magic vim expressions, see |\v|).
Unless you set |g:atp_bibsearch|="vim" (the default is "python").
Python regular expressions are quite similar to vim with 'nomagic' set
( grouping with '(' and ')', with separating alternatives with '|').
But there is no vim '\&' in python regexp.
The pattern to highlight matching string is passed to |@/| hence you can
use |n| and |N| in the BibSearch buffer. This will only work for
{pattern} which is both vim and python regular expression.
See |atp-bibflags| for the [flag] argument.
Note: Upper pattern is vim pattern lower one is python regexp.
Before the match all the ligature symbols and {:} are removed. For
example \`a, \' e, \oa,\ea are substituted with a, e, oa, ea
(respectively). Note that the space in \' e is also removed. Each
line (without ligatures) of every bib file found in your tex document
will be matched against the pattern, for example if the pattern is:
the BibSearch function will find all the bibliographic fields
which in one line have the words 'author' and 'Grothendieck' (in most
cases it means that you will see only works of Grothendieck). Another
'^\(\s*author.*Joayl\)\|Galois Theory'
'^(\s*author.*Joayl)|Galois Theory'
will result in all bib fields which author is Joyal or
which includes the words 'Galois Theory' (which by the way appear in
many article/book titles), yet another example:
'author.*Joayl\|title.*Galois Theory'
'author.*Joayl|title.*Galois Theory'
This will match against all bib entries written by Joyal or which title
includes the word 'Galois Theory'.
! python has no '\&' !
will find all the bib entries which were written by Joyal and Tirney
(and maybe somebody else).
For now, there is no possibility to filter bibliographic entries which
both match a pattern in separate lines, i.g. to show all bib entries
written by Joyal on 'Descent Theory'.
Before a match, all '{', and '}' are deleted from the line of the bib file.
But you will see them in the output (what can be useful for debugging
errors in bib files)
Note that in Vim patterns should be quoted using '...' not "...".
Further examples are supplied after the next section
|atp-bibflags:examples|, which describes other functionalities of the
BibSearch/BibChoose commands.
The variable 'b:atp_LastBibPattern' stores the last pattern used by
bib search.
The optional argument [flags] chooses what and in which order you want
to see the bib entries found (entries are listed in the order they
appear in bib file). Flag is a word made of letters. There are three
kinds of flags: entry flags which matches against labels of bib
entries, like author, title, etc..., and keyword flags: which matches
against keywords of bib fields: @article, @book, @techreport, etc...
and two special flags 'All' and 'L'. A flag is a word on letters:
a - author
e - editor
t - title
b - booktitle
j - journal
s - series
y - year
n - number
v - volume
p - pages
P - Publisher
N - Note
S - School
h - howpublished
o - organization
u - url
H - Homepage
any other letter - do not show anything but the first line of bib entry
@a - article /@article/
@b - book or booklet /@book,@booklet/
@B - Booklet /@booklet/
@c - incollection /@incollection,@inbook/
@p - proceedings, inproceedings, conference /@proceedings,@inproceedings,@conference/
@m - misc /@misc/
@M - Manual /@manual/
@t - master or PhD thesis /@masterthesis,@phdthesis/
@T - Techreport /@techreport/
@u - unpublished /@unpublished/
All - all flags (see |atp-bibflags:all|)
L - last flags (see |atp-bibflags:last|)
tayu@a --> show the entries: tile, author, year, url of matching articles.
baeP@b --> show the entries: booktitle, author, editor,
publisher of matching books (@book,@booklet).
Flags '@.' are filtered out, if one does not belong to the one above
then it is deleted. You can see which flags are defined using
ShowOptions function/command (they are listed as Available
The default flag is stored in the global variable g:defaultbibflags and is
equal to 'tabejsyu'. This means that the output for each bib field found
will include the
if title,author,... are specified in the bibliography for the given
position. If there are many position which match you can set flags to
be as simple as possible to include more lines on the screen. For
example 'tabe' is quite reasonable (note that all bib entries are
matched separately, i.e. if a bib field has both 'title' and 'booktitle'
bib entries it will give you both of them.
If you just want to list just the lines with bib fields keywords:
@article{, @book{, etc. supply a flag which do not belongs to
'g:defaultallbibflags', for example 'X', or 'X@a'
You can also specify flags with '+', for example:
This feature ADDS FLAGS TO THE DEFAULT VALUE defined in the variable
g:defaultbibflags (see |atp-defaulbibflags|). The first will result in
showing the default entries and the page number, the second will
result in showing only books with the default bib entries. You can
specify as many additional flags as you wish. *atp-bibflags:output*
Note that the function shows the line with database file name if there
are entries in this bibliography which match the pattern thus,for
example, if you specify the flag '@a' and you see the line with
database file name, but you do not see any bib entry, then in this
database there are bib fields which match but these are not articles.
The flags='All' is a synonym of flag=g:defaultallbibflags which by default is
equal to'tabejfsvnyPNSohiuHcp' i.e. all flags in this order. If you
add your own flag you should change this global variable. You can add to
this flag any flag which contains '@' (see |atp-bibflags|) by
the plus operator, i.e. All+@a@b or +@aAll will give the same result.
The variable 'b:atp_LastBibFlags' stores the recently used flags. The flag
'L' sets the flags for this search to the value of 'b:atp_LastBibFlags'.
You can write '+L@a', '+L@a', 'L@a' or '@aL' but not '+@La', if you
want to add some flags to previous searches. Next time the flag 'L'
will change the meaning (i.e. it is really the last time not earlier
:) However, there is no '-' :( '-@aL' could be helpful.
The variable 'b:atp_LastBibFlags' is not changed when you use the 'All'
You can add your own flags but not keyword flags (i.e. @a,@b,...).
Just add an entry to the dictionary g:bibflagsdict. (:ShowOptions v to
see its current value), For example
let g:bibflagsdict=extend(g:bibflagsdict,
\ { '<flags_name>' : [ '<bib_entry_name>': '<how_to_show>'] })
where, <flags_name> is the flag to use (it should be one letter), it
must be different from the defined flags, <bib_entry_name> is a
lower case bib entry name, like 'title', 'url', etc., <how_to_show> if
you want to have a nice output put the bib entry name and that much of
white spaces to get 13 strings.
Some examples: *atp-bibflags:examples*
< Above command shows all bib fields with
the default flags (might be slow, why not to
open bib file with :GotoFile)
:BibSearch @ yt
< and this is a tip how to show all bib fields with
different flags than the default ones(the '@'
will match at every bib field!). It is
equivalent to:
:BibSearch // yt
:BibSearch /title[\s.]*Galois Theory/ aetb
The next one shows all bib fields which were written by Joyal and
Tirney (and may by somebody else).
:BibSearch author.*Joyal\&.*Tirney
< This is not possible with |g:atp_bibsearch|="python" (the default).
:{BibEntry}Yank [RegisterName] *atp-:Yank*
map {count[register]}c, map {count[register]}y
This function/command is only available in the window with BibSearch
results and allows to copy a bib entry key to a register or directly
to the last opened buffer (after the cursor position). It is mapped to
'c' and 'y'. You will be asked to give the number of bib entry to
<bib entry number><register name><Enter> - to copy it to a register
<bib entry number><Enter> - to copy to the " register
<Enter> - to skip the choice
< When the {count} is given the bib item {count} will be copied to the
register ".
For example: >
:5Yank e
:7Yank +
< Copy the bibkey to register e,+, or " (this might depend on the
'clipboard' option in which register the bib key will be put). The
same you will obtain using the nmaps y or c.
This commands and maps are only in the BibSearch buffer.
:{BibEntry}Paste [RegisterName]
map {count}p, {count}P
The syntax is the same as for |atp-:BibYank|. It paste the bib entry
to the tex buffer (where the |atp-:BibSearch| was inoked). The bib
entry is also copied to the " register.
The colours of the output are set by the syntax file
'syntax/bibsearch_atp.Vim'. All groups except one are the same as in
the syntax file for bib files ('syntax/bib.Vim' in your $VIMRUNTIME
directory). Their names are 'bibsearchEntryKw' instead 'bibEntryKw'.
The one that is differently defined 'bibsearchComment'. Which is
changed in that way to highlight the bib file names. One additional
highlight group is: 'bibsearchInfo'. It highlights the number of
entry and its line number in the bib file. By default all bibsearch
groups are linked to the corresponding bib group, the bibsearchInfo
group is not set.
In a colour file (~/.Vim/color/*.Vim) you can use these groups to set
colours. See |highlight| or just read a colour file. For example,
this is a nice set of colours for dark background
BIBSEARCH COMMENTS *atp-bibsearch-comments*
Please do not hesitate to report any bug to the mailing list
The algorithm will work only if all kind of bib entries of your bib
file are included in the list g:bibentries. However, changing just
this variable is not enough. In that case the search engine (function
s:search) will produce correct output, but the function which displays
found entries, will not know how to work with the new entries. One
would have to add an entry to the dictionary 'g:bibflagsdict'. If
it is the case, please let me know: |atp-mailing-list|.
As you can see entries of the type '@string' which can be used in bib
files are not supported (i.e. there is no function which substitutes
the variables defined in @string to their values), but it is doable.
@string{ Name = Value }
COMPLETION *atp-completion*
The completion is by default mapped to <C-X><C-O> (expert mode) and <C-X>o
(non expert mode). However if you set |g:atp_tab_map| to 1 (in your |vimrc|
or |atprc| file), then <Tab> (expert mode) and <S-Tab> (non expert mode) are
used. For example if you type \math<C-X><C-o> you will get a list of choices
which completes this command. (See ':h popupmenu-completion' and ':h
completion' for more).
There are two completion algorithm: expert mode and non expert mode: the
keyword for completion in expert mode must match at the begining, in non
expert mode any where. Also in expert mode the list of possible completions is
smaller (for example there is no '\lneqq', there is only '\lneq').
Note: Non expert mode doesn't check if you are editing math (see
|g:atp_MathOpened|), and is useful when you want to complete a non-math
command inside mathematics.
If you prefer to use map <Tab> key then you can define |g:atp_tab_map|=1 in
your |vimrc| file or atprc file |atprc|. Note that Vim can add/remove
tabshift width from the beginning of line in other ways: in normal mode with
|>>| and |<<|, in insert mode: |i_CTRL-T|, |i_CTRL-D| and in visual mode with
|>| and |<|. Also you can use |atp-g>| and |atp-g<|. The alignment of tabular
and other environments can be done with |atp-:TexAlign| command.
You can switch off/on completion modes adjusting the variable
|g:atp_completion_active_modes|, all names of completion modes are stored in
the variable |g:atp_completion_modes|.
If |g:atp_local_completion| is set to non zero value, then input files will be
scanned for \def, \newcommand, \newnevironment and \newtheorem commands and
they will be used for completion (with |atp-:LocalCommands|). If its value is
1 then this will be done during first completion, if it is set to 2 then this
will be done at start up. The default value is 2 when vim has |+python|
feature otherwise it is 1. With |+python| this is done at every time you
use the completion.
NOTE: if you press <C-X><C-O> but then you changed your mind, the completion
pop-up menu allows to cancel completion: press <C-p> (i.e. go up - some
times more than once) and then press <Space>.
Note: The completion checks the preamble for definitions of LaTeX packages. If
a supported package is present (for example: tikz) then the completion will
contain additional commands. If you add a package or a class you should unlet
corresponding variable: |g:atp_LatexPackages| and |g:atp_LatexClasses| and ATP
will regenerate them when necessary.
:ToggleTab {only available if g:atp_tab_map=0}
nmap, imap `<Tab>
It is a command to toggle the tab map off/on: :ToggleTab, it is also mapped
to `<Tab>.
Note: see |atp-Tab-note|.
I added extended versions of dictionaries of latex-suite to ATP (the files
dictionaries/dictionary and dictionary/SIunits). They are added to
|'complete'| vim option, so you can use them through |ins-completion|.
I made one more dictionary (dictionaries/ams_dictionary) with ams commands
and environment names. It will be added to the vim |'complete'| option if
you use amsmath package or if the document class is one of the standard
ams classes or of |g:atp_amsmath| is set to 1.
COMPLETION MODES *atp-completion-modes*
commands ~
if g:atp_check_if_math_mode = 1 then the pull of commands
contains math commands only if there you are inside a math
environment. This works perfectly if you switch from $:$ and
$$:$$ to their equivalent (and more up-to-date) \(:\) and \[:\].
The list of math environment in which ATP will think you are
editing a math mode is stored in the variable:
'g:atp_math_modes'. Its entries are two element list of
patterns which matches the beginning and end of a math mode.
The '0' entry have to provide the beginning and end pattern of
in line math '\(:\)', the second for displayed math '\[:\]'.
Its default value is given below.
If you add a package (like tikz or amsmath, or amssymb) then
the set of completions will contain extra commands/environment
names defined in these packages Because some classes calls
amsmath package silently setting the variable
'g:atp_amsmath=1' will ensure that you will get completions
for these commands. The algorithm checks if you have this
package declared or if you use some of the standard ams
class (actually checks if the document class name matches
If you do not want math commands completions at all define
':let g:atp_no_math_command_completion=1' (you can put it in
your |vimrc| or |atprc| file, or define while writing,
both will work, so you can switch off the math completions
The label command completes in a special way: for example in
a line like:
will complete to
The dictionary of short names is 'g:atp_shortname_dict'. If
you do not likes this idea (however it can help you to
correctly write \ref{ - to avoid referring to lemmas as
propositions, and also it makes completion for \ref{ nicer
- you can list only labels for theorems), so if you do not
want it anyway: 'let g:atp_no_short_names=1' will make the
If |g:atp_amsmath|=1 or you use one of ams classes, or the
package amsmath is found by ATP ams math commands and
environment names will be added to the list of completions.
By default the first time you are completing an environment
name or a command a list of locally defined environments and
commands is made (it takes a few seconds). If you do not want
to completions for them define "let |g:atp_local_completion|=0",
if |g:atp_local_completion|=2" then the search for local
definitions and commands will be done on startup (after
version 8.4 for this you have to switch off abbreviations by
setting g:atp_noabbreviations to 1 - but anyway it is not time
consuming because these variables are loaded from
If you added a command or an environment the command
:LocalCommands! will update the list of local definitions.
With bang "!" it update the list of input files
|b:ListOfFiles| in which the search is done. The output is
stored in three variables: >
< If a command was declared with a arguments (i.e. using \def#1, or
\def#1#2, etc. or with \newcommand{...}[1]{...}) a single '{'
is attached. It doesn't match for definitions inside comments.
This command will also make abbreviations to environments
found, see |atp-abbreviations|.
Note: the python version searches for commands, environments,
... defined in the beginning of line (with possible white
Note: the python version of LocalCommands will save the
current buffer, without saving project script and with
'nowritebackup' and 'nobackup' set.
tikzpicture ~
There is an extended support for tikz picture environment both
in-line \tikz{:} and displayed: \begin{tikzpicture}
\end{tikzpicture}. The completion works for both commands and
keywords. The pull of them is enlarged if you add tikz
libraries. Normal commands are added if you are inside {:}.
NOTE!: Keyword completion is only active in non expert mode
ref/label/cite ~
For label completion puts short names, for ref and eqref
commands the completions are the labels found in all files
associated to the main file (the plugin searches the input
and include files for them). The same for cite: which searches
also in bib files defined in the main file.
In the popup menu the first column show the label name, second
column contains the first letter of the counter name used:
e for equation, t for theorem, s for section, c for chapter,
I for Item, etc. - these are the most common things you will
see. The third column contains the value of the counter. It is
put in brackets () if it comes from equation counter.
There is also omni completion (see |i_CTRL-X_CTRL-O|) for
\cite command. Check it out, as it is very nice (especially in
gvim!) and very fast.
For both completion and omni completion for the cite command,
the text after \cite{ [ or after a comma after \cite{ ] is
treated as a regular expression. Thus you can write:
to get the completions for things written by both author 1 and
2 (regardless of the order they appear in bib files).
BibTeX omni completion is triggered by '\cite{', '\citep{' or
'\citet{'. For example, assume you have in your .bib files an
entry looking like: >
@book { knuth1981,
author = "Donald E. Knuth",
title = "Seminumerical Algorithms",
publisher = "Addison-Wesley",
year = "1981" }
Then, try: >
\cite{Knuth 1981<CTRL-X><CTRL-O>
\ref{{pattern}<Tab> matches the label name for the {pattern}.
When pattern is matched for a number of a label '^' is added in
front of the pattern (see below). In this case both completion modes:
expert and non-expert works in the same way.
You can also use Vim patterns after '\cite{'.
< Tab Completion for labels (|atp-completion|) allows to specify
the number of the counter, e.g. >
< will complete into the label of the counter with value '3.1'.
As for now you can not specify which counter to complete. You
can also write '\ref{3.1$' then '^3.1$' is used as a pattern!
For this two work the aux file must be present. As for now
the aux file, if it is not present, is not made.
This is working with the main document classes: article, book,
review, amsart, amsbook, memoir. If for some class it is not
working thanks for reporting me (it's enough to email me just
the document class).
brackets ~
Closing of brackets {:},{:},[:],(:) (also closes math modes \(:\) and
Relevant variables are: g:atp_bracket_dict a dictionary of
brackets by default it consists of pairs '(' : ')', '{' : '}',
'[' : ']'. There is a second dictionary g:atp_sizes_of_brackets
which contains all the sizes of brackets in latex plus a pair
'\' : '\', for closing the math modes: \(:\), \[:\] and the
brackets \{:\}.
math modes ~
\(:\), \[:\], $:$ and $$:$$ will be closed when all brackets
after the opening \(, \[, $ or $$ are closed. If \[ or $$ is
in line which matches '^\s*\(\\[\|\$\$\)\s*$' it will be
closed in a following line.
environments ~
Completes after '\begin{' and '\end{'. For example
'\begin{cen<Tab>' will give '\begin{center}'
But '\begin{theorem}<Tab>' or
'\begin{theorem}\label{thm:1}<Tab> will close the environment.
The algorithm tries to close environment in many natural
situations: for example when it did found less than one command
completion. It closes the right environment when they are
nested (however not in right place!) and it preserves the
indention. When after \begin{center}\label{...} XXX there is
something (in place of XXX) it will close the environment
after the cursor position otherwise in next line
(\hypertarget{...}{...} command is treated like \lebl{...}).
The environments opened in tex definitions ('\def',
'\newcommand', '\renewcommand') will not be closed unless the
current cursor position is in that line (sometimes one might
want to have a definition which only opens an environment).
If you type \begin{envname}<Tab> the cursor position will not
change. You can use |i_CTRL-M| (|i_CTRL-J| is used by
|atp-j_motion|) after <Tab> to open new line inside {envname}.
Otherwise the cursor position will be right after the closing
See |g:atp_amsmath|.
Examples: ~
(the <Tab> indicates in which position the
<Tab> can be pressed to get the described
\item .....
\item .....
< Usually the closing comes in the next line,
unless we are inside an environment which is opened
after the non closed environment:
\item .....
\item .....
< Then the closing will be put just after the last
opened environment closes, or
\item .....
\item .....
< If we are outside the theorem environment,
'\end{enumerate}' will be placed just above
'\end{theorem}', and
\item .....
\item .....
< will put \end{minipage} just above
\begin{enumerate}. Furthermore, if:
\item .....
\item .....
< '\end{minipage}' will be put just above
'\end{enumerate}'. Furthermore,
\begin{theorem}[...]\label{...} Let \(C\) be a ....
......<Tab> XXXXX
That is, if you like to write \begin{}:\end{} in the beginning
and end of a line this will be preserved. However, there is no
support for nested environments then!
abbreviations ~
There is tab completion for insert mode abbreviation names
(use <CTRL-y> to choose one from the list and then type
<space>, just typing <space> should also work).
font declarations ~
This is completion for the commands
It first splits the line and take a part between the commands
\selectfont (if there is not \selectfont command this step is
Then if the <encoding> is declared the font families for the
completion will only come from this <encoding>.
If <font_family> is defined, <font_series> and <font_shape>
come from the particular font definition file (the declared
encoding is used if not the value of
|g:atp_font_encoding| is used).
If <font_family> and <font_series> are defined then the
<font_shape> for this font (in the above encoding) is found.
The completed <encoding>'s are taken from the variable:
bibstyle ~
Completion for the command '\bibliographystyle{'. Finds all
"bst" files available in your tex distribution.
documentclass ~
Completion for the command '\documentclass'. Returns list of
all classes available in your distribution.
documentclass options ~
package options ~
You can write your own scrip which will add support for
documentclass or a package (see |atp-copmletion-new-package|).
Put it under 'ftplugin/ATP_files/packages/' directory in your
vim path. Supported variables:
< Note: ATP (if |+python|) scans package and documentclass files
for options, so in general this variables are not needed. The
values in this variables will be added to completion. They
might be used if there are options which atp cannot find.
< These are just list of options/commands. math_commands will be
added to completion only in math mode.
< This is a dictionary. It is used to find completion for values
of options of a given command: for example
Each key is a pattern which will match against the command
name. The value is a dictionary which keys matchs for an
option name and the corresponding entry is a list of possible
values of the option.
(see ftplugin/ATP_files/packages/listings.vim)
< This variable is a vim dictionary: keys are vim patterns which
should match a package option, values are lists of the option
values. See 'ftplugin/ATP_files/packages/caption.vim' for an
example. This was tested with the following option syntax: >
< In a similar way works the variable: >
< See 'ftplugin/ATP_files/packages/enumitem.vim' for an example
(or use ':echo g:atp_enumitem_command_values').
or 'ftplugin/ATP_files/packages/xcolors.vim'
The value of a key in this dictionary might be a string, which
is supposed to be a name of a function to get list of
completions. Afterwards this list will be filtered to get
only matching completions. It should return a vim list. An
example is in 'ftplugin/ATP_files/packages/xcolors.vim'.
g:atp_{p_name}_loading = { "package" : "option", ... }
< This variable is a dictionary { "package" : "option" } which
loads xcolor package, when option is empty means that the
package is always loading. Both "package" and "option" are
vim patterns. See xcolor for an example. Loading through
document class is not yet supported, but might be added on
< This is a dictionary. It is used to find completion for values
of options of a given environment: for example
Each key is a pattern which will match against the environment
name. The value is a dictionary which keys matches for
an option name and the corresponding entry is a list of
possible values of the option.
(see ftplugin/ATP_files/packages/listings.vim)
ATP is scanning packages on the fly, i.e. there is a python script which
scans package file for its options, commands and evironments that it
defines. This happens for packages that have a file under
ftplugin/ATP_files/packages directory. So if you want ATP to scan
a package that you use it is enough to make an empty file under this
directory with a name package.vim (e.g. listings.vim for listings.sty
package). You can (see other files in that directories) define list of
options, commands, environments, etc and ATP is will add only the entries
that you have missed (the reason for this is that when the package is
updated in might have a new option/command/environment).
ATP COMPLETION VARIABLES *atp-completion-variables*
These are all variables which can help to customise the completion:
(if the value is given it is the default, if it is not means it is too long to
put it here).
g:atp_completion_limits = [ 40, 60, 80, 120, 30 ]
The above variable specifies how long should atp plugin search for
closed/unclosed environments:
the first value - search for \(:\) [ in line math ]
the second - search for \[:\] [ displayed math ]
the third - search for \begin{<env>:\end{<env>
the fourth - for environments defined in
the variable g:atp_long_environments
the fifth - for checking brackets defined in
|g:atp_bracket_dict|. You can speed up Tab
Completion by removing brackets that you
don't use from |g:atp_bracket_dict|.
You can also put "-1" as the values of |g:atp_completion_limits|,
then the search forward/backward will last till first/last line.
However, this makes it run slower.
g:atp_long_environments = []
If some of your environments are very long put their names in this
list. Do not forget that is environment <env> is long and is put
inside environment <center> then <center> is also long!
However, this will not close long environments (for that you have
to change the third argument of |g:atp_completion_limits| !). This
just prevents closing environments which are closed and to long to
see that.
g:atp_completion_modes = [
\ 'commands', 'inline_math',
\ 'displayed_math', 'package_names',
\ 'tikz_libraries', 'environment_names',
\ 'close_environments' ,'labels',
\ 'bibitems', 'input_files',
\ 'bibfiles', 'bibstyles',
\ 'documentclass' ]
This is the list of completion modes.
g:atp_completion_active_modes = g:atp_completion_modes
< This is the list of completion modes which are active, by
default all modes are active. Remove a value from this list to
make it inactive (You can use remove() command, see ':h
g:atp_sort_completion_list = 12
< If the length of completion list for Tab Completion is longer
than this value, entries will be sorted alphabetically, else
they are provided in, I hope, useful order. If set to 0 the
list will not be sorted (if set to 1 it will be always
sorted). >
< It is used to define <short_name> in
when completing the \label command.
g:atp_separator = ':'
< It is used as a separator in:
when completing the \label command.
g:atp_no_separator = 0
g:atp_no_separator_list = ['', 'titlepage']
< The following variable if set to one then completion for \label
command will put short name of the environment where it stand.
It uses the dictionary g:atp_shortname_dict to get the short
name. >
g:atp_env_short_names = 1
These variables are lists which stores LaTeX commands used in
completion. >
< The two last are lists of commands will be add only in
the non expert mode (|atp-completion-non-expert-mode|).
g:atp_completion_truncate = 4
do not complete commands less than 4 characters (not counting
the leading '\' if present). If 0 then complete all the
defined commands. This only works in the expert mode.
g:atp_MathOpened = 1
< the default value is 1. With the default value expert mode
completion will check if you are completing inside
mathematical environment or not. Inside math environment only
math commands are completed and outside math commands are
disabled. This makes the set of completions more accurate. If
you need non math command (like \textrm{}) inside math use non
expert mode (see |atp-completion-non-expert-mode|)
let g:atp_MathZones = [
\ 'texMathZoneV', 'texMathZoneW',
\ 'texMathZoneX', 'texMathZoneY',
\ 'texMathZoneA', 'texMathZoneAS',
\ 'texMathZoneB', 'texMathZoneBS',
\ 'texMathZoneC', 'texMathZoneCS',
\ 'texMathZoneD', 'texMathZoneDS',
\ 'texMathZoneE', 'texMathZoneES',
\ 'texMathZoneF', 'texMathZoneFS',
\ 'texMathZoneG', 'texMathZoneGS',
\ 'texMathZoneH', 'texMathZoneHS',
\ 'texMathZoneI', 'texMathZoneIS',
\ 'texMathZoneJ', 'texMathZoneJS',
\ 'texMathZoneK', 'texMathZoneKS',
\ 'texMathZoneL', 'texMathZoneLS',
\ 'texMathZoneT' ]
< the default value in plaintex files is >
g:atp_MathZones = [ 'plaintexMath' ]
< These are zones recognized by tab completion as mathematical
ones (see |g:atp_MathOpened|).
g:atp_no_complete = ['document']
< List of environments which is not closed by <tab> completion.
(The document environment in longer documents can be not seen
by the algorithm as closed, because it searches only in a part
of the text, see |g:atp_completion_limits| variable above).
g:atp_bracket_dict = { '(' : ')', '{' : '}', '[' : ']', '<' : '>',
\ '\lceil' : '\rceil', '\lfloor' : '\rfloor',
\ '\langle' : '\rangle', '\lgroup' : '\rgroup' }
< You can speed up Tab Completion by removing brackets that you
don't use. >
g:atp_sizes_of_brackets = {'\left': '\right', '\bigl' : '\bigr',
\ '\Bigl' : '\Bigr', '\biggl' : '\biggr' ,
\ '\Biggl' : '\Biggr', '\' : '\' }
The variables: >
< stores list of packages and classes in your tex distribution. They are
restored when you exit Vim from the global project script (see
|atp-ProjectScript_global|). They are used for completion of the LaTeX
commands \usepackage and \documentclass.
If you reinstall, add or remove tex classes/packages from your tex
distribution it is enough to unlet these variables. ATP will find new
values when it will need them for the first time.
There are several options you can set, and they might be set in your Vimrc
file. The default values are given below (except the completion setup and
bibtex documented above). Note: not all variables are listed below.
All the values of important variables with their values can be shown
(grepped) by |atp-:ShowOptions| command.
$HOME/.atprc.vim (only on Unix and GNU/Linux) or
A configuration file for ATP. You do not have to use autocommands to set
local-buffer variables, just place them here. The settings in |atprc| file
override the values in the project script (|atp-ProjectScript|). You can
also overwrite the plugin maps there it you want to have different
behaviour on the key map used by ATP. This file is source twice, before
and after sourcing ATP.
Tip: If you want to see (almost) all the variables, type ':let g:atp_<CTRL_D>',
and ':let b:atp_CTRL-d'.
All buffer variables (see |b:var|), i.e. these which name begins with "b:",
should be set in your |vimrc| or |atprc| file. If you want to use your vimrc file
then the best way to do that is by using an autocommand:
au BufReadPre *.tex let b:atp_TexCompiler="latex"
If you put just let |b:atp_TexCompiler|, this will also work but not always: for
example when you open a new buffer in existing Vim session. However, if you
put them in your |atprc| it is enough to use the standard "let b:...=".
let b:atp_TexCompiler = "pdflatex"
< Used by functions: TEX() (map <LocalLeader>l, imap <LocalLeader>l),
VTEX() (map <F5>, imap <F5>)
You can set it to latex, tex, luatex, and so on and possibly to
lilypond as well.
There is a command to set this variable with nice completion, see
let b:atp_TexCompilerVariable = "max_print_line=2000"
< You can use it to set an environment variables for the compiler. The
"max_print_line" sets the maximal length of a line in the log file.
The value 2000 is high enough to prevent line breaking.
Note: the grammar for this variable: it should be a semicolon separated
list of variables and values, i.e. 'variable_1=value_1;variable_2=value_2'
let b:atp_BibCompiler = "bibtex"
< This variable sets the bibtex backend. There are other programs which
might be used, for example biber and pybib (not tested with ATP).
The default value will be "biber" if the preamule contains
\usepackge[backend=biber]{biblatex}. If it is set to "biber" ATP will
adjust |g:atp_keep| variable (add run.xml, bcf extensions) when you use
|atp-:TEX|, |atp-:Bibtex|, or |atp-:MakeLatex| commands.
Biblatex package allows for putting \bibliography{} type commands only
in the preamble. Thus ATP will search for them only there. The
|g:atp_inputfile_pattern| might not contain any pattern for
bibliographies (\addbibresource, \bibliography, etc.). The
|atp-:InputFiles| command will search for them in a special subroutine
which only searches in the preamble. This makes it slightly faster.
let b:atp_TexFlavor = "tex"
< If you are editing a plain tex file it is automatically set to
'plaintex', then you get highlighting for $$:$$. Some other features
are planned (you can also set this while editing a 'tex' file, i.e.
latex document but using $$:$$ is latex is not recommended it is know
to break some latex specific things).
let b:atp_TexOptions = "-synctex=1"
< This variable is a string of TeX compiler options separated by a comma.
If you want to set some additional options to your tex compiler you
can use this variable, note that '-output-directory' and
'-interaction' are set by ATP.
let b:atp_OutDir = fnameescape(fnamemodify(resolve(b:atp_MainFile,":h")) . "/"
< This is the directory in which tex will put the output files. If the
open file is not a symbolic link it is equal to the directory in which
the tex file is located. If the open file is a symbolic link it points
to the directory in which the real file is located.
If you set this variable to './' (or '.') and change the current
working directory for example to /tmp (:cd /tmp) then the latex output
will be placed in /tmp, i.e. it will move with with cd. However, the
default value of b:atp_OutDir is not affected by :cd command.
White spaces and other characters should not be escaped. It will be
quoted in '...' using the |shellescape()| function.
You can see the current output directory in the status (it is in the
short notation) to see it whole type:
:echo b:atp_OutDir
or use the |atp-:ShowOptions| command.
If in your environment the variable $TEXMFOUTDIR is set the value of
b:atp_OutDir will be set to its value.
let b:atp_auruns = 1
< This variable control how many times the automatic function calls tex
compiler (consecutively). It is useful if you are working with PDF
files and you want to have bookmarks (you can get them using hyperref
package with the option: bookmarks. Then set b:atp_auruns to '2'.
< This variable stores the current number of running instances of latex.
When it is greater than 1 a message in the status line is shown. If :PID
command returns that no latex is running this variable this variable
is reset to 0.
g:atp_MathVimOptions = { 'textwidth' : '0' }
< This variable is a dictionary of Vim settings and its values which
will be valid when you edit mathematics inside the pairs \(:\), $:$,
\[:\], $$:$$ (only in plain tex files or if g:atp_TexFlavour
= 'plaintex'). For example, the default value will toggle between
your 'textwidth' in non-math and 0 in math. The dictionary may
contain short option names equally well as long names.
Note: the standard tex syntax file defines other zones: for example
for align and equation environments (and many others) but some how
they are not accessible using synstack() function.
This feature can be turned off setting variable >
< to '0', the default is '1'.
let g:atp_autex_check_if_closed = 1
< This feature is not implemented.
tex run if all environments \begin:\end, \(:\) and \[:\] are closed.
Set g:atp_autex_check_if_closed=0 in order to not make the checks.
let g:texmf = substitute(system("kpsewhich -expand-var='$TEXMFHOME'"), '\n', '', 'g')
< This variable configures where local input files are placed. See
|atp-:Edit|. Note: if you set this variable in |vimrc| or |atprc| file
vim will startup a bit faster with tex files, since calling kpsewhich
is slow.
let g:askforoutdir = 0
< Its values are 1 and 0. When it is set to 1 you will be asked for the
name of a directory where tex will put output files, note that this
name should end with a "/".
let b:atp_Viewer = "okular"
< it was tested with Xpdf, Evince, ePdfViewer, Kpdf, Okular, Xdvi and
they all works fine. I'm using Xpdf and the Xpdf server options are
supported so that the file is automatically reloaded (other viewers,
except epdfview, have this functionality as well. This do not works
for acroread. Read more about viewers in |atp-viewers|.
If you use program b:atp_Viewer then you can use the variable
b:atp_{b:atp_Viewer}Options to set the options (it is a vim list), for
example if b:atp_Viewer="xpdf" then you might use:
|b:atp_evinceOptions|, etc ... (also global variables g:atp_...Options)
Used by function: ViewOutput() (map <LocalLeader>v, map <F3>, imap <F3>)
These are lists in which every viewer switch and its value should be
placed as element (separate!). See examples below.
For example, if you want to have different look of one document you can
set it to "-bg gray20". Some examples:
let b:atp_xpdfOptions = ['-bg', 'Grey30', '-mattecolor', 'SlateBlue2', '-papercolor', 'White']
let g:atp_xpdfOptions = ['-bg', 'NavajoWhite4', '-fg', 'black', '-mattecolor', 'burlywood']
let b:atp_xdviOptions = ['-expertmode', '0', '-s', '6', '-watchfile', '1']
let b:atp_XpdfServer=fnamemodify(expand("%"),":t")
< This variables stores the name of Xpdf server (if you use xpdf to view
pdf files).
Used by the command |atp-:View| (map <LocalLeader>v, map <F3>,
imap <F3>) and also |atp-:SyncTex| (map <LocalLeader>f).
You do not need escape spaces in the name (shellescape() function is
used before it is send to the shell).
let b:atp_LocalXpdfServer=fnamemodify(expand("%"),":t")
< This variables stores the name of Xpdf server which will host compiled
Used by the command |atp-:ViewL| (map <LocalLeader>V, map <S-F3>,
imap <S-F3>) and also |atp-:SyncTexL| (map <LocalLeader>F).
You do not need escape spaces in the name (shellescape() function is
used before it is send to the shell).
let b:atp_OpenViewer = 1
< If the function which calls TeX compiler do not see that you are
viewing the output file it will open it for you if b:atp_OpenViewer=1.
Otherwise, this feature is disabled.
let g:atp_delete_output = 0
< If set to 1 then Delete function (map <F6>d) will delete also the
output file.
let g:atp_cpcmd = "/bin/cp"
< This sets the copy command used by compiler. The value tries to not use
shell internal function and to avoid the -i switch (ask if overwrite).
let g:atp_tex_extensions=["aux", "log", "bbl", "blg", "bcf", "run.xml", "spl", "snm", "nav", "thm", "brf", "out", "toc", "mpx", "idx", "maf", "blg", "glo", "mtc[0-9]", "mtc1[0-9]", "pdfsync" , "ind"]
This list is used by the |atp-:Delete| command which deletes all the
files with the specified extension in the directory |b:atp_OutDir|.
let g:atp_keep = [ "log", "aux", "toc", "bbl", "ind", "idx", "synctex.gz", "blg", "loa", "toc", "lot", "lof", "thm", "out" ]
< Files with an extension belonging to this list will be copied from
'b:atp_OutDir' to the temporary directory with appropriate name. Then it
will be used by (La)TeX. (log file will be copied after it is created,
other files will be copied back and forth between 'b:atp_OutDir' and the
temporary directory). These four elements: log,aux,toc,bbl are
essentially minimum to work with: table of contents, pdf-bookmarks and
bibtex. There are possibly other classes, like beamer, or packages
like theorem (produce .thm files) which will need to configure this
If you use "biber" ATP will add "run.xml" and "bcf".
You can change this variable by the command:
:let g:atp_keep+=["spl"]
let g:printeroptions = ""
< You can set the printer options. These are options for the 'lpr'
command, which will print the output file (pdf or dvi) this depends on
the b:atp_TexCompiler that you use.
< This variable is for debugging purposes. It stores the last executed command to
compile your document. It changes also when your compiler was run
automatically. >
:echo g:atp_TexCommand
:echo g:atp_TexCommand
< It is read-only variable.
b:atp_TempDir = b:atp_OutDir/.tmp
< In this directory vim (or python) will make a temporary directory
(with a unique name) to which output files will be put by your TeX
compiler. This is done so to prevent overwriting the output file while
the compilation is being done (this can cause problems when there are
many TeX processes and the Viewer is accessing not yet compiled
file). The output files are copied back to b:atp_OutDir after
compilation. The temporary directory is passed to your TeX compiler
using '-output-directory' switch.
< In this directory the logs of ATP are stored. If vim has python support
is created by python in most secure way available (readable only by
the user) if not it is made using |mkdir()| vim function with 0700
let g:atp_CompilersDict = {
\ "pdflatex": ".pdf", "pdftex" : ".pdf",
\ "xetex" : ".pdf", "latex" : ".dvi",
\ "tex" : ".dvi", "elatex" : ".dvi",
\ "etex" : ".dvi", "luatex" : ".pdf"}
< This variable is used to associate an extension to the compiler that
is used.
g:defaultbibflags see |atp-bibflags:default|
g:defaultallbibflags see |atp-bibflags:all|
b:atp_LastBibFlags see |atp-bibflags:last|
b:bibfiles see |atp-variables-bib|
For more on bib flags see |atp-bibflags|.
let t:toc_window_width=g:atp_toc_window_width
< t:toc_window with is set to g:atp_toc_window_width (by default is 30)
The global variable configures the initial width of the window with
table of contents.
let t:labels_window_width=30
< g:labels_window_width (by default not set, if set overrides
Configures the initial width of the window with labels.
< by default it is not set, put the line
let g:atp_statusline=0
in your |vimrc| or |atprc| file if you do not want the status line provided by this
plugin. (See |atp-:Status|).
let b:atp_TruncateStatuSection=40
< This variable sets how many characters of the section/subsection title
(or chapter/section titles if you write a book) should be shown in the
status line. Section title and subsection title gets equal amount of
< This two variables stores the information returned by
'kpsewhich -show-path tex'
They are locked. The first one has pretended '**' wild cards to every
directory, which is done for using with globpath() and findfile()
g:atp_VimCompatible variable
< with default value 0 ("no"). Its values are 0/1 or yes/no. It changes
the behaviour of '%'. In nocomatible mode it goes to matching pair
in a different line in compatible mode it finds the matching pair only
if the ending bracket is in the same line.
See also how it changes the behaviour of |atp-]%| and |atp-[%|.
< by defalt ATP is useing LatexBox indentation script. If you set this
to 0 the vim runtime indantation script will be used. Also
'indentkeys' differ.
If set to 1 (the default is 0) then |atp-gf| can go to package and
class files under texmf tree. When set on startup within your |vimrc|
or |atrc| file then also |atp-:Texdef| is defined (when set in |vimrc|
file it be defined in any filetype - not only tex).
WRITING PROJECTS *atp-ProjectFiles*
let b:atp_MainFile = expand("%:p")
< This variable points to the main file of the project, it is set on the
start up to the file you open. If you edit project file (for the first
time), start with the main file and use gf (see |atp-gf|) to go to the
project file you want to edit. In this way all the project files will
have correctly set this variable. The value of this variable is used
by compilation functions. This variable is written in the project
script (see |atp-ProjectScript|). And when the project script is on (see
|atp-ProjectScript|, or set |b:atp_ProjectScript|=1) it is restored between
sessions. In this way, next time, you can open any project file and
the b:atp_MainFile variable will be set to the correct value.
The project feature stores more variables: |b:TreeOfFiles| a dictionary
which contains the tree of input files, |b:ListOfFiles| - list of input
files, |b:TypeDict| dictionary of types of input files, where the type
is one of following: {preamble}, {input}, {bib}. The last variable is
|b:LevelDict| which is a dictionary of input levels (for example: an
input file in input file has level 2).
There are other tools to make editing project files more easy. There
is search function: |atp-:S| which works better than the Vim |:ijump|
command, which cannot go above the current file in the tree of input
files /but |:ijump| is much faster/.
If you write a project you might want to use subfiles package. Then
you can compile with |atp-:TEXL|, view with |atp-:ViewL| and forward
search with |atp-:SyncTexL|. Furthermore, you can still use completion
of labels by numbers if you add to the preambule of the subfile the
following command (requires ifthen package): >
< This command will manually set the chapter number to CHAPTER_NR.
However, when you compile the whole project this command will not
affect the project.
Stores the project directory, by default where |b:atp_MainFile| is
located (the filename is resolved if it is a symbolic link). It is not
written to the |atp-ProjectScript| (this makes the |atp-ProjectScript|
independent of the host when |g:atp_RelativePath| is set). This
variable is mainly for internal purposes. If you want to set the
output directory use |b:atp_OutDir|.
If set to 1 (which is the default), project variables: |b:atp_MainFile|,
|b:TreeOfFiles|, |b:ListOfFiles|, |b:TypeDict|, |b:LevelDict| will store path
relative to |b:atp_ProjectDir| (which is the same as path to your main
file, however if the file is a symbolic link it will hint to the
resolved path). The |atp-:S| will use correctly these values. This is
particularly useful if you want to share the project file.
If you run into problems with |atp-:S| you can set this variable to
0 and use |atp-:InputFiles| to regenerate the variables - they will
now store the full path (the other way around also works).
:ToggleNn [on] *atp-:ToggleNn*
The command |atp-:ToggleNn| toggles the value of |g:atp_mapNn| variable.
The optional argument [on] has three possible values: "", "on" or
"off". The default "", toggles the value of |g:atp_mapNn|, "on" sets
g:atp_mapNn to 1 and "off" sets it to 0.
g:atp_mapNn = 0
< If it is set to 1 then several tools use |atp-:S| command instead of
Vim |search()| function (which looks only in the current buffer).
These are:
|atp-:NPart|, |atp-:NChap|, |atp-:NSec|, |atp-:NSSec|, |atp-:NSSSec|,
|atp-:PPart|, |atp-:PChap|, |atp-:PSec|, |atp-:PSSec|, |atp-:PSSSec|.
The default value of |g:atp_mapNn| is 0.
The variable g:atp_mapNn should be always set as follows (in
|atprc| or |vimrc| file): >
if !exists("g:atp_mapNn")
let g:atp_mapNn = 1
< Then the value will be preserved when atp opens new buffer
when using |atp-:S| command. If you want to have project specific
setting use |atp-ProjectScript|.
Another good tip for LaTeX project files is to set |b:atp_TexFlavor|
variable to 'tex' (in your |vimrc| or |atprc| file). This will prevent
from situations that Vim recognizes input file as a plain TeX while it
is an input file into a LaTeX project.
Another way is add options to 'viewoptions' (see |'viewoptions'|). And
set mkview and loadview via autocommands >
au BufWinLeave *.tex mkview
au BufWinEnter *.tex silent loadview
< This will ensure that filetype variable is set correctly. Some ATP tools
behave in a different way in plaintex files. For example TreeOfFiles
function (it makes the variables |b:TreeOfFiles|, |b:ListOfFiles|,
|b:TypeDict|, |b:LevelDict|). It is recursive in LaTeX files but not in
plain TeX files). On this function is based the command
|atp-:LocalCommands| which makes list of commands, environments and
colours for Tab Completion and also |atp-:S| command. It is done so,
because in plain tex there is no way to distinguish input files from
input packages which we do not want to scan (especially recursively,
which might be time consuming).
PROJECT SCRIPT *atp-ProjectScript*
< The file: |b:atp_MainFile| . ".project.vim", called local project
script, in the same directory as |b:atp_MainFile| stores values of
variables saved before Vim left the buffer (it is very similar to
|View|). It is a configuration script per project. There is additional
file which stores some global variables, see
Loading procedure searches for files which ends with '.project.vim'. There
might be many such files in one directory. The file is used which contains
the current buffer in the list |b:ListOfFiles| or as a value of
|b:atp_MainFile|. If there wasn't any such the project scripts file
then a new project script will be written for the current buffer. Before
writing the project script file if |b:ListOfFiles| doesn't exists it
will be generated and written.
The project script is stored locally so that it is possible to include
it in a revision system (git, bzr, svn, etc.) and share it with
The variable |g:atp_ProjectLocalVariables| stores the names of
variables written to the local project script, similarly the varaible
|g:atp_ProjectGlobalVariables| is a list of variables stored in the
global project file.
The |atprc| file (and tex.vim file in after/ftplugin/ directory) is
executed after the global project script and before the local one.
(Precisely all the |:let| statements are executed before |atprc| file
but all the |:set| and |:setl| statements are executed afterwards).
The |:set| and |:setl| statements are executed only once (per project
If you want to have two main files (for example a copy of a project
in another directory below the project main directory), i.e.
Then the easiest way is to open tmp/main.tex and adjust the variables:
|b:atp_ProjectScriptFile| to point to tmp/main.tex.project.vim and
|b:atp_MainFile| (this is necessary only if |g:atp_RelativePath|=0)
and run |atp-:InputFiles|, then use |atp-:WriteProjectScript|.
Setting one of the variables |b:atp_ProjectScript| or
|g:atp_ProjectScript| to 0 the feature will be turned off. Local
variable, i.e. b: has precedence over the global one g:. So you can
turned off the feature for only specific files. The global variable
will turn it off for all files.
Local and global variables can be stored in the local project script.
The variables which are cached in local project script are listed in:
let g:atp_ProjectLocalVariables = [
\ "b:atp_MainFile", "g:atp_mapNn", "b:atp_autex",
\ "b:atp_TexCompiler", "b:atp_TexOptions", "b:atp_TexFlavor",
\ "b:atp_auruns", "b:atp_ReloadOnErr",
\ "b:atp_OpenViewer", "b:atp_XpdfServer",
\ "b:atp_Viewer", "b:TreeOfFiles", "b:ListOfFiles",
\ "b:TypeDict", "b:LevelDict", "b:atp_BibCompiler",
\ "b:atp_StarEnvDefault", "b:atp_StarMathEnvDefault",
\ "b:atp_updatetime_insert", "b:atp_updatetime_normal"
\ ]
If you want to alter value of this variable, it should be done in
|atprc| or |vimrc| files. When you remove a variable from this list it
will not automattically be removed from the local project script. You
need to delete it your self (or delete the project script with
If your vim doesn't have python support |+python| three more variables
are stored: |b:atp_LocalEnvironments| |b:atp_LocalCommands|, and
|b:atp_LocalColors|. With |+python| this is not needed since
|atp-:LocalCommands| is then very fast and is run on |BufEnter|.
let b:atp_ProjectScriptFile = b:atp_MainFile.".project.vim"
< This variables stores the name of the current local project script file.
There is also file for variables for all projects. It stores values of
global variables (by default it is "ftplugin/ATP_files/common_var.vim".
The global variables that are written in this file are given in Vim
let g:atp_ProjectGlobalVariables = [
\ 'g:atp_LatexPackages',
\ 'g:atp_LatexClasses',
\ 'g:atp_Library' ]
If you want to disable this feature for some reason you can set: >
let g:atp_ProjectScript = 0
< or >
let b:atp_ProjectScript = 0
< if you want to disable this feature only for a given buffer.
(The value of local variable overrides the value of global one!).
Hint: (if you want to disable loading project script for one file):
In your .vimrc file you can set the local variable via
autocommand group BufEnter or you can put an if statement in your
|atprc| file: >
if expand("%:p") == <path_to_file>
let b:atp_ProjectScript = 0
< or you can add to the project scrpit:
(1) write in its first line 'finish', or
(2) include in it 'let |b:atp_ProjectScript| = 0'.
There are these commands: ~
:LoadProjectScript[!] [local/common] *atp-:LoadProjectScript*
:WriteProjectScript[!] [local/common] *atp-:WriteProjectScript*
:DeleteProjectScript[!] [local/common] *atp-:DeleteProjectScript*
:ToggleProjectScript[!] [on/off] *atp-:ToggleProjectScript*
which do the obvious thing (if |g:atp_ProjectScript|=0 or |b:atp_ProjectScript|=0 they
will not work). The default value of the optional argument is "local".
:DeleteProjectScript [local] command (with optional argument [local]) deletes
the project script file for the current buffer (only the local one), with
bang "!" it deletes also global project scrip. The bang of
:WriteProjectScript forces to write to project script even when
project script is turned off (|b:atp_ProjectScript|==0 or
!exists("|b:atp_ProjectScript|") && |g:atp_ProjectScript|==0).
The command ':ToggleProjectScript [on/off]' turns on/off the feature
for this buffer (it sets |b:atp_ProjectScript|). When no argument is
given it will toggle the value. With bang it also sets the global
variable |g:atp_ProjectScript|. |b:atp_ProjectScript| is by default in the >
< so it will be restored afterwards. |b:atp_ProjectScript| if defined
overrides the value of global variable |g:atp_ProjectScript|. So you can set
in your atp file g:atp_ProjectScript = 0 and for some files using the
if-construction: >
let g:atp_ProjectScript = 0
if expand("%:t") == "myfile.tex"
let b:atp_ProjectScript = 1
< will turn on the feature only for myfile.tex. Something more elaborate
would be to set |b:atp_ProjectScript| only for files with modification time
less than two days for example.
Note: If you delete the project script for the current buffer it will be
written after exiting Vim, unless you turn off the project feature.
The project script is disabled for files which full path matches
"texmf". With the optional bang |atp-:LoadProjectScript| loads the
common project script also for them. |atp-:WriteProjectScript| command
will write the project script disregarding if the file is under texmf
directory or not.
Note: If you use this feature, you might need to use the commands:
|atp-:LocalCommands| and |atp-:InputFiles| which will update
b:atp_LocalCommands, b:atp_LocalColors, b:atp_LocalEnvironments and
|b:TreeOfFiles|, |b:ListOfFiles|, |b:TypeDict| and |b:LevelDict|. Use
these commands with a bang "!". The second set of variables is also
updated by |atp-:S| (also with "!") and and |atp-:GotoFile| (with "!"
as well).
Note: Also when you add a package to tex you should remove the common
project scrip, so that the new packages will be added to completion
:S[!] /{pattern}/ [flags]
The pattern is a Vim pattern (with 'magic'). With bang "!" it
regenerates the tree of input files.
This is command does the same job as |/| but is recursive in the tree
of files (so it is useful only in project files). The syntax of this
command is similar to |:vimgrep|. It also sets the ` mark and thus it