file: texviman.txt current version at http://sites.netscape.net/benjif/vim/ tex-related macros for vim--User Manual version 0.03 Last modified: Fri Mar 10, 2000 13:33:54 Eastern Standard Time author: Benji Fisher Table of Contents 1. Summary 2. Installation 3. Configuration 4. Usage 5. Design 1. Summary Note that you can search for the next section with '/^\d' This manual describes the vim macros in texmacro.vim and related files. I hope you find these macros useful if you edit TeX or LaTeX files with The One True Editor, Vim (Vi IMproved). If you really like this, type :help uganda within vim. Thanks to Ralf Arens for letting me use his scripts for producing LaTeX environments. 2. Installation You should be able to get the current versions of these files from the URL in the header of this document. At a minimum, get the file texmacro.vim and save it with your other vim files. If your vimrc file is in the directory /some/path/vim/ then I recommend making a new directory /some/path/vim/TeX/ and putting texmacro.vim there. If you do not have a vimrc file, read :help vimrc within vim. Then, add the lines augroup TeX autocmd FileType tex source $VIM/TeX/texmacro.vim augroup END to your vimrc file. This is enough. The next time you start vim (or otherwise source your vimrc file) and edit a TeX file, texmacro.vim will be loaded automatically and you will have the following features: * automatic conversion of " into `` or '' as appropriate * menu commands for running latex on the current file * menu commands for entering latex environments automatically (Mac users: sorry, but the second item is not available to you. As soon as someone implements cooperation between vim and other Mac programs, I will take advantage of it!) If you do not like using menus, just read the next section. It describes configuration and additional files that you may want to install. Section 4 describes in detail the functionality provided by these menus. Note: See the discussion of autocommands in Sections 3 and 5, below. 3. Configuration I will assume that you have installed texmacro.vim as described above, in the directory /some/path/vim/TeX/ If you have put it elsewhere, modify these instructions accordingly. Get the file texvimrc.vim. Save a copy of this in the same directory as above, so that you will have it for reference, but also make a copy and put it in the same directory as your vimrc file, /some/path/vim/ . The rationale is the same as for placing your vimrc file there: you do not want to over-write your customizations when you get an updated version of texmacro.vim and related files, so the rc file goes in a directory where you will not be putting standard distribution files. Edit the file some/path/vim/texvimrc.vim to your liking. It should be self-explanatory. I will not attempt to provide full documentation here, but here are examples of what you can do. Uncomment the lines " French <> " let TeX_open = "<<" " let TeX_close = ">>" (not the first one!) if you want "French quotes" automatically converted to <>. Edit the lines let TeX_DVI_key = '' let TeX_matrix_key = '\m' if you want (function key 4) to generate a DVI file (run latex) and you want to map '\m' to call the function TeX_matrix(). This will do two things: define the mappings (a.k.a. key bindings) and it will also modify the menu items so that '' and '\m' appear. That way, you can use the menus for actions that you rarely need and you can also use the menus to remind you what mappings you have defined. The function TeX_matrix(), among others, is described in Section 4. See also Section 5. Warning: this is a new feature in version 0.3 and has not yet been tested much. If you get strange results from this feature, let me know ASAP and I will make it more robust in the next version. I also recommend that you get Michael Geddes's macros in the file BuffOptions.vim . This file is available from my vim page (see the header of this document). Have a look at them: you may want to use these scripts for much of your vim editing. If you put this file in /some/path/vim/TeX/ (the same file as texmacro.vim ) then it will be automatically sourced when texmacro.vim is run. The effect is that any mappings you have defined using texvimrc.vim (as described above) will be removed when you start editing a non-TeX buffer and any previous mappings will be restored. Using the example above, if you have already mapped to do something useful (but not useful for editing TeX) then that function will be available when editing non-TeX files, but when editing TeX files will be mapped as above. Any extra commands that you want to be executed before the body of texmacro.vim should also be placed in some/path/vim/texvimrc.vim . Any extra commands that you want to be executed after the body of texmacro.vim should be placed in another file, some/path/vim/texauto.vim : a sample texauto.vim (that does not actually do anything) is provided. In particular, if you want to define additional TeX autocommands, this is where to put them. If you define them in your vimrc file or in some/path/vim/texvimrc.vim then they will get clobbered by texmacro.vim . 4. Usage If the menus are well designed, they should be fairly self-explanatory. If this is not the case, let me know so that I can improve them. This section is divided into subsections as follows: 4a. Running tex and previewing 4b. Entering latex environments 4c. Formatting tables 4d. Linear algebra (specialized) 4a. Running tex and previewing These commands are available from all modes. menu: generate DVI function: TeX_DVI() what it does: run latex, generating a DVI file customization: TeX_dvioptions TODO: Add sample customizations for various tex distributions; add support for plain tex. menu: view DVI function: TeX_DVI() what it does: launch the DVI previewer customization: TeX_dviviewer TODO: Add sample customizations for various tex distributions. menu: generate PDF function: TeX_PDF() what it does: run pdflatex, generating a PDF file customization: TeX_dvioptions TODO: Add sample customizations for various tex distributions; add support for plain tex; support systems that do not have pdftex. menu: view PDF function: TeX_PDF() what it does: launch the PDF previewer customization: TeX_dviviewer TODO: Add sample customizations for various tex distributions. 4b. Entering latex environments TODO: Fiddle with Ralf Arens's scripts. Test them some more. These commands are available in any mode. menu: Environment (prompt) function: TeX_ask_env() what it does: The script prompts you for the name of the environment and then for options appropriate to that environment, then gives you a skeleton. For example, \begin{figure}[t] \begin{center} \input{fig.eps} \caption{This is a caption} \label{fig:samp} \end{center} \end{figure} was produced by entering all the information on the command line. customization: none TODO: Add help options and a "stick with defaults" variant. menu: Environment (copy) function: TeX_read_env() what it does: Same as above, but it reads the environment name from the current line. Thus you enter the environment name (figure or tabular or ...) on a new line, then call this function. This allows you to take advantage of Insert-mode completion while entering the environment name. customization: none TODO: same as above 4c. Formatting tables These commands are available from Normal and Visual modes. See also Section 4d, below. Instead of starting a LaTeX environment, such as array, and entering your data with LaTeX formatting, these commands allow you to enter your data as a tab-formatted table, then convert it to the appropriate LaTeX environment. For example, you can enter 1 2 3 4 5 6 and then, in a few keystrokes, turn it into \begin{bmatrix} 1 &2 &3 \\ 4 &5 &6 \end{bmatrix} (In fact, I just did so!) Note that each tab becomes a LaTeX column separator, so 1 23456789 3 4 5 6 (with two tabs between the 5 and 6) becomes \begin{bmatrix} 1 &23456789 &3 \\ 4 &5 & &6 \end{bmatrix} which is probably not what you want. So take the description "tab-formatted" with a grain of salt! TODO: So far, I have only done math-related environments, and I assume that AMS-LaTeX is available. This should be generalized and made customizable. menu: Make Matrix function: TeX_matrix() what it does: As above, it makes a bmatrix environment (AMS-LaTeX) customization: TODO Visual mode: Select the tab-formatted table and invoke TeX_matrix() (from menu or key binding). Normal mode: Position the cursor at the first line of the tab-formatted matrix and type (number of lines) and invoke TeX_matrix() (from menu or key binding). Since this is a .txt file, not a tex file, I actually did the example above by typing "2:call TeX_matrix()". menu: Undo Matrix function: TeX_unmatrix() what it does: This undoes TeX_matrix(), returning you to a tab-formatted table. It ignores the environment name, so should work with all variants. Visual mode: Same as above, including the \begin{bmatrix} and \end{bmatrix} lines. Normal mode: Same as above, where the count (number of lines) includes the \begin{bmatrix} and \end{bmatrix} lines. customization: TODO menu: Make Cases function: TeX_cases() what it does: As above, it makes a cases environment (AMS-LaTeX?) customization: TODO Visual mode: Select the tab-formatted table and invoke TeX_cases() (from menu or key binding). Normal mode: Position the cursor at the first line of the tab-formatted matrix and type (number of lines) and invoke TeX_cases() (from menu or key binding). menu: Exercise List function: TeX_exercise_list() what it does: Very specialized: this takes an exercise list in the form
Section 1.1: 1, 2, 3; (all on one line, so visually selecting is not necessary) and converts it to \setcounter{section}{1} \setcounter{subsection}{1} \addtocounter{subsection}{-1} \subsection{} \setcounter{subsubsection}{1} \addtocounter{subsubsection}{-1} \subsubsection{} \setcounter{subsubsection}{2} \addtocounter{subsubsection}{-1} \subsubsection{} \setcounter{subsubsection}{3} \addtocounter{subsubsection}{-1} \subsubsection{} I use this to take the homework assignment from an HTML file and prepare to write solutions in LaTeX. customization: not unless someone asks for it 4d. Linear algebra (specialized) These commands are available from Normal and Visual modes. As in Section 4c, these commands work with tab-formatted arrays. If you are going to use these at all, you are likely to be doing it a lot, so the descriptions below assume that you have mapped some key sequence, , to invoke these functions. menu: Equation function: TeX_equation() what it does: Turn a single line, such as 1 2 3 4 into a LaTeX linear equation: x_{1} + 2 x_{2} + 3 x_{3} = 4 (Note: leading tabs were added after the fact in this example!) customization: not unless someone asks for it Visual mode: Not really necesary, but you could select the line and use your key sequence . Normal mode: Position the cursor on the desired line and type . menu: SystemEquation function: TeX_System_of_eqns_key() what it does: Turn several lines, such as 1 2 3 4 -1 2 -5 6 into a LaTeX system of linear equations: \begin{cases} x_{1} + 2 x_{2} + 3 x_{3} &= 4 \\ -x_{1} + 2 x_{2} - 5 x_{3} &= 6 \end{cases} (Note: leading tabs were added after the fact in this example!) customization: not unless someone asks for it Visual mode: Visually select the lines and type . Normal mode: Position the cursor on the first line and type 2 if (as in the example) you have two lines. menu: Row Reduce function: TeX_Row_reduce() what it does: Given two lines such as 1 2 3 4 -1 2 -5 6 (only whole numbers!) add a multiple of one to the other. For example, adding 3 times the first row to the second gives 1 2 3 4 2 8 4 18 \begin{cases} x_{1} + 2 x_{2} + 3 x_{3} &= 4 \\ -x_{1} + 2 x_{2} - 5 x_{3} &= 6 (Note: leading tabs were added after the fact in this example!) customization: not unless someone asks for it Visual mode: Not really necesary; modify the instructions for Normal mode. Normal mode: Position the cursor on the first line and yank it ("yy"). Position the cursor on the second line and type to invoke the function. It will prompt you to enter a multiple, do its stuff, and move you down one line. menu: Transpose function: TeX_transpose() what it does: Given two lines such as 1 2 3 4 5 6 turn it into 1 4 2 5 3 6 (all without leading tabs). One can now apply the function to the individual rows, producing the columns of the original matrix. customization: not unless someone asks for it Visual mode: Visually select the lines and type , if the key has been mapped, or select Transpose from the menu. Normal mode: Position the cursor on the first line and type 2 if (as in the example) you have two lines. Omit the count for a single row. 5. Design I implement most features with vim functions (:help user-functions). All of my function names start with "TeX_", so they should not conflict with anything you have defined yourself. I provide menu items to access each of these functions. They are all available to you without forcing any key bindings that might override your choices, and it only takes up one slot on your menu bar. It is easy to map a key sequence or define a command to call any of these functions. (:help mapping, :help user-commands) The file texmacro.vim is large and getting larger. I do not want it to be sourced every time I start up vim because this takes time and memory. A single TeX autocommand causes the file to be sourced as soon as it is needed: as soon as a TeX file is loaded. The autocommands in texmacro.vim start off by clobbering the autocommand that loaded texmacro.vim (and any other TeX autocommands). Thus the file is loaded only once. (Keep this in mind if you modify texmacro.vim or related files.) The user file, some/path/vim/texvimrc.vim , is sourced before most of texmacro.vim . That way, the customiztions can be added to the menu. Additional autocommands can be defined in some/path/vim/texauto.vim . If you want to make a package for editing other types of files with vim, I sugest that you borrow my function TeX_menuMaker() and consider using the same structure of autocommands and customization files. I have done my best to be compatible with the design goals of vim itself. (See :help design-flexible, but see also :help design-not, which I violate.) This package is still under development. As long as I am the only known user, it will reflect my needs and preferences. If there is something that you would like to see added, let me know. (See the header of this file for my e-mail address. These comments were made on March 10, 2000 and may not still be true when you read this. I will consider it a sign of success if someone bothers to read this a long time after I have written it!)