Annotation of wikisrc/tutorials/latex_in_netbsd.mdwn, revision 1.2

1.1       jdf         1: # Latex in NetBSD
                      2: 
                      3: [LaTeX](http://en.wikipedia.org/wiki/LaTeX) is a typesetting system, most famous
                      4: for its use in scientific environments.
                      5: 
                      6: Especially when you need mathematical formulas or complicated diagrams, or you
                      7: want to generate documents automatically, Latex is a very good choice.
                      8: 
                      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.
                     13: 
                     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).
                     18: 
                     19: ## Installing Latex
                     20: 
                     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.
                     24: 
                     25: ## Installing additional packages from pkgsrc
                     26: 
                     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.
                     29: 
                     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.
                     33: 
                     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.
                     37: 
                     38: ### Example: amsmath
                     39: 
                     40: I've just been looking for the `amsmath` package I use for some mathematical
                     41: formula markup. So I did (using binary packages):
                     42: 
                     43:     $ pkgin search amsmath
                     44:     tex-amsmath-doc-2.13pl26389  Documentation for tex-amsmath
                     45:     tex-amsmath-2.13nb2 = AMS mathematical facilities for LaTeX
                     46: 
                     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
                     50: 
                     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:
                     55: 
                     56:     $ pkgin install tex-amsmath
                     57:     calculating dependencies... done.
                     58: 
                     59:     nothing to upgrade.
                     60:     1 packages to be installed: tex-amsmath-2.13nb2 (0B to download, 174K to
                     61:     install)
                     62: 
                     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
                     73: 
                     74: ## Installing additional packages by hand
                     75: 
                     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.
                     79: 
                     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.
                     83: 
                     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.
                     88: 
                     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`).
                     91: 
                     92: In my case, I wanted to use `alphadin`, a package for having German-styled
                     93: citation references. So I went to
                     94: [CTAN](http://www.ctan.org/tex-archive//bibliography/bibtex/contrib/german/din1505),
                     95: downloaded the package, and unpacked it:
                     96: 
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  
                    115: 
                    116: 
                    117: Running `kpsepath` showed that the directory to install the contained `.bst`
                    118: files was `~/texmf/bibtex/bst`:
                    119: 
                    120:     $ kpsepath bst
                    121:     .:/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//
                    122: 
1.2     ! jdf       123: So I moved the files to `~/texmf/bibtex/bst` (and created the directory before 
        !           124: that):
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
                    129: 
                    130: Afterwards, compiling everything worked fine.
                    131: 
                    132: ## Useful packages
                    133: 
                    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:
                    137: 
                    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.
                    146: 
                    147: ## Editors
                    148: 
                    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.
                    155: 
                    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.
                    161: 
                    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).
                    165: 
                    166: ## Workflow
                    167: 
                    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.
                    171: 
                    172: ### Makefiles
                    173: 
                    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:
                    181: 
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
                    188: 
                    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.
                    192: 
                    193: ### Version control systems
                    194: 
                    195: When developing software, people often use
                    196: [version control systems (VCS)](http://en.wikipedia.org/wiki/Version_control_system):
                    197: This text is not an introduction to VCSes, where you should definetly consider a
                    198: tutorial or a book, but about how to use them with Latex.
                    199: 
                    200: I personally use 
                    201: [fossil](http://en.wikipedia.org/wiki/Fossil_(software))
                    202: (devel/fossil) because it provides also an integrated webserver and a GUI you
                    203: use in your web browser, while most people currently prefer
                    204: [git](http://en.wikipedia.org/wiki/Git_(software))
                    205: (devel/scmgit). The commands are nearly 1:1 usable by replacing
                    206: `fossil` by `git`, but you should learn how to use your own VCS anyway.
                    207: 
                    208: So, when I start a project with Latex, I create the directory, and then a fossil
                    209: repository in it:
                    210: 
                    211:     $ mkdir ba
                    212:     $ cd ba
                    213:     $ fossil new repo.fossil
                    214:     project-id: 0e8cff7588381fbd87525d2dddc9359e3b9717a5
                    215:     server-id:  194b4ed5e1c17724009d038b6bbcd0c44cc3aed7
                    216:     admin-user: gnrp (initial password is "660930")
                    217:     $ fossil open repo.fossil
                    218:     $ vi Makefile
                    219:     $ vi ba.tex
                    220:     $ vi ba.bib
                    221:     ...[Writing content to these three files]...
                    222:     $ fossil add ba.tex ba.bib Makefile
                    223:     $ fossil commit
                    224: 
                    225: And commit them for the first time.
                    226: Now, all you have to do is to do a `fossil commit` everytime you finish some
                    227: work, or want to synchronise the documents between computers.
                    228: If you should by accident delete a file, you can recover it from the version
                    229: control system. Or if you notice you deleted a paragraph long ago, but you still
                    230: need it, you can use the VCS to check which version it was in and then recover
                    231: it from that version.
                    232: 
                    233: Learning how to use a VCS *really* helps in working in a more secure manner, and
                    234: being able to recover from errors or for looking at the progress of the project
                    235: (when you use fossil, start a fossil gui by `fossil ui` and then look at the
                    236: *Timeline*).

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