README.md

   1 Inform Beginner's Guide
   2 =======================
   3
   4 Introduction
   5 ------------
   6
   7 This repository contains the sources for an updated version of the
   8 [Inform Beginner's Guide](http://www.firthworks.com/roger/IBG.html),
   9 henceforth known as the IBG.  This version is in a new source format that's
  10 more version-control and contributor-friendly:
  11 [Sphinx](http://sphinx-doc.org), a documentation build tool written in
  12 [Python](http://python.org).  With Sphinx, the source files are in a very
  13 readable format called
  14 [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText).
  15
  16 This version of the IBG is a work-in-progress; see the
  17 [issue tracker](https://github.com/i6/ibg/issues) for how it's going.
  18 Initially it will be a straight conversion of the 3rd edition.  After that,
  19 the 4th edition will be prepared.  The rationale for a 4th edition is:
  20
  21 * There have been quite a few updates to Inform and its support libraries
  22   in the time since 2004, when the 3rd edition was published.
  23
  24 * The nitty-gritty information about how to install and run programs goes
  25   stale pretty fast.
  26
  27 * Some old web links have gone away, to be replaced by new and better
  28   ones.
  29
  30 If you want a preview of how the online HTML version of the new guide
  31 looks, you can find it [here](http://inform-beginners-guide.readthedocs.org).
  32
  33 Building from source
  34 --------------------
  35
  36 As well as these document sources, you will need:
  37
  38 * Sphinx.  You can find the complete installation instructions
  39   [here](http://www.sphinx-doc.org/en/stable/install.html).
  40
  41 * [Blockdiag](https://pypi.python.org/pypi/blockdiag) is used for some of
  42   the diagrams.
  43
  44 * To create the HTML version, you'll need a recent (>=0.7.8) version of the
  45   [Alabaster](https://pypi.python.org/pypi/alabaster) theme.
  46
  47 If you have `pip`, this command will be all you need:
  48
  49     pip install -U sphinx blockdiag alabaster
  50
  51 After you have everything installed, you can build the HTML version of the
  52 guide from a command prompt, like this:
  53
  54         make html
  55
  56 For building the PDF version, you need a reasonably recent installation of
  57 TeX Live.  Release 2014 will do.  You will also need the Emerald font
  58 package from https://www.ctan.org/tex-archive/fonts/emerald/.  This cannot
  59 be installed with `tlmgr`, nor does it seem to be packaged by the usual
  60 Linux or BSD distributions.  Scripts for installing and uninstalling
  61 Emerald are provided in the `tools` directory.  When you're ready, type
  62 this:
  63
  64         make latexpdf
  65
  66 Other formats are available; just type `make` for more details.