1 Inform Beginner's Guide
2 =======================
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).
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:
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.
24 * The nitty-gritty information about how to install and run programs goes
27 * Some old web links have gone away, to be replaced by new and better
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).
36 As well as these document sources, you will need:
38 * Sphinx. You can find the complete installation instructions
39 [here](http://www.sphinx-doc.org/en/stable/install.html).
41 * [Blockdiag](https://pypi.python.org/pypi/blockdiag) is used for some of
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.
47 If you have `pip`, this command will be all you need:
49 pip install -U sphinx blockdiag alabaster
51 After you have everything installed, you can build the HTML version of the
52 guide from a command prompt, like this:
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
66 Other formats are available; just type `make` for more details.