/vim/doc/latex-suite-quickstart.txt
Plain Text | 448 lines | 355 code | 93 blank | 0 comment | 0 complexity | 1149eefc4c703148b3852e0ed304e2c1 MD5 | raw file
1 A (very) quick introduction to Latex-Suite
2 *latex-suite-quickstart.txt*
3 Srinath Avadhanula <srinath AT fastmail DOT fm>
4
5
6
7 Abstract
8 ========
9Latex-Suite is a comprehensive set of scripts to aid in editing, compiling and
10viewing LaTeX documents. A thorough explanation of the full capabilities of
11Latex-Suite is described in the user manual. This guide on the other hand,
12provides a quick 30-45 minute running start to some of the more commonly used
13functionalities of Latex-Suite.
14
15 *latex-suite-quickstart.txt-toc*
16|lq_1| Using this tutorial
17|lq_2| Inserting a template
18|lq_3| Inserting a package
19|lq_4| Inserting an Environment
20|lq_5| A few keyboard shortcuts
21|lq_6| Folding in Latex-Suite
22|lq_7| Inserting a Reference
23|lq_8| Compiling a document
24 |lq_8_1| Debugging LaTeX source files
25|lq_9| Viewing DVI files
26 |lq_9_1| Performing forward searches
27 |lq_9_2| Performing inverse searches
28|lq_10| Conclusions
29
30================================================================================
31Viewing this file
32
33This file can be viewed with all the sections and subsections folded to ease
34navigation. By default, vim does not fold help documents. To create the folds,
35press za now. The folds are created via a foldexpr which can be seen in the
36last section of this file.
37
38See |usr_28.txt| for an introduction to folding and |fold-commands| for key
39sequences and commands to work with folds.
40
41================================================================================
42Using this tutorial *lq_1* *lq_a_bc*
43 *lsq-using-tutorial*
44
45
46
47This tutorial assumes that you have vim version 6.1+ installed on your machine.
48To check, open vim and type >
49 :ver
50You will see the version in the first line of the output. Get the latest vim
51version from http://vim.sf.net |lq_u_1|.
52
53Assuming you have Vim 6.1+ already up and running, follow the instructions here
54|lq_u_2| to set up Latex-Suite. Remember to make sure your 'grepprg' setting of
55Vim works.
56
57Good, now you are all set to start the tutorial. Since this tutorial aims to
58explain the newbie-friendly version of Latex-Suite, it needs some GUI
59functionality. Therefore, at least for this tutorial, open the gui version of
60vim. (On MS windows, this is the default). Open up this help file in either the
61same gvim session in a split window or in a different session and follow the
62(friendly) instructions.
63
64================================================================================
65Inserting a template *lq_2* *lq_a_bd*
66 *lsq-inserting-template*
67
68
69
70Start up gvim and begin editing a new file. >
71 e newfile.tex
72If the installation went well, you should see a new set of menus appear. Goto
73Tex-Suite > Templates. You will see a number of templates to choose from. For
74now, choose to insert a template for an article. You should get the following in
75the main vim window (after possibly a hit-enter prompt). >
76
77 1 % File: sample.tex
78 2 % Created: Sun Jun 22 04:00 PM 2003 P
79 3 % Last Change: Sun Jun 22 04:00 PM 2003 P
80 4 %
81 5 \documentclass[a4paper]{article}
82 6 \begin{document}
83 7
84 8 \end{document}
85 9
86 10 ~
87 11 ~
88 12 ~
89 13 ~
90 -- INSERT -- 7,1 All
91
92
93
94The cursor is left on line 7 (just after the \begin{document} line) from where
95you can start typing straight away. Trying to lessen movement is a recurring
96theme in Latex-Suite.
97
98================================================================================
99Inserting a package *lq_3* *lq_a_be*
100 *lsq-lsq-inserting-package*
101
102
103
104Assume that we are writing a mathematical paper and we want to use the popular
105amsmath package. We will use some functionality which Latex-Suite provides
106specifically for including LaTeX packages, providing options etc. Navigate to
107before the \begin{document} line (The portion of the document before the
108\begin{document} is called the _preamble_ in LaTeX). On an empty line in the
109preamble, type the single word amsmath and then press <F5> in normal mode. The
110line will change to >
111 \usepackage[]{amsmath}<++>
112with the cursor positioned conveniently between the []'s. For now, do not worry
113about the trailing <++> at the end of this line. Assume we want to provide the
114sumlimits options to amsmath. You can either type in this option manually, or
115choose from a menu of package options which Latex-Suite automatically creates
116when you insert a package using <F5>. With the cursor still placed between the
117[], goto TeX-Suite > Packages > amsmath Options. Choose the sumlimits option.
118The package line should get converted to: >
119 \usepackage[sumlimits,]{amsmath}<++>
120
121
122with the cursor before ]. Press <C-j> in insert mode. You will see the cursor
123jump to the end of the package line and the trailing <++> will disappear. What
124just happened?! You had your first taste of _Placeholders_. Read more about them
125(later) here |lq_u_3|. In short, pressing <C-j> in insert mode takes you to the
126next <++> in the text.
127
128================================================================================
129Inserting an Environment *lq_4* *lq_a_bf*
130 *lsq-insert-environment*
131
132
133
134Now let us type in a simple formula in LaTeX. Move back to the body of the
135document (The portion of the document between \begin{document} and
136\end{document} is called the body). Type in a few simple sentences and then on
137an empty line, type the single word eqnarray. Escape to normal mode and press
138<F5>. (Remember: <F5> is very useful!) This time, the line will change to: >
139 \begin{eqnarray}
140 \label{}<++>
141 \end{eqnarray}<++>
142<with the cursor between the {}. Enter a label. We will use eqn:euler. After
143typing in eqn:euler, press <C-j>. This will take you outside the curly-braces.
144Another time you used a Placeholder!
145
146================================================================================
147A few keyboard shortcuts *lq_5* *lq_a_bg*
148 *lsq-keyboard-shortcuts*
149
150
151
152Now to type in the famous Euler formula. Our aim is to type >
153 e^{j\pi} + 1 &=& 0
154Instead of typing this blindly, let us use a few shortcuts to reduce movement.
155Start out by typing e^. Now instead of typing {, type another ^. You will see
156the e^^ change instantly to e^{}<++> with the cursor between {}'s. (The ^^
157changed to ^{}<++>.) Continue with the following sequence of letters: j`p. This
158will change instantly to j\pi. (The `p changed to \pi.) Having typed in all we
159need to type between the {}'s, press <C-j>. You will pop back out of the
160curly-braces. Continue typing the rest of the formula. You can use == as a
161shortcut for &=&. Latex-Suite provides a large number of such shortcuts which
162should making typing much more fun and fast if you get acquainted with them. A
163list is provided here |lq_u_4|. Definitely spend some time getting a feel for
164them. Most of them are pretty intuitive like `/ for \frac{}{}, `8 for \infty
165etc.
166
167In order to understand the next section better, it will be helpful to have one
168more \label. Lets use the handy <F5> key to insert another equation. This time
169something simple like the following will do: >
170 \begin{eqnarray}
171 \label{eqn:simple}
172 1 + 1 = 2
173 \end{eqnarray}
174
175
176================================================================================
177Folding in Latex-Suite *lq_6* *lq_a_bh* *lsq-folding*
178
179
180
181Okay, we have typed enough. At this stage, hopefully, your file is looking
182something like this: >
183
184 1 % File: sample.tex
185 2 % Created: Sun Jun 22 04:00 PM 2003 P
186 3 % Last Change: Mon Dec 15 07:00 PM 2003
187 4 %
188 5 \documentclass[a4paper]{article}
189 6
190 7 \usepackage[sumlimits,]{amsmath}
191 8
192 9 \begin{document}
193 10 \begin{eqnarray}
194 11 \label{eqn:euler}
195 12 e^{j\pi} + 1 &=& 0
196 13 \end{eqnarray}
197 14 This is the famous euler equation. I
198 15 will type another equation, just as
199 16 true:
200 17 \begin{eqnarray}
201 18 \label{eqn:simple}
202 19 1 + 1 &=& 2
203 20 \end{eqnarray}
204 21 This is my contribution to mathematics.
205 22 \end{document}
206
207In normal mode, press \rf. This will fold up the entire file and you should see
208the file looking as below: >
209
210 1 % File: sample.tex
211 2 % Created: Sun Jun 22 04:00 PM 2003 P
212 3 % Last Change: Mon Dec 15 07:00 PM 2003
213 4 %
214 5 +-- 4 lines: Preamble: \documentclass[a4paper]{article} -----
215 9 \begin{document}
216 10 +-- 4 lines: eqnarray (eqn:euler) \label{eqn:euler} -----------
217 14 This is the famous euler equation. I
218 15 will type another equation, just as
219 16 true:
220 10 +-- 4 lines: eqnarray (eqn:simple) \label{eqn:simple} ---------
221 21 This is my contribution to mathematics.
222 22 \end{document}
223
224What has happened is that Latex-Suite folded away blocks of LaTeX code into
225folded regions. You can open and close folds by using the command za in normal
226mode.
227
228================================================================================
229Inserting a Reference *lq_7* *lq_a_bi*
230 *lsq-inserting-reference*
231
232
233
234A necessary part of LaTeX editing is referencing equations, figures,
235bibliographic entries etc. This is done with the \ref and the \cite commands.
236Latex-Suite provides an easy way to do this. Somewhere in the body of the
237document, type in the following sentence >
238 This is a reference to (\ref{}).
239With the cursor between the {} press <F9> in insert mode. Your vim session will
240sprout two new windows and it should look like below: >
241
242 9 \begin{document}
243 10 +-- 4 lines: eqnarray (eqn:euler) : \label{eqn:euler}-----------------------
244 14 This is the famous euler equation. I
245 15 will type another equation, just as
246 16 true:
247 17 +-- 4 lines: eqnarray (eqn:simple) : \label{eqn:simple}---------------------
248 21 This is my contribution to mathematics.
249 22 This is a reference to (\ref{}<++>)<++>
250 23 \end{document}
251 ~
252 ~
253 ~
254 test.tex [+] 22,29 Bot
255 test.tex|11| \label{eqn:euler}
256 test.tex|18| \label{eqn:simple}
257 ~
258 ~
259 ~
260 [Error List] 1,1 All
261 7 \usepackage[sumlimits,]{amsmath}
262 8
263 9 \begin{document}
264 10 \begin{eqnarray}
265 11 \label{eqn:euler}
266 12 e^{j\pi} + 1 &=& 0
267 13 \end{eqnarray}
268 14 This is the famous euler equation. I
269 15 will type another equation, just as
270 16 true:
271 test.tex [Preview][+] 11,2-5 46%
272
273
274
275The cursor will relocate to the middle window which shows all \labels found in
276all the .tex file in the current directory. You can scroll up and down in the
277middle window till you reach the reference you want to insert. Notice how when
278you scroll in the middle window, the bottom "Preview" window scrolls
279automatically to show you the location of the current selection. This helps you
280identify the reference with greater ease because often times, \labels are not
281descriptive enough or there might be too many of them. To insert the reference,
282just position the cursor on the relevant line in the middle window and press
283<enter>. The line which you were editing will change to: >
284 This is a reference to (\ref{eqn:euler})
285<and the bottom windows close automatically.
286
287The <F9> key also works for inserting \cite commands to reference bibliographic
288entries, inserting file names for the \inputgraphics command and just plain
289searching for words. Click here |lq_u_5| for more information.
290
291================================================================================
292Compiling a document *lq_8* *lq_a_bj*
293 *lsq-compiling*
294
295|lq_8_1| Debugging LaTeX source files
296
297
298Great! We have just created a small latex file. The next step is to make the
299latex compiler create a .dvi file from it. Compiling via latex-suite is simple.
300Goto normal mode and press \ll (replace \ with whatever mapleader setting you
301have). This will call the latex compiler. If all goes well, then the focus
302should return to the vim window.
303
304Nothing happend? Ouch! You might need to do some additional settings as
305described here. |lq_u_6|
306
307
308--------------------------------------------------------------------------------
309Debugging LaTeX source files *lq_8_1* *lq_a_bk*
310 *lsq-debugging*
311
312To illustrate the debugging procedure, let's create a few mistakes in the file.
313Insert the following ``mistakes'' in the file: >
314 This is a $\mistake$.
315 And this is $\another$
316Now press \ll again. This time you will notice that after compilation finishes,
317the cursor automatically lands on $\mistake$. In addition, 2 new windows will
318appear as shown here:
319
320The middle window is an _Error List_ window showing you the errors which the
321latex compiler found. Th bottom window is a _Log Preview_ window, which shows
322you the context of the error made by displaying the relevant portion of the .log
323file created during the latex compilation procedure. Jump to the _Error List_
324window and try scrolling around in it using either the j, k keys or the arrow
325keys. You will notice that the _Log Preview_ window scrolls automatically to
326retain the context of the error you are currently located on. If you press
327<enter> on any line, you will see the cursor jump to the location of the error.
328Latex-Suite tries to guess the column location as best as it can so you can
329continue typing straight away.
330Having got a taste for compiling, proceed by deleting the erroneous lines and
331re-compiling.
332
333The Latex-Suite compiler is capable of much more including selectively filtering
334out common errors which you might want to ignore for the moment, compiling parts
335of a document, setting levels of verbosity in the compiler output etc. See here
336|lq_u_7| for more.
337
338================================================================================
339Viewing DVI files *lq_9* *lq_a_bl*
340 *lsq-viewing-dvi*
341
342|lq_9_1| Performing forward searches
343|lq_9_2| Performing inverse searches
344
345
346Now that you have compiled your first latex source, its time to view it. Again,
347this should be pretty simple. Press \lv in normal mode. Depending on your
348platform, a DVI viewer program should open up and display the dvi file generated
349in compilation step previously.
350
351Nothing happend? Ouch! You might need to do some additional settings as
352described here. |lq_u_8|
353
354
355--------------------------------------------------------------------------------
356Performing forward searches *lq_9_1* *lq_a_bm*
357 *lsq-quick-forward-searching*
358
359If you are using a modern DVI viewer, then it is possible to do what is called
360forward and inverse searching. However, you will need to customize the standard
361Latex-Suite distribution in order to utilize this functionality. Type in the
362following on the command line: >
363 :let g:Tex_CompileRule_dvi = 'latex -src-specials -interaction=nonstopmode $*'
364 :TCTarget dvi
365
366
367Now recompile the latex file by pressing \ll. This time, instead of pressing \lv
368to view the file, press \ls from within the tex file. If the DVI viewer supports
369forward searching (most of them do), then the viewer will actually display the
370portion of the DVI file corresponding to the location where you were editing the
371tex file.
372
373NOTE: The reason Latex-Suite does not have this setting by default is that on
374 some systems this causes unpredictable results in the DVI output. If you
375 find the DVI output satisfactory, then you can insert the first of the 2
376 lines above into your $VIM/ftplugin/tex.vim file. $VIM is ~/vimfiles for
377 windows and ~/.vim for *nix machines.
378
379
380
381--------------------------------------------------------------------------------
382Performing inverse searches *lq_9_2* *lq_a_bn*
383 *lsq-quick-inverse-searching*
384
385Most DVI viewers also support inverse searching, whereby you can make the DVI
386viewer ask vim to display the tex source corresponding to the DVI file being
387shown. This is extremely helpful while proofreading large documents.
388
389Simply double-click anywhere in the viewer window. If the viewer supports it,
390then it will attempt to open an editor window at the location corresponding to
391where you double-clicked. On *nix platforms, Latex-Suite attempts to start the
392viewer program in such a way that it already knows to use vim to open the tex
393source. Thus you should see a vim window open up showing the tex file. However,
394if there is an error, or some other program is used, you will need to tell the
395viewer program to use gvim as the editor. On windows platforms, if you use the
396commonly available yap viewer (available as part of the miktex distribution),
397then this option can be set from View > Options > Inverse Search. In the Command
398line: window, write >
399 "C:\Program Files\vim\vim61\gvim" -c ":RemoteOpen +%l %f"
400(Customize the path according to where you have installed gvim). If you double
401click in the view pane now, you will see gvim start up and take you to the
402relevant portion of the tex file.
403
404================================================================================
405Conclusions *lq_10* *lq_a_bo*
406 *lsq-conclusions*
407
408
409
410Thats all folks! By now, you should know enough of the basic functions of
411latex-suite. Ofcourse, latex-suite is capable of much, much more such as
412compiling files multiple times to resolve changed labels, compiling
413dependencies, handling user packages and more. To get a feel for that, you will
414need to take a look at the Latex-Suite user manual. |lq_u_9|
415
416================================================================================
417URLs used in this file
418
419*lq_u_1* : http://vim.sf.net
420*lq_u_2* : http://vim-latex.sourceforge.net/index.php?subject=download&title=Download
421*lq_u_3* : http://vim-latex.sourceforge.net/documentation/latex-suite/latex-macros.html
422*lq_u_4* : http://vim-latex.sourceforge.net/documentation/latex-suite/auc-tex-mappings.html
423*lq_u_5* : http://vim-latex.sourceforge.net/documentation/latex-suite/latex-completion.html
424*lq_u_6* : http://vim-latex.sourceforge.net/index.php?subject=faq&title=FAQ#faq-2
425*lq_u_7* : http://vim-latex.sourceforge.net/documentation/latex-suite/latex-compiling.html
426*lq_u_8* : http://vim-latex.sourceforge.net/index.php?subject=faq&title=FAQ#faq-3
427*lq_u_9* : http://vim-latex.sourceforge.net/index.php?subject=manual&title=Manual#user-manual
428
429================================================================================
430About this file
431
432This file was created automatically from its XML variant using db2vim. db2vim is
433a python script which understands a very limited subset of the Docbook XML 4.2
434DTD and outputs a plain text file in vim help format.
435
436db2vim can be obtained via anonymous CVS from sourceforge.net. Use
437
438cvs -d:pserver:anonymous@cvs.vim-latex.sf.net:/cvsroot/vim-latex co db2vim
439
440Or you can visit the web-interface to sourceforge CVS at:
441http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/vim-latex/db2vim/
442
443The following modelines should nicely fold up this help manual.
444
445vim:ft=help:fdm=expr:nowrap
446vim:foldexpr=getline(v\:lnum-1)=~'-\\{80}'?'>2'\:getline(v\:lnum-1)=~'=\\{80}'?'>1'\:getline(v\:lnum)=~'=\\{80}'?'0'\:getline(v\:lnum)=~'-\\{80}'?'1'\:'='
447vim:foldtext=substitute(v\:folddashes.substitute(getline(v\:foldstart),'\\s*\\*.*',"",""),'^--','\ \ \ \ \ \ ','')
448================================================================================