File:  [NetBSD Developer Wiki] / wikisrc / tutorials / latex_in_netbsd.mdwn
Revision 1.1: download - view: text, annotated - select for diffs
Mon Apr 8 17:53:02 2013 UTC (12 months, 2 weeks ago) by jdf
Branches: MAIN
CVS tags: HEAD
Add article about Latex in NetBSD

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

    $ 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`:

    $ cd din1505/
    $ 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 Makeba
    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.

### 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*).

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb