/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

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