Add RTD link to README.

[ibg.git] / README.md

diff --git a/README.md b/README.md
index e90ea9345bedf700d090ac1767bc232fa7507c1c..f2c7b151101483914c339c12764b9ce3ba0f8bf8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,12 +4,17 @@ Inform Beginner's Guide
 Introduction
 ------------
 
-This repository contains the sources for the
+This repository contains the sources for an updated version of 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:
 
@@ -22,16 +27,28 @@ the 4th edition will be prepared.  The rationale for a 4th edition is:
 * Some old web links have gone away, to be replaced by new and better
   ones.
 
+If you want a preview of how the online HTML version of the new guide
+looks, you can find it [here](http://inform-beginners-guide.readthedocs.org).
+
 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).
+
+* [Blockdiag](https://pypi.python.org/pypi/blockdiag) is used for some of
+  the diagrams.
+
+* To create the HTML version, you'll need a recent (>=0.7.8) version of the
+  [Alabaster](https://pypi.python.org/pypi/alabaster) theme.
+
+If you have `pip`, this command will be all you need:
+
+    pip install -U sphinx blockdiag alabaster
 
-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