# A (very) quick introduction to Latex-Suite

## Using this tutorial

This tutorial assumes that you have vim version 6.1+ installed on your machine. To check, open vim and type

    :ver

You will see the version in the first line of the output. Get the latest vim version from http://vim.sf.net.

Assuming you have Vim 6.1+ already up and running, follow the instructions here to set up Latex-Suite.

Good, now you are all set to start the tutorial. Since this tutorial aims to explain the newbie-friendly version of &ls;, it needs some GUI functionality. Therefore, at least for this tutorial, open the gui version of vim. (On MS windows, this is the default). Open up this help file in either the same gvim session in a split window or in a different session and follow the (friendly) instructions.

## Inserting a template

Start up gvim and begin editing a new file.

    e newfile.tex

If the installation went well, you should see a new set of menus appear. Goto `Tex-Suite > Templates`. You will see a number of templates to choose from. For now, choose to insert a template for an article. You should get the following in the main vim window (after possibly a hit-enter prompt).

          1 %        File: sample.tex
          2 %     Created: Sun Jun 22 04:00 PM 2003 P
          3 % Last Change: Sun Jun 22 04:00 PM 2003 P
          4 %
          5 \documentclass[a4paper]{article}
          6 \begin{document}
          7
          8 \end{document}
          9
         10 ~
         11 ~
         12 ~
         13 ~
    -- INSERT --                                     7,1           All

The cursor is left on line 7 (just after the `\begin{document}` line) from where you can start typing straight away. Trying to lessen movement is a recurring theme in Latex-Suite.

## Inserting a package

Assume that we are writing a mathematical paper and we want to use the popular amsmath package. We will use some functionality which Latex-Suite provides specifically for including LaTeX packages, providing options etc. Navigate to before the `\begin{document}` line (The portion of the document before the `\begin{document}` is called the preamble in LaTeX). On an empty line in the preamble, type the single word `amsmath` and then press `<F5>` in normal mode. The line will change to

    \usepackage[]{amsmath}&ph;

with the cursor positioned conveniently between the `[]`'s. For now, do not worry about the trailing `&ph;` at the end of this line. Assume we want to provide the `sumlimits` options to amsmath. You can either type in this option manually, or choose from a menu of package options which Latex-Suite automatically creates when you insert a package using `<F5>`. With the cursor still placed between the `[]`, goto `TeX-Suite > Packages > amsmath Options`. Choose the `sumlimits` option. The package line should get converted to:

    \usepackage[sumlimits,]{amsmath}&ph;

with the cursor before `]`. Press `<C-j>` in insert mode. You will see the cursor jump to the end of the package line and the trailing `&ph;` will disappear. What just happened?! You had your first taste of Placeholders. Read more about them (later) here. In short, pressing `<C-j>` in insert mode takes you to the next `&ph;` in the text.

## Inserting an Environment

Now let us type in a simple formula in LaTeX. Move back to the body of the document (The portion of the document between `\begin{document}` and `\end{document}` is called the body). Type in a few simple sentences and then on an empty line, type the single word `equation`. Escape to normal mode and press `<F5>`. (Remember: `<F5>` is very useful!) This time, the line will change to:

    \begin{equation}
    	<+content+>
    	\label{<+label+>}
    \end{equation}&ph;

with the cursor on the `<+content+>`.

## A few keyboard shortcuts

Now to type in the famous Euler formula. Our aim is to type

    e^{j\pi} + 1 = 0

Instead of typing this blindly, let us use a few shortcuts to reduce movement. Start out by typing `e^`. Now instead of typing `{`, type another `^`. You will see the `e^^` change instantly to `e^{}&ph;` with the cursor on `<+content+>`. (The `^^` changed to `^{}&ph;`.) Continue with the following sequence of letters: `j`p`. This will change instantly to `j\pi`. (The ``p` changed to `\pi`.) Having typed in all we need to type between the `{}`'s, press `<C-j>`. You will pop back out of the curly-braces. Continue typing the rest of the formula. Latex-Suite provides a large number of shortcuts which should making typing much more fun and fast if you get acquainted with them. A list is provided here. Definitely spend some time getting a feel for them. Most of them are pretty intuitive like ``/` for `\frac{}{}`, ``8` for `\infty` etc.

Now enter a label. Press `<C-j>` to jump to `<+label+>`. We will use `eqn:euler`. After typing in `eqn:euler`, press `<C-j>`. This will take you outside the curly-braces. Another time you used a Placeholder!

In order to understand the next section better, it will be helpful to have one more `\label`. Lets use the handy `<F5>` key to insert another equation. This time something simple like the following will do:

    \begin{equation}
      \label{eqn:simple}
      1 + 1 = 2
    \end{equation}

## Folding in &ls;

Okay, we have typed enough. At this stage, hopefully, your file is looking something like this:

          1 %        File: sample.tex
          2 %     Created: Sun Jun 22 04:00 PM 2003 P
          3 % Last Change: Mon Dec 15 07:00 PM 2003
          4 %
          5 \documentclass[a4paper]{article}
          6
          7 \usepackage[sumlimits,]{amsmath}
          8
          9 \begin{document}
         10 \begin{equation}
         11 	\label{eqn:euler}
         12 	e^{j\pi} + 1 = 0
         13 \end{equation}
         14 This is the famous euler equation. I
         15 will type another equation, just as
         16 true:
         17 \begin{equation}
         18 	\label{eqn:simple}
         19 	1 + 1 = 2
         20 \end{equation}
         21 This is my contribution to mathematics.
         22 \end{document}

