An Introduction to AUTOMATIC (La)TeX PLUGIN (ver. 9.6.1)

by Marcin Szamotulski
atp-vim-list [AT]

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

Features Include:

* 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,
* table of contents which allows to switch between different sections, files, but also to delete and paste sections:
See atp-:TOC,
* 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


The project is hosted on SourceForge


You can [DONATE] for this project through your [PayPal] account (my email is ). This will be highly appreciated. You can also feel like you are supporting my [PhD] in Mathematics :). Whether you donate or not you are always cordially invited to give suggestions, feature requests, bug reports or just to write that you like it or not :).

Thank You.

Note: The donations are accepted through PayPal, if you are from Europe and you want to donate Euro, use your PayPal account rather than SourceForge link where you cannot donate Euro (avoiding twice money exchange).

- There is a mailing list which will serve for: feature requests, bug reports, suggestions. You can subscribe with this link

- For detailed list of changes you can look here

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

Table of Contents

Functions and Commands

Some Most Important Commands:




atp-:SyncTex /forward searching/




atp-:Tags /make tags file/


atp-:Dsearch /definition search/
atp-:S /search in projects/
Commands/Maps in ToC window and Labels window.
Bibtex filetype plugin
Searching in bib files
BibSearch Variables
Tab Completion
Completion Modes
Completion for Commands
Completion for Tikzpicutre Environment
Completion for \ref/\label/\cite commands
Completion for Brackets
Completion for Environments
Completion for Abbreviations
Completion for Font Commands
Completion for \bibstyle Command
Completion for \documentclass Command
Completion Variables
Omni Completion
Omni Completion for Commands
Omni Completion for Environments
Omni Completion for Labels
Omni Completion for Bib Entries
Variables How to configure ATP to your needs
A note how to write project files within ATP
A script executing project specific settings
font imaps
Greek letters imaps
environments imaps
miscellaneous mathematical imaps
mathematical imaps
diacritics imaps
Debugging ATP
Editing tools
Viewers (with how to configure reverse searching for Okular)
Some tex oriented tips
Colours and syntax files
Final remarks
Copy Rights


Changes in version 10.1

:Dictionary {word}
an interface to see atp-:Dictionary.

instead of :EditInputFile

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

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 g:atp_imap_over_leader.

The value of g:atp_MapSelectComment is now =c (it used to be _c) You can also use vip over commented lines to select them.

New math imaps: (atp-imaps-math)

++\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.

:TOC and :Labels commands when open together will be in one column wtith 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 statrs/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.

Changes in version 9.7.4

See atp-completion-packages: the variable g:atp_package_{p_name}_command_values was added. Some new packages are now supported (for the completion).

You can read now about imaps implementation: atp-imaps. There are new font imaps: ##fr (\mathfrak{}) and #cr (\mathscr{}), see atp-imap-fonts. Also the imaps ##cal, ##fr, ##cr, ##bb when used in text mode will insert '\(' (or '$' for tex files), which opens the LaTeX math mode.

_> and <_ imaps for \Rightarrow and \Leftarrow.

Deleted some imaps to non existing uppercase greek letters. There are imaps togreek letters:

\varpi #vp
\varphi #vf
\vartheta #vo
\varsigma #vs
\varepsilon #ve

The main change is the speed up of writing in insert mode by consolidation autocommands for CursorMovedI group and changing them when they are actually run. This is used for defining imaps, see atp-imaps, and for setting vim options in LaTeX math mode, see g:atp_MathVimOptions.

g:atp_no_python -- set this to one if you want to switch off python. (This is not yet well integrrated but might help).

New imap

t* \times

Changes in version 9.7

The g:atp_imap_first_leader, g:atp_imap_second_leader, g:atp_imap_third_leader, g:atp_imap_fourth_leader variables are now called: g:atp_imap_leader_1, g:atp_imap_leader_2, g:atp_imap_leader_3, g:atp_imap_leader_4.

See b:atp_MaxProcesses and b:atp_KillYoungest.

The variables b:atp_TexOptions, b:atp_StarEnvDefault, b:atp_StarMathEnvDefault are added to g:atp_ProjectLocalVariables.

See g:atp_imap_diacritics_inteligent how to write diacritics with ATP.

Tikzpicture keyword completion is only active in non expert mode (atp-completion-non-expert-mode). See atp-completion-tikzpicture.

atp-:LocalCommands will make abbreviations to found environments.

See atp->f for two new motions made for beamer frame environment.

See atp-completion-documentclass-options, atp-completion-pacakages-options.

Q? and Q/ searching maps removed.

Some new imaps:

