diff options
Diffstat (limited to 'dot_vim/doc/latex-suite-quickstart.txt')
| -rw-r--r-- | dot_vim/doc/latex-suite-quickstart.txt | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/dot_vim/doc/latex-suite-quickstart.txt b/dot_vim/doc/latex-suite-quickstart.txt new file mode 100644 index 0000000..8c18b72 --- /dev/null +++ b/dot_vim/doc/latex-suite-quickstart.txt @@ -0,0 +1,448 @@ + 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: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*\\*.*',"",""),'^--','\ \ \ \ \ \ ','') +================================================================================ |