File:  [NetBSD Developer Wiki] / wikisrc / tutorials / latex_in_netbsd.mdwn
Revision 1.3: download - view: text, annotated - select for diffs
Wed Dec 17 19:22:34 2014 UTC (5 years, 11 months ago) by wiki
Branches: MAIN
CVS tags: HEAD
web commit by dmcmahill: Add section on LaTeX-Mk for managing/building LaTeX based projects.

    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: 
   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)
  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: 
  123: So I moved the files to `~/texmf/bibtex/bst` (and created the directory before 
  124: that):
  125: 
  126:     $ cd din1505/
  127: 	$ mkdir -p ~/texmv/bibtex/bst
  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: 
  182:     $ cat Makefile
  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: ### LaTeX-Mk
  194: 
  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:
  201: 
  202:     NAME= mydoc
  203:     TEXSRCS= ch1.tex ch2.tex ch3.tex refs.tex
  204:     BIBTEXSRCS= mybib.bib
  205: 
  206:     .include "/usr/pkg/share/latex-mk/latex.mk" 
  207: 
  208: The build system implemented by LaTeX-Mk provides various targets like view, pdf, viewpdf, etc.  
  209: For example
  210: 
  211:    make viewpdf
  212: 
  213: will take the steps needed to process the document, create a pdf file, and open a pdf viewer.
  214: 
  215: For complete information on LaTeX-Mk's features and usage, visit 
  216: the [LaTeX-Mk homepage](http://latex-mk.sf.net).
  217: 
  218: ### Version control systems
  219: 
  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.
  224: 
  225: I personally use 
  226: [fossil](http://en.wikipedia.org/wiki/Fossil_(software))
  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
  229: [git](http://en.wikipedia.org/wiki/Git_(software))
  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.
  232: 
  233: So, when I start a project with Latex, I create the directory, and then a fossil
  234: repository in it:
  235: 
  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
  249: 
  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.
  257: 
  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
  261: *Timeline*).

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