`Dsee in atp-imap-math-misc.

+ Many Small Bug Fixes :)

Changes in version 9.6.1

The main work was to make ATP web page: with proper html version of documentation at

New imaps added: see atp-imap-diacritics. Read also paragraph before atp-imap-math. The command atp-:ToggleMathIMaps is now called atp-:ToggleIMaps and also toggles atp-imap-diacritics.

I added to doc section about latexmk interface: atp-:Latexmk, atp-:LatexmkStatus, atp-:LatexmkClear, atp-:LatexmkStop. The LatexBox commands :LatexmkForce, :LatexmkStatusDetailed and :LatexmkClearAll are simulated with bang.

imap ++ \sum (which can be turned off with :ToggleIMaps or ' imap and nmap)

Several small fixes (thanks to user reports on the atp-mailing-list!)

Changes in version 9.6

Some functions where rewritten in python making ATP much faster.

ATP loads 1/3 faster (after first run when you save project file, which is done when you save your file!).

Use g:atp_no_local_abbreviations if you don't want to have abbreviations to locally defined environments (this takes time if your vim was compiled without |+python| feature, as it runs atp-:LocalCommands command - which is slow in this case).

Note: the python version of LocalCommands will save the current buffer, without saving project script and with 'nowritebackup' and 'nobackup' set.

I added b:atp_LocalEnvironments, b:atp_LocalCommands and b:atp_LocalColors to g:atp_ProjectLocalVariables if vim doesn't have +python feature otherwise g:atp_local_completion is set to 2, hence atp-:LocalCommands is run with BufEnter. It is so because the function LocalCommands was written also in python which is more than 10 times faster than the old vim implementation.

atp-:ViewOutput -- removed the [sync] argument.

atp-:BibSearch is written in python. It is much faster. Thus the argument should be a python regular expression. If you want to use vim script (and vim regular expression) set g:atp_bibsearch="vim". Then both Tab Completion and atp-:BibSearch will use vim code.

Tab completion for labels (\ref and \eqref commands) gives more information inside the popup menu.

The F2 map is back -- it turns on/off cmap to \_s\+. But this time this map by default is turned on. It is made to it doesn't interact with other command modes than / and ?. If you want to turn in off/on use F2. If you want to turn it off in your vimrc or atprc files use:

let g:atp_cmap_space = 0
Pressing F2 will define this map.

Some other small fixes.

Changes in version 9.5

The keys j, k, gj and gk are no longer mapped by ATP. There is a better solution for updating the Table of Contents highlighted line. It is done using autocommand CursorHold.

See the new command atp-:Tags.


This used to be :DefiSearch. This I found more in vim style. Also g:atp_DsearchMaxWindowHeight is used instead of g:atp_DefiSearchMaxWindowHeight.

g:atp_statusOutDir fixed.

g:atp_IMapCC instead of g:atp_MapCC.

And bunch of other fixes :).


Checkout cmdalias plugin (vimscript#745). It lets define lower case aliases to commands. You can put in your atprc file:

Alias tex TEX
Alias toc TOC

Changes in version 9.4

ATP and Gentoo Linux

Thanks to Tim Harder there is a gentoo ebuild, if you use gentoo check for automatictexplugin in the portage tree.


Small but nice change in closing environments: If you type \begin{envname} the cursor position will not change. You can use i_CTRL-M (i_CTRL-J is used by atp-j_motion) after to open new line inside {envname}. Otherwise the cursor position will be right after the closing \end{envname}.

Local Commands


-- do not search in comments,
-- add single { if command has defined arguments.

Note: the format of viewer options has changed from a string to a vim list. Every option and its value should be placed as a separate element of vim list. See atp-Viewers_Options for examples.

New imaps

New imaps for some commonly used math commands: see atp-imap-math.

All mathematical imaps: for symbols, greek letters, are defined only when inside LaTeX (or TeX) mathematical environment.

There is new predefined layout for environment imaps available, but disabled by default. If you like longer and more intuitive environment insert mode maps set g:atp_ShortEnvIMaps=0 in your vimrc or atprcc files. Use atp-:HelpEnvIMaps to see them. There is also one new environment ]let in this new layout which inputs a letter environment. If you want a short imap for it you can set g:atp_imap_letter="w" and ATP will make a map ]w for it. Note that "l", and "L" are already taken and using "le" will slow down "l", also "e" and "r" are used, so there is no good choice for it. You can set g:atp_letter_opening and g:atp_letter_closing to customize default opening and closing statements.

If you decide to use short imaps (the default) there is one change: ]i is mapped to \item and ]I is mapped to itemize environment (this is the only type of change in the short layout. In long layout ]I is mapped ot \item and ]ite is mapped to itemize environment.

There is also a small change with completion: after typing \begin{envname} the cursor will not move, so you can use |i_CTRL-M| to open new line.

The abbreviations are customizable: g:atp_imap_{envname}, also the leader is customizable with g:atp_imap_third_leader and environment names for example if you set g:atp_EnvNameTheorem="thm" then ]the imap will insert \begin{thm}:\end{thm} pair. You can list supported environments with ':let g:atp_EnvName'. If you set g:atp_imap_{envname} to empty string "" the corresponding imap will not be defined.

See also atp-:ToggleMathIMaps.

New Motions

There are two more nice map >E which is something like %>e, i.e. jump over the current environment and go to next one. The reverse E you can put this in your |atprc| file:

map >E JumptoNextEnvironmentzz
map JumptoPreviousEnvironmentzz

atp--S, atp--s, atp--c, atp--p new maps for atp-:SSec, atp-:Sec, atp-:Chap and atp-:Part. They also works relatively to the current unit (section/chapter/part), i.e. 2]s will jump to second section of the current chapter.


b:atp_updatetime_insert can be changed on the fly to 0 (previously it requires to quitting vim and making changes in vimrc/atprc files.

Make LaTeX

atp-:MakeLatex is rewritten in python. The "!" is not yet implemented.

Python 3 compatibility

All python scripts are compatible with Python 3. Traceback info is forwarded to vim (and log files) in case exceptions are handled.


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.

Status Line

Status notifications has the ability to show if b:atp_BibCompiler, or "makeindex" are running. Unless |g:atp_statusNotif|=0 or g:atp_callback=0 atp-:MakeLatex will echo a single message when it returns.

There is also new status line for QuickFix window with number of errors and warnings printed (this depends on b:atp_ErrorFormat).

Biber and BibLaTeX Support

Support for biber and biblatex is added (in atp-:MakeLatex, atp-:Bibtex, atp-:Delete, atp-:InputFiles commands), g:atp_keepp variable will adjust on the fly (add run.xml and bcf extensions). b:atp_BibCommand will be set to biber if the preamble contains \usepackage[backend=biber]{biblatex}

If you use biblatex, it 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 work slightly faster.

TeX Options Variable (new format)

b:atp_TexOptions is a comma separated list of TeX compiler options. If you use g:atp_Compiler="bash" this might be just a white space separated list.


Space cmap

cmap \_s\+
cmap \_s\+

The C-Space Vim, instead C-@ is used which works as C-Space. In Vim, and gVim as well, you can also use atp-Q/, atp-Q? where is mapped to \_s\+.

Note: from version 9.6 Space is mapped to \_s\+ in cmdline modes / and ?. F2 turns it on/off. The above maps are always on.


nmap <LocalLeader>e

To get list of errors with current b:atp_ErrorFormat.

:ErrorFormat {efm}

This is new interface to :SetErrorFormat. If {efm} is not given it will show the current value b:atp_ErrorFormat. It sets the variable b:atp_ErrorFormat and rereads the log file with |cgetfile|. The variable b:atp_ErrorFormat is also set when you use the command atp-:ShowErrors. In addition you can use +{flag} and -{flag} as an argument, then {flag} will be added/removed from b:atp_ErrorFormat.

EasyMotion and ATP

If you want to use EaseMotion 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 in plugin/EasyMotion.vim add let g:atp_changedtick = b:changedtick You might want to change g:EasyMotion_leader_key (see |easymotion-leader-key| if you have EasyMotion), 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.

Select Comments nmap and vmap is now |_c| (previously \sc was interfering with an ATP font map).

(Almost all) maps became :map-silent.


The atprc file is now sourced twice at startup: at the beginning to set the variables, and once again at the end to set the maps defined in it.


Despite the status line for quick fix window, :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
You can also put this in your atprc or |vimrc| file.



if you want to develop/debug ATP set g:atp_atpdev to 1 run atp-:ReloadATP and this command will allow to print (cat) debug files under g:atp_TempDir.

I hope I didn't missed anything important. If you want to see detailed changes you can always read the svn logs at atp-sourceforge.

Chears, Marcin


Neccessary 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 this link for other ATP requirements.

Get ATP Updates

To get updates it is enought 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).

Requires python.

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


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 symultanous 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 processes.

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 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. The key 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.

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 enhancments (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 stores the return code of compilation.

See atp-requirements-python for nonstandard python libraries that are used by ATP.

Call Back and Debug Mode

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:

* Status Line Notification: status line can show if tex is running
let g:atp_status_notification = 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.

* The log file will be automatically read after compilation (:cgetfile).
* 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).
* if t:atp_DebugMode = 'silent'
:DebugMode silent
nmap s
You will not get any message from compilation.
* if t:atp_DebugMode = 'debug'
:DebugMode debug
nmap 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' mode).
* if t:atp_DebugMode= 'Debug'
:DebugMode Debug
nmap D
This mode is the same as 'debug' + after compilation ATP jumps to first error.
* 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 errorstopmode).

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. (b:atp_ProgressBar is a dictionary { 'pid' : 'pagenr' } - status line shows max of pagenr's).

Note: the time between you start to compile and [1] appears in the status line is mostly the time when LaTeX is reading all the packages that you loaded in the preamble.

This is a read only variable. It is equal to empty string '' if compilation is not going on, and while compilation it stores the page number which LaTeX is processing.

g:atp_DebugModeQuickFixHeight = 8
You can invoke compiler in the 'debug' mode with '||d', '||D' for 'Debug' mode (jump to first error), '||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_DefaultDebugMode.

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]
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[!] silent
(:DebugMode[!] s)
nmap s
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'.
:DebugMode debug
(:DebugMode[!] d)
nmap d
It will load error file (|cgetfile|) and open |quickfix| window with |:copen|. Sets |t:atp_DebugMode|='debug'
:DebugMode Debug
(:DebugMode[!] D)
nmap D
It will load error file (|cgetfile|) and open |quickfix| window with |:copen|. Sets |t:atp_DebugMode|='Debug'
:DebugMode verbose
(:DebugMode[!] v)
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 g:atp_DebugModeQuickFixHeight.

Works slightly different than |:copen|. The [height] argument will not take efect. Use |:resize| instead. ATP computes the hiegth 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 reloaded).

There is also a variable which stores the last command which executed your tex compiler, see |g:atp_TexCommand|.

Compilation Commands

:{runs}TEX[!] [debug_mode]
map \l, map \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 {runs} 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)

Without "!" it copies the aux file only if there are no compilation errors, with "!" it updates the aux file even if there were errors. This is done to make the labels completion work better, when there are errors they often affect the aux file in a way that interferes with atp-:Labels command.

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 number).

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 atp-debug-mode.

\d is mapped to :TEX debug and \l to :TEX (thus it uses your default debug mode).

map \d
This is equivalent to ':TEX debug'.

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 algorithms. ':MakeLatex!' should be used when an entry in the bibliography was deleted (when 'bibtex' is involved this is when you delete last citation command of a bib entry).

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 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 only).

:Bibtex[!] [debug_mode]
map \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 afterwards.

Wihtout BANG "!" If you want to just run bibtex use :Bibtex without bang.

The command :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'.

Kill python scripts running (b:atp_PythonPIDs) and all pids in b:atp_LatexPIDs. This only works with g:atp_Compiler="python".

Prints PIDs of all running instances of b:atp_TexComopiler.

:Compiler {compiler-program}
Command which help to set b:atp_TexCompiler variable (with completion).

This is a command which sets the b:atp_OutDir variable and the |'errorfile'| option. See b:atp_OutDir for the default value.

Latexmk Interface

Compile with latexmk in background. With bang "!": Force compilation with latexmk in background.

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.

LaTeX Errors

:ShowErrors [flag]
nmap 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, which is a word made of letters:

e- include errors
w- include all warning messages
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 packages loaded by tex
(messages which start with 'Package: ')
all- show all above,
All- show All the log file,
o- open the log file in a new buffer (split).

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 r
will show all reference and citation warnings.

Note: this command works in quickfix window. It will change errorformat but will not reload quickfix list. Better use atp-:ErrorFormat instead.

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 b:atp_ErrorFormat.

ShowErrors maps:

view errors with current b:atp_ErrorFormat
to see all errors
:ShowErrors e
to see all warnings
:ShowErrors w
to see warnings coming
from references or citations
:ShowErrors rc
to see font warnings
:ShowErrors f

this is not a texloganalyzer mapping but it is a good place to mention it:

to open log file in a new split window this is a mapping to the atp-:OpenLog.

:ErrorFormat {flag}
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 atp-:ShowErrors.

As an argument you mey use +{flag} and -{flag} then {flag} will be added/removed from |b:atp_ErrorFormat|, example:

:ErrorFormat +w
will add 'w' to |b:atp_ErrorFormat|. Note: this command works in quickfix window.

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
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 (log) and atp-:SyncXpdf (log)) These tools can sync tex file/Xpdf automatically using autocommand group |CursorMoved|.

:SyncTex[!] (inside log file)
nmap \g
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_SyncLog = 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_SyncLog you can use :Sync command. ':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_developer = 1 this command will also go to files under texmf tree (packages and classes).

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.


map \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, b: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.

map t, map
Which makes an forward search (vim->Viewer). As for now ATP supports Okular, Xpdf and Xdvi with this feature (Evince is not yet supported).

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

Note: with bang atp-:SyncTex will not check if viewer is running.

Read atp-:SyncTex_with_Okular if you use Okular.

:Viewer {viewer-program}
Command which help to set b:atp_Viewer variable (with nice completion).

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)

(although dvi is using srcspecials rather than synctex)
map t
nmap <S-LeftMouse>
For inverse searching hold CTRL and 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 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.

Bib Commands

:BibSearch /{pattern}/ [flag]
See atp-:BibSearch
This command finds bib entries in bib files defined in your tex file and in the variable b:atp_BibFiles (see 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 g:atp_bibref.

map c, map y, map p
See atp-:BibChoose
This function is defined in the buffer with results of BibSearch command. It is mapped to 'y', 'c' and 'p' and let you copy the bib entry key to a register (see |atp-:BibChoose|) or directly to last opened buffer (after the last cursor position). When you choose to paste, it will close the BibSearch window.

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. This function is called internally be the script functions BibSearch/BibChoose. The command :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.

Open Files

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{}, \input \include{}. 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 g:atp_bibinputs).

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 or \documentclass tex 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|.

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-separeted list of directory names. You should use wildcards '**' 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. <\a>

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]
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 hardcoded in ATP (it is too slow to get it), since the dictionary evolves it might contain new entries.

map 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 the extensions from |g:atp_DeleteWithBang| are removed from |g:atp_tex_extensions|. The defualt value of |g:atp_DeleteWithBang| contains for exemple '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=@' it will print via ssh on the 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 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.

Wrapping Tools

:WrapSelection {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 [endWrapper] is '}'. The last argument [new_lines] 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 and environment \begin{}:\end{}.

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

:InteligentWrapSelection {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-:WrapSelection. If the opening leader in is not given then this command is not wrapping the text (see below for the suggested map '\tx').

The command arguments should be separated with commas and quoted separately (see ||).

For the predefined maps which use atp-:WrapSelection see below atp-maps-InteligentWrapSelection or use atp-:HelpVMaps.

These are the provided maps in visual mode:

vmap <buffer> \rm :<C-U>InteligentWrapSelection ['\\textrm{'], ['\\mathrm{']<CR>
vmap <buffer< \em :<C-U>InteligentWrapSelection ['\\emph{'], ['\\mathit{']<CR>
vmap <buffer> \it :<C-U>InteligentWrapSelection ['\\textit{'], ['\\mathit{']<CR>
vmap <buffer> \sf :<C-U>InteligentWrapSelection ['\\textsf{'], ['\\mathsf{']<CR>
vmap <buffer> \tt :<C-U>InteligentWrapSelection ['\\texttt{'], ['\\mathtt{']<CR>
vmap <buffer> \bf :<C-U>InteligentWrapSelection ['\\textbf{'], ['\\mathbf{']<CR>
vmap <buffer> \bb :<C-U>InteligentWrapSelection ['\\textbf{'], ['\\mathbb{']<CR>
vmap <buffer> \tx :<C-U>InteligentWrapSelection ['\\textrm{'], ['\\text{']>CR<
vmap <buffer> \sl :<C-U>WrapSelection \\textsl{<CR>
vmap <buffer> \sc :<C-U>WrapSelection \\textsc{<CR>
vmap <buffer> \up :<C-U>WrapSelection \\textup{<CR>
vmap <buffer> \md :<C-U>WrapSelection \\textmd{<CR>
vmap <buffer> \un :<C-U>WrapSelection \\underline{<CR>vmap <buffer> \ov :<C-U>WrapSelection \\overline{<CR>
vmap <buffer> \n :<C-U>InteligentWrapSelection ['\\textnormal{'],['\\mathnormal{']<CR>
vmap <buffer> \cal :<C-U>InteligentWrapSelection [''],['\\mathcal{']<CR>
vmap <LocalLeader>mb :WrapSelection \\mbox{ } begin<CR>
Suggested maps:
vmap <buffer> \tx :<C-U>InteligentWrapSelection [''],['\\text{']<CR>
vmap <buffer> \in :<C-U>InteligentWrapSelection [''],['\\intertext{']<CR>"
The leader '\' in above commands is configurable: the value of
g:atp_vmap_text_font_leader is used (the default value is <LocalLeader>).

Another provided font wrapper:

vmap LocalLeaderf :exe ':WrapSelection {\usefont{'.g:atp_font_encoding.'}{}{}{}\selectfont\ }'.(len(g:atp_font_encoding)+11).'<CR>'
Where the variable:

stores the default encoding which is 'OT1', unless you use fontenc package, then the default for fontenc is used (the last defined in \usepackage[...]{fontenc} see the 'Latex2e font selection' /font user guide/ available on CTAN).

Other wrappers:

vmap m :WrapSelection \( \)<CR>
vmap M :WrapSelection \[ \]<CR>
vmap <LocalLeader>( :WrapSelection ( ) begin<CR>
vmap <LocalLeader>[ :WrapSelection [ ] begin<CR>
vmap <LocalLeader>{ :WrapSelection { } begin<CR>
vmap <LocalLeader>) :WrapSelection ( ) end<CR>
vmap <LocalLeader>] :WrapSelection [ ] end<CR>
vmap <LocalLeader>} :WrapSelection { } end<CR>
vmap <LocalLeader>b( :WrapSelection \left( \right) begin<CR>
vmap <LocalLeader>b[ :WrapSelection \left[ \right] begin<CR>
vmap <LocalLeader>b( :WrapSelection \left( \right) begin<CR>
vmap <LocalLeader>b[ :WrapSelection \left[ \right] end<CR>
vmap <LocalLeader>b{ :WrapSelection \left{ \right} end<CR>
vmap <LocalLeader>b{ :WrapSelection \left{ \right} end<CR>
And the maps to put the selected text into an environment:
vmap <LocalLeader>A :WrapSelection \begin{align} \end{align} 0 1<CR>
vmap <LocalLeader>C :WrapSelection \begin{center} \end{center} 0 1<CR>
vmap <LocalLeader>E :WrapSelection \begin{equation} \end{equation} 0 1<CR>
vmap <LocalLeader>L :WrapSelection \begin{flushleft} \end{flushleft} 0 1<CR>
vmap <LocalLeader>R :WrapSelection \begin{flushright} \end{flushright} 0 1<CR>
The leader can be changes using the variable g:atp_vmap_environment_leader (its default value is <LocalLeader>). Note: that the arguments for this command must be put in ':' or ":". the highlighted text will put inside \textbf{ }.

You can also use a wrapper which was yanked into register 'a':

:WrapSelection @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 \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.

Motion Commands

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

nmap \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 \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.

TOC() supports many edited files. For example 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 q 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, q 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.

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 \t).

map \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 ' 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).

: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 atp-:Tags.

:GotoNamedDest <destination_name>
{only in Xpdf}
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.

:[count]F {arg}
Go (forward) to {arg}, {arg} might be: part, section, subsection, subsubsection, and defined environment. You can use command completion which uses all the locally defined environments.

:[count]B {arg}
Go (backward) to {arg}, like above atp-:F.

:NEnv {environment}
:[count]F {environment}
[count]map >e
[count]map <C-F>
Move to next environment, for example ':NEnv definition'. Completion is set, which finds environments defined in current tex source file. This function omits environments in comment lines.

{environment} can be also math or displayedmath. For convenience there are maps: }m and }M respectively.

If g:atp_mapNn is set to one (see atp-:ToggleNn) then this command is using atp-:S.

:PEnv {environment}
[count]:B {environment}
[count]map <e
[count]map <C-B>
Move to previous environment, for example ':NEnv definition'. Completion is set, which finds environments defined in current tex source file. This function omits environments in comment lines.

{environment} can be also math or displayedmath. For convenience there are maps: {m and {M respectively.

If g:atp_mapNn is set to one (see atp-:ToggleNn) then this command is using 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: part/chapter/section/subsection/subsubsection.

Map Command Meaning
go to next part
go to next chapter
go to next section
go to next subsection

You can set the leader '>' using g:atp_map_forward_motion_leaderr variable.

Note: If you leave the default value of g:atp_map_forward_motion_leader 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_map_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.

: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. "g:atp_map_backward_motion_leader"

You can set the leader '<' using g:atp_map_bacward_motion_leader variable.

The {section} argument for :B is one off: part/chapter/section/subsection/subsubsection.

For description of arguments read atp-:NextSection just above.

go to previous part
go to previous chapter
go to previous section
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_mapNng: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 leave the default value of g:atp_map_forward_motion_leaderr 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_map_forward_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.

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 aplies to other section types.

You can set the leader for maps with g:atp_goto_section_leader.

nmap ]* gc
Go to end of current/next comment group.

nmap [* gC
Go to begining of current/previous comment group.

Environment Tools

map <LocalLeader>s
Add/removs a star from the current environment (if it is not one belonging to the list:
See b:atp_StarEnvDefault and b:atp_StarMathEnvDefault.

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

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

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). Check if it works for you! If there is a label or reference to which it wants to change it doesn't change labels and issue a Warning Message, thus I believe it should work for every one, but as this changes your file it is turned off by default.)

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 anvironment 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 {==} for \textcolor{red}{} and {++} for \textcolor{blue}{}. 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).

Definition Search

:Dsearch[!] [/]{pattern}[/]
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).

It works likes ]d but handles multi line definitions.

You can set the maximal hieght of the window wich shows the results of atp-:Dsearch (default is 15).

Font Search and Preview

: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 'T1')
: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)
ppreview the fonts defined in the fd file under the cursor, do not shows the latex source.
Ppreview 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 :) )
qclose 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 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 :).

Various Commands

This comman 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. The status line will also contain the information about processing compelation: 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 *.tex :call Status()
In this way every opened window with a '*.tex' file will get the correct status line.

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.

ToDo({keyword}, {stop}, [bufname])
:ToDo [bufname]
:Note [bufname]
The function list all the lines of the buffer [bufname] which match for the pattern '%.*{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='\c\' and stop='\s*%.*\c\', and the command :Note sets keyword='\c\' and stop='\s*%.*\c\'. This prevent from listing ToDo lines with Notes and vice versa.

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 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_keymaps 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 then the function 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).

lists LaTeX packages defined in the preamble.

echoes the preamble to vim pager.

Reloads ATP plugin: variables, functions, and maps. Note that maps are not deleted.

Table of Contents Window

For the table of contents command and maps read atp-:TOC.

The Table of Contents window is used by both atp-:TOC and atp-:Labelss commands.

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),
's'it splits the window with your tex source file and sets the current line to the beginning of the chapter/section under the cursor,
'q'to quit, and finally,
<Enter>to go to the chapter under the cursor and close ToC.
<space>to go to the chapter under the cursor but leave ToC open.

There are also commands: ':C' and ':P', which do the same as 'c' and 'p' mappings. They all call the function 'Yank()', the argument <where> can be one of: '@<register name>' or 'p'.

You can also delete and paste sections using the Table of Contents window:

These commands are available in table of contents. They act on parts/chapters/sections/subsections/subsubsections.

: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 (|registers|).

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

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.

Searching in Bib Files

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]

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 python regular expression not vim regular exression. 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.

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

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 example:
'^\(\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 first 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 KeyWordFlags).

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

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, { '' : [ '': ''] })
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:

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
:BibChoose {BibEntry[RegisterName]}
map c, map y, map p

This 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 yank:

	    <bib entry number><register name><Enter>	- to copy it to a register
	    <bib entry number><Enter>			- to paste it to 'tex' file
	    <Enter>					- to skip the choice
When you paste the bib entry key the bib search window will close. For example:
:BibChoose 5e
:BibChoose 7+
:BibChoose 2
Copy the bibkey to register e,+ or paste directly to the buffer in which :BibSearch was invoked, at last cursor position.

The same you will obtain using the nmaps y or c.

This commands and maps are only in the BibSearch buffer.

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


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 on the 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 }


The completion is by default mapped to . For example if you type \math 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 beginning, 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 not map <Tab> key then you can define g:atp_no_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_tab_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 Tab completion.

NOTE: if you press <Tab> but then you changed your mind, the completion pop-up menu allows to cancel completion: press ctrl+p (i.e. go up - some times more than once) and then press <space>.

Note: 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.

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.

Completion Modes


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 '^ams').

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 temporarily).

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

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 atp-ProjectScript).


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 #1, or #1#2, etc.) a single '{' is attached. It doesn't match for definitions inside comments.

Note: the python version searches for commands, environments, ... defined in the begining of line (with possible white spaces).

Note: the python version of LocalCommands will save the current buffer, without saving project script and with 'nowritebackup' and 'nobackup' set.


There is an extended support for tikz picture environment both inline \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 {:}.


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 (CTRL-X CTRL-O, 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} 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).


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 \{:\}.


Completes after '\begin{' and '\end{'. For example '\begin{cen' will give '\begin{center}' But '\begin{theorem}' or '\begin{theorem}\label{thm:1} 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} the cursor position will not change. You can use |i_CTRL-M| (|i_CTRL-J| is used by |atp-j_motion|) after to open new line inside {envname}. Otherwise the cursor position will be right after the closing \end{envname}.

See g:atp_amsmath.


(the <Tab> indicates in which position the <Tab> can be pressed to get the described behaviour).

				    \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!


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 omitted).

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.


Completion for the command '\bibliographystyle{'. Finds all "bst" files available in your tex distribution.


Completion for the command '\documentclass'. Returns list of all classes available in your distribution.

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', '100' ]

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{:\end{	
	    the fourth	 	- for environments defined in the variable


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 remove()').

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 in \label{ when completing the \label command.

g:atp_separator = ':'

It is used as a separator in: \label{ when completing the \label command.

g:atp_no_separator = 0
g:atp_no_separator_list = ['', 'titlepage']

The following variabe 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 = { '(' : ')', '{' : '}', '[' : '] }
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.

Omni Completion

by David Munger (LatexBox plugin)

Completion is achieved through omni completion |compl-omni|, with default bindings <CTRL-X><CTRL-O>. There are four types of completion:


Command completion is triggered by the '\' character. For example,

completes to

Associated settings:


Environment completion is triggered by '\begin{'. For example, >

completes to

Completion of '\end{' automatically closes the last open environment.

Associated settings:


Label completion is triggered by '\ref{' or '\eqref{'. For example, >

offers a list of all matching labels, with their associated value and page number. Labels are read from the aux file, so label completion works only after compilation.

It matches:
1. Labels:

2. Numbers:
3. Labels and numbers together (separated by whitespace): >
\eqref{eq 2<CTRL-X><CTRL-O>

Associated settings:

BibTeX Entries

BibTeX 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>

You can also use regular expressions (or Vim patterns) after '\cite{'.

Associated settings:

let g:LatexBox_cite_pattern = '\\cite\(p\|t\)\?\*\?\_\s*{'
let g:LatexBox_ref_pattern = '\\v\?\(eq\|page\)\?ref\*\?\_\s*{'

Patterns to match \cite and \ref commands for BibTeX and label completion. Must include the trailing '{'. To match all commands that contain 'cite' (case insensitive), use:

let g:LatexBox_cite_pattern = '\c\\\a*cite\a*\*\?\_\s*{'
To match all commands that end with 'ref' (case insensitive):
let g:LatexBox_ref_pattern = '\c\\\a*ref\*\?\_\s*{'
Both examples match commands with a trailing star too.

let g:LatexBox_bibtex_wild_spaces = 1

If nonzero, spaces act as wildcards ('.*') in completion. For example, if nonzero, >

\cite{Knuth 1981
is equivalent to >

let g:LatexBox_completion_close_braces = 1

If nonzero, omni completion will add closing brackets where relevant. For example, if nonzero,

completes to


Static completion lists for environments atp-omnicompletion-environments and commands atp-omnicompletion-commands.

How to Configure ATP to Your Needs

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.

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 \l, imap \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 atp-:Compiler.

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

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 is a comma ',' sepparated list of TeX compiler options. 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 apt-:ShowOptions command.

If in your environment the variable $TEXMFOUTDIR is set the value of b:atp_OutDir will be set to its value.

See b:atp_MainFile.

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 = $HOME/texmf
This variable configures where input files are placed. See atp-:EditInputFile.

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:

, etc ... (also global variables g:atp_...Options) Used by function: ViewOutput() (map \v, map <F3>, imap <F3>)

These are lists in which every viewer switch and its value should be placed as element (seprate!). 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']

let b:atp_XpdfServer=fnamemodify(expand("%"),":t")
Used by function: ViewOutput() (map \v, map <F3>, imap <F3>)

It is equal to the name of the source file. 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 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 variable.

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 compelation is being done (this can cause problems when there are many TeX processes and the Viewer is accessing not yet compilated file). The output files are copied back to b:atp_OutDir after compelation. The tmporary directory is passed to your TeX compiler using '-output-directory' switch.

In this direcory 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 permissions.

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.

see atp-bibflags:default
see atp-bibflags:all
see atp-bibflags:last
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 globale 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 t:labels_window_width) 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 characters.

This two variables stores the information returned by
'kpsewhich -show-path tex'
They are locked. The first one has pretended '**' wildcards to every directory, which is done for using with globpath() and findfile() functions.

variable with default value 0 ("no"). Its values are 0/1 or yes/no. It changes the behaviour of '%'. In nocomatible mode it gen go to matching pair in a different line in compatible mode it find the matching pair only if the ending bracket is in the same line.

Writing Projects

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

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.

g:atp_RelativePath = 1
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]
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, atp-:NEnv, atp-:PEnv.

The default value of g:atp_mapNnis 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

The file: b:atp_MainFile . ".project.vim", in the same directory as b:atp_MainFile stores values of local variables saved before Vim leaved a buffer (it is very similar to |View|). Also values of some global variables are stored in a seprate file (oine for all tex files).

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. If none of the project scripts was containing the current buffer name in b:ListOfFiles then 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.

If the project script is stored locally the it is easier to include it in a revision system (bzr, svn, etc.) and share it with collaborators.

The global project script (which, by default, stores global variables: g:atp_LatexPackages, g:atp_LatexClasses, g:atp_Library) is now '~/.vim/ftplugin/ATP_files/common_var.vim'.

atprc file is executed before project script file (with local variables) and common_var.vim (with global variables) files are sourced. Thus this files will override the settings in |vimrc| and atprc files.

b:atp_ProjectScript = 1
g:atp_ProjectScript (not set)
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.

let b:atp_ProjectScriptFile = b:atp_MainFile.".project.vim"
This variables stores the name of local project script file.

Local and global variables are supported. The local variables which are cached in this way 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_OutDir", "b:atp_auruns", "b:atp_ReloadOnErr", \ "b:atp_OpenViewer", "b:atp_XpdfServer", "b:atp_ProjectDir", \ "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 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|.

Each file has separate project scrips which stores the values Ef these variables. It's name is stored in b:atp_ProjectScriptFile.

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 list:

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
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") == let b:atp_ProjectScript = 0 endif
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]
:WriteProjectScript[!] [local/common]
:DeleteProjectScript[!] [local/common]
:ToggleProjectScript[!] [on/off]
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 globa 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") and 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 g:atp_ProjectLocalVariables 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 endif
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 list.

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

This works similarly to |:ijump|. But also goes back to the root file (b:atp_MainFile).

It sets the alternate file to the buffer from which the search begun. Note that this means that if nothing was found the alternate file before search will be lost.

The {pattern} is any Vim pattern as described in |pattern| (it was only tested with 'magic' set on).

The supported [flags] are 'bcewW'. Their meaning is the same as flags for |search()| function.

You can enclose the pattern with any non-ID character (see |'isident'|) instead of /, as far as it does not appear in the {pattern}. Examples:

:S pattern\_swith\_sspaces
will work but:
:S pattern with spaces
will not.

Note that the function might be slow when the project files where not yet opened.

There is a function to check where the input file is on the hard drive if the name in the input command doesn't include the full path. It asks kpsewhich which directories to search, filters out directories which are not under '/home' (I assume that there is your local texmf tree) and also directories which name contains one of the two keywords 'texlive' and 'kpsewhich'. This makes the searching faster.

Furthermore, the command is designed so that it can find all patterns '\\input' (and thus easily find next/previous input file). You can use:

:S \\input
:S \\input b

and you can use |n| and |N| Vim normal commands. Note that it if you go backward, then it means that it will find the most deep line, e.g.:

			\input{file.1} ---->  -------
':S /\\input/ b' in the X position fill find \input{file.1.1} assuming file.1.1.tex doesn't includes any other file.

The pattern can be '\\input'. Then it goes recursively to the first input line.

Now it also doesn't search inside commented input files. There two commands:

nmap ]gf, nmap >i
nmap [gf, nmap <i
which finds the next/previous input line (also commented). See atp-:S_input to find how it works. They depend on g:atp_mapNn, if 1 atp-S: is used if 0 Vim |search()| function. To repeat search you can use |n| and |N| Vim normal commands. These commands omit comment lines.


Lots of mappings which are given here uses #. This is a convenient map on British keyboards, but not in the US layout, you can change them for '`' or some other key that it is not used in Vim (there are not many of them though). The most commonly used latex-suite plugin uses similar set of mappings (but there might be some differences). The easy way to change imap leaders is by using the variables:

