Hi there.  This is a template for using Dexy to produce talks for the 2012 yt
workshop.   Email me if you run into any problems (matthewturk@gmail.com).

What Does Dexy Do For Us?
=========================

Dexy will:

 * Automatically re-run any scripts it has detected have changed
 * Include the output of those scripts (stdout) in your presentation if
   requested
 * Include the syntax-highlighted content of those scripts in your presentation
   if requested
 * Allow you to version control your talk
 * Separate scripts from the talk: people can download and inspect them without
   having to copy/paste from a PDF

If you don't want to use Dexy, and instead prefer something like Keynote or
PowerPoint, please feel free to use those.  It would be very helpful if you
would include annotations on each slide that includes a script that point to a
paste on paste.yt-project.org, so that we can include them in a repository at a
later time.

Getting Started
===============

 * First install Dexy, which can be done with pip:

    $ pip install dexy

   Dexy's homepage is http://dexy.it , but for the most part we might be able to
   avoid detailed documentation.

 * In this directory, copy the example.tex_ file to a filename of your talk.
   (It has an extra underscore because I don't want it to get run by dexy.)
   You can name them however you like, but mine will be lowercase with
   underscores.  You'll need to 'hg add' this file.

 * Now we have to initialize dexy.  Run this command:

    $ dexy setup

 * I've already provided a config file, .dexy , which you can inspect or
   modify.  It took me a while to decipher the contents when I started using
   dexy, but basically it describes associations between files and operations
   to perform on those files.

How To Add Scripts
==================

Inside the scripts directory, you can place new scripts which can then be
included.  While support exists for many different types, I have only ever used
.py and .sh scripts.  For examples on these, see the princeton tutorial I gave,
here:

  https://bitbucket.org/MatthewTurk/2011-yt-princeton-tutorial/src

To add a new script to the presentation, it should be under the scripts/
subdirectory.  You then simply include it in the presentation with this little
bit of magic:

    <<d['scripts/inspect_grids.py|fn|pyg|l']>>

This tells Dexy to take the file scripts/inspect_grids.py, tell it that it's a
filename, run it through pygments (a syntax highlighter) and then convert it to
LaTeX.  Whew!  This won't actually *run* the script, but it will include the
contents verbatim.  To have Dexy run the script through Python, you have to
additionally specify a 'py' filter, like so:

    <<d['scripts/inspect_grids.py|fn|py|pyg|l']>>

So, for instance, this is how I set up a slide in my talk, using Beamer (and a
few macros of my own.)

    \begin{frame}[fragile,t]{}
    \tiny
    <<d['scripts/popiii_proj.py|fn|pyg|l']>>
    \hline
    <<d['scripts/popiii_proj.py|fn|py|pyg|l']>>
    \end{frame}
    \fullimage{DD0087_Projection_x_Density_Density.png}

This uses the "fullimage" command which I made for Beamer, but you should feel
free to include images however you like.  NOTE: If you want to include images
*not* created from the output of running scripts, you have to use ../ to point
back to the top level.

How To Reference Data
=====================

All scripts will be run from under the artifacts/ subdirectory.  To use data,
I recommend you place it somewhere else and create a symbolic link inside
artifacts/ that points to that location.  For instance, I might have a
artifacts/DD0087/ symlink that points to my ~/data/ directory.

How To Build Your Talk
======================

Now that you have a .tex file with some scripts and images included, just run:

  $ dexy

This will build any .tex files in your current directory.  The resulting PDF
will be under output/ .