# Latex in NetBSD [LaTeX](http://en.wikipedia.org/wiki/LaTeX) is a typesetting system, most famous for its use in scientific environments. Especially when you need mathematical formulas or complicated diagrams, or you want to generate documents automatically, Latex is a very good choice. It is much more difficult to use than Office, and you have to expect to learn much before you can use it, and to consult a web search or a good book often if you want to use it. So if you just want to type a few letters, you are probably better off using some Office suite which is intuitively usable. This tutorial is about using Latex on NetBSD. If you want to learn Latex, you should either go to a Latex course or introduction, or read a book about it (there is a [good one](http://en.wikibooks.org/wiki/LaTeX) available on Wikibooks, though it is imho rather good as a reference than a tutorial). ## Installing Latex If you want to use Latex, you should at least install the package `tex-latex-bin`. Then you have the minimal definitions you need for compiling primitive Latex files. ## Installing additional packages from pkgsrc Latex in NetBSD is split into several small packages, each providing one more Latex packages If you want to use Latex, you don't have to do much. For each package, there's usually also a package with the same name, but `-doc` appended, which is the documentation for the package. So you can install each package without its documentation. If you want to install further files, you should search on [pkgsrc.se](http://pkgsrc.se) for the files. Entering the search terms and "latex" will usually find the appropriate result. ### Example: amsmath I've just been looking for the `amsmath` package I use for some mathematical formula markup. So I did (using binary packages): $ pkgin search amsmath tex-amsmath-doc-2.13pl26389 Documentation for tex-amsmath tex-amsmath-2.13nb2 = AMS mathematical facilities for LaTeX =: package is installed and up-to-date <: package is installed but newer version is available >: installed package has a greater version than available package Here you see there is the normal package (`tex-amsmath-2.13nb2`), and the documentation package (`tex-amsmath-doc-2.13pl26389`). As I have a good internet connection in the university, I don't need the local documentation, and I only install the `tex-amsmath` package: $ pkgin install tex-amsmath calculating dependencies... done. nothing to upgrade. 1 packages to be installed: tex-amsmath-2.13nb2 (0B to download, 174K to install) proceed ? [Y/n] downloading packages... installing packages... installing tex-amsmath-2.13nb2... pkg_install warnings: 1, errors: 0 pkg_install error log can be found in /var/db/pkgin/pkg_install-err.log reading local summary... processing local summary... updating database: 100% marking tex-amsmath-2.13nb2 as non auto-removable ## Installing additional packages by hand You will come across some smaller packages that are not available in pkgsrc. But there are also ways to install a package local (e.g., in your home directory), without interfering with the package management. The major resource for documents installed in your home is `~/texmf/`, where you put your own Latex classes. For system-wide files, `/usr/pkg/share/texmf-dist/` is the major resource. So if you found a package (e.g., on [CTAN](http://www.ctan.org), a major resource for Latex files), you unpack it and put the files in one of these directories, depending on whether you want them only for one user or for all users on the system. For all filetypes, there are special subdirectories of these (along many other paths). You can find them using the tool `kpsepath` (part of `kpathsea`). In my case, I wanted to use `alphadin`, a package for having German-styled citation references. So I went to [CTAN](http://www.ctan.org/tex-archive//bibliography/bibtex/contrib/german/din1505), downloaded the package, and unpacked it: $ ftp http://mirrors.ctan.org/biblio/bibtex/contrib/german/din1505.zip Requesting http://mirrors.ctan.org/biblio/bibtex/contrib/german/din1505.zip Redirected to http://sunsite.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/biblio/bibtex/contrib/german/din1505.zip Requesting http://sunsite.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/biblio/bibtex/contrib/german/din1505.zip 100% |********************************************************************************************| 408 KiB 244.11 KiB/s 00:00 ETA 417797 bytes retrieved in 00:01 (244.09 KiB/s) $ unzip din1505.zip Archive: din1505.zip creating: din1505/ extracting: din1505/abbrvdin.bst extracting: din1505/alphadin.bst extracting: din1505/plaindin.bst extracting: din1505/unsrtdin.bst extracting: din1505/natdin.bst extracting: din1505/natbib.cfg extracting: din1505/leitbild3.pdf extracting: din1505/leitbild.bib extracting: din1505/normpatsoft.pdf Running `kpsepath` showed that the directory to install the contained `.bst` files was `~/texmf/bibtex/bst`: $ kpsepath bst .:/home/gnrp/.texlive2012/texmf-config/bibtex/bst//:/home/gnrp/.texlive2012/texmf-var/bibtex/bst//:/home/gnrp/texmf/bibtex/bst//:!!/usr/pkg/etc/texmf/bibtex/bst//:!!/var/lib/texmf/bibtex/bst//:!!/usr/pkg/share/texmf/bibtex/bst//:!!/usr/pkg/share/texmf-local/bibtex/bst//:!!/usr/pkg/share/texmf-dist/bibtex/bst//:/home/gnrp/.texlive2012/texmf-config/bibtex/csf//:/home/gnrp/.texlive2012/texmf-var/bibtex/csf//:/home/gnrp/texmf/bibtex/csf//:!!/usr/pkg/etc/texmf/bibtex/csf//:!!/var/lib/texmf/bibtex/csf//:!!/usr/pkg/share/texmf/bibtex/csf//:!!/usr/pkg/share/texmf-local/bibtex/csf//:!!/usr/pkg/share/texmf-dist/bibtex/csf// So I moved the files to `~/texmf/bibtex/bst` (and created the directory before that): $ cd din1505/ $ mkdir -p ~/texmv/bibtex/bst $ mv *.bst ~/texmf/bibtex/bst Afterwards, compiling everything worked fine. ## Useful packages For writing my Bachelor's thesis, I used the following packages. Some of them are very basic and are generally useful for many purposes, but especially for scientific documents, they are useful: * `tex-babel` * `tex-amsmath` * `tex-amscls` * `tex-stmaryrd` * `tex-microtype` * `tex-oberdiek` * `tex-bibtex` -- [BibTeX](http://en.wikipedia.org/wiki/Bibtex) is a system to handle citations in a document. ## Editors If you don't want to hassle learning Latex, but still use its powerful typesetting, or some other specifics (such as the formulas), you can use the software LyX (editors/lyx), which creates Latex documents with a WYSIWYG (or rather, WYSIWYM) interface. Even if you can write Latex, you should have a look at it -- it's a very mighty tool sometimes making your work much easier. When it comes to editors, there are several different ones, each with its own specific strength. Many people use just plain vi or vim, which I did in the beginning as well. But then, I found `geany` (devel/geany), which is an IDE originally, but also serves for coding Latex. It is a lightweight, but also minimalistic tool for writing Latex code. Another very popular tool is `kile` (editors/kile), which has many features, and also is part of KDE, but a bit too much for some of my older computers (where I don't install KDE because of disk space issues). ## Workflow When using Latex, you have the full set of tools available which are usually used for software development. There are two major ideas that are very handy for using Latex: Version control systems and Makefiles. ### Makefiles For some specific tasks, you have to build a Latex file several times, and in a specific order. E.g., when you want to have the table of contents, and bibtex work correctly, you have to call Latex three times, and bibtex after the first run. So instead of typing `latex ba.tex` three times, or always using your cursor keys to get `latex ba.tex; bibtex ba; latex ba.tex; latex ba.tex`, you could also put everything in a Makefile: $ cat Makefile all: pdflatex ba.tex bibtex ba pdflatex ba.tex pdflatex ba.tex So when you call `make` in the directory of your Latex file now, all these commands will be called one after the other, and you don't have to care for the order afterwards anymore -- this is handled in the Makefile now. ### LaTeX-Mk The latex-mk package in pkgsrc (print/latex-mk) provides a more comprehensive and capable build system for LaTeX based documents that is similar in spirit to the BSD make system used for building NetBSD. As a simple example, consider a document where the top level file is `mydoc.tex` and in turn, `ch1.tex`, `ch2.tex`, `ch3.tex`, and `refs.tex` are included. In addition, a bibliography produced with BibTeX is in the file `mybib.bib`. The `Makefile` for this project would be: NAME= mydoc TEXSRCS= ch1.tex ch2.tex ch3.tex refs.tex BIBTEXSRCS= mybib.bib .include "/usr/pkg/share/latex-mk/latex.mk" The build system implemented by LaTeX-Mk provides various targets like view, pdf, viewpdf, etc. For example make viewpdf will take the steps needed to process the document, create a pdf file, and open a pdf viewer. For complete information on LaTeX-Mk's features and usage, visit the [LaTeX-Mk homepage](http://latex-mk.sf.net). ### Version control systems When developing software, people often use [version control systems (VCS)](http://en.wikipedia.org/wiki/Version_control_system): This text is not an introduction to VCSes, where you should definetly consider a tutorial or a book, but about how to use them with Latex. I personally use [fossil](http://en.wikipedia.org/wiki/Fossil_(software)) (devel/fossil) because it provides also an integrated webserver and a GUI you use in your web browser, while most people currently prefer [git](http://en.wikipedia.org/wiki/Git_(software)) (devel/scmgit). The commands are nearly 1:1 usable by replacing `fossil` by `git`, but you should learn how to use your own VCS anyway. So, when I start a project with Latex, I create the directory, and then a fossil repository in it: $ mkdir ba $ cd ba $ fossil new repo.fossil project-id: 0e8cff7588381fbd87525d2dddc9359e3b9717a5 server-id: 194b4ed5e1c17724009d038b6bbcd0c44cc3aed7 admin-user: gnrp (initial password is "660930") $ fossil open repo.fossil $ vi Makefile $ vi ba.tex $ vi ba.bib ...[Writing content to these three files]... $ fossil add ba.tex ba.bib Makefile $ fossil commit And commit them for the first time. Now, all you have to do is to do a `fossil commit` everytime you finish some work, or want to synchronise the documents between computers. If you should by accident delete a file, you can recover it from the version control system. Or if you notice you deleted a paragraph long ago, but you still need it, you can use the VCS to check which version it was in and then recover it from that version. Learning how to use a VCS *really* helps in working in a more secure manner, and being able to recover from errors or for looking at the progress of the project (when you use fossil, start a fossil gui by `fossil ui` and then look at the *Timeline*).