|
From: <sri...@us...> - 2003-12-16 04:04:49
|
Update of /cvsroot/vim-latex/vimfiles/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv2807
Added Files:
latex-suite-quickstart.txt latex-suite-quickstart.xml
Log Message:
adding quick-start tutorial files
--- NEW FILE: latex-suite-quickstart.txt ---
A (very) quick introduction to Latex-Suite
*latex-suite-quickstart.txt*
Srinath Avadhanula <srinath AT fastmail DOT fm>
Abstract
========
Latex-Suite is a comprehensive set of scripts to aid in editing, compiling and
viewing LaTeX documents. A thorough explanation of the full capabilities of
Latex-Suite 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 Latex-Suite.
*latex-suite-quickstart.txt-toc*
|lq_1| Using this tutorial
|lq_2| Inserting a template
|lq_3| Inserting a package
|lq_4| Inserting an Environment
|lq_5| A few keyboard shortcuts
|lq_6| Folding in Latex-Suite
|lq_7| Inserting a Reference
|lq_8| Compiling a document
|lq_8_1| Debugging LaTeX source files
|lq_9| Viewing DVI files
|lq_9_1| Performing forward searches
|lq_9_2| Performing inverse searches
|lq_10| Conclusions
================================================================================
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.
================================================================================
Using this tutorial *lq_1* *lq_a_bc*
*lsq-using-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 |lq_u_1|.
Assuming you have Vim 6.1+ already up and running, follow the instructions here
|lq_u_2| to set up Latex-Suite. Remember to make sure your 'grepprg' setting of
Vim works.
Good, now you are all set to start the tutorial. Since this tutorial aims to
explain the newbie-friendly version of Latex-Suite, 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 *lq_2* *lq_a_bd*
*lsq-inserting-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 *lq_3* *lq_a_be*
*lsq-lsq-inserting-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}<++>
with the cursor positioned conviniently between the []'s. For now, do not worry
about the trailing <++> 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}<++>
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 <++> will dissapear. What
just happened?! You had your first taste of _Placeholders_. Read more about them
(later) here |lq_u_3|. In short, pressing <C-j> in insert mode takes you to the
next <++> in the text.
================================================================================
Inserting an Environment *lq_4* *lq_a_bf*
*lsq-insert-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 eqnarray. Escape to normal mode and press
<F5>. (Remember: <F5> is very useful!) This time, the line will change to: >
\begin{eqnarray}
\label{}<++>
\end{eqnarray}<++>
<with the cursor between the {}. Enter a 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!
================================================================================
A few keyboard shortcuts *lq_5* *lq_a_bg*
*lsq-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^{}<++> with the cursor between {}'s. (The ^^
changed to ^{}<++>.) 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. You can use == as a
shortcut for &=&. 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 here |lq_u_4|. Definitely spend some time getting a feel for
them. Most of them are pretty intuitive like `/ for \frac{}{}, `8 for \infty
etc.
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{eqnarray}
\label{eqn:simple}
1 + 1 = 2
\end{eqnarray}
================================================================================
Folding in Latex-Suite *lq_6* *lq_a_bh* *lsq-folding*
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{eqnarray}
11 \label{eqn:euler}
12 e^{j\pi} + 1 &=& 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 &=& 2
20 \end{eqnarray}
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: 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}
What has happened is that Latex-Suite 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 *lq_7* *lq_a_bi*
*lsq-inserting-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 two new windows and it should look like below: >
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{}<++>)<++>
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 &=& 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%
The cursor will relocate to the middle window which shows all \labels found in
all the .tex 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, \labels 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
<enter>. The line which you were editing will change to: >
This is a reference to (\ref{eqn:euler})
<and the bottom windows close automatically.
The <F9> key also works for inserting \cite commands to reference bibliographich
entries, inserting file names for the \inputgraphics command and just plain
searching for words. Click here |lq_u_5| for more information.
================================================================================
Compiling a document *lq_8* *lq_a_bj*
*lsq-compiling*
|lq_8_1| Debugging LaTeX source files
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. |lq_u_6|
--------------------------------------------------------------------------------
Debugging LaTeX source files *lq_8_1* *lq_a_bk*
*lsq-debugging*
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. Th 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
|lq_u_7| for more.
================================================================================
Viewing DVI files *lq_9* *lq_a_bl*
*lsq-viewing-dvi*
|lq_9_1| Performing forward searches
|lq_9_2| Performing inverse searches
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. |lq_u_8|
--------------------------------------------------------------------------------
Performing forward searches *lq_9_1* *lq_a_bm*
*lsq-quick-forward-searching*
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.
NOTE: 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 *lq_9_2* *lq_a_bn*
*lsq-quick-inverse-searching*
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 extremeley 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 *lq_10* *lq_a_bo*
*lsq-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 Latex-Suite user manual. |lq_u_9|
================================================================================
URLs used in this file
*lq_u_1* : http://vim.sf.net
*lq_u_2* : http://vim-latex.sourceforge.net/index.php?subject=download&title=Download
*lq_u_3* : http://vim-latex.sourceforge.net/documentation/latex-suite/latex-macros.html
*lq_u_4* : http://vim-latex.sourceforge.net/documentation/latex-suite/auc-tex-mappings.html
*lq_u_5* : http://vim-latex.sourceforge.net/documentation/latex-suite/latex-completion.html
*lq_u_6* : http://vim-latex.sourceforge.net/index.php?subject=faq&title=FAQ#faq-2
*lq_u_7* : http://vim-latex.sourceforge.net/documentation/latex-suite/latex-compiling.html
*lq_u_8* : http://vim-latex.sourceforge.net/index.php?subject=faq&title=FAQ#faq-3
*lq_u_9* : http://vim-latex.sourceforge.net/index.php?subject=manual&title=Manual#user-manual
================================================================================
About this file
This file was created automatically from its XML variant using db2vim. db2vim is
a python script which understands a very limited subset of the Docbook XML 4.2
DTD and outputs a plain text file in vim help format.
db2vim can be obtained via anonymous CVS from sourceforge.net. Use
cvs -d:pserver:ano...@cv...:/cvsroot/vim-latex co db2vim
Or you can visit the web-interface to sourceforge CVS at:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/vim-latex/db2vim/
The following modelines should nicely fold up this help manual.
vim:ft=help:fdm=expr:nowrap
vim:foldexpr=getline(v\:lnum-1)=~'-\\{80}'?'>2'\:getline(v\:lnum-1)=~'=\\{80}'?'>1'\:getline(v\:lnum)=~'=\\{80}'?'0'\:getline(v\:lnum)=~'-\\{80}'?'1'\:'='
vim:foldtext=substitute(v\:folddashes.substitute(getline(v\:foldstart),'\\s*\\*.*',"",""),'^--','\ \ \ \ \ \ ','')
================================================================================
--- NEW FILE: 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: 2003/12/16 04:04:45 $">
<!ENTITY ls "Latex-Suite">
<!ENTITY latex "LaTeX">
<!ENTITY vim "Vim">
<!ENTITY ph "<++>">
]>
<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&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 > 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><F5></literal> in normal mode. The line will change to
<programlisting>\usepackage[]{amsmath}&ph;</programlisting>
with the cursor positioned conviniently 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><F5></literal>. With the cursor still
placed between the <literal>[]</literal>, goto <literal>TeX-Suite >
Packages > 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><C-j></literal> in insert mode. You will see the cursor
jump to the end of the package line and the trailing
<literal>&ph;</literal> will dissapear. 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><C-j></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><F5></literal>. (Remember:
<literal><F5></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><C-j></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 &=& 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><C-j></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>&=&</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><F5></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 &=& 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 &=& 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><F9></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 &=& 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><enter></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><F9></literal> key also works for inserting
<literal>\cite</literal> commands to reference bibliographich 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&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><enter></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&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 extremeley 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 > Options > 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&title=Manual#user-manual">&ls;
user manual.</ulink>
</para>
</section>
</article>
<!--
vim: et:sw=1:ts=1
-->
|
