Annotation of wikisrc/tutorials/latex_in_netbsd.mdwn, revision 1.3
1.1 jdf 1: # Latex in NetBSD
3: [LaTeX](http://en.wikipedia.org/wiki/LaTeX) is a typesetting system, most famous
4: for its use in scientific environments.
6: Especially when you need mathematical formulas or complicated diagrams, or you
7: want to generate documents automatically, Latex is a very good choice.
9: It is much more difficult to use than Office, and you have to expect to learn
10: much before you can use it, and to consult a web search or a good book often if
11: you want to use it. So if you just want to type a few letters, you are probably
12: better off using some Office suite which is intuitively usable.
14: This tutorial is about using Latex on NetBSD. If you want to learn Latex, you
15: should either go to a Latex course or introduction, or read a book about it
16: (there is a [good one](http://en.wikibooks.org/wiki/LaTeX) available on
17: Wikibooks, though it is imho rather good as a reference than a tutorial).
19: ## Installing Latex
21: If you want to use Latex, you should at least install the package
22: `tex-latex-bin`. Then you have the minimal definitions you need for compiling
23: primitive Latex files.
25: ## Installing additional packages from pkgsrc
27: Latex in NetBSD is split into several small packages, each providing one more
28: Latex packages If you want to use Latex, you don't have to do much.
30: For each package, there's usually also a package with the same name, but `-doc`
31: appended, which is the documentation for the package. So you can install each
32: package without its documentation.
34: If you want to install further files, you should search on
35: [pkgsrc.se](http://pkgsrc.se) for the files. Entering the search terms and
36: "latex" will usually find the appropriate result.
38: ### Example: amsmath
40: I've just been looking for the `amsmath` package I use for some mathematical
41: formula markup. So I did (using binary packages):
43: $ pkgin search amsmath
44: tex-amsmath-doc-2.13pl26389 Documentation for tex-amsmath
45: tex-amsmath-2.13nb2 = AMS mathematical facilities for LaTeX
47: =: package is installed and up-to-date
48: <: package is installed but newer version is available
49: >: installed package has a greater version than available package
51: Here you see there is the normal package (`tex-amsmath-2.13nb2`), and the
52: documentation package (`tex-amsmath-doc-2.13pl26389`). As I have a good internet
53: connection in the university, I don't need the local documentation, and I only
54: install the `tex-amsmath` package:
56: $ pkgin install tex-amsmath
57: calculating dependencies... done.
59: nothing to upgrade.
60: 1 packages to be installed: tex-amsmath-2.13nb2 (0B to download, 174K to
63: proceed ? [Y/n]
64: downloading packages...
65: installing packages...
66: installing tex-amsmath-2.13nb2...
67: pkg_install warnings: 1, errors: 0
68: pkg_install error log can be found in /var/db/pkgin/pkg_install-err.log
69: reading local summary...
70: processing local summary...
71: updating database: 100%
72: marking tex-amsmath-2.13nb2 as non auto-removable
74: ## Installing additional packages by hand
76: You will come across some smaller packages that are not available in pkgsrc. But
77: there are also ways to install a package local (e.g., in your home directory),
78: without interfering with the package management.
80: The major resource for documents installed in your home is `~/texmf/`, where you
81: put your own Latex classes. For system-wide files, `/usr/pkg/share/texmf-dist/`
82: is the major resource.
84: So if you found a package (e.g., on [CTAN](http://www.ctan.org), a major
85: resource for Latex files), you unpack it and put the files in one of these
86: directories, depending on whether you want them only for one user or for all
87: users on the system.
89: For all filetypes, there are special subdirectories of these (along many other
90: paths). You can find them using the tool `kpsepath` (part of `kpathsea`).
92: In my case, I wanted to use `alphadin`, a package for having German-styled
93: citation references. So I went to
95: downloaded the package, and unpacked it:
1.2 jdf 97: $ ftp http://mirrors.ctan.org/biblio/bibtex/contrib/german/din1505.zip
98: Requesting http://mirrors.ctan.org/biblio/bibtex/contrib/german/din1505.zip
99: Redirected to http://sunsite.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/biblio/bibtex/contrib/german/din1505.zip
100: Requesting http://sunsite.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/biblio/bibtex/contrib/german/din1505.zip
101: 100% |********************************************************************************************| 408 KiB 244.11 KiB/s 00:00 ETA
102: 417797 bytes retrieved in 00:01 (244.09 KiB/s)
1.1 jdf 103: $ unzip din1505.zip
104: Archive: din1505.zip
105: creating: din1505/
106: extracting: din1505/abbrvdin.bst
107: extracting: din1505/alphadin.bst
108: extracting: din1505/plaindin.bst
109: extracting: din1505/unsrtdin.bst
110: extracting: din1505/natdin.bst
111: extracting: din1505/natbib.cfg
112: extracting: din1505/leitbild3.pdf
113: extracting: din1505/leitbild.bib
114: extracting: din1505/normpatsoft.pdf
117: Running `kpsepath` showed that the directory to install the contained `.bst`
118: files was `~/texmf/bibtex/bst`:
120: $ kpsepath bst
1.2 jdf 123: So I moved the files to `~/texmf/bibtex/bst` (and created the directory before
1.1 jdf 125:
126: $ cd din1505/
1.2 jdf 127: $ mkdir -p ~/texmv/bibtex/bst
1.1 jdf 128: $ mv *.bst ~/texmf/bibtex/bst
130: Afterwards, compiling everything worked fine.
132: ## Useful packages
134: For writing my Bachelor's thesis, I used the following packages. Some of them
135: are very basic and are generally useful for many purposes, but especially for
136: scientific documents, they are useful:
138: * `tex-babel`
139: * `tex-amsmath`
140: * `tex-amscls`
141: * `tex-stmaryrd`
142: * `tex-microtype`
143: * `tex-oberdiek`
144: * `tex-bibtex` -- [BibTeX](http://en.wikipedia.org/wiki/Bibtex) is a system to
145: handle citations in a document.
147: ## Editors
149: If you don't want to hassle learning Latex, but still use its powerful
150: typesetting, or some other specifics (such as the formulas), you can use the
151: software LyX (editors/lyx), which creates Latex documents with
152: a WYSIWYG (or rather, WYSIWYM) interface. Even if you can write Latex, you
153: should have a look at it -- it's a very mighty tool sometimes making your work
154: much easier.
156: When it comes to editors, there are several different ones, each with its own
157: specific strength. Many people use just plain vi or vim, which I did in the
158: beginning as well. But then, I found `geany` (devel/geany), which is an IDE
159: originally, but also serves for coding Latex. It is a lightweight, but also
160: minimalistic tool for writing Latex code.
162: Another very popular tool is `kile` (editors/kile), which has many features, and
163: also is part of KDE, but a bit too much for some of my older computers (where I
164: don't install KDE because of disk space issues).
166: ## Workflow
168: When using Latex, you have the full set of tools available which are usually
169: used for software development. There are two major ideas that are very handy for
170: using Latex: Version control systems and Makefiles.
172: ### Makefiles
174: For some specific tasks, you have to build a Latex file several times, and in a
175: specific order. E.g., when you want to have the table of contents, and bibtex
176: work correctly, you have to call Latex three times, and bibtex after the first
177: run. So instead of typing `latex ba.tex` three times, or always using your
178: cursor keys to get
179: `latex ba.tex; bibtex ba; latex ba.tex; latex ba.tex`,
180: you could also put everything in a Makefile:
1.2 jdf 182: $ cat Makefile
1.1 jdf 183: all:
184: pdflatex ba.tex
185: bibtex ba
186: pdflatex ba.tex
187: pdflatex ba.tex
189: So when you call `make` in the directory of your Latex file now, all these
190: commands will be called one after the other, and you don't have to care for the
191: order afterwards anymore -- this is handled in the Makefile now.
1.3 ! wiki 193: ### LaTeX-Mk
! 195: The latex-mk package in pkgsrc (print/latex-mk) provides a more comprehensive and capable
! 196: build system for LaTeX based documents
! 197: that is similar in spirit to the BSD make system used for building NetBSD. As a simple example,
! 198: consider a document where the top level file is `mydoc.tex` and in turn, `ch1.tex`, `ch2.tex`, `ch3.tex`,
! 199: and `refs.tex` are included. In addition, a bibliography produced with BibTeX is in the file
! 200: `mybib.bib`. The `Makefile` for this project would be:
! 202: NAME= mydoc
! 203: TEXSRCS= ch1.tex ch2.tex ch3.tex refs.tex
! 204: BIBTEXSRCS= mybib.bib
! 206: .include "/usr/pkg/share/latex-mk/latex.mk"
! 208: The build system implemented by LaTeX-Mk provides various targets like view, pdf, viewpdf, etc.
! 209: For example
! 211: make viewpdf
! 213: will take the steps needed to process the document, create a pdf file, and open a pdf viewer.
! 215: For complete information on LaTeX-Mk's features and usage, visit
! 216: the [LaTeX-Mk homepage](http://latex-mk.sf.net).
1.1 jdf 218: ### Version control systems
220: When developing software, people often use
221: [version control systems (VCS)](http://en.wikipedia.org/wiki/Version_control_system):
222: This text is not an introduction to VCSes, where you should definetly consider a
223: tutorial or a book, but about how to use them with Latex.
225: I personally use
227: (devel/fossil) because it provides also an integrated webserver and a GUI you
228: use in your web browser, while most people currently prefer
230: (devel/scmgit). The commands are nearly 1:1 usable by replacing
231: `fossil` by `git`, but you should learn how to use your own VCS anyway.
233: So, when I start a project with Latex, I create the directory, and then a fossil
234: repository in it:
236: $ mkdir ba
237: $ cd ba
238: $ fossil new repo.fossil
239: project-id: 0e8cff7588381fbd87525d2dddc9359e3b9717a5
240: server-id: 194b4ed5e1c17724009d038b6bbcd0c44cc3aed7
241: admin-user: gnrp (initial password is "660930")
242: $ fossil open repo.fossil
243: $ vi Makefile
244: $ vi ba.tex
245: $ vi ba.bib
246: ...[Writing content to these three files]...
247: $ fossil add ba.tex ba.bib Makefile
248: $ fossil commit
250: And commit them for the first time.
251: Now, all you have to do is to do a `fossil commit` everytime you finish some
252: work, or want to synchronise the documents between computers.
253: If you should by accident delete a file, you can recover it from the version
254: control system. Or if you notice you deleted a paragraph long ago, but you still
255: need it, you can use the VCS to check which version it was in and then recover
256: it from that version.
258: Learning how to use a VCS *really* helps in working in a more secure manner, and
259: being able to recover from errors or for looking at the progress of the project
260: (when you use fossil, start a fossil gui by `fossil ui` and then look at the
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb