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.txt | 3460 ----------------------------------------- 1 file changed, 3460 deletions(-) delete mode 100644 vim-latex/doc/latex-suite.txt (limited to 'vim-latex/doc/latex-suite.txt') diff --git a/vim-latex/doc/latex-suite.txt b/vim-latex/doc/latex-suite.txt deleted file mode 100644 index b55e053..0000000 --- a/vim-latex/doc/latex-suite.txt +++ /dev/null @@ -1,3460 +0,0 @@ - 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 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 - - " OPTIONAL: Starting with Vim 7, the filetype of empty .tex files defaults to - " 'plaintex' instead of 'tex', which results in vim-latex not being loaded. - " The following changes the default filetype back to 'tex': - let g:tex_flavor='latex' - - - -In addition, the following settings could go in your ~/.vim/ftplugin/tex.vim -file: > - " this is mostly a matter of taste. but LaTeX looks good with just a bit - " of indentation. - set sw=2 - " TIP: if you write your \label's as \label{fig:something}, then if you - " type in \ref{fig: and press 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[<