init copy

1 files changed, 471 insertions, 0 deletions

diff --git a/vim-latex/doc/latex-suite-quickstart.xml b/vim-latex/doc/latex-suite-quickstart.xml
new file mode 100644
index 0000000..da3e995
--- /dev/null
+++ b/vim-latex/doc/latex-suite-quickstart.xml
@@ -0,0 +1,471 @@
+<?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. Th 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
+-->