g:atp_imap_first_leader == "#"
for Greak letters and some math commands,

g:atp_imap_second_leader == "##"
for font commands, (another good choice is "_")

g:atp_imap_third_leader == "]"
for environments,

g:atp_imap_fourth_leader == "["
for extra environments in the old layout (this will be removed).

g:atp_map_forward_motion_leader == "<"
for maps to atp-:NInput, atp-:NSec, .... , atp->E, atp->e.

g:atp_map_backward_motion_leader == ">"
for maps to atp-:PInput, atp-:PSec, .... , atp-<E, atp-<e.

Note: the best way to list mappings with leader '#' in insert mode is to use

':imap #<CR>'.

You can list imaps with atp-:HelpMathIMaps and atp-:HelpEnvIMaps but the best way is to use |imap| directly.

All other mappings (|map|, |vmap|, |nmap|, ...) are using || which can be altered with the option |maplocalleader|. A good alternate solution is to use "_" instead of "##".

Maps are using the option thus are local to the buffer. To unmap you also have to use this option, for example to unmap \l issue the command:

:unmap <buffer> <LocalLeader>l
The maps are loaded unless you set one of variables: 'g:no_plugin_maps' or 'g:no_atp_maps' (disables maps defined in tex_atp.Vim), 'g:no_atp_toc_maps' (disables maps defined in 'toc_atp.Vim'), 'g:atp_no_env_maps' (disables the environment maps '[*', ']*') or 'g:atp_no_tab_map' (disables the tab map for completion, then completion is mapped to and (for the non expert mode) but there is no map for 'WrapSelection()', you have to provide one by your self).

