From 14d64785aaac4bb792f31c2fafb7332b74612c9f Mon Sep 17 00:00:00 2001 From: David Kaufmann Date: Mon, 14 Nov 2011 00:13:19 +0100 Subject: init copy --- vim-latex/doc/latex-suite-quickstart.xml | 471 +++++++++++++++++++++++++++++++ 1 file changed, 471 insertions(+) create mode 100644 vim-latex/doc/latex-suite-quickstart.xml (limited to 'vim-latex/doc/latex-suite-quickstart.xml') diff --git a/vim-latex/doc/latex-suite-quickstart.xml b/vim-latex/doc/latex-suite-quickstart.xml new file mode 100644 index 0000000..da3e995 --- /dev/null +++ b/vim-latex/doc/latex-suite-quickstart.xml @@ -0,0 +1,471 @@ + + + + + + + + +]> +
+ + + A (very) quick introduction to Latex-Suite + + + Srinath + Avadhanula + +
srinath AT fastmail DOT fm
+ + + + + &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;. + + + &date; + + +
+ Using this 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. + + + Assuming you have Vim 6.1+ already up and running, follow the + instructions here + 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 &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. + +
+
+ Inserting a 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 + + 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}&ph; + with the cursor positioned conveniently between the + []'s. For now, do not worry about the trailing + &ph; 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}&ph; + + + 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 + &ph; will disappear. What just happened?! You had + your first taste of Placeholders. Read more about + them (later) here. + In short, pressing <C-j> in insert mode takes + you to the next &ph; in the text. + +
+
+ Inserting an 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{}&ph; +\end{eqnarray}&ph; + 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 + + 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^{}&ph; with the cursor between + {}'s. (The ^^ changed to + ^{}&ph;.) 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. 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 &ls; + + 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 &ls; 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 + + 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 + for more information. + +
+
+ Compiling a document + + 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. + +
+ Debugging LaTeX source files + + 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 + for more. + +
+
+ Viewing DVI files + + 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. + +
+ Performing forward searches + + 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. + + + + 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 + + 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 + + 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 &ls; + user manual. + +
+
+ + -- cgit v1.2.3