Ladot 1.0
---------
2003-03-31
Brighten Godfrey
godfreyb@bigw.org

License
-------

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Description
-----------

For a general description of Ladot, please see

    http://brighten.bigw.org/projects/ladot/

One-time setup
--------------

1.  Install psfrag, dot (graphviz), and latex.  If you are using this
    program, you probably already have dot and latex.  psfrag is available
    here:

        http://www.ctan.org/tex-archive/help/Catalogue/entries/psfrag.html?action=/tex-archive/macros/latex/contrib/supported/psfrag/

    Click on the yellow star to download.

Usage
-----

1.  Specify your graph in a file ending in `.ladot'.  The format is like
    dot's, but you may replace text with LaTeX math expressions.

        digraph mygraph {
            $v_1$(2) $v_2$
            $v_1$ -> $v_2$
            }

    You may optionally append a size hint in parenthesis as shown above.
    this tells Ladot about how many characters wide your rendered LaTeX
    will be (not an exact science).  If you leave out the size hint, as
    in the second node in the above, Ladot will take a guess.  You only
    have to use the size hint once for each unique LaTeX snippet.

2.  Run ladot on the file:

        ladot mygraph.ladot

    This creates `mygraph.ps' (the raw PostScript output of dot) and
    `mygraph.tex' (a snippet of LaTeX code which tells psfrag to
    substitute tags in the PostScript for the LaTeX figures).

3.  In the preamble of your LaTeX file, put

        \usepackage{psfrag}

    LyX users: Set your preamble in Layout -> Document -> Preamble.

4.  Where you would like to include the graph, write
    
        \input{mydot.tex}
        \includegraphics{mydot.ps}

    LyX users: use Insert -> Include File and Insert -> Graphics.

5.  Process your LaTeX file with `latex' as normal.  Note that psfrag
    is sadly not compatible with pdflatex.

An example of all this is in the `example' directory.  Just type "make"
to do all the processing, creating the final output in test.ps.

Limitations/Bugs/To Do
----------------------

    * Tested with Graphviz 2.0.  With 2.2, it appears graphviz outputs
      postscript in which psfrag won't replace tags.  Let me know if you
      are able to fix this.
    * Cannot exploit full power of psfrag, especially regarding alignment
      in formatting.  Ladot centers everything.  Should add option for this.
    * Quoting is nonexistent.  Don't try to put a dollar sign in any of your
      TeX or Dot! :-)
    * Multi-line equations are not supported.  That is, don't put a newline
      in a LaTeX snippet in your Ladot file.  This is a silly limitation that
      can easily be corrected.
    * Since I only ever need to use LaTeX in Dot for math, Ladot only handles
      math expressions.  This is a needless limitation, but it makes the
      format more convenient.  You can still use normal text, however, by
      turning on the appropriate font within the equation.
    * It can't take input on stdin.
    * Your files must have the suffix ".ladot".
    * Ladot picks short random strings for the stubs inserted into the
      PostScript (which you can see in the mydot.ps output, but which are
      replaced with LaTeX in the output of your LaTeX file).  There is a
      chance these could conflict with each other or with other labels in the
      Dot file, causing incorrect, confusing, and frustrating results.
      The best solution would be to make the stubs much longer, thus
      making the probability of a conflict negligible.  However, currently
      we sometimes need to pick short stubs since the stub length tells Dot
      how much space to leave for the label.
    * Should have better control on how much space is left for rendered LaTeX
      (e.g., inches/pixels/mm instead of fuzzy "number of characters" measure).