Note: in all mappings '\' is set to your || (and thus, in fact, the maps listed below might differ).

Note: The list of commands might not be complete.

Note: There are many internal maps defined |<Plug>|, they are not documented, but you can easily find them (you can start with ftplugin/ATP_files/mappings.vim, where they are used in rhs of maps or you can search for them inside the scripts).

Note: you might like to use |'notimeout'| and |'nottimeout'| settings. However, they require that there are no maps such that no lhs is a subset ot the another, i.e. like "ab" and "abc". With the default settings it is shouldn't be a problem.

atp-j motion
atp-k motion

imap <Ctrl-j>, imap <Ctrl-k> - these are two motions (based on syntax) which help to navigate thought brackets (but not only) in insert mode.

map <Ctrl-j>, map <Ctrl-k>

- as above but in normal mode.

These motions emulate the behaviour of latex-suite place holder system <++>, without putting the placeholder into tex file.

map \l,imap \l
map <F5>, imap <F5>,
map \v,map <F3>, imap \v, imap <F3>

map \b
run only BibTeX, with bang [!] run LaTeX+BibTeX+LaTeX+LaTeX if you use g:atp_Compiler='python' and BibTeX returned with errors the compilation will stop. In the debug mode you will also get BibTeX output. It is stored in b:atp_BibtexOutput, BibTeX return code is in b:atp_BibtexReturnCode.

