gamebookformat/readme.org

* 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
:   -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.                                                            |
| 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.

| Name   | Formats | Description                          |
|--------+---------+--------------------------------------|
| a4     | tex     | A4 paper size documents (PDF).       |
| a5     | tex     | A5 paper size documents (PDF).       |
| letter | tex     | Letter paper size documents (PDF).   |
| 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 [[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 :: Make pdf 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.