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 contributor-friendly (see below).  It's a work-in-progress; see the
  11 [issue tracker](https://github.com/i6/ibg/issues) for how it's going.
  12
  13 Initially it will be a straight conversion of the 3rd edition.  After that,
  14 the 4th edition will be prepared.  The rationale for a 4th edition is:
  15
  16 * There have been quite a few updates to Inform and its support libraries
  17   in the time since 2004, when the 3rd edition was published.
  18
  19 * The nitty-gritty information about how to install and run programs goes
  20   stale pretty fast.
  21
  22 * Some old web links have gone away, to be replaced by new and better
  23   ones.
  24
  25 Building from source
  26 --------------------
  27
  28 The new source format is [Sphinx](http://sphinx-doc.org), a documentation
  29 build tool written in [Python](http://python.org), which you will need to
  30 install if you want to build the document.  You can find the complete
  31 installation instructions
  32 [here](http://www.sphinx-doc.org/en/stable/install.html).
  33
  34 After you have Sphinx installed, you can build the HTML version of the
  35 guide from a command prompt, like this:
  36
  37         make html
  38
  39 For building the PDF version, you need a reasonably recent installation
  40 of TeX Live.  Release 2014 will do.  You will also need the Emerald
  41 package from https://www.ctan.org/tex-archive/fonts/emerald/.  This
  42 cannot be installed with tlmgr, nor does it seem to be packaged by the
  43 usual Linux or BSD distributions.  Scripts for installing and
  44 uninstalling Emerald are provided here.  When you're ready, type this:
  45
  46         make latexpdf
  47
  48 Other formats are available; just type `make` for more details.
  49
  50 Conversion strategy
  51 -------------------
  52
  53 The first three editions of the IBG were created with
  54 [Adobe FrameMaker](http://www.adobe.com/products/framemaker.html).  And the
  55 FrameMaker source files have kindly been supplied by Roger Firth to make
  56 this update, which opened up the possibility of creating an auto-converter.
  57
  58 But unfortunately, what with FrameMaker being proprietary, there isn't much
  59 out there apart from FrameMaker itself that can read them.  I was hoping
  60 that conversion using [Mif2Go](http://mif2go.com) might be a possibility,
  61 but it turns out that that's just a plugin for FrameMaker.  I guess I could
  62 get a trial FrameMaker license, try to set up the plugin and get it to
  63 autoconvert to some usable format, but it all looks far too messy.  But on
  64 the plus side, the supplied GIF images are totally usable.
  65
  66 So, it's back to my original plan: use the PDF file.  Here's the first
  67 (major) part of the work:
  68
  69 * Dump the text out of the PDF file
  70 * Convert all the 3rd edition text to Sphinx format
  71 * Get the online version to look good
  72
  73 After that comes the 4th edition changes, hopefully in collaboration with
  74 others.  Also, in parallel with that, other niceties:
  75
  76 * Add a glossary
  77 * Add an index
  78 * Prepare a new PDF version, via the Sphinx LaTeX converter