Latex in NetBSD

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 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 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, 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, 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:

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.

Version control systems

When developing software, people often use version control systems (VCS): 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) (devel/fossil) because it provides also an integrated webserver and a GUI you use in your web browser, while most people currently prefer git) (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).