README.md

   1 Inform Beginner's Guide
   2 =======================
   3
   4 Introduction
   5 ------------
   6
   7 This repository contains the sources for 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 Building from source
  31 --------------------
  32
  33 As well as these document sources, you will need:
  34
  35 * Sphinx.  You can find the complete installation instructions
  36   [here](http://www.sphinx-doc.org/en/stable/install.html).
  37
  38 * [Blockdiag](https://pypi.python.org/pypi/blockdiag) is used for some of
  39   the diagrams.
  40
  41 * To create the HTML version, you'll need a recent (>=0.7.8) version of the
  42   [Alabaster](https://pypi.python.org/pypi/alabaster) theme.
  43
  44 If you have `pip`, this command will be all you need:
  45
  46     pip install -U sphinx blockdiag alabaster
  47
  48 After you have everything installed, you can build the HTML version of the
  49 guide from a command prompt, like this:
  50
  51         make html
  52
  53 For building the PDF version, you need a reasonably recent installation of
  54 TeX Live.  Release 2014 will do.  You will also need the Emerald font
  55 package from https://www.ctan.org/tex-archive/fonts/emerald/.  This cannot
  56 be installed with `tlmgr`, nor does it seem to be packaged by the usual
  57 Linux or BSD distributions.  Scripts for installing and uninstalling
  58 Emerald are provided in the `tools` directory.  When you're ready, type
  59 this:
  60
  61         make latexpdf
  62
  63 Other formats are available; just type `make` for more details.
  64
  65 Conversion strategy
  66 -------------------
  67
  68 The first three editions of the IBG were created with
  69 [Adobe FrameMaker](http://www.adobe.com/products/framemaker.html).  And the
  70 FrameMaker source files have kindly been supplied by Roger Firth to make
  71 this update, which opened up the possibility of creating an auto-converter.
  72
  73 But unfortunately, what with FrameMaker being proprietary, there isn't much
  74 out there apart from FrameMaker itself that can read them.  I was hoping
  75 that conversion using [Mif2Go](http://mif2go.com) might be a possibility,
  76 but it turns out that that's just a plugin for FrameMaker.  I guess I could
  77 get a trial FrameMaker license, try to set up the plugin and get it to
  78 autoconvert to some usable format, but it all looks far too messy.  But on
  79 the plus side, the supplied GIF images are totally usable.
  80
  81 So, it's back to my original plan: use the PDF file.  Here's the first
  82 (major) part of the work:
  83
  84 * Dump the text out of the PDF file
  85 * Convert all the 3rd edition text to Sphinx format
  86 * Get the online version to look good
  87
  88 After that comes the 4th edition changes, hopefully in collaboration with
  89 others.  Also, in parallel with that, other niceties:
  90
  91 * Add a glossary
  92 * Add an index
  93 * Prepare a new PDF version, via the Sphinx LaTeX converter