mirror of
https://github.com/kastdeur/dotfiles.git
synced 2024-12-22 17:23:33 +01:00
448 lines
20 KiB
Text
Executable file
448 lines
20 KiB
Text
Executable file
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 conveniently 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 disappear. 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 bibliographic
|
|
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 extremely helpful while proofreading large documents.
|
|
|
|
Simply double-click anywhere in the viewer window. If the viewer supports it,
|
|
then it will attempt to open an editor window at the location corresponding to
|
|
where you double-clicked. On *nix platforms, Latex-Suite attempts to start the
|
|
viewer program in such a way that it already knows to use vim to open the tex
|
|
source. Thus you should see a vim window open up showing the tex file. However,
|
|
if there is an error, or some other program is used, you will need to tell the
|
|
viewer program to use gvim as the editor. On windows platforms, if you use the
|
|
commonly available yap viewer (available as part of the miktex distribution),
|
|
then this option can be set from View > Options > Inverse Search. In the Command
|
|
line: window, write >
|
|
"C:\Program Files\vim\vim61\gvim" -c ":RemoteOpen +%l %f"
|
|
(Customize the path according to where you have installed gvim). If you double
|
|
click in the view pane now, you will see gvim start up and take you to the
|
|
relevant portion of the tex file.
|
|
|
|
================================================================================
|
|
Conclusions *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:anonymous@cvs.vim-latex.sf.net:/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*\\*.*',"",""),'^--','\ \ \ \ \ \ ','')
|
|
================================================================================
|