:ShowErrors o
map <F6>l, imap <F6>l

map <F6>d

map \t
This is a mapping to the command atp-:TOC

map \L
This is a mapping to the command atp-:Labels

nmap gf

nmap >m, nmap <m
Goto the beginning of next/previous math environment.

nmap >M, nmap <M
Goto the beginning of next/previous displayed math environment.

nmap ]], vmap ]]
Goto next \begin{

nmap ]], vmap ]]
Goto previous \begin{

nmap ]], vmap ][
Goto next \end{

nmap [], vmap []
Goto previous \end{

nmap gcl, vmap gc
Goto end of comment group (current or next if not in comment).

nmap gC, vmap gC
Goto begin of comment group (current or previous if not in comment).

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 eqaul 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 :).

nmap ]gf
Goto next input file.

nmap [gf
Goto previous input file.

Runs pdffonts command on pdf output file.

nmap \c, vmap \c
nmap \u, vmap \u

Comment/Uncomment lines (both in |Normal| and |Visual| modes).

Comment leader can be set with the variable g:atp_CommentLeader (by default it is '% '). If you do not want this maps or you want to remap them to something else you can set g:atp_MapCommentLines=0 in your |vimrc| or atprc file and use <Plug>CommentLines, <Plug>UnCommentLines (these are normal maps), for example:

nmap <LocalLeader>C <Plug>UnCommentLines
vmap <LocalLeader>C <Plug>UnCommentLines
A usefull map for uncommenting atp-_c (i.e. atp-select-comments).

cmap <buffer> <C-Space> \_s\+
cmap <buffer> <C-_> \_s\+
The <C-Space> map doesn't work in Vim, instead <C-@> is used which works as <C-Space>. In Vim, and gVim as well, you can also use |atp-Q/|, atp-Q? or atp-<F2> where <Space> is mapped to \_s\+.

nmap Q/, nmap Q?, nmap <F2>
Q/ and Q? to enter command-line window in which <space> is mapped to '\_s\+'. If you want to insert a white space type CTRL-V followed by <Space>.

<F2> acts as 'Q/i' (i.e. enters insert mode). If you want Q/ and Q? enter insert mode as well you can set: >

nmap Q/ q/:call ATP_CmdwinToggleSpace('on')<CR>i
nmap Q? q?:call ATP_CmdwinToggleSpace('on')<CR>i
in your atprc or |vimrc| file.

Font Commands

imap ##rm
imap ##it
imap ##sl
imap ##sf
imap ##bf
imap ##mit
imap ##mrm
imap ##msf
imap ##mbf

Greek Letters

Note: You can list this mappings using the command |atp-:HelpMathIMaps|. You might not see them using |:imap| unless the last cursor position in insert mode was inside mathematics.

Note: If you do not want imaps for greek letters you can set g:atp_ima_define_greek_letters = 0

imap #a
imap #b
imap #c
imap #d
imap #e
imap #f
imap #y
imap #g
imap #h
imap #k
imap #l
imap #i
imap #m
imap #n
imap #p
imap #o
imap #r
imap #s
imap #t
imap #u
imap #vs
imap #vo
imap #w
imap #x
imap #z

Not all upper Greek letters are in LaTeX:

imap #D
imap #Y
imap #F
imap #G
imap #L
imap #M
imap #P
imap #O
imap #S
imap #T
imap #U
imap #V
imap #W
imap #Z

Environment Imaps

By default the short environment imaps are defined, but if you set this variable to 0 you will get three letter abbreviations. The only clashes is for proof (pro) and proposition (Pro) environments and itemize (ite) and \item (I). You can also reconfigure them using the variables: g:atp_imap_{env_name} (for example g:atp_imap_theorem, if you don't want a map for particular environment set the corresponding variable to empty string ""), g:atp_imap_third_leader is used as a leader (the default is ]). Map for letter environment is not defined when you use short imaps.

Note: you can list this mappings using the command atp-:HelpEnvIMaps.
Note: This can be effectivly set only in atprc or |vimrc| files.

These maps are fully customizable: both sides: the lhs and rhs side ! Here is how you can set the rhs:

This variables defines environment names put it the following environment imaps.

variable with value "*" or "" (the default). This star is added to theorem like environment imaps (atp-imap-environments). By default it will be restored by the project script. See g:atp_ProjectLocalVariables.

variable with values "*" or "" (the default). It is added to align and equation imaps (atp-imap-environments). By default it will be restored by the project script. See g:atp_ProjectLocalVariables.

imap ]b
imap ]e
imap ]C
imap ]d
imap ]t
imap ]P
imap ]l
imap ]r
imap ]c
imap ]p
imap ]x
imap ]n
imap ]E
imap ]I
imap ]i

