dotfiles/vim/vim-latex/doc/latex-suite-quickstart.xml

<?xml version='1.0' encoding='ISO-8859-1'?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "docbook-xml/docbookx.dtd" 
[<!ENTITY dummy      "dummy">
<!ENTITY date       "$Date$">
<!ENTITY ls         "Latex-Suite">
<!ENTITY latex      "LaTeX">
<!ENTITY vim        "Vim">
<!ENTITY ph         "&lt;++&gt;">
]>
<article lang="en">
 <articleinfo id="lsq-articleinfo">

  <title id="lsq-articleinfo-title">A (very) quick introduction to Latex-Suite</title>

  <author>
   <firstname>Srinath</firstname>
   <surname>Avadhanula</surname>
   <affiliation>
    <address><email>srinath AT fastmail DOT fm</email></address>
   </affiliation>
  </author>

  <abstract>
   &ls; is a comprehensive set of scripts to aid in editing, compiling and
   viewing &latex; documents. A thorough explanation of the full
   capabilities of &ls; is described in the user manual. This guide on the
   other hand, provides a quick 30-45 minute running start to some of the
   more commonly used functionalities of &ls;.
  </abstract>

  <date>&date;</date>

 </articleinfo>
 <section id="lsq-using-tutorial">
  <title id="using-tutorial">Using this tutorial</title>
  <para>
   This tutorial assumes that you have vim version 6.1+ installed on your
   machine. To check, open vim and type
   <programlisting>:ver</programlisting>
   You will see the version in the first line of the output. Get the latest
   vim version from <ulink url="http://vim.sf.net">http://vim.sf.net</ulink>.
  </para>
  <para>
   Assuming you have Vim 6.1+ already up and running, follow the
   instructions <ulink
    url="http://vim-latex.sourceforge.net/index.php?subject=download&amp;title=Download">here</ulink>
   to set up Latex-Suite. Remember to make sure your
   <literal>'grepprg'</literal> setting of &vim; works.
  </para>
  <para>
   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.
  </para>
 </section>
 <section id="lsq-inserting-template">
  <title id="inserting-template-title">Inserting a template</title>
  <para>
   Start up gvim and begin editing a new file.
   <programlisting>e newfile.tex</programlisting>
   If the installation went well, you should see a new set of
   menus appear. Goto <literal>Tex-Suite &gt; Templates</literal>. 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).
   <programlisting>
      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
</programlisting>
  </para>
  <imageobject>
   <imagedata fileref="" format="png"></imagedata>
  </imageobject>
  <para>
   The cursor is left on line 7 (just after the
   <literal>\begin{document}</literal> line) from where you can start
   typing straight away. Trying to lessen movement is a recurring theme in
   Latex-Suite.
  </para>
 </section>
 <section id="lsq-lsq-inserting-package">
  <title>Inserting a package</title>
  <para>
   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
   <literal>\begin{document}</literal> line (The portion of the document
   before the <literal>\begin{document}</literal> is called the
   <emphasis>preamble</emphasis> in LaTeX). On an empty line in the
   preamble, type the single word <literal>amsmath</literal> and then press
   <literal>&lt;F5&gt;</literal> in normal mode. The line will change to
   <programlisting>\usepackage[]{amsmath}&ph;</programlisting>
   with the cursor positioned conveniently between the
   <literal>[]</literal>'s. For now, do not worry about the trailing
   <literal>&ph;</literal> at the end of this line. Assume we want to
   provide the <literal>sumlimits</literal> 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 <literal>&lt;F5&gt;</literal>.  With the cursor still
   placed between the <literal>[]</literal>, goto <literal>TeX-Suite &gt;
    Packages &gt; amsmath Options</literal>. Choose the
   <literal>sumlimits</literal> option. The package line should get
   converted to:
   <programlisting>\usepackage[sumlimits,]{amsmath}&ph;</programlisting>
  </para>
  <para>
   with the cursor before <literal>]</literal>. Press
   <literal>&lt;C-j&gt;</literal> in insert mode. You will see the cursor
   jump to the end of the package line and the trailing
   <literal>&ph;</literal> will disappear. What just happened?! You had
   your first taste of <emphasis>Placeholders</emphasis>. Read more about
   them (later) <ulink
    url="http://vim-latex.sourceforge.net/documentation/latex-suite/latex-macros.html">here</ulink>.
   In short, pressing <literal>&lt;C-j&gt;</literal> in insert mode takes
   you to the next <literal>&ph;</literal> in the text.
  </para>
 </section>
 <section id="lsq-insert-environment">
  <title>Inserting an Environment</title>
  <para>
   Now let us type in a simple formula in LaTeX. Move back to the body of
   the document (The portion of the document between
   <literal>\begin{document}</literal> and
   <literal>\end{document}</literal> is called the body). Type in a few
   simple sentences and then on an empty line, type the single word
   <literal>eqnarray</literal>. Escape to normal mode and press
   <literal>&lt;F5&gt;</literal>. (Remember:
   <literal>&lt;F5&gt;</literal> is very useful!) This time, the line will
   change to:
  <programlisting>\begin{eqnarray}
    \label{}&ph;
