• gamebookformat
  • Usage
  • Supported Output Formats
  • Included Optional Templates
  • Number Map Files
  • Gamebook Format
  • Dependencies
    • Required
    • Optional
    • Development
  • License

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

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.
Debug Plain Text	.debug	Plain text debug output of gamebook contents.

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.
static	html	Remove script link from HTML output.

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.

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

To make something useful from some of the outputted files.

pdflatex

Or other tool to make PDF documents from tex files.

Graphviz

Includes the dot command that can make images from 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.