In normal mode, press `\rf`. This will fold up the entire file and you should see the file looking as below:

          1 %        File: sample.tex
          2 %     Created: Sun Jun 22 04:00 PM 2003 P
          3 % Last Change: Mon Dec 15 07:00 PM 2003
          4 %
          5 +--  4 lines: Preamble:   \documentclass[a4paper]{article} -----
          9 \begin{document}
         10 +--  4 lines: equation (eqn:euler) \label{eqn:euler} -----------
         14 This is the famous euler equation. I
         15 will type another equation, just as
         16 true:
         10 +--  4 lines: equation (eqn:simple) \label{eqn:simple} ---------
         21 This is my contribution to mathematics.
         22 \end{document}

What has happened is that &ls; folded away blocks of &latex; code into folded regions. You can open and close folds by using the command `za` in normal mode.

## Inserting a Reference

A necessary part of LaTeX editing is referencing equations, figures, bibliographic entries etc. This is done with the `\ref` and the `\cite` commands. Latex-Suite provides an easy way to do this. Somewhere in the body of the document, type in the following sentence

    This is a reference to (\ref{}).

With the cursor between the `{}` press `<F9>` in insert mode. Your vim session will sprout a new windows showing all the `\label`s found in all the `.tex` files of your current project. To insert the reference, just position the cursor on the relevant line and press `<enter>`. The line which you were editing will change to:

    This is a reference to (\ref{eqn:euler})

and the bottom window closes automatically.

The `<F9>` key also works for inserting `\cite` commands to reference bibliographic entries, inserting file names for the `\inputgraphics` command and just plain searching for words. Click here for more information.

## Compiling a document

Great! We have just created a small latex file. The next step is to make the latex compiler create a .dvi file from it. Compiling via latex-suite is simple. Goto normal mode and press `\ll` (replace `\` with whatever `mapleader` setting you have). This will call the latex compiler. If all goes well, then the focus should return to the vim window.

Nothing happend? Ouch! You might need to do some additional settings as described here.

### Debugging LaTeX source files

To illustrate the debugging procedure, let's create a few mistakes in the file. Insert the following ``mistakes'' in the file:

    This is a $\mistake$.
    And this is $\another$

Now press `\ll` again. This time you will notice that after compilation finishes, the cursor automatically lands on `$\mistake$`. In addition, 2 new windows will appear as shown here:

The middle window is an Error List window showing you the errors which the latex compiler found. The bottom window is a Log Preview window, which shows you the context of the error made by displaying the relevant portion of the `.log` file created during the latex compilation procedure. Jump to the Error List window and try scrolling around in it using either the `j, k` keys or the arrow keys. You will notice that the Log Preview window scrolls automatically to retain the context of the error you are currently located on. If you press `<enter>` on any line, you will see the cursor jump to the location of the error. Latex-Suite tries to guess the column location as best as it can so you can continue typing straight away.

Having got a taste for compiling, proceed by deleting the erroneous lines and re-compiling.

The Latex-Suite compiler is capable of much more including selectively filtering out common errors which you might want to ignore for the moment, compiling parts of a document, setting levels of verbosity in the compiler output etc. See here for more.

## Viewing DVI files

Now that you have compiled your first latex source, its time to view it. Again, this should be pretty simple. Press `\lv` in normal mode. Depending on your platform, a DVI viewer program should open up and display the dvi file generated in compilation step previously.

Nothing happend? Ouch! You might need to do some additional settings as described here.

### Performing forward searches

If you are using a modern DVI viewer, then it is possible to do what is called forward and inverse searching. However, you will need to customize the standard Latex-Suite distribution in order to utilize this functionality. Type in the following on the command line:

    :let g:Tex_CompileRule_dvi = 'latex -src-specials -interaction=nonstopmode $*'
    :TCTarget dvi

Now recompile the latex file by pressing `\ll`. This time, instead of pressing `\lv` to view the file, press `\ls` from within the tex file. If the DVI viewer supports forward searching (most of them do), then the viewer will actually display the portion of the DVI file corresponding to the location where you were editing the tex file.

The reason Latex-Suite does not have this setting by default is that on some systems this causes unpredictable results in the DVI output. If you find the DVI output satisfactory, then you can insert the first of the 2 lines above into your `$VIM/ftplugin/tex.vim` file. `$VIM` is `~/vimfiles` for windows and `~/.vim` for *nix machines.

### Performing inverse searches

Most DVI viewers also support inverse searching, whereby you can make the DVI viewer ask vim to display the tex source corresponding to the DVI file being shown. This is extremely helpful while proofreading large documents.

Simply double-click anywhere in the viewer window. If the viewer supports it, then it will attempt to open an editor window at the location corresponding to where you double-clicked. On *nix platforms, Latex-Suite attempts to start the viewer program in such a way that it already knows to use vim to open the tex source. Thus you should see a vim window open up showing the tex file. However, if there is an error, or some other program is used, you will need to tell the viewer program to use gvim as the editor. On windows platforms, if you use the commonly available `yap` viewer (available as part of the miktex distribution), then this option can be set from `View > Options > Inverse Search`. In the `Command line:` window, write

    "C:\Program Files\vim\vim61\gvim" -c ":RemoteOpen +%l %f"

(Customize the path according to where you have installed gvim). If you double click in the view pane now, you will see gvim start up and take you to the relevant portion of the tex file.

## Conclusions

Thats all folks! By now, you should know enough of the basic functions of latex-suite. Ofcourse, latex-suite is capable of much, much more such as compiling files multiple times to resolve changed labels, compiling dependencies, handling user packages and more. To get a feel for that, you will need to take a look at the &ls; user manual.