/vim/doc/latex-suite-quickstart.txt
https://bitbucket.org/vertespain/config · Plain Text · 448 lines · 355 code · 93 blank · 0 comment · 0 complexity · 1149eefc4c703148b3852e0ed304e2c1 MD5 · raw 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*\\*.*',"",""),'^--','\ \ \ \ \ \ ','')
- ================================================================================