Lasso Guide

The goal of the Lasso Guide project is to have a central, authoritative, plain-text package of documentation for Lasso 9 that can be collaboratively viewed and edited, and processed into HTML, PDF, or any other format. The base docs are in the plain-text reStructuredText (reST) format, and use the Sphinx documentation processor to generate HTML and PDF versions.

These build instructions assume you're running Mac OS X, though building on Linux should also be possible.

Environment Setup

Before building, you'll need Xcode installed and a Python development environment set up. Ideally, use Homebrew to install Python 3 and virtualenv. Then use pip to install these packages:

• Pygments for syntax highlighting: pip install pygments
• Sphinx for HTML generation: pip install sphinx
• Lasso domain for Sphinx: pip install sphinxcontrib-lassodomain
• breathe for building the LCAPI reference page: pip install breathe

Building as HTML

After checking out this repo in a new Terminal, enter it and build:

cd ~/path/to/LassoGuide/
make html

If you have the required packages installed, you should get a "Build finished" message, indicating the new HTML site is available in LassoGuide/build/html/.

Building as PDF

You'll need some extra tools to accomplish this. On OS X, you have two options:

1. Install the MacTeX package, which is a HUGE installation—the installer alone is over 2GB. If you're so inclined, you can just grab & install that and be done.
2. But if you'd like to be a bit more selective, just get BasicTeX and use the tlmgr command to install the additional packages below.

sudo tlmgr update --self
sudo tlmgr update --all
sudo tlmgr install fncychap titlesec tabulary framed threeparttable wrapfig capt-of multirow eqparbox environ trimspaces enumitem tocloft

The following fonts are also required:

• Myriad Pro
• Consolas (bundled with MS Office)
• Arial Unicode MS (pre-installed with OS X)

If any of these fonts are installed in your home folder at ~/Library/Fonts/ instead of in /Library/Fonts/, you'll need to download and open the TeX Live Utility, open Preferences, and check "Automatically enable fonts in my home directory".

Then run make latexpdf to create a PDF in the LassoGuide/build/latex/ folder.

More info:

• http://tex.stackexchange.com/questions/974/why-is-the-mactex-distribution-so-large-is-there-anything-smaller-for-os-x
• http://en.wikibooks.org/wiki/LaTeX/

Updating vector resources

Some items in the _static folder exist in both SVG and PDF forms. If you update an SVG file, you'll need to recreate its PDF version. If you don't have rsvg-convert, use homebrew to install librsvg, then regenerate the PDF version with:

rsvg-convert -f pdf file_name.svg -o file_name.pdf

By using a directive like .. image:: /_static/file_name.*, Sphinx will pick an appropriate file format for the target you're building; in this case, SVG for HTML, and PDF for Latex.

The syntax diagrams were created in OmniGraffle 5 and exported to SVG. Something goes awry with the arrowheads when converting to PDF causing them to appear off-center, but according to this forum post all you need to do is edit the SVG file and change x & y to 0 for each marker's viewBox="x y a b". Also, Helvetica doesn't convert well to PDF, so use Arial instead.

Writing in reStructuredText

The reST markup language, bundled with the Docutils package, is made for marking up single documents; Sphinx then adds reST-like markup constructs for multipage, programming-related documentation. Below are some resources for writing reST:

• http://docutils.sourceforge.net/docs/user/rst/quickref.html
• http://www.sphinx-doc.org/en/stable/rest.html
• https://raw.github.com/ralsina/rst-cheatsheet/master/rst-cheatsheet.pdf - PDF cheat sheet
• http://rst.ninjs.org/ - online reST editor

Syntax highlighting of reST is available in Sublime Text, BBEdit and TextWrangler via plugin, and many other text editors.

Previewing with restview

Use restview to get a real-time HTML preview of the file you're working on. It doesn't currently support any of Sphinx's directives, however.

After installing with pip install restview, pass it a folder of reST files:

cd ~/path/to/LassoGuide/
restview -l localhost:5555 source/

and open http://localhost:5555/ in a web browser.

BBEdit can be configured to automatically preview the current document using restview. In version 10.5 or later:

1. create a new Project for LassoGuide's source folder
2. in the project's Site Settings (under the cloud icon), set the following:
   • Local site root: full path to LassoGuide/source/
   • Use local preview server: enabled and set to http://localhost:5555/

Then with a reST file open and restview running in Terminal, select Markup > Preview in BBEdit to open a self-updating HTML preview of the file.