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
57 of TeX Live. Release 2014 will do. You will also need the iftex
58 package, which may or may not be automatically installed. For Debian
59 and Debian-derived systems, the "texlive-generic-extra" package will
62 You will also need the Emerald font package from
63 https://www.ctan.org/tex-archive/fonts/emerald/. This cannot be
64 installed with `tlmgr`, nor does it seem to be packaged by the usual
65 Linux or BSD distributions. Scripts for installing and uninstalling
66 Emerald are provided in the `tools` directory. When you're ready, type
71 Other formats are available; just type `make` for more details.