X-Git-Url: https://jxself.org/git/?p=ibg.git;a=blobdiff_plain;f=README.md;h=eb05a28441f8bb27bab0be603111494d2d4f604e;hp=6a89c81508709e6bfcf3923c675e903c4b0893d6;hb=dc7fec99d92b670126e1e73e05df8f60706edc2d;hpb=00e42bd8b271a01dd1a4a7c6b90c12bf5b52ae76

diff --git a/README.md b/README.md
index 6a89c81..eb05a28 100644
--- a/README.md
+++ b/README.md
@@ -7,9 +7,14 @@ Introduction
 This repository contains the sources for the
 [Inform Beginner's Guide](http://www.firthworks.com/roger/IBG.html),
 henceforth known as the IBG.  This version is in a new source format that's
-more contributor-friendly (see below).  It's a work-in-progress; see the
-[issue tracker](https://github.com/i6/ibg/issues) for how it's going.
+more version-control and contributor-friendly:
+[Sphinx](http://sphinx-doc.org), a documentation build tool written in
+[Python](http://python.org).  With Sphinx, the source files are in a very
+readable format called
+[reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText).
 
+This version of the IBG is a work-in-progress; see the
+[issue tracker](https://github.com/i6/ibg/issues) for how it's going.
 Initially it will be a straight conversion of the 3rd edition.  After that,
 the 4th edition will be prepared.  The rationale for a 4th edition is:
 
@@ -25,23 +30,30 @@ the 4th edition will be prepared.  The rationale for a 4th edition is:
 Building from source
 --------------------
 
-The new source format is [Sphinx](http://sphinx-doc.org), a documentation
-build tool written in [Python](http://python.org), which you will need to
-install if you want to build the document.  You can find the complete
-installation instructions
-[here](http://www.sphinx-doc.org/en/stable/install.html).
+As well as these document sources, you will need:
+
+* Sphinx.  You can find the complete installation instructions
+  [here](http://www.sphinx-doc.org/en/stable/install.html).
+
+* Sphinx makes use of [Blockdiag](https://pypi.python.org/pypi/blockdiag)
+  for some of the diagrams; you'll need that too.
+
+If you have `pip`, this command will be all you need:
+
+    pip install sphinx blockdiag
 
-After you have Sphinx installed, you can build the HTML version of the
+After you have everything installed, you can build the HTML version of the
 guide from a command prompt, like this:
 
 	make html
 
-For building the PDF version, you need a reasonably recent installation 
-of TeX Live.  Release 2014 will do.  You will also need the Emerald 
-package from https://www.ctan.org/tex-archive/fonts/emerald/.  This 
-cannot be installed with tlmgr, nor does it seem to be packaged by the 
-usual Linux or BSD distributions.  Scripts for installing and 
-uninstalling Emerald are provided here.  When you're ready, type this:
+For building the PDF version, you need a reasonably recent installation of
+TeX Live.  Release 2014 will do.  You will also need the Emerald font
+package from https://www.ctan.org/tex-archive/fonts/emerald/.  This cannot
+be installed with `tlmgr`, nor does it seem to be packaged by the usual
+Linux or BSD distributions.  Scripts for installing and uninstalling
+Emerald are provided in the `tools` directory.  When you're ready, type
+this:
 
 	make latexpdf