Writing and Formatting Opus Documentation using the LaTeX Document Preparation System

This section provides instructions for using LaTeX. The Opus and UrbanSim Reference Manual and Users Guide (aka Manual) are written using the LaTeX document preparation system. Advantages of LaTeX are that it is open-source, platform independent, provides a rich set of features for indexing and cross-referencing, and is the standard used for documenting Python packages. It also typesets elegantly, particularly for mathematical formulae. The disadvantage is that it is not a WYSIWYG (“what you see is what you get”) system. Instead, you edit a source document with a text editor, then use LaTeX to format it and produce a pdf file and / or a set of html pages. The home page for the LaTeX project is at http://www.latex-project.org/. If you are new with LaTeX, also take a look at the Getting Started with TeX, LaTeX, and Friends page.

The source for the Manual resides in the opus_docs/manual package. The root LaTeX source file is 'opus-userguide.tex'. It includes a set of other .tex files for the major parts, which in turn include other files (normally one file per chapter). The latex files use the Python latex documentation standards and latex definition files (although not yet consistently); see http://www.python.org/doc/2.5.2/doc/doc.html. (Python itself changed from LaTeX to a custom reStructuredText markup as of version 2.6, but that's another story.)

Installing a LaTeX environment

There are many applications and environments that support editing LaTeX files -- see the LaTeX project download page.

SuSe comes with LaTeX, as do most other Linux distributions.

On the Mac, use TeXShop or MacTeX.

On Windows, you can use proTeXt. The Texlipse Eclipse plug-in also provides LaTeX support.

Running LaTeX

The easiest way to rebuild a local version of the pdf and html documentation for the Manual is to use a Python script that is in the opus_docs Opus package:

1. Get the opus_docs package from the subversion repository and put it in your workspace (e.g., to C:\opus\src\opus_docs)
2. Open a command window and navigate to the location of your opus_docs/manual directory.
3. Run this command to build a local copy of the documentation:

python build_docs.py

The new pdf file, and associated html pages, will be in the opus_docs/manual directory. The script also generates the html version of the manual using latex2html; if you don't have that program, this final command will fail (but the pdf of the manual will still be generated).

Alternatively, you can issue the individual commands:

pdflatex opus-userguide 
makeindex opus-userguide.idx 
bibtex opus-userguide 
pdflatex opus-userguide 
pdflatex opus-userguide 

If you get an error message that the file userguide.ind wasn't found (this will happen the first time you do the above command), just hit return and continue, since the next step will create this index file.

makeindex generates the index, and bibtex generates the bibliography. You have to run latex a couple of times after making the index and bibliography files to incorporate the index and resolve any cross-references correctly.

-- AlanBorning - 17 Aug 2009