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
:   -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 [[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                                                                     |
| twine2           | .twine2   | Story file that can be imported to [[http://twinery.org/2/#stories][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 [[https://github.com/oreillymedia/HTMLBook][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 [[http://www.libreoffice.org/][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* ([[http://www.latex-project.org/][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
[[http://en.wikibooks.org/wiki/LaTeX][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. [[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.
** Twine 2 Export
There is experimental support to generate output for [[http://twinery.org/2/#stories][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 [[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.