13 KiB
gamebookformat
A tool to format gamebooks into various formats useful for playing the gamebook on paper or a screen (or for debugging it).
Usage
formatgamebook.py [-h] [-M] [-t D] inputfile [inputfile ...] outputfile positional arguments: inputfile input gamebook file (eg test.gamebook) outputfile output file (eg test.tex or test.rtf) optional arguments: -h, --help show this help message and exit -i T, --include T only include sections with tag -e T, --exclude T exclude sections with tag -M, --no-default-map ignore default map file -t D, --template D add custom template dir -o D, --option D add template override options dir -S, --no-shuffle do not shuffle sections -m F, --map-file F number map file -x, --allow_unknown allow unknown tags
Supported Output Formats
| Name | Extension | Description |
|---|---|---|
| LaTeX | .tex | Useful to generate PDFs using pdflatex or whatever LaTeX tools you prefer. |
| Rich Text Format | .rtf | Supported because the Windhammer Prize requires it. |
| Graphviz DOT | .dot | Use with the Graphviz dot tool to generate a flowchart graph of all sections in the gamebook. |
| HTML | .html | Play gamebook in browser. |
| Plain Text | .txt | Raw plain text without formatting. |
| JSON | .json | JSON-format for debugging |
| twine2 | .twine2 | Story file that can be imported to Twine 2 |
More to be added. Custom output formats or modifications to the default formats can easily be added. Use the -t command-line option to add subdirectories containing new templates or overrides for default templates.
Included Optional Templates
The -o command-line option is like -t but searches the options subdirectory (next to the default templates subdirectory) that contains useful overrides for some behavior of the default output formats. For example adding -o letter to the command-line will produce LaTeX files in Letter size rather than the default A5 size. You can use -o list to generate a text file listing all sections and their numbers, or -o list -i todo to only list sections tagged as todo (or substitute whatever other tag(s) you are interested in).
| Name | Formats | Description |
|---|---|---|
| a4 | tex | A4 paper size documents (PDF). |
| a5 | tex | A5 paper size documents (PDF). |
| htmlbook | html | Generate HTMLBook compatible HTML. |
| letter | tex | Letter paper size documents (PDF). |
| list | txt | Only generate list of sections. |
| paged | rtf,tex | Insert page-break before each section. (Not supported by all RTF viewers.) |
| static | html | Remove script link from HTML output. |
Adding Custom Templates
Any of the built-in templates can be overridden easily. New tags can be added that can generate any output you need for different file formats. However to add a tag that is not included in the default distribution the command-line flat -x is required to tell gamebookformat that you know what you are doing. Otherwise when an unknown tag is encountered you get an ugly error message. The reason for making it moderately difficult to add a new tag is that all the builtin tags have been choosen to work reasonably well in anything from static printed gamebooks to dynamic digital app gamebooks. Anyone thinking of adding a new tag should think twice about how having that tag might mean that some output formats are not longer useful. Sticking to the default tags and not overriding them to do bad things ensures that your gamebooks are still readable and playable in all supported output formats. (The process of adding new templates and new output formats really should be better documented.)
Styles and Scripts
Generated html files use the included gamebookformat.css for styling and gamebookformat.js for scripting (except with the htmlbook or static options). You need those files in the same directory (folder) as your generated html file for it to look right. Of course for a more professional look you probably want to tweak that CSS and possibly the script to look better. A problem with using your own modified versions is that you have to manually merge them with future versions of the files provided with gamebookformat. To avoid that it is better to add styles and scripts using custom templates. There are some hooks in the standard templates to make it easy to add overrides without replacing anything (for instance by making a template with a html/head-overrides.html file). (TODO: Add example showing how to do that, because the last few sentences here probably did not make sense to anyone.)
PDF (easy way)
An easy way to make a PDF is to make a RTF of a book (eg formatgamebook.py mybook.gamebook mybook.rtf) and then open the created document in LibreOffice and use the Export to PDF feature in that application. You might also have luck using other applications like OpenOffice or Microsoft Office, although LibreOffice is known to be able to generate a PDF with all cross-references still intact, and it's free anyway, so if you have a problem with the other applications you can always install it and hopefully that will work. The problem with RTF is that the generated document is very plain, has no images (yet?) and it is rather painful to write custom templates for. You might also have success converting the static HTML version to PDF, if you find a tool that does a good job at that (recommendations?).
PDF (good way)
The best way to make a PDF is to export to TEX (LaTeX) and then use LaTeX (in one of its many versions) to create a PDF. This will look much better than going through RTF, but explaining how to install and use LaTeX is beyond this README document. A good thing about LaTeX is that templates can be easily created to do any layout and decorations you can imagine for your book, so you can get a professional gamebook to print, if you read up a bit on how LaTeX works first.
EPUB
There is no built-in support for generating EPUB books, however there are numerous tools out there to import one of the file formats generated by gamebookformat that can convert them to EPUB (and other ebook formats). The most suitable format is probably html with the -o htmlbook or -o htmlbook options. Calibre seems to do a good job converting these to EPUB, so that should be a start. You probably want to do some experimentation to find a way that creates results you like.
Twine 2 Export
There is experimental support to generate output for Twine 2. Use output format .twine2. Use the Import From File link in the Twine 2 user interface to import the generated file. If everything works as it should you can then edit and play or debug the story in Twine 2. Currently most formatting will be ignored and there is no support for handling collections or counters (yet?).
Check Gamebook
The included checkgamebook.py script can be used to run tests on a book and warn about things that do not look right. To use it first generate a json output file version of the book, using the same flags (eg include-tags) as when formatting the real book. Then run checkgamebook.py bookname.json. Currently only tests that all sections can be reached, in theory, from the start section. It only looks for existing references, and has no idea for instance if a locked door can never be unlocked because it is impossible to find enough money to pay for a key. Future versions will hopefully catch more problems, but never all of them in complex books.
Run checkgamebook.py -v for verbose mode. Currently that just means that all ending (death?) sections of the book are printed, allowing you to manually check that there are no unexpected dead-ends.
Number Map Files
Whenever formatgamebook.py runs it looks for a file with the same name as the output file, but with a .map suffix (eg output.map if the output file is output.html). That file is expected to contain a JSON object mapping section names to numbers, and all sections included in that file are given those numbers rather than being randomly shuffled like other paragraphs. You can also add more map files using the –map-file (or -m) option on the command-line. The -M flag disables the default map file. Unless it has been disabled a default map file is also written, containing all the sections output. This way if you generate the same output file (or files with the same name but different types) they always get the same section numbers assigned. The generated map file can also be used from other scripts to easily read what numbers were assigned to sections, if you need to use the number of some section for something outside of the gamebook itself.
tl;dr: If you make different output files in different formats the generated .map file will ensure that all files use the same random numbers for the same section.
Gamebook Format
The input file expected by the formatgamebook.py script must be in a format containing information about all sections in the book plus some optional metadata. The format should (when TBD) be documented here.
By design the format is similar enough to Emacs Org-Mode that some edit shortcuts works in that mode without additional configuration (eg C-c C-q to edit section tags). References to sections can be followed using C-c C-o while editing the book in org-mode.
Dependencies
Required
- Python 2.7
- To run formatgamebook.py.
Optional
Development
The following are only needed for working on improving the scripts (and even then you can proabbly do without all or most).
- GNU make
- Runs tests and various other useful development tasks. (This in turn depends on some tools like diff, but if you have make installed you probably have them as well.)
- node.js
- To run some tests of HTML (JavaScript) templates.
- nodeunit
- Unit test framework for node.js.
License
Copyright (c) 2013 Pelle Nilsson All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.