434 lines
18 KiB
XML
434 lines
18 KiB
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 "<++>">
|
|
]>
|
|
<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.
|
|
</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 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><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 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><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>equation</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{equation}
|
|
<+content+>
|
|
\label{<+label+>}
|
|
\end{equation}&ph;</programlisting>
|
|
with the cursor on the <literal><+content+></literal>.
|
|
</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 on
|
|
<literal><+content+></literal>. (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.
|
|
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 <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>
|
|
Now enter a label.
|
|
Press <literal><C-j></literal> to jump to
|
|
<literal><+label+></literal>.
|
|
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>
|
|
<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{equation}
|
|
\label{eqn:simple}
|
|
1 + 1 = 2
|
|
\end{equation}</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{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}
|
|
</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: 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}
|
|
</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 a new windows showing all the
|
|
<literal>\label</literal>s found in all the <literal>.tex</literal> files
|
|
of your current project.
|
|
To insert the reference, just position the cursor on
|
|
the relevant line 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 window closes automatically.
|
|
</para>
|
|
<para>
|
|
The <literal><F9></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&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><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 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 > 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
|
|
-->
|