This map has more features: if the preceding line is of the form:

then using this map in a next line will result with
This will work for other types of items, (1) -> (2), 1) -> 2), [1] -> [2], 1. -> 2. and also (a) -> (b), b) -> c), [c] -> [d], but also (1a) -> (1b).

imap ]a
imap ]q
imap ]l
imap ]R
imap ]T
imap ]f
imap ]let

By default g:atp_letter_opening and g:atp_letter_closing are ''.

Next three sets of imaps: ">atp-imap-math, atp-imap-math-misc and atp-imap-diacritics define imaps with overlaping keys (lhs), but note that first two are defined only in math environment, while the last only in non math environment. In this way `' in math environment will produce \acute{} while in non math \'{}.

Math Imaps

These imaps are defined in g:atp_imap_math variable (except ]m and ]M imaps). They might be turned off usgin atp-:ToggleIMaps commands or g:atp_imap_define_math variable (be setting it to 0, works on the fly).

For convienience, there are:

imap ~~
imap ~^
\hat{} [^^ is used for ^{}]
If g:atp_imap_wide is set to 1 (default is 0) the above imaps to \widetilde{} and \widehat{}.

The last two maps and the following maps work around |'timeout'| vim setting (behave like |'notimeout'| was set):

imap ==
imap =~
imap ~~
imap ++
imap o+
imap O+
imap o-
imap o.
imap O.
imap o*
imap O*
imap s+
\cup [ set +]/set = set theoretic/
imap s-
\setminus [ set -]
imap S+
\bigcup [big set +]
imap s*
\cap [ set *]
imap S*
\bigcap [big set *]
imap c*
\prod [ cat *]/cat = categorical/
imap c+
\coprod [ cat +]
imap <=
imap >=
imap t<
imap t>
imap s<
\subseteq [ set <]
imap s>
\supseteq [ set >]
If you want to write 'o*' you can wait until |'timeoutlen'| passes or write 'o *' (TeX in math mode doesn't see spaces).

Math Imaps Misc

These imaps are defined in g:atp_imap_math variable (except ]m and ]M imaps). They might be turned off usgin atp-:ToggleIMaps commands or by setting the variable g:atp_imap_define_math to 0 (this should also work on the fly).

These are very useful mappings for typing mathematics. Some of the ideas were taken from TeX_9 by Elias Toivanen and also AuTeX by Carl Mueller.
Note: you might not see them using |:imap| unless the last cursor position in insert mode was inside mathematics.

AuTeX maps

imap __ _{}<Left>
imap ^^ ^{}<Left>
You can set the leader for these two maps using g:atp_imap_subscript, g:atp_imap_supscript variables. If you do not have any maps which begins with _ or ^ then you can set them to _ and ^, if this is the case thes maps will not be fired if you type \_ or \^ (which means literal _ or ^ in LaTeX).

Both above maps can be turned on/off on the fly with g:atp_imaps (1 - on, 0 - off). Use atp-:ToggleMathIMaps (mapped to ') to switch it on/off.

imap ]m \[\]<Left><Left>
imap ]M \[\]<Left><Left>
The following imaps can be turned on/off on the fly with g:atp_imap_define_math variable (0 - off, 1 - on). You can use atp-:ToggleMathIMaps (mapped to '<Tab>).

imap #\
imap #/
imap #&
imap #ve
imap #V
imap #N
imap #=
imap `8
\infty [the default '#' is not working, ` is used intead, but only if g:atp_imap_first_leader='#']
imap `6
\partial [as above, you can also use \p<Tab>]
imap #@
imap #=
imap #*
imap #+
imap #\
imap #>
imap #<
imap #.
\dot [#.s will put \dots]

Math Accents

These imaps are defined in g:atp_imap_math_misc variable. They might be turned off usgin atp-:ToggleIMaps commands or g:atp_imap_define_math_misc variable.

imap ``
imap `'
imap `>
imap `.
imap `v
imap `_
imap `~
\tilde{} [if g:atp_imap_wide is nonempty it is \widetilde{}]
imap `^
\hat{} [as above]


These maps are defined in g:atp_imap_diacritics variable.They might be turned off usgin atp-:ToggleIMaps commands or g:atp_imap_define_diacritics variable (be setting it to 0, works on the fly).

imap `'
imap `"
imap `^
imap `v
imap `b
imap `d
imap ``
imap `H
imap `~
imap `.
imap `c
imap `t


nmap, imap '<Tab>
This command toggles off/on impas defined in the vim lists g:atp_imap_math, g:atp_imap_math_misc and g:atp_imap_diacritics plus _ for _{} and ^ for ^{}.

Log File Maps

This are available maps in the log file, when it was opened with atp-:OpenLog command

- go to next/previous error message in log file
- go to next/previous warning message in log file
- go to next/previous citation warning message in log file
- go to next/previous reference warning message in log file
- go to next/previous info message in log file
- go to next/previous font info message in log file
- go to next/previous font package message in log file
- go to next/previous page in log file
- searchpair for (:).
You can use |n| and |N| Vim normal commands to repeat previous search [count] times.


The following abbreviations are defined:

	+- for \pm
	+| for \dagger
	++ for \ddager
	=<env_name>= for environments.

You can use atp-completion (<Tab>) for abbreviation names, see atp-completion-abbreviations.

Locally defined environments are also supported (the one defined in b:atp_LocalEnvironments). If you need something different than abbreviation for

	     <Cursor placed here>
for example:
You can set the variable g:atp_abbreviation_{environment_name}. It is list with two elements. First is used after \begin{...} and the second after \end{...}. For the above examples:
let g:atp_abbreviation_theorem = [ '<CR>', '<ESC>O' ]
let g:atp_abbreviation_corollary = [ '<CR>', '<ESC><UP>A' ]
The first one is the default so you do not need to set it. In the second example the abbreviation command will look like:
abbreviate =corollary= \begin{corollary}<CR>\end{corollary}<ESC><UP>A
This will only work for b:atp_LocalEnvironments, LaTeX and AMS environments are set accordingly. Environment name abbreviations are defined only if there were not defined. So you can override the settings using atprc file (or |vimrc| file).

Furthermore, you can change the "=":

let g:atp_iabbrev_leader = "="

It is used in insert mode abbreviations like: =theorem=, =proposition=, =corollary=, =lemma=, etc.

Debugging ATP

This section describes some limitation of ATP (as you see, this section is not written, but the aim is to make it disappear anyway ;).

There are many debug variables with names g:atp_debug{fname} where {fname} is a shortname of the function for which it will turn on the debug info. These variables are documented in ftplugin/ATP_files/options.vim file.

A possible error which may occur using the :BibSearch commands has a simple cause: we count number of brackets '()', '{}' and '"' (but nor '\"') to see where the bib entry ends and where to join lines. The message error is echoed when more than 30 lines where processed and the matching bracket was not found (or the number of '"' is odd). Look at your bib file at the specified position. Syntax highlighting for bib files can help you finding where such an error is located. (After reading the bib file comment lines and lines which begin with @string are removed, so that the brackets in comment lines do not count.)

Editing Tools

visual mode: ie, iE, ae, im, am, ip, ap, iS, aS, <LocalLeader>sc normal and mode: <LocalLeader>sc.

They select the current environment in two ways:

- inner
- outer
- environment
- paragraph
- math zones: \(:\), $:$, \[:\], $$:$$, or math environment \begin:\end.ard search is set by ATP
- bracket
- syntax

ie, iE, ae
select environment: from the nearest \begin (top) to the nearest \end (bottom).

'viE' selects a bit more than 'vie' but less than 'vae', it selects a bracket pair before the beginning of the inner part of an environment, so it can be environment name or an option just after.

im, am
selects mathematics.

ip, ap
selects paragraph.
In inner mode: from the nearest
\begin, \end, \par, \newline or empty line (top)
to the nearest >
\begin, \end, \par, \newline or empty line (bottom).
in outer mode: from the nearest >
\par or empty line (top)
to the nearest >
\par or empty line (bottom).

iS, aS
selects using syntax stack (see |synstack()|), inner is the top element in the syntax stack (the highlighted area will be small) and outer uses the most bottom element in the syntax stack (the resulting are will be wide). Some syntax groups are filtered out (like 'texDocZone') which not always are synchronised.

select comment lines which begin with '^\s*%'. If not in comment line, end visual mode. You can change this map with variables g:atp_MapSelectComment (this can be only changed in atprc or vimrc file, you need restart Vim, or use atp-:ReloadATP).

nmap gw
Quite useful normal map: m`vipgq``. It is mapped to gw (in normal mode).

nmaps: g>, g<, 2g>, ..., 6g>
A normal map to m`vipg>`` (or m`vip2g>``).


See this web page.

Notes on Viewers

See the section atp-Viewers_Options how to set options for viewer programs.


It is supported. It is configured in the way that when your tex file have errors, Xpdf viewer will not reload your file, which I found useful. Xpdf supports forward searching (vim->Xpdf) with command: atp-:SyncTex
map t
map <S-LeftMouse>
Read also atp-:SyncTex_Xpdf-hack and see atp-:SetXpdf command description. You can set your own options of Xpdf using b:atp_xpdfOptions (or g:atp_xpdfOptions), for example:
let b:atp_xpdfOptions=['-bg', 'NavajoWhite4', '-fg', 'black', '-mattecolor', 'burylwood']
will make Xpdf view different. This is helpful when you edit to files, and do not want to mix them. Another nice example:
let b:atp_xpdfOptions="-bg Grey30 -mattecolor SlateBlue2 -papercolor White"


Works fine.


Works fine. It supports both forward (Vim->Okular) and inverse (Okular->Vim) searches. Okular supports forward searching (vim->Okular) with command: atp-:SyncTex >
map t
map <S-LeftMouse>
Here is how to configure reverse searching (Okular->Vim): open Okular and go to
settings>Configure Okular>Editor
and set
EditorCustom Text Editor
Commandpython $HOME/.vim/ftplugin/ATP_files/ '%f' '%l'
NOTE: You must substitute $HOME directory to its value!!! It will not work other way. You can also copy the script somewhere inside your $PATH but then when this script will change you have to keep in mind to copy it again.

If you set the command as above (with python before the path to you do not need to make executable. Note, that otherwise whenever you update ATP you will have to make the script executable!

If it is not working for you, please report it, you can also use:

gvim --remote-wait +%l "+normal %c|" %f

NOTE: :SyncTex command uses "--unique" switch for okular. However, when you do not set b:atp_okularOptions to ["--unique"] as well, then using :SyncTex will open new instance of Okular regardless if it was openned or not. You can use "--unique" as an Okular option (in g:atp_okularOptins or b:atp_okularOptions), but the if you open many files tex, all will use only one instance of Okular. This is a limitation of using Okular. Xpdf has a server option which allows for vim->Xpdf communication to the right Xpdf instance.

Then you can use <Shift>+<Left_Mouse> in Okular to synchronize the Vim (gVim) with pdf.

The function atplib#FindAndOpen() asks each running gvim server if is is "hosting" source of the file %f. Then it uses this server to set the line (but it doesn't check if the cursor is in the right window!). Note: if you like command line Vim (which has its own beauty - actually I'm just typing in it :) you need to set up Vim server option on startup:
vim --servername VIM <file>
Limitations: The project files which are split into many input files are not yet supported.


Works fine (moves page a little bit when updates a file).


This viewer does not support automatic reloads when the file changes (but it seems that the work is in progress). You have to issue CTRL-R yourself when the file is changed.


As with epdfview (with the difference that it supports automatic updates, but it do not works somehow). There is a way to configure forward searching (Vim->AcroRead)! but it is not supported yet, if you really want it, write to me.


Works fine. The file will be updated after a click (or use the xdvi options '-watchfile 1' see man xdvi for explanations). You can set forward/reverse searching by the command |SetXdvi| then use |atp-:SyncTex| for forward searching (Vim->Xdvi). To get reverse searching Xdvi must be opened by ATP (:ViewOutput, or any other command)

If you want to use Vim you have to run it with the command: >

vim --servername xdvi <file>
You can pick any server name.

ATP supports forward (Vim->Xdvi) and inverse (Xdvi->Vim) searching for Xdvi. The forward search is set by ATP (see |atp:SyncTex|), the inverse search is set by:

let b:atp_TexCompiler = "latex"
let b:atp_TexOptions = ["-src-specials"]
let b:atp_Viewer = "xdvi"
let b:atp_xdviOptions = ["-editor", "'gvim --remote-wait +%l %f'"]
They are not set by default, however there is simple command to set them at once atp-:SetXdvi. This are excellent sources of information on this here and here.


Perfectly works (but there is no reverse/inverse searching).


It is the fastest pdf viewer program ever made, why? because it renders only one page :). But it can be nicly set with ATP: via autocommands and :SyncTex you can load a page where the cursor is located (for example with autocmd event |CursorHold|). This might be nice on a big enough monitor on which you can see both vim and mupdf on one screen.


If you have any nice tip on editing (La)TeX with Vim or ATP :) you can share it here (my email you'll find on top of the help file), or put them on the script web page.

>nmap gS :%s/<c-r>=expand("<cword>")<cr>/
Pull word under the cursor to substitute command.

List loaded packages with line numbers

When standing on 1st line - copy the preamble (possibly to a register)

Delete comment lines

Compress empty lines / when there are more than two empty lines it leaves just one /

Format inner paragraph. Or even better:
This is so nice that I added a map:
nmap gw m`vipgq``

Indent inner paragraph, they are mapped to: >
nmap g> m`vip>``
nmap g< m`vip<``
There are also defined maps: 2g>, 3g> , 4g> up to 6g>.

:TeXdoc ams<Ctrl-d>
Show tex documentation which matches ams (the completion for TeXdoc command finds matches in alias files of texdoc :!texdoc -f).

will list all cross references to theorems (if you use the prefix thm: for theorems.

If you want to change the name of a command, you can try:

augroup DelCommands
au VimEnter *tex delcommand SetXdvi
au VimEnter *tex delcommand SetXpdf
augroup END
command! -buffer Xdvi :call SetXdvi()
command! -buffer Xpdf :call SetXpdf()

However, not all functions are defined without <SID> (you can always try to reach me).

:'<,'>WrapSelection @q

Wrap a visual area with wrapper from the register q and with the default '}' end wrapper.

:'<,'>WrapSelection @q,@w

As above but with the end wrapper from register w.

:map ]= ]sz=

Goto the first spelling error and list

:map [= [sz=

suggestions. Another version is to use ]S and [S instead of ]s and [s.

Colour Highlighting and Syntax Groups

When the cursor is positioned on \begin{envname} or \end{envname} both corresponding \begin:\end get highlighted with syntax group MatchParen. To disable it type this in ex mode or put it in your atprc file:

augroup LatexBox_HighlightPairs
augroup END

There is a colour scheme included: coots-beauty-256. You need 256 colours to use it (in the terminal).

These are the highlights groups defined for various files and the default links:

ToC file

highlight atp_FileName Title
highlight atp_LineNr LineNr
highlight atp_Number Number
highlight atp_Chapter Label
highlight atp_Section Label
highlight atp_SubSectionLabel
highlight atp_AbstractLabelthis group highlights abstract and all the unnumbered chapters and the bibliography.

The chapter group highlights or chapters, or sections, or parts, depending what is your top level section in your latex document. This applies, accordingly, to other groups.

Labels file

highlight atp_label_FileNameTitle
highlight atp_label_LineNrLineNr
highlight atp_label_NameLabel
highlight atp_label_CounterKeyword

BibSearch file

this is very much the same as the standard syntax for bib files. Groups are named bibsearch<NAME> instead of bib<NAME>. There is one more group added:

highlight bibsearchInfo
which highlights the line number of the bib entry in the bib file. All bibsearch groups are by default linked to the bib groups.

Yet, there is no default highlighting, try coots-beauty-256 colour scheme. If you like it, I'm glad, if you have a nice (non standard) colour scheme, I'm happy to get it, if you like to share it.

Status line:

The notification message that your compiler is running can be highlighted. For this set the variables:

Their values will be passed to gui guifg and guibg values of the highlight command. The g:colors_name variable is set by colour scheme. Usually it is just the colour scheme name but there might be a difference, for example: the provided colour scheme file name is 'coots-beauty-256' but the variable is set to 'coots_beauty_256'. Example:
let g:atp_notification_coots_beauty_256_gui="DeepPink4"
will set the foreground colour of 'pdfLaTeX' message to DeepPink4.

The status message 'LaTeX' ( if you use latex or 'pdfLaTeX' when you use pdflatex, and so on) can be highlighted. There are several variables to set this:
where g:colors_name is the name of the colour scheme, for example the supplied colour scheme with atp 'runtimepath/colors/coots-beauty-256' has name 'coots_beauty_256' so the first variable should be
value of these variables are used to set highlight for the group UserN where N is the value of g:atp_statusNotifHi. Its value should be 0,1,...,9. Where 0 means no highlight for status notification (which is the default). If it is set to positive value then the default values of these variables should give the same colour as the status line has.

The variable g:atp_StatusLine is stores the value of Vim option 'statusline'; actually 'statusline' option is set by:

set statusline=%!g:atp_StatusLine

Final Remarks

To see some messages that are issued you can use the |:mes| command.

If you find this plugin useful and have some comments you are cordially invited to write to the author: <mszamot [AT] gmail [dot] com>, add some "karma" poitns on vim script page, make a recommendation or write a review on SourceForge: atp-sourceforge.

Best, and hopefully you will find this useful :)

Marcin Szamotulski

Copy Rights

Copyright (C) 2010 Marcin Szamotulski Permission is hereby granted to use and distribute this code, with or without modifications, provided that this copyright notice is copied with it.

Automatic Tex Plugin for Vim is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Automatic Tex Plugin for Vim is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Automatic Tex Plugin for Vim. If not, see here.

This licence applies to all files shipped with Automatic Tex Plugin, exluding the following two dictionary files:

where taken from latex-suite Vim plugin and are under Vim charity |license|.