* gamebookformat A tool to format [[http://www.gamebooks.org/][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 ** 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 [[http://www.arborell.com/windhammer_prize.html][Windhammer Prize]] requires it. | | Graphviz DOT | .dot | Use with the [[http://www.graphviz.org][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 | [[http://json.org][JSON-format]] for debugging | 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 [[https://github.com/oreillymedia/HTMLBook][HTMLBook]] compatible HTML. | | letter | tex | Letter paper size documents (PDF). | | list | txt | Only generate list of sections. | | static | html | Remove script link from HTML output. | ** 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.) ** 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. [[http://calibre-ebook.com/][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. ** 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 [[http://orgmode.org][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 To make something useful from some of the outputted files. - pdflatex :: Or other tool to make PDF documents from [[http://www.latex-project.org/][tex files]]. - Graphviz :: Includes the dot command that can make images from [[http://en.wikipedia.org/wiki/DOT_%28graph_description_language%29][dot files]]. *** 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.