Latex-Suite Reference *latex-suite.txt* Srinath Avadhanula Mikolaj Machowski Abstract ======== Latex-Suite attempts to provide a comprehensive set of tools to view, edit and compile LaTeX documents in Vim. Together, they provide tools starting from macros to speed up editing LaTeX documents to functions for forward searching .dvi documents. Latex-Suite has been possible because of the contributions of many people. Please see latex-suite-credits [|ls_a_dU|] for a list of people who have helped. Latex-Suite is released under the Vim charityware license. For license and conditions of use look at |copyright|. Replace all occurrences of ``Vim'' with ``Latex-Suite''. The current copyright holders of Latex-Suite are Srinath Avadhanula and Mikolaj Machowski. Homepage: http://vim-latex.sourceforge.net |ls_u_1| *latex-suite.txt-toc* |ls_1| Installation and recommended Settings |ls_2| Inserting Templates |ls_3| Latex-Suite Macros |ls_3_1| Environment Mappings |ls_3_2| Command Mappings |ls_3_3| Font Mappings |ls_3_4| Section Mappings |ls_3_5| Greek Letter Mappings |ls_3_6| Auc-Tex Key Bindings |ls_3_7| Diacritics |ls_3_8| BibTeX Shortcuts |ls_3_9| Smart Key Mappings |ls_3_10| Alt Key Macros |ls_3_11| Custom Macros |ls_3_12| Making your own Macros via IMAP() |ls_4| Package Handling |ls_4_1| Inserting package commands |ls_4_2| Actions taken for supported packages |ls_4_3| Automatic Package detection |ls_4_4| Writing supporting for a package |ls_5| Latex Completion |ls_5_1| Latex-Suite completion example |ls_5_2| Latex-Suite \ref completion |ls_5_3| Latex-Suite \cite completion |ls_5_4| Latex-Suite filename completion |ls_5_5| Custom command completion |ls_6| LaTeX Compiling |ls_6_1| Setting Compilation rules |ls_6_2| Handling dependencies in compilation |ls_6_3| Compiling multiple times |ls_6_4| Customizing the compiler output |ls_6_5| Compiling parts of a file |ls_7| Latex Viewing and Searching |ls_7_1| Setting Viewing rules |ls_7_2| Forward Searching DVI documents |ls_7_3| Inverse Searching |ls_8| Latex Folding |ls_8_1| Default Folding Scheme in Latex-Suite |ls_8_2| Customizing what to fold |ls_8_3| Editing the folding.vim file directly |ls_9| Multiple file LaTeX projects |ls_9_1| Latex-Suite project settings |ls_9_2| Specifying which file to compile |ls_10| Latex-Suite Commands and Maps |ls_10_1| Latex-Suite Maps |ls_10_2| Latex Suite Commands |ls_11| Customizing Latex-Suite |ls_11_1| General Settings |ls_11_2| Place-Holder Customization |ls_11_3| Macro Customization |ls_11_4| Smart Key Customization |ls_11_5| Latex Completion Customization |ls_11_6| Compiler Customization |ls_11_7| Viewer Customization |ls_11_8| Menu Customization |ls_11_9| Folding Customization |ls_11_10| Package Handling Customization |ls_12| Credits ================================================================================ Viewing this file This file can be viewed with all the sections and subsections folded to ease navigation. By default, vim does not fold help documents. To create the folds, press za now. The folds are created via a foldexpr which can be seen in the last section of this file. See |usr_28.txt| for an introduction to folding and |fold-commands| for key sequences and commands to work with folds. ================================================================================ Installation and recommended Settings *ls_1* *ls_a_bc* *recommended-settings* If you are reading this, it most probably means that you have already installed Latex-Suite and the help files. If this is not the case, follow the detailed instructions on Latex-Suite's download page |ls_u_2|. Make sure that you create a few necessary settings in your ~/.vimrc. > " REQUIRED. This makes vim invoke Latex-Suite when you open a tex file. filetype plugin on " IMPORTANT: win32 users will need to have 'shellslash' set so that latex " can be called correctly. set shellslash " IMPORTANT: grep will sometimes skip displaying the file name if you " search in a singe file. This will confuse Latex-Suite. Set your grep " program to always generate a file-name. set grepprg=grep\ -nH\ $* " OPTIONAL: This enables automatic indentation as you type. filetype indent on In addition, the following settings could go in your ~/.vim/ftplugin/tex.vim file: > " this is mostly a matter of taste. but LaTeX looks good with just a bit " of indentation. set sw=2 " TIP: if you write your \label's as \label{fig:something}, then if you " type in \ref{fig: and press you will automatically cycle through " all the figure labels. Very useful! set iskeyword+=: ================================================================================ Inserting Templates *ls_2* *ls_a_bd* *latex-suite-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 Latex-Suite 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 Latex-Suite releases a template with the same name, these files should not get over-written when you install a new release over an existing one. NOTE: Templates are also accessible for non-gui users with the command |:TTemplate|. The argument should be name of the corresponding template file. If the command is called without arguments (preferred usage), then a list of available templates is displayed and the user is asked to choose one of them. ================================================================================ Latex-Suite Macros *ls_3* *ls_a_be* *latex-macros* |ls_3_1| Environment Mappings |ls_3_2| Command Mappings |ls_3_3| Font Mappings |ls_3_4| Section Mappings |ls_3_5| Greek Letter Mappings |ls_3_6| Auc-Tex Key Bindings |ls_3_7| Diacritics |ls_3_8| BibTeX Shortcuts |ls_3_9| Smart Key Mappings |ls_3_10| Alt Key Macros |ls_3_11| Custom Macros |ls_3_12| Making your own Macros via IMAP() Latex-Suite ships with a very comprehensive set of insert mode and |visual-mode| mappings and menu items to typeset most of the LaTeX elements. NOTE: These mappings are are not standard mappings in the sense that only the last character is mapped. See plugin/imaps.vim for further documentation. For example, in the case of the mapping EFI provided by Latex-Suite you can press the characters 'E', 'F' and 'I' as slowly as you wish (unlike the normal imap command where timeout issues are involved). The characters are visible as you type them (unlike normal imaps) and you can use the movement or backspace key to correct yourself unlike normal mappings. *place-holder* *ls_a_dV* *place-holders* *ls_a_eD* NOTE: Place Holders ------------- Almost all macros provided in Latex-Suite implement Stephen Riem's bracketing system and Gergely Kontra's JumpFunc() for handling place-holders. This consists of using "place-holders" to mark off locations where the next relevant editing has to be done. As an example, when you type EFI in |insert-mode|, you will get the following: > \begin{figure}[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 (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. *overriding-macros* *ls_a_eE* NOTE: Over-riding Latex-Suite 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() [|ls_a_bG|] section. An important thing to note is that if you wish to over-ride macros created by Latex-Suite rather than merely create new macros, you should place the IMAP() calls in a script which gets sourced after the files in Latex-Suite. A good place typically is as a file-type plugin file in the ~/.vim/after/ftplugin/ directory. (Use ~/vimfiles if you are using WINDOWS). For example to over-ride `w to \omega instead of \wedge, place the following line in (say) ~/.vim/after/ftplugin/tex_macros.vim: > call IMAP('`w', '\omega', 'tex') < NOTE: 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-imaps* *ls_a_eF* NOTE: 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 Latex-Suite. -------------------------------------------------------------------------------- Environment Mappings *ls_3_1* *ls_a_bf* *environment-mappings* Latex-Suite provides a rich set of mappings to insert, enclose and modify LaTeX environments, i.e, \begin{...} ... \end{...} pairs. Inserting Environments *ls_3_1_1* *ls_a_bg* *inserting-environments* Latex-Suite provides the following ways to insert environments Method 1: Pressing *ls_3_1_1_1* *ls_a_bh* *inserting-env-f5* If you press in the insert or normal mode while on an empty line, Latex-Suite prompts you with a list of environments you might want to insert. You can either choose one from the list or type in a new environment name. If you press on a line which already has a word, then that word is used instead of prompting. See Tex_Env_name [|ls_a_cZ|] for a description of how Latex-Suite uses the word to form the expansion and how to modify Latex-Suite's behavior. The list of environments which Latex-Suite prompts you with (when is pressed on an empty line) is formed from the Tex_PromptedEnvironments [|ls_a_di|] setting. In addition to this setting, Latex-Suite also lists environments found in custom packages as described in the section Package actions. [|ls_a_bL|] Method 2: Using - *ls_3_1_1_2* *ls_a_bi* *inserting-env-shift-f1* The shifted function keys, to can be mapped to insert very commonly used environments. The environments mapped to each key can be customized via the g:Tex_HotKeyMappings [|ls_a_dj|] setting. Method 3: Using three letter sequences *ls_3_1_1_3* *ls_a_bj* *inserting-env-threeletter* 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: 1. All environment mappings begin with E 2. 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_3_1_2* *ls_a_bk* *enclosing-environments* Latex-Suite provides visual-mode mappings which enclose visually selected portions of text in environments. There are two ways provided to do this. Method 1: Pressing *ls_3_1_2_1* *ls_a_bl* *enclosing-env-f5* You can also select a portion of text visually and press while still in visual mode. This will prompt you with a list of environments. (This list can be customized via the g:Tex_PromptedEnvironments [|ls_a_di|] setting). You can either choose from this list or type in a new environment name. Once the selection is done, Latex-Suite encloses the visually selected portion in the chosen environment. Method 2: Using three letter mappings *ls_3_1_2_2* *ls_a_bm* *enclosing-env-threeletter* 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 [|ls_a_bj|]. 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 *ls_3_1_3* *ls_a_bn* *changing-environments* Pressing 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 will prompt you to change the array environment, not the eqnarray environment. In addition, Latex-Suite will also try to change lines within the environment to be consistent with the new environment. For example, if the original environment was an eqnarray environment with a \label command, then changing it to an eqnarray* environment will delete the \label. Pressing in normal mode has the same effect as pressing in insert-mode, namely you will be prompted to choose an environment to insert. -------------------------------------------------------------------------------- Command Mappings *ls_3_2* *ls_a_bo* *latex-command-maps* Latex-Suite provides a rich set of mappings to insert, enclose and modify LaTeX commands. Inserting LaTeX commands *ls_3_2_1* *ls_a_bp* *inserting-commands* *ls-imap-f7* *ls_a_dW* *ls-imap-s-f7* *ls_a_dX* Pressing in insert or normal mode while the cursor is touching a word will insert a command formed from the word touching the cursor. For certain common commands, Latex-Suite will expand them to include additional arguments as needed. For example, frac becomes \frac{<++>}{<++>}<++>. Otherwise, it will simply change the word under the cursor as follows > word --> \word{<++>}<++> You can define custom expansions of commands using the Tex_Com_{name} setting as described in here [|ls_a_da|]. If is pressed when the cursor is on white-space, then Latex-Suite will prompt you to choose a command and insert that instead.The list of commands is constructed from the g:Tex_PromptedCommands [|ls_a_dk|] setting and also from commands which Latex-Suite finds while scanning custom packages which Latex-Suite finds. See the Package actions [|ls_a_bL|] section for details on which files are scanned etc. Enclosing in a command *ls_3_2_2* *ls_a_bq* *enclosing-commands* You can select a portion of text visually and press while still in visual mode. This will prompt you with a list of commands. (This list can be customized via the g:Tex_PromptedCommands [|ls_a_dk|] setting). You can either choose from this list or type in a new command name. Once the selection is done, Latex-Suite encloses the visually selected portion in the chosen command. Changing commands *ls_3_2_3* *ls_a_br* *changing-commands* *ls-vmap-f7* *ls_a_dY* In both insert and normal mode 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 *ls_3_3* *ls_a_bs* *font-maps* These mappings insert font descriptions such as: \textsf{<++>}<++> with the cursor left in place of the first placeholder [|ls_a_eD|] (the <++> characters). Mnemonic: 1. first letter is always F (F for font) 2. next 2 letters are the 2 letters describing the font. Example: Typing FEM in insert-mode expands to \emph{<++>}<++>. Just like environment mappings, you can visually select an area and press `sf to have it enclosed in: \textsf{word} or > {\sffamily line } depending on character-wise or line-wise selection. -------------------------------------------------------------------------------- Section Mappings *ls_3_4* *ls_a_bt* *section-mappings* These maps insert LaTeX sections such as: > \section{<++>}<++> etc. Just as in the case of environments and fonts, can be enclosed with a visual selection. The enclosing is not sensitive to character or line-wise selection. Mnemonic: (make your own!) > SPA for part SCH for chapter SSE for section SSS for subsection SS2 for subsubsection SPG for paragraph SSP for subparagraph Example: SSE in insert mode inserts > \section{<++>}<++> If you select a word or line and press ,se, then you get > \section{section name} The menu item in Tex-Environments.Sections have a sub-menu called 'Advanced'. Choosing an item from this sub-menu asks a couple of questions (whether you want to include the section in the table of contents, whether there is a shorter name for the table of contents) and then creates a more intelligent template. -------------------------------------------------------------------------------- Greek Letter Mappings *ls_3_5* *ls_a_bu* *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 NOTE: LaTeX does not support upper case for all greek alphabets. Just like other Latex-Suite mappings, these mappings are not created using the standard imap command. Thus you can type slowly, correct using etc. -------------------------------------------------------------------------------- Auc-Tex Key Bindings *ls_3_6* *ls_a_bv* *auc-tex-mappings* These are simple 2 key expansions for some very commonly used LaTeX elements: > `^ Expands To \Hat{<++>}<++> `_ expands to \bar{<++>}<++> `6 expands to \partial `8 expands to \infty `/ expands to \frac{<++>}{<++>}<++> `% expands to \frac{<++>}{<++>}<++> `@ expands to \circ `0 expands to ^\circ `= expands to \equiv `\ expands to \setminus `. expands to \cdot `* expands to \times `& expands to \wedge `- expands to \bigcap `+ expands to \bigcup `( expands to \subset `) expands to \supset `< expands to \le `> expands to \ge `, expands to \nonumber `~ expands to \tilde{<++>}<++> `; expands to \dot{<++>}<++> `: expands to \ddot{<++>}<++> `2 expands to \sqrt{<++>}<++> `| expands to \Big| `I expands to \int_{<++>}^{<++>}<++> (again, notice the convenient place-holders) In addition the visual mode macros are provided: > `( encloses selection in \left( and \right) `[ encloses selection in \left[ and \right] `{ encloses selection in \left\{ and \right\} `$ encloses selection in $$ or \[ \] depending on characterwise or linewise selection -------------------------------------------------------------------------------- Diacritics *ls_3_7* *ls_a_bw* *diacritic-mappings* These mappings speed up typing European languages which contain diacritic characters such as a-umlaut etc. > + expands to \v{} = expands to \'{} where is an alphabet. > +} expands to \"{a} +: expands to \^{o} Latex-Suite also ships with smart backspacing [|ls_a_dZ|] functionality which provides another convenience while editing languages with diacritics. NOTE: Diacritics are disabled by default in Latex-Suite because they can sometimes be a little too intrusive. Moreover, most European users can nowadays use font encodings which display diacritic characters directly instead of having to rely on Latex-Suite's method of displaying diacritics. Set the g:Tex_Diacritics [|ls_a_df|] variable to enable diacritics. -------------------------------------------------------------------------------- BibTeX Shortcuts *ls_3_8* *ls_a_bx* *bibtex-bindings* Latex-Suite provides an easy way of entering bibliographic entries. Four insert-mode mappings: BBB, BBL, BBH and BBX are provided, all of which essentially act in the same manner. When you type any of these in insert-mode, you will get a prompt asking you to choose a entry type for the bibliographic entry. When you choose an entry type, a bibliographic entry template will be inserted. For example, if you choose the option 'book' via the map BBB, then the following template will be inserted: > @BOOK{<+key+>, author = {<++>}, editor = {<++>}, title = {<++>}, publisher = {<++>}, year = {<++>}, otherinfo = {<++>} }<++> <+key+> will be highlighted in select-mode and you can type in the bib-key. After that you can use 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. NOTE: Mnemonic -------- B for Bibliographic entry, L for Large entry, H for Huge entry, and X stands for all eXtras. Customizing Bib-TeX fields *ls_3_8_1* *ls_a_by* *adding-bib-options* If you wish the BBB command to insert a few additional fields in addition to the fields it creates, then you will need to define global variables of the form > g:Bib_{type}_options in you $VIM/ftplugin/bib.vim file, where {type} is a string like 'article', 'book' etc. This variable should contain one of the letters defined in the following table Character Field Type~ w address a author b booktitle c chapter d edition e editor h howpublished i institution k isbn j journal m month z note n number o organization p pages q publisher r school s series t title u type v volume y year For example, by default, choosing 'article' via BBB inserts the following template by default > @ARTICLE{<+key+>, author = {<++>}, title = {<++>}, journal = {<++>}, year = {<++>}, otherinfo = {<++>} }<++> However, if g:Bib_article_options is defined as 'mnp', then 'article' will insert the following template > @ARTICLE{<+key+>, author = {<++>}, title = {<++>}, journal = {<++>}, year = {<++>}, month = {<++>}, number = {<++>}, pages = {<++>}, otherinfo = {<++>} }<++> If you have some other fields you wish to associate with an article which are not listed above, then you will have to use the Bib_{type}_extrafields option. This is a newline separated string of complete field names which will be included in the template. For example, if you define > let g:Bib_article_extrafields = "crossref\nabstract" then the article template will include the lines > crossref = {<++>}, abstract = {<++>}, NOTE: You will need to define Bib_* settings in your $VIMRUNTIME/ftplugin/bib.vim file. -------------------------------------------------------------------------------- Smart Key Mappings *ls_3_9* *ls_a_bz* *smart-keys* Latex-Suite ships with the following smart keys: Smart Backspace --------------- *smart-backspace* *ls_a_dZ* Pressing 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 ----------- Latex-Suite maps the 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 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_3_10* *ls_a_bA* *altkey-mappings* Latex-Suite utilizes a set of macros originally created by Carl Mueller in auctex.vim to make inserting all the \left ... \right stuff very easy and to also make some use of the heavily under-utilized key. NOTE: By default, typing Alt- in Vim takes focus to the menu bar if a menu with the hotkey 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. NOTE: Customizing the maps -------------------- If for some reason, you wish to not map the keys, (some European users need to use the key to enter diacritics), you can change these maps to other keys as described in the section Customizing Alt-key maps [|ls_a_cx|]. *ls_3_10_1* *ls_a_bB* *Alt-L* This is a polymorphic insert-mode mapping which expands to one of the following depending on the character just before the cursor location. Character before cursor Expansion~ ( \left( <++> \right) [ \left[ <++> \right] | \left| <++> \right| { \left\{ <++> \right\} < \langle <++> \rangle q \lefteqn{<++>}<++> If the character before the cursor is none of the above, then it will simply insert a \label{<++>}<++>. *ls_3_10_2* *ls_a_bC* *Alt-B* This insert-mode mapping encloses the previous character in \mathbf{}. *ls_3_10_3* *ls_a_bD* *Alt-C* In insert mode, this key is polymorphic as follows: 1. If the previous character is a letter or number, then capitalize it and enclose it in \mathcal{}. 2. otherwise insert \cite{}. In visual mode, it will simply enclose the selection in \mathcal{} *ls_3_10_4* *ls_a_bE* *Alt-I* 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, has styles defined forthe following environments: Environment Style~ itemize \item enumerate \item theindex \item thebibliography \item[<+biblabel+>]{<+bibkey+>} <++> description \item[<+label+>] <++> 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 % will insert "\item[<+label+>] <++>" if % used here \end{description} \item third item % will insert "\item " when if used here. \end{itemize} % will insert nothing ("") if used here < The style used by can be customized using the g:Tex_ItemStyle_environment [|ls_a_dl|] variable. -------------------------------------------------------------------------------- Custom Macros *ls_3_11* *ls_a_bF* *custom-macros-menu* This functionality available via the TeX-Suite.Macros menu, provides a way of inserting customized macros into the current file via the menu. When Latex-Suite starts up, it scans the $VIM/ftplugin/latex-suite/macros/ directory and creates a menu from the files found there. Each file is considered as a single macro. You can place your own macros in this directory, using placeholders [|ls_a_eD|] if wanted. When you choose a macro from the menu, the corresponding file is read into the current buffer after the current cursor position. In non-gui mode, you can use the |TMacro| command instead of choosing from the menu. This command takes the macro file name as an argument. When called without arguments (preferred usage), then a list of available macro files is displayed and the user is prompted to choose one of them). There are some other tools provided in this menu, namely: {New} Creates a new (unnamed) buffer in the latex-suite/macros/ directory. Use the command :TexMacroNew in non-gui mode. {Edit} Opens up the corresponding macro file for editing. Use |:TexMacroEdit| in non-gui mode. When you try to edit {macro} not from local directory Latex-Suite will copy it to your local directory with suffix "-local". If local copy already exists Latex-Suite prompt for overwriting it. {Delete} Deletes the corresponding macro. Use the prefixed numbers for fast navigation of menus. Use |:TexMacroDelete| in non-gui mode. When you choose to delete {macro} which is not in your local directory Latex-Suite will refuse to delete it. {Redraw} Rescans the macros/ directories and refreshes the macros list. -------------------------------------------------------------------------------- Making your own Macros via IMAP() *ls_3_12* *ls_a_bG* *ls-new-macros* If you find the need to create your own macros, then you can use the IMAP() function provided with Latex-Suite. See [|ls_a_bH|] for a short explanation of why you might prefer IMAP() over Vim's standard :imap command. An example best explains the usage: > :call IMAP('NOM', '\nomenclature{<++>}<++>', 'tex') This will create a Latex-Suite-style mapping, where if you type NOM in insert mode, you will get \nomenclature{<++>}<++> with the cursor left in place of the first <++> characters. See [|ls_a_bI|] 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 IMAP() *ls_3_12_1* *ls_a_bH* *why-IMAP* Using IMAP instead of Vim's built-in :imap command has a couple of advantages: 1. 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. 2. If you mistype one of the letters of the lhs, then the mapping is deactivated as soon as you backspace to correct the mistake. 3. 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 *ls_3_12_2* *ls_a_bI* *ls-imaps-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 etc. To do this, you will need to specify the second argument in double-quotes as follows: > :call IMAP('EFE', "\\begin{figure}\<++>\\end{figure}<++>", '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. *IMAP_PutTextWithMovement* *ls_a_ea* You can also set up a Latex-Suite style mapping which calls a custom function as follows: > :call IMAP('FOO', "\=MyFoonction()\", 'tex') < where MyFoonction is a custom function you have written. If MyFoonction also has to return a string containing <++> characters, then you will need to use the function IMAP_PutTextWithMovement(). An example best explains the usage: > call IMAP('FOO', "\=AskVimFunc()\", '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 = '' else let sidstr = '' endif return IMAP_PutTextWithMovement( \ "\" ".name.": <+short description+> \" . \ "Description: <+long description+>\" . \ "\function! ".name."(<+arguments+>)<++>\" . \ "<+function body+>\" . \ "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 [|ls_a_cV|] and Imap_PlaceHolderEnd [|ls_a_er|] settings. ================================================================================ Package Handling *ls_4* *ls_a_bJ* *latex-packages* |ls_4_1| Inserting package commands |ls_4_2| Actions taken for supported packages |ls_4_3| Automatic Package detection |ls_4_4| Writing supporting for a package Latex-Suite has a lot of functionality written to ease working with packages. Packages here refers to files which you include into the LaTeX document using the \usepackage command. -------------------------------------------------------------------------------- Inserting package commands *ls_4_1* *ls_a_bK* *inserting-packages* When you first invoke Latex-Suite, it scans the $VIM/ftplugin/latex-suite/packages directory for package script files and creates a menu from all the files found there. This menu is created under TeX-Suite > Packages > Supported. This menu contains a list of packages "supported" by Latex-Suite. When you choose one of the packages from this menu (for example the amsmath package), then a line of the form > \usepackage[<++>]{amsmath}<++> will be inserted into the current file. The \usepackage line can also be inserted in an easy manner in the current file by pressing 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 in the preamble on a line containing a single word will construct a \usepackage line from that word. You can also use the TPackage [|ls_a_cD|] 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 [|ls_a_bL|]. -------------------------------------------------------------------------------- Actions taken for supported packages *ls_4_2* *ls_a_bL* *package-actions* Latex-Suite takes the following actions for packages detected when a file is loaded, or a new \usepackage line is inserted using one of the methods described in the previous section [|ls_a_bK|]. If you are using the GUI and you have g:Tex_Menus [|ls_a_dI|] set to 1, Latex-Suite will create the following sub-menus TeX-Suite > Packages > Options TeX-Suite > Packages > Commands where is the package you just inserted (or was detected). You can use these menus to insert commands, environments and options which Latex-Suite recognizes as belonging to this package. NOTE: While inserting an option, you need to position yourself in the appropriate place in the document, most commonly inside the square braces in the \usepackage[]{packname} command. Latex-Suite will not navigate to that location. In addition to creating these sub-menus, Latex-Suite will also scan the $VIM/ftplugin/latex-suite/dictionaries directory and if a dictionary file corresponding to the package file is found, then it will add the file to the 'dict' setting in Vim so you can use the command to complete words from that file. For example, the SIUnits package has a custom dictionary. *latex-package-scanning* *ls_a_eb* If a package detected at startup is found by Latex-Suite in the current directory or in a location specified by the g:Tex_TEXINPUTS [|ls_a_dT|] variable, Latex-Suite will scan the package for \newenvironment and newcommand lines and also append any commands and environments found to the list of commands and environments which you are prompted with when you press [|ls_a_bh|] or [|ls_a_dW|] in insert mode. In addition, the TeX-Suite > Packages menu also contains the following submenus Update ------ This command is to be invoked with the cursor placed on the package name. If the corresponding package is found, then a sub-menu with the supported commands and options is created. Update All ---------- This function reads the preamble of the document for \usepackage lines and if Latex-Suite supports the detected packages, then sub-menus containing the package options and commands are created. -------------------------------------------------------------------------------- Automatic Package detection *ls_4_3* *ls_a_bM* *automatic-package-detection* Whenever Latex-Suite begins editing a new LaTeX file, it scans it for \usepackage{name} lines, and if a supported package is found, then it will create sub-menus and add to the 'dict' setting as described above. If a master-file [|ls_a_ct|] has been specified, then it will scan that file instead of the current file. See the section Custom Packages [|ls_a_bN|] to see which files Latex-Suite will scan in more detail. For all the packages detected in this manner, Latex-Suite will take certain actions as described in the section package support. [|ls_a_bL|]. Custom Packages *ls_4_3_1* *ls_a_bN* *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. Latex-Suite tries to search such customs package for other \usepackage lines, so that supported packages included in this indirect manner can also be used to create sub-menus, extend the 'dict' setting etc. The most obvious place to place such custom packages is in the same directory as the edited file. In addition, LaTeX also supports placing custom packages in places pointed to by the $TEXINPUTS environment variable. If you use the $TEXINPUTS variable in LaTeX, and you wish Latex-Suite to search these custom packages for \usepackage lines, then you need to initialize the g:Tex_TEXINPUTS [|ls_a_dT|] 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. NOTE: The present directory '.' is always searched. You need not include that in g:Tex_TEXINPUTS. -------------------------------------------------------------------------------- Writing supporting for a package *ls_4_4* *ls_a_bO* *supporting-packages* 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. g:Tex_package_option_ *ls_4_4_1* *ls_a_bP* This setting is a string containing a comma separated list of options supported by this package. Example: > g:Tex_package_option_mypack = 'opt1,opt2=,sbr:group1,opt3,opt4' The = suffix means that the option takes a value. Use sbr:group name to separate options into sub-menus. All successive options will be clubbed into the group1 sub-menu till the next sbr: option is encountered. g:Tex_package_ *ls_4_4_2* *ls_a_bQ* > g:TeX_package_ = "pre:Command,pre:Command1" More detailed example is in latex-suite/packages/exmpl file (slightly outdated). Here is short summary of prefixes which can be used in package files: (x - place with cursor, <++> - |placeholder|) {env:command} Environment: creates simple environment template \begin{command} x \end{command}<++> {eno:command} Environment with option: \begin[x]{command} <++> \end{command}<++> {ens:command[<