\end{eqnarray}&ph;</programlisting>
   with the cursor between the <literal>{}</literal>. Enter a label. We
   will use <literal>eqn:euler</literal>. After typing in
   <literal>eqn:euler</literal>, press <literal>&lt;C-j&gt;</literal>. This
   will take you outside the curly-braces.  Another time you used a
   Placeholder!
  </para>
 </section>
 <section id="lsq-keyboard-shortcuts">
  <title>A few keyboard shortcuts</title> 
  <para>
   Now to type in the famous Euler formula. Our aim is to type
   <programlisting>e^{j\pi} + 1 &amp;=&amp; 0</programlisting> Instead
   of typing this blindly, let us use a few shortcuts to reduce
   movement.  Start out by typing <literal>e^</literal>. Now instead of
   typing <literal>{</literal>, type another <literal>^</literal>. You
   will see the <literal>e^^</literal> change instantly to
   <literal>e^{}&ph;</literal> with the cursor between
   <literal>{}</literal>'s. (The <literal>^^</literal> changed to
   <literal>^{}&ph;</literal>.) Continue with the following sequence of
   letters: <literal>j`p</literal>. This will change instantly to
   <literal>j\pi</literal>. (The <literal>`p</literal> changed to
   <literal>\pi</literal>.) Having typed in all we need to type between
   the <literal>{}</literal>'s, press <literal>&lt;C-j&gt;</literal>.
   You will pop back out of the curly-braces. Continue typing the rest
   of the formula. You can use <literal>==</literal> as a shortcut for
   <literal>&amp;=&amp;</literal>. Latex-Suite provides a large number
   of such shortcuts which should making typing much more fun and fast
   if you get acquainted with them. A list is provided <ulink
    url="http://vim-latex.sourceforge.net/documentation/latex-suite/auc-tex-mappings.html">here</ulink>. Definitely spend some time getting a feel for
   them. Most of them are pretty intuitive like <literal>`/</literal>
   for <literal>\frac{}{}</literal>, <literal>`8</literal> for
   <literal>\infty</literal> etc.
  </para>
  <para>
   In order to understand the next section better, it will be helpful
   to have one more <literal>\label</literal>. Lets use the handy
   <literal>&lt;F5&gt;</literal>
   key to insert another equation. This time something simple like the
   following will do:
   <programlisting>\begin{eqnarray}
  \label{eqn:simple}
  1 + 1 = 2
\end{eqnarray}</programlisting>
  </para>
 </section>
 <section id="lsq-folding">
  <title>Folding in &ls;</title>
  <para>
   Okay, we have typed enough. At this stage, hopefully, your file is
   looking something like this:
