Introduction.

Schooz (pronounced "skews", "shews" or "skooz" - you choose)
is a Scheme-based engine for interactive hypertext.
The framework is minimal, and based on a few key concepts:


(a) Links and menus.

Affordances in schooz are presented via hypertext, using menus and
links.  The exact implementation will depend on the interface; a
JavaScript client may use pop-up menus and HTML links with mouseover
and onClick properties, whereas a terminal client may use a
Curses-style interface, or simply present all menu options in a list
after the text.  The basic semantics are generally those of hypertext.

A single hyperlink is generated by the (link...) macro:
 (link LinkText FunctionBody)

A visible menu is generated by the (menu...) and (choice...) macros:
 (menu (choice Text1 FuncBody1) (choice Text2 FuncBody2)...)

A hidden (popup or drop-down) menu is generated by (popup...) and (choice...):
 (popup LinkText (choice Text1 FuncBody1) (choice Text2 FuncBody2)...)

Each function-body in a (link...) or (choice...) macro represents a
new action; see (c) below.

Both these link-creating functions have side-effects, depending on the
user interface implementation (in a JavaScript implementation, they
define new functions in the JS namespace; in a terminal
implementation, they accumulate options on the monolithic menu of
affordances that will eventually be presented to the player).

As well as the side-effects, the (link...), (menu...) and (popup...)
functions return the actual hyperlink for the particular user
interface implementation (e.g. an <a onClick=foo>...</a> anchor for a
JavaScript link; for the terminal implementation, there are no
hyperlinks per se, as the affordances appear in a separate menu, but
the (link...) function still returns the boldfaced link text).


(b) Hypertext.

A hypertext is an S-expression constructed using the (link...) and
(menu...) macros, as well as regular quoting, quasiquoting, other
function calls, etc.

By default, a hypertext S-expression is interpreted as SXML.  This can
be overridden, and in general the processing and presentation of the
hypertext will depend on the user interface (for example, it could be
rendered directly as HTML, flattened into plain text, partitioned
among various ID'd elements on a webpage, etc.)


(c) Actions.

An action is a function, taking no arguments, that returns a
hypertext.  Action functions are typically defined anonymously via
(link...) or (choice...) macros, although they can also be defined
separately using (define (action) ...)  or (define action (lambda ()
...)) etc., then referenced using the alternate forms of the link &
choice macros, (link*...) and (choice*...).

The hypertext returned by an action may contain hyperlinks (and menus)
offering more actions.  (If it doesn't contain any such links, the
action is terminal: the game is over.)  Thus, an action function
dynamically constructs its possible successor actions, embedded within
a text that (semantically) describes the immediate consequences of the
action.

Actions need not be "pure" functions; in fact, they will generally
have side-effects that advance the story.

Technically, actions are all that is needed to implement a CYOA.
However, at a bare minimum, it is also useful to have some tools for
designing state-machines (and hierarchical state-machines).

Thus...

(d) Pushdown automata.

As a convenience for world-building, the library implements named
state-machines with stacks (pushdown automata).  These are useful for
implementing constructs like rooms, scenes, side-quests, simple
conversations, puzzles, etc.

(e) Descriptors.

Each named state machine has a mapping from states to associated
descriptor functions.  A descriptor function generates hypertexts or
fragments of hypertext, describing the current state of the machine.
(Note that a descriptor is technically an action and can, in
principle, have side-effects.)

(f) The story graph.

The state machine named "narrative" is distinguished, in that the
library offers syntactic shortcuts, such as (look) to call the current
descriptor, (goto...) to change the state, etc.

(g) Automatic actions.

The (link...) and (menu...) macros can be configured to automatically
append or prepend actions, such as executing (look) after every move.

(h) Syntactic sugar for stories.

Shortcuts such as (link-goto...) and (choice-goto...) allow compact
representation of story graphs.