update tools README

src/tools/README.md

@@ -2,6 +2,45 @@
 
 Tools for cl-quil developers.
 
+These provide functionality above and beyond core `cl-quil`, but perhaps at the cost of additional system dependencies (e.g. `graphviz` or `pdflatex`). Read the instructions carefully!
+
+A short summary of what follows in this README is indicated below.
+
+| Section | Description |
+| --- | ----------- |
+| Circuit Diagrams | Generate plots of circuit diagrams from Quil code.  |
+| Hasse Schedule | Visualize `logical-scheduler` data. |
+
+## Circuit Diagrams
+
+### Usage
+
+To generate a Jupyter object capable of rendering inline,
+```
+(plot-circuit <parsed-program>)
+```
+
+To save SVG output, use `:output-file <filename>`. To generate plain LaTeX source, add the `:latex-only t` option. See the docstring for more information about keyword options.
+
+An example Jupyter session is shown below.
+
+![Example PLOT-CIRCUIT usage in a Jupyter notebook](images/plot-circuit-example.png)
+
+
+### Dependencies
+
+You will need `pdflatex` and `pdf2svg` in your path. On macOS, `pdflatex` is part of the `mactex` distribution. Both of these may be installed with homebrew:
+```
+brew install mactex
+brew install pdf2svg
+```
+
+These executables are referred to in `cl-quil.tools` by `*pdflatex-exe*` and `*pdf2svg-exe`, should you wish to override them.
+
+To use this in a Jupyter notebook, you should use [common-lisp-jupyter](https://github.com/yitzchak/common-lisp-jupyter). As an installation note, some users have found that on macOS the default SBCL path associated with the jupyter kernel (e.g. in `~/Library/Jupyter/kernels/common-lisp/kernel.json`) is incorrect; this will result in `jupyter` being unable to start the Common Lisp kernel.
+
+
+
 ## Hasse Schedule
 
 The *Hasse schedule* tool helps you to visualize the *logical-scheduler* data structure, which is used by the addresser to organize and manage resource dependencies between instructions on 'logical' qubits.