<programlisting>
      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{eqnarray}
     11 	\label{eqn:euler}
     12 	e^{j\pi} + 1 &amp;=&amp; 0
     13 \end{eqnarray}
     14 This is the famous euler equation. I
     15 will type another equation, just as
     16 true:
     17 \begin{eqnarray}
     18 	\label{eqn:simple}
     19 	1 + 1 &amp;=&amp; 2
     20 \end{eqnarray}
     21 This is my contribution to mathematics.
     22 \end{document}
</programlisting>
    In normal mode, press <literal>\rf</literal>. This will fold up the
    entire file and you should see the file looking as below:
<programlisting>
      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: eqnarray (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: eqnarray (eqn:simple) \label{eqn:simple} ---------
     21 This is my contribution to mathematics.
     22 \end{document}
</programlisting>
    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
    <literal>za</literal> in normal mode.
  </para>
 </section>
 <section id="lsq-inserting-reference">
  <title>Inserting a Reference</title>
  <para>
   A necessary part of LaTeX editing is referencing equations, figures,
   bibliographic entries etc. This is done with the
   <literal>\ref</literal> and the <literal>\cite</literal> commands.
   Latex-Suite provides an easy way to do this. Somewhere in the body of
   the document, type in the following sentence
   <programlisting>This is a reference to (\ref{}).</programlisting>
   With the cursor between the <literal>{}</literal> press
   <literal>&lt;F9&gt;</literal> in insert mode. Your vim session will
   sprout two new windows and it should look like below:
<programlisting>
      9 \begin{document}
     10 +--  4 lines: eqnarray (eqn:euler) :  \label{eqn:euler}-----------------------
     14 This is the famous euler equation. I
     15 will type another equation, just as
     16 true:
     17 +--  4 lines: eqnarray (eqn:simple) :  \label{eqn:simple}---------------------
     21 This is my contribution to mathematics.
     22 This is a reference to (\ref{}&lt;++&gt;)&lt;++&gt;
     23 \end{document}
~
~
~
test.tex [+]                                                        22,29          Bot
test.tex|11| \label{eqn:euler}
test.tex|18| \label{eqn:simple}
~
~
~
[Error List]                                                        1,1            All
      7 \usepackage[sumlimits,]{amsmath}
      8
      9 \begin{document}
     10 \begin{eqnarray}
     11     \label{eqn:euler}
     12     e^{j\pi} + 1 &amp;=&amp; 0
     13 \end{eqnarray}
     14 This is the famous euler equation. I
     15 will type another equation, just as
     16 true:
test.tex [Preview][+]                                               11,2-5         46%
</programlisting>
  </para>
  <imageobject>
   <imagedata fileref="" format=""></imagedata>
  </imageobject>
  <para>
   The cursor will relocate to the middle window which shows all
   <literal>\label</literal>s found in all the <literal>.tex</literal> file
   in the current directory. 
   You can scroll up and down in the middle window till you reach the
   reference you want to insert. Notice how when you scroll in the
   middle window, the bottom "Preview" window scrolls automatically to
   show you the location of the current selection. This helps you
   identify the reference with greater ease because often times,
   <literal>\labels</literal> are not descriptive enough or there might be too
   many of them. To insert the reference, just position the cursor on
   the relevant line in the middle window and press
   <literal>&lt;enter&gt;</literal>. The line which you were editing will change
   to:
   <programlisting>This is a reference to (\ref{eqn:euler})</programlisting>
   and the bottom windows close automatically.
  </para>
  <para>
   The <literal>&lt;F9&gt;</literal> key also works for inserting
   <literal>\cite</literal> commands to reference bibliographic entries,
   inserting file names for the <literal>\inputgraphics</literal> command
   and just plain searching for words. Click <ulink
    url="http://vim-latex.sourceforge.net/documentation/latex-suite/latex-completion.html">here</ulink>
   for more information.
  </para>
 </section>
 <section id="lsq-compiling">
  <title>Compiling a document</title>
  <para>
   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 <literal>\ll</literal>
   (replace <literal>\</literal> with whatever <literal>mapleader</literal> setting you
   have). This will call the latex compiler. If all goes well, then
   the focus should return to the vim window. 
  </para>
  <para>
   Nothing happend? Ouch! You might need to do some additional settings as
   described <ulink
    url="http://vim-latex.sourceforge.net/index.php?subject=faq&amp;title=FAQ#faq-2">here.</ulink>
  </para>
  <section id="lsq-debugging">
   <title>Debugging LaTeX source files</title>
   <para>
    To illustrate the debugging procedure, let's create a few mistakes
    in the file. Insert the following ``mistakes'' in the file:
    <programlisting>This is a $\mistake$.
And this is $\another$</programlisting>
    Now press <literal>\ll</literal> again. This time you will notice that
    after compilation finishes, the cursor automatically lands on
    <literal>$\mistake$</literal>. In addition, 2 new windows will appear
    as shown here:
   </para>
   <imageobject>
    <imagedata fileref="" format=""></imagedata>
   </imageobject>
   <para>
    The middle window is an <emphasis>Error List</emphasis> window
    showing you the errors which the latex compiler found. The bottom
    window is a <emphasis>Log Preview</emphasis> window, which shows you
    the context of the error made by displaying the relevant portion of
    the <literal>.log</literal> file created during the latex
    compilation procedure. Jump to the <emphasis>Error List</emphasis>
    window and try scrolling around in it using either the <literal>j,
     k</literal> keys or the arrow keys. You will notice that the
    <emphasis>Log Preview</emphasis> window scrolls automatically to
    retain the context of the error you are currently located on. If you
    press <literal>&lt;enter&gt;</literal> 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.
   </para>
  </section>
  <para>
   Having got a taste for compiling, proceed by deleting the erroneous
   lines and re-compiling.
  </para>
  <para>
   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 <ulink
    url="http://vim-latex.sourceforge.net/documentation/latex-suite/latex-compiling.html">here</ulink>
   for more.
  </para>
 </section>
 <section id="lsq-viewing-dvi">
  <title>Viewing DVI files</title>
  <para>
   Now that you have compiled your first latex source, its time to
   view it. Again, this should be pretty simple. Press
   <literal>\lv</literal> in normal mode. Depending on your platform, a DVI
   viewer program should open up and display the dvi file generated in
   compilation step previously.
  </para>
  <para>
   Nothing happend? Ouch! You might need to do some additional settings as
   described <ulink
    url="http://vim-latex.sourceforge.net/index.php?subject=faq&amp;title=FAQ#faq-3">here.</ulink>
  </para>
  <section id="lsq-quick-forward-searching">
   <title>Performing forward searches</title>
   <para>
    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:

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

    Now recompile the latex file by pressing <literal>\ll</literal>.
    This time, instead of pressing <literal>\lv</literal> to view the
    file, press <literal>\ls</literal> 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.
   </para>
   <note>
    <para>
     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
     <literal>$VIM/ftplugin/tex.vim</literal> file.
     <literal>$VIM</literal> is <literal>~/vimfiles</literal> for
     windows and <literal>~/.vim</literal> for *nix machines.
    </para>
   </note>
  </section>
  <section id="lsq-quick-inverse-searching">
   <title>Performing inverse searches</title>
   <para>
    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.
   </para>

   <para>
    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 <literal>yap</literal>
    viewer (available as part of the miktex distribution), then this
    option can be set from <literal>View &gt; Options &gt; Inverse
     Search</literal>. In the <literal>Command line:</literal> window,
    write
    <programlisting>"C:\Program Files\vim\vim61\gvim" -c ":RemoteOpen +%l %f"</programlisting>
    (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.
   </para>
  </section>
 </section>
 <section id="lsq-conclusions">
  <title>Conclusions</title>
  <para>
   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 <ulink
    url="http://vim-latex.sourceforge.net/index.php?subject=manual&amp;title=Manual#user-manual">&ls;
    user manual.</ulink>
  </para>
 </section>
</article>

<!--
vim: et:sw=1:ts=1
-->