X-Git-Url: https://jxself.org/git/?p=ibg.git;a=blobdiff_plain;f=README.md;h=eadb3a6e19b8b1bc6b0fd2a62914f7233aabb2a7;hp=e90ea9345bedf700d090ac1767bc232fa7507c1c;hb=HEAD;hpb=387fd4f060cd59e1d96b016733947e20d6277b49 diff --git a/README.md b/README.md index e90ea93..eadb3a6 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,17 @@ Inform Beginner's Guide Introduction ------------ -This repository contains the sources for the +This repository contains the sources for an updated version of the [Inform Beginner's Guide](http://www.firthworks.com/roger/IBG.html), henceforth known as the IBG. This version is in a new source format that's -more contributor-friendly (see below). It's a work-in-progress; see the -[issue tracker](https://github.com/i6/ibg/issues) for how it's going. +more version-control and contributor-friendly: +[Sphinx](http://sphinx-doc.org), a documentation build tool written in +[Python](http://python.org). With Sphinx, the source files are in a very +readable format called +[reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText). +This version of the IBG is a work-in-progress; see the +[issue tracker](https://github.com/i6/ibg/issues) for how it's going. Initially it will be a straight conversion of the 3rd edition. After that, the 4th edition will be prepared. The rationale for a 4th edition is: @@ -22,58 +27,45 @@ the 4th edition will be prepared. The rationale for a 4th edition is: * Some old web links have gone away, to be replaced by new and better ones. +If you want a preview of how the online HTML version of the new guide +looks, you can find it [here](http://inform-beginners-guide.readthedocs.org). + Building from source -------------------- -The new source format is [Sphinx](http://sphinx-doc.org), a documentation -build tool written in [Python](http://python.org), which you will need to -install if you want to build the document. You can find the complete -installation instructions -[here](http://www.sphinx-doc.org/en/stable/install.html). +As well as these document sources, you will need: -After you have Sphinx installed, you can build the HTML version of the -guide from a command prompt, like this: +* Sphinx. You can find the complete installation instructions + [here](http://www.sphinx-doc.org/en/stable/install.html). - make html +* [Blockdiag](https://pypi.python.org/pypi/blockdiag) is used for some of + the diagrams. -For building the PDF version, you need a reasonably recent installation of -TeX Live. Release 2014 will do. You will also need the Emerald font -package from https://www.ctan.org/tex-archive/fonts/emerald/. This cannot -be installed with `tlmgr`, nor does it seem to be packaged by the usual -Linux or BSD distributions. Scripts for installing and uninstalling -Emerald are provided in the `tools` directory. When you're ready, type -this: +* To create the HTML version, you'll need a recent (>=0.7.8) version of the + [Alabaster](https://pypi.python.org/pypi/alabaster) theme. - make latexpdf +If you have `pip`, this command will be all you need: -Other formats are available; just type `make` for more details. + pip install -U sphinx blockdiag alabaster -Conversion strategy -------------------- - -The first three editions of the IBG were created with -[Adobe FrameMaker](http://www.adobe.com/products/framemaker.html). And the -FrameMaker source files have kindly been supplied by Roger Firth to make -this update, which opened up the possibility of creating an auto-converter. - -But unfortunately, what with FrameMaker being proprietary, there isn't much -out there apart from FrameMaker itself that can read them. I was hoping -that conversion using [Mif2Go](http://mif2go.com) might be a possibility, -but it turns out that that's just a plugin for FrameMaker. I guess I could -get a trial FrameMaker license, try to set up the plugin and get it to -autoconvert to some usable format, but it all looks far too messy. But on -the plus side, the supplied GIF images are totally usable. +After you have everything installed, you can build the HTML version of the +guide from a command prompt, like this: -So, it's back to my original plan: use the PDF file. Here's the first -(major) part of the work: + make html -* Dump the text out of the PDF file -* Convert all the 3rd edition text to Sphinx format -* Get the online version to look good +For building the PDF version, you need a reasonably recent installation +of TeX Live. Release 2014 will do. You will also need the iftex +package, which may or may not be automatically installed. For Debian +and Debian-derived systems, the "texlive-generic-extra" package will +take care of this. + +You will also need the Emerald font package from +https://www.ctan.org/tex-archive/fonts/emerald/. This cannot be +installed with `tlmgr`, nor does it seem to be packaged by the usual +Linux or BSD distributions. Scripts for installing and uninstalling +Emerald are provided in the `tools` directory. When you're ready, type +this: -After that comes the 4th edition changes, hopefully in collaboration with -others. Also, in parallel with that, other niceties: + make latexpdf -* Add a glossary -* Add an index -* Prepare a new PDF version, via the Sphinx LaTeX converter +Other formats are available; just type `make` for more details.