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