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
:   -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.                                                            |
| Debug JSON       | .debug    | [[http://json.org][JSON-formatted]] 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 [[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 *debug* output file version of
the book, using the same flags (eg include-tags) as when
formatting the real book. Then run *checkgamebook.py bookname.debug*.
(TODO: Currently does not really test anything. The idea
is that it should do things like trying to tell you about
sections that can not be reached, or items that are required
before they can possibly have been found.)

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