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

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: 
        !            97:     $ unzip din1505.zip 
        !            98:     Archive:  din1505.zip
        !            99:        creating: din1505/
        !           100:      extracting: din1505/abbrvdin.bst  
        !           101:      extracting: din1505/alphadin.bst  
        !           102:      extracting: din1505/plaindin.bst  
        !           103:      extracting: din1505/unsrtdin.bst  
        !           104:      extracting: din1505/natdin.bst  
        !           105:      extracting: din1505/natbib.cfg  
        !           106:      extracting: din1505/leitbild3.pdf  
        !           107:      extracting: din1505/leitbild.bib  
        !           108:      extracting: din1505/normpatsoft.pdf  
        !           109: 
        !           110: 
        !           111: Running `kpsepath` showed that the directory to install the contained `.bst`
        !           112: files was `~/texmf/bibtex/bst`:
        !           113: 
        !           114:     $ kpsepath bst
        !           115:     .:/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//
        !           116: 
        !           117: So I moved the files to `~/texmf/bibtex/bst`:
        !           118: 
        !           119:     $ cd din1505/
        !           120:     $ mv *.bst ~/texmf/bibtex/bst
        !           121: 
        !           122: Afterwards, compiling everything worked fine.
        !           123: 
        !           124: ## Useful packages
        !           125: 
        !           126: For writing my Bachelor's thesis, I used the following packages. Some of them
        !           127: are very basic and are generally useful for many purposes, but especially for
        !           128: scientific documents, they are useful:
        !           129: 
        !           130:  * `tex-babel`
        !           131:  * `tex-amsmath`
        !           132:  * `tex-amscls`
        !           133:  * `tex-stmaryrd`
        !           134:  * `tex-microtype`
        !           135:  * `tex-oberdiek`
        !           136:  * `tex-bibtex` -- [BibTeX](http://en.wikipedia.org/wiki/Bibtex) is a system to
        !           137:    handle citations in a document.
        !           138: 
        !           139: ## Editors
        !           140: 
        !           141: If you don't want to hassle learning Latex, but still use its powerful
        !           142: typesetting, or some other specifics (such as the formulas), you can use the
        !           143: software LyX (editors/lyx), which creates Latex documents with
        !           144: a WYSIWYG (or rather, WYSIWYM) interface. Even if you can write Latex, you
        !           145: should have a look at it -- it's a very mighty tool sometimes making your work
        !           146: much easier.
        !           147: 
        !           148: When it comes to editors, there are several different ones, each with its own
        !           149: specific strength. Many people use just plain vi or vim, which I did in the
        !           150: beginning as well. But then, I found `geany` (devel/geany), which is an IDE
        !           151: originally, but also serves for coding Latex. It is a lightweight, but also
        !           152: minimalistic tool for writing Latex code.
        !           153: 
        !           154: Another very popular tool is `kile` (editors/kile), which has many features, and
        !           155: also is part of KDE, but a bit too much for some of my older computers (where I
        !           156: don't install KDE because of disk space issues).
        !           157: 
        !           158: ## Workflow
        !           159: 
        !           160: When using Latex, you have the full set of tools available which are usually
        !           161: used for software development. There are two major ideas that are very handy for
        !           162: using Latex: Version control systems and Makefiles.
        !           163: 
        !           164: ### Makefiles
        !           165: 
        !           166: For some specific tasks, you have to build a Latex file several times, and in a
        !           167: specific order. E.g., when you want to have the table of contents, and bibtex
        !           168: work correctly, you have to call Latex three times, and bibtex after the first
        !           169: run. So instead of typing `latex ba.tex` three times, or always using your
        !           170: cursor keys to get
        !           171: `latex ba.tex; bibtex ba; latex ba.tex; latex ba.tex`, 
        !           172: you could also put everything in a Makefile:
        !           173: 
        !           174:     $ cat Makeba
        !           175:     all:
        !           176:             pdflatex ba.tex
        !           177:             bibtex ba
        !           178:             pdflatex ba.tex
        !           179:             pdflatex ba.tex
        !           180: 
        !           181: So when you call `make` in the directory of your Latex file now, all these
        !           182: commands will be called one after the other, and you don't have to care for the
        !           183: order afterwards anymore -- this is handled in the Makefile now.
        !           184: 
        !           185: ### Version control systems
        !           186: 
        !           187: When developing software, people often use
        !           188: [version control systems (VCS)](http://en.wikipedia.org/wiki/Version_control_system):
        !           189: This text is not an introduction to VCSes, where you should definetly consider a
        !           190: tutorial or a book, but about how to use them with Latex.
        !           191: 
        !           192: I personally use 
        !           193: [fossil](http://en.wikipedia.org/wiki/Fossil_(software))
        !           194: (devel/fossil) because it provides also an integrated webserver and a GUI you
        !           195: use in your web browser, while most people currently prefer
        !           196: [git](http://en.wikipedia.org/wiki/Git_(software))
        !           197: (devel/scmgit). The commands are nearly 1:1 usable by replacing
        !           198: `fossil` by `git`, but you should learn how to use your own VCS anyway.
        !           199: 
        !           200: So, when I start a project with Latex, I create the directory, and then a fossil
        !           201: repository in it:
        !           202: 
        !           203:     $ mkdir ba
        !           204:     $ cd ba
        !           205:     $ fossil new repo.fossil
        !           206:     project-id: 0e8cff7588381fbd87525d2dddc9359e3b9717a5
        !           207:     server-id:  194b4ed5e1c17724009d038b6bbcd0c44cc3aed7
        !           208:     admin-user: gnrp (initial password is "660930")
        !           209:     $ fossil open repo.fossil
        !           210:     $ vi Makefile
        !           211:     $ vi ba.tex
        !           212:     $ vi ba.bib
        !           213:     ...[Writing content to these three files]...
        !           214:     $ fossil add ba.tex ba.bib Makefile
        !           215:     $ fossil commit
        !           216: 
        !           217: And commit them for the first time.
        !           218: Now, all you have to do is to do a `fossil commit` everytime you finish some
        !           219: work, or want to synchronise the documents between computers.
        !           220: If you should by accident delete a file, you can recover it from the version
        !           221: control system. Or if you notice you deleted a paragraph long ago, but you still
        !           222: need it, you can use the VCS to check which version it was in and then recover
        !           223: it from that version.
        !           224: 
        !           225: Learning how to use a VCS *really* helps in working in a more secure manner, and
        !           226: being able to recover from errors or for looking at the progress of the project
        !           227: (when you use fossil, start a fossil gui by `fossil ui` and then look at the
        !           228: *Timeline*).

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