+/**
+ * stylehint_Indentation:
+ *
+ * How much to indent lines of text in the given style. May be a negative
+ * number, to shift the text out (left) instead of in (right). The exact metric
+ * isn't precisely specified; you can assume that +1 is the smallest indentation
+ * possible which is clearly visible to the player.
+ */
+
+/**
+ * stylehint_ParaIndentation:
+ *
+ * How much to indent the first line of each paragraph. This is in addition to
+ * the indentation specified by %stylehint_Indentation. This too may be
+ * negative, and is measured in the same units as %stylehint_Indentation.
+ */
+
+/**
+ * stylehint_Justification:
+ *
+ * The value of this hint must be one of the constants
+ * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification),
+ * %stylehint_just_Centered, or %stylehint_just_RightFlush.
+ */
+
+/**
+ * stylehint_Size:
+ *
+ * How much to increase or decrease the font size. This is relative; 0 means the
+ * interpreter's default font size will be used, positive numbers increase it,
+ * and negative numbers decrease it. Again, +1 is the smallest size increase
+ * which is easily visible.
+ * <note><para>
+ * The amount of this increase may not be constant. +1 might increase an
+ * 8-point font to 9-point, but a 16-point font to 18-point.
+ * </para></note>
+ */
+
+/**
+ * stylehint_Weight:
+ *
+ * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for
+ * normal weight, and -1 for light-weight fonts.
+ */
+
+/**
+ * stylehint_Oblique:
+ *
+ * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal
+ * angle.
+ */
+
+/**
+ * stylehint_Proportional:
+ *
+ * The value of this hint must be 1 for proportional-width fonts, or 0 for
+ * fixed-width.
+ */
+
+/**
+ * stylehint_TextColor:
+ *
+ * The foreground color of the text. This is encoded in the 32-bit hint value:
+ * the top 8 bits must be zero, the next 8 bits are the red value, the next 8
+ * bits are the green value, and the bottom 8 bits are the blue value. Color
+ * values range from 0 to 255.
+ * <note><para>
+ * So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
+ * </para></note>
+ */
+
+/**
+ * stylehint_BackColor:
+ *
+ * The background color behind the text. This is encoded the same way as
+ * %stylehint_TextColor.
+ */
+
+/**
+ * stylehint_ReverseColor:
+ *
+ * The value of this hint must be 0 for normal printing (%stylehint_TextColor on
+ * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on
+ * %stylehint_TextColor).
+ * <note><para>
+ * Some libraries may support this hint but not the %stylehint_TextColor and
+ * %stylehint_BackColor hints. Other libraries may take the opposite tack;
+ * others may support both, or neither.
+ * </para></note>
+ */
+
+/**
+ * stylehint_just_LeftFlush:
+ *
+ * A value for %stylehint_Justification representing left-justified text.
+ */
+
+/**
+ * stylehint_just_LeftRight:
+ *
+ * A value for %stylehint_Justification representing fully justified text.
+ */
+
+/**
+ * stylehint_just_Centered:
+ *
+ * A value for %stylehint_Justification representing centered text.
+ */
+
+/**
+ * stylehint_just_RightFlush:
+ *
+ * A value for %stylehint_Justification representing right-justified text.
+ */
+
+/**
+ * imagealign_InlineUp:
+ *
+ * The image appears at the current point in the text, sticking up. That is, the
+ * bottom edge of the image is aligned with the baseline of the line of text.
+ */
+
+/**
+ * imagealign_InlineDown:
+ *
+ * The image appears at the current point, and the top edge is aligned with the
+ * top of the line of text.
+ */
+
+/**
+ * imagealign_InlineCenter:
+ *
+ * The image appears at the current point, and it is centered between the top
+ * and baseline of the line of text. If the image is taller than the line of
+ * text, it will stick up and down equally.
+ */
+
+/**
+ * imagealign_MarginLeft:
+ *
+ * The image appears in the left margin. Subsequent text will be displayed to
+ * the right of the image, and will flow around it — that is, it will be
+ * left-indented for as many lines as it takes to pass the image.
+ *
+ * <warning><para>Margin images are not implemented yet.</para></warning>
+ */
+
+/**
+ * imagealign_MarginRight:
+ *
+ * The image appears in the right margin, and subsequent text will flow around
+ * it on the left.
+ *
+ * <warning><para>Margin images are not implemented yet.</para></warning>
+ */
+
+/**
+ * glkdate_t:
+ * @year: The full (four-digit) year
+ * @month: The month number, ranging from 1-12, 1 is January
+ * @day: The day of the month, ranging from 1-31
+ * @weekday: The day of the week, ranging from 0-6, 0 is Sunday
+ * @hour: The hour of the day, ranging from 0-23
+ * @minute: The minute of the hour, ranging from 0-59
+ * @second: The second of the minute, ranging from 0-59; may be 60 during a leap
+ * second
+ * @microsec: The fraction of the second in microseconds, ranging from 0-999999
+ *
+ * This structure represents a human-readable date in a specific timezone.
+ */
+
+/**
+ * glktimeval_t:
+ * @high_sec: The most significant 32 bits of the timestamp in seconds.
+ * @low_sec: The least significant 32 bits of the timestamp in seconds.
+ * @microsec: The fraction of the timestamp, in microseconds, ranging from
+ * 0-999999.
+ *
+ * This structure represents the Unix timestamp, i.e. the number of seconds
+ * since January 1, 1970.
+ */
+
+/*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
+
+/**
+ * gidispatch_count_classes:
+ *
+ * Returns the number of opaque object classes used by the library. You will
+ * need to know this if you want to keep track of opaque objects as they are
+ * created; see <link linkend="gidispatch-set-object-registry">Opaque Object
+ * Registry</link>.
+ *
+ * As of Glk API 0.7.0, there are four classes: windows, streams, filerefs, and
+ * sound channels (numbered 0, 1, 2, and 3 respectively.)
+ *
+ * Returns: Number of opaque object classes used by the library.
+ */
+
+/**
+ * gidispatch_get_class:
+ * @index: Unique integer index of the class.
+ *
+ * Returns a structure describing an opaque class that the library exports.
+ * @index can range from 0 to <inlineequation><mathphrase>N -
+ * 1</mathphrase><alt>N - 1</alt></inlineequation>, where N is the value
+ * returned by gidispatch_count_classes().
+ *
+ * Returns: A #gidispatch_intconst_t structure describing the class.
+ */
+
+/**
+ * gidispatch_count_intconst:
+ *
+ * Returns the number of integer constants exported by the library.
+ *
+ * Returns: Number of integer constants exported by the library.
+ */
+
+/**
+ * gidispatch_get_intconst:
+ * @index: Unique integer index of the integer constant.
+ *
+ * Returns a structure describing an integer constant which the library exports.
+ * These are, roughly, all the constants defined in the <filename
+ * class="headerfile">glk.h</filename> file. @index can range from 0 to
+ * <inlineequation><mathphrase>N - 1</mathphrase><alt>N -
+ * 1</alt></inlineequation>, where N is the value returned by
+ * gidispatch_count_intconst().
+ *
+ * Returns: A #gidispatch_intconst_t structure describing the integer constant.
+ */
+
+/**
+ * gidispatch_intconst_t:
+ * @name: Symbolic name of the integer constant.
+ * @val: Value of the integer constant.
+ *
+ * This structure simply contains a string and a value. The string is a
+ * symbolic name of the value, and can be re-exported to anyone interested in
+ * using Glk constants.
+ *
+ * <note><para>
+ * In the current <filename>gi_dispa.c</filename> library, these structures
+ * are static and immutable, and will never be deallocated. However, it is
+ * safer to assume that the structure may be reused in future
+ * gidispatch_get_intconst() calls.
+ * </para></note>
+ */
+
+/**
+ * gidispatch_count_functions:
+ *
+ * Returns the number of functions exported by the library.
+ *
+ * Returns: Number of functions exported by the library.
+ */
+
+/**
+ * gidispatch_get_function:
+ * @index: Unique integer index of the function.
+ *
+ * Returns a structure describing a Glk function. @index can range from 0 to
+ * <inlineequation><mathphrase>N - 1</mathphrase><alt>N -
+ * 1</alt></inlineequation>, where N is the value returned by
+ * gidispatch_count_functions().
+ *
+ * <note><para>
+ * Again, it is safest to assume that the structure is only valid until the
+ * next gidispatch_get_function() or gidispatch_get_function_by_id() call.
+ * </para></note>
+ *
+ * Returns: A #gidispatch_function_t structure describing the function.
+ */
+
+/**
+ * gidispatch_function_t:
+ * @id: Dispatch selector of the function.
+ * @fnptr: Pointer to the function.
+ * @name: Name of the function, without the <code>glk_</code> prefix.
+ *
+ * The @id field is a selector — a numeric constant used to refer to the
+ * function in question. @name is the function name, as it is given in the
+ * <filename class="headerfile">glk.h</filename> file, but without the
+ * <quote><code>glk_</code></quote> prefix. And @fnptr is the address of the
+ * function itself.
+ *
+ * <note><para>
+ * This is included because it might be useful, but it is not recommended. To
+ * call an arbitrary Glk function, you should use gidispatch_call().
+ * </para></note>
+ *
+ * See <link linkend="chimara-Table-of-Selectors">Table of Selectors</link> for
+ * the selector definitions. See <link
+ * linkend="chimara-Dispatching">Dispatching</link> for more about calling Glk
+ * functions by selector.
+ */
+
+/**
+ * gidispatch_get_function_by_id:
+ * @id: A selector.
+ *
+ * Returns a structure describing the Glk function with selector @id. If there
+ * is no such function in the library, this returns %NULL.
+ *
+ * <note><para>
+ * Again, it is safest to assume that the structure is only valid until the
+ * next gidispatch_get_function() or gidispatch_get_function_by_id() call.
+ * </para></note>
+ *
+ * Returns: a #gidispatch_function_t structure, or %NULL.
+ */
+
+/**
+ * gidispatch_call:
+ * @funcnum: Selector of the function to call.
+ * @numargs: Length of @arglist.
+ * @arglist: List of arguments to pass to the function.
+ *
+ * @funcnum is the function number to invoke; see <link
+ * linkend="chimara-Table-of-Selectors">Table of Selectors</link>. @arglist is
+ * the list of arguments, and @numargs is the length of the list.
+ *
+ * The arguments are all stored as #gluniversal_t objects.
+ * </para><refsect3 id="chimara-Basic-Dispatch-Types"><title>Basic Dispatch
+ * Types</title><para>
+ * Numeric arguments are passed in the obvious way — one argument per
+ * #gluniversal_t, with the @uint or @sint field set to the numeric value.
+ * Characters and strings are also passed in this way — #char<!---->s in
+ * the @uch, @sch, or @ch fields (depending on whether the #char is signed) and
+ * strings in the @charstr field. Opaque objects (windows, streams, etc) are
+ * passed in the @opaqueref field (which is <code>void*</code>, in order to
+ * handle all opaque pointer types.)
+ *
+ * However, pointers (other than C strings), arrays, and structures complicate
+ * life. So do return values.
+ * </para></refsect3>
+ * <refsect3 id="chimara-References"><title>References</title><para>
+ * A reference to a numeric type or object reference — that is,
+ * <code>#glui32*</code>, <code>#winid_t*</code>, and so on — takes
+ * <emphasis>one or two</emphasis> #gluniversal_t objects. The first is a flag
+ * indicating whether the reference argument is %NULL or not. The @ptrflag field
+ * of this #gluniversal_t should be %FALSE (0) if the reference is %NULL, and
+ * %TRUE (1) otherwise. If %FALSE, that is the end of the argument; you should
+ * not use a #gluniversal_t to explicitly store the %NULL reference. If the flag
+ * is %TRUE, you must then put a #gluniversal_t storing the base type of the
+ * reference.
+ *
+ * For example, consider a hypothetical function, with selector
+ * <code>0xABCD</code>:
+ * |[
+ * void glk_glomp(glui32 num, winid_t win, glui32 *numref, strid_t *strref);
+ * ]|
+ * ...and the calls:
+ * |[
+ * glui32 value;
+ * winid_t mainwin;
+ * strid_t gamefile;
+ * glk_glomp(5, mainwin, &value, &gamefile);
+ * ]|
+ *
+ * To perform this through gidispatch_call(), you would do the following:
+ * |[
+ * gluniversal_t arglist[6];
+ * arglist[0].uint = 5;
+ * arglist[1].opaqueref = mainwin;
+ * arglist[2].ptrflag = TRUE;
+ * arglist[3].uint = value;
+ * arglist[4].ptrflag = TRUE;
+ * arglist[5].opaqueref = gamefile;
+ * gidispatch_call(0xABCD, 6, arglist);
+ * value = arglist[3].uint;
+ * gamefile = arglist[5].opaqueref;
+ * ]|
+ *
+ * Note that you copy the value of the reference arguments into and out of
+ * @arglist. Of course, it may be that
+ * <function>glk_glomp()</function> only uses these as pass-out
+ * references or pass-in references; if so, you could skip copying in or out.
+ *
+ * For further examples:
+ * |[
+ * glk_glomp(7, mainwin, NULL, NULL);
+ * ...or...
+ * gluniversal_t arglist[4];
+ * arglist[0].uint = 7;
+ * arglist[1].opaqueref = mainwin;
+ * arglist[2].ptrflag = FALSE;
+ * arglist[3].ptrflag = FALSE;
+ * gidispatch_call(0xABCD, 4, arglist);
+ * ]|
+ *
+ * |[
+ * glk_glomp(13, NULL, NULL, &gamefile);
+ * ...or...
+ * gluniversal_t arglist[5];
+ * arglist[0].uint = 13;
+ * arglist[1].opaqueref = NULL;
+ * arglist[2].ptrflag = FALSE;
+ * arglist[3].ptrflag = TRUE;
+ * arglist[4].opaqueref = gamefile;
+ * gidispatch_call(0xABCD, 5, arglist);
+ * gamefile = arglist[4].opaqueref;
+ * ]|
+ *
+ * |[
+ * glk_glomp(17, NULL, &value, NULL);
+ * ...or...
+ * gluniversal_t arglist[5];
+ * arglist[0].uint = 17;
+ * arglist[1].opaqueref = NULL;
+ * arglist[2].ptrflag = TRUE;
+ * arglist[3].uint = value;
+ * arglist[4].ptrflag = FALSE;
+ * gidispatch_call(0xABCD, 5, arglist);
+ * value = arglist[3].uint;
+ * ]|
+ *
+ * As you see, the length of @arglist depends on how many of the reference
+ * arguments are %NULL.
+ * </para></refsect3>
+ * <refsect3 id="chimara-Structures"><title>Structures</title><para>
+ * A structure pointer is represented by a single @ptrflag, possibly followed by
+ * a sequence of #gluniversal_t objects (one for each field of the structure.)
+ * Again, if the structure pointer is non-%NULL, the @ptrflag should be %TRUE
+ * and be followed by values; if not, the @ptrflag should be %NULL and stands
+ * alone.
+ *
+ * For example, the function glk_select() can be invoked as follows:
+ * |[
+ * event_t ev;
+ * gluniversal_t arglist[5];
+ * arglist[0].ptrflag = TRUE;
+ * gidispatch_call(0x00C0, 5, arglist);
+ * ev.type = arglist[1].uint;
+ * ev.win = arglist[2].opaqueref;
+ * ev.val1 = arglist[3].uint;
+ * ev.val2 = arglist[4].uint;
+ * ]|
+ *
+ * Since the structure passed to glk_select() is a pass-out reference (the entry
+ * values are ignored), you don't need to fill in <code>arglist[1..4]</code>
+ * before calling gidispatch_call().
+ *
+ * <note><para>
+ * Theoretically, you would invoke <code>#glk_select(%NULL)</code> by setting'
+ * <code>arglist[0].ptrflag</code> to %FALSE, and using a one-element @arglist
+ * instead of five-element. But it's illegal to pass %NULL to glk_select(). So
+ * you cannot actually do this.
+ * </para></note></para></refsect3>
+ * <refsect3 id="chimara-Arrays"><title>Arrays</title><para>
+ * In the Glk API, an array argument is always followed by a numeric argument
+ * giving the array's length. These two C arguments are a single logical
+ * argument, which is represented by <emphasis>one or three</emphasis>
+ * #gluniversal_t objects. The first is a @ptrflag, indicating whether the
+ * argument is %NULL or not. The second is a pointer, stored in the @array
+ * field. The third is the array length, stored in the @uint field. And again,
+ * if the @ptrflag is %NULL, the following two are omitted.
+ *
+ * For example, the function glk_put_buffer() can be invoked as follows:
+ * |[
+ * char buf[64];
+ * glui32 len = 64;
+ * glk_put_buffer(buf, len);
+ * ...or...
+ * gluniversal_t arglist[3];
+ * arglist[0].ptrflag = TRUE;
+ * arglist[1].array = buf;
+ * arglist[2].uint = len;
+ * gidispatch_call(0x0084, 3, arglist);
+ * ]|
+ *
+ * Since you are passing a C char array to gidispatch_call(), the contents will
+ * be read directly from that. There is no need to copy data into @arglist, as
+ * you would for a basic type.
+ *
+ * If you are implementing a VM whose native representation of char arrays is
+ * more complex, you will have to do more work. You should allocate a C char
+ * array, copy your characters into it, make the call, and then free the array.
+ *
+ * <note><para>
+ * glk_put_buffer() does not modify the array passed to it, so there is no
+ * need to copy the characters out.
+ * </para></note></para></refsect3>
+ * <refsect3 id="chimara-Return-Values"><title>Return Values</title><para>
+ * The return value of a function is not treated specially. It is simply
+ * considered to be a pass-out reference argument which may not be %NULL. It
+ * comes after all the other arguments of the function.
+ *
+ * For example, the function glk_window_get_rock() can be invoked as follows:
+ * |[
+ * glui32 rock;
+ * winid_t win;
+ * rock = glk_window_get_rock(win);
+ * ...or...
+ * gluniversal_t arglist[3];
+ * arglist[0].opaqueref = win;
+ * arglist[1].ptrflag = TRUE;
+ * gidispatch_call(0x0021, 3, arglist);
+ * rock = arglist[2].uint;
+ * ]|
+ * </para></refsect3><para>
+ */
+
+/**
+ * gluniversal_t:
+ * @uint: Stores a #glui32.
+ * @sint: Stores a #glsi32.
+ * @opaqueref: Stores a #winid_t, #strid_t, #frefid_t, or #schanid_t.
+ * @uch: Stores an #unsigned #char.
+ * @sch: Stores a #signed #char.
+ * @ch: Stores a #char with the default signedness.
+ * @charstr: Stores a null-terminated string.
+ * @unicharstr: Stores a zero-terminated string of #glui32 values representing
+ * Unicode characters.
+ * @array: Stores a pointer to an array, and should be followed by another
+ * #gluniversal_t with the array length stored in the @uint member.
+ * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL,
+ * in which case it represents the entire argument. If %TRUE, should be followed
+ * by another #gluniversal_t with the pointer in its @opaqueref or @array field.
+ *
+ * This is a union, encompassing all the types that can be passed to Glk
+ * functions.
+ */
+
+/**
+ * gidispatch_prototype:
+ * @funcnum: A selector for the function to be queried.
+ *
+ * This returns a string which encodes the proper argument list for the given
+ * function. If there is no such function in the library, this returns %NULL.
+ *
+ * The prototype string for the <function>glk_glomp()</function>
+ * function described above would be: <code>"4IuQa&Iu&Qb:"</code>. The
+ * <code>"4"</code> is the number of arguments (including the return value, if
+ * there is one, which in this case there isn't.) <code>"Iu"</code> denotes an
+ * unsigned integer; <code>"Qa"</code> is an opaque object of class 0 (window).
+ * <code>"&Iu"</code> is a <emphasis>reference</emphasis> to an unsigned
+ * integer, and <code>"&Qb"</code> is a reference to a stream. The colon at
+ * the end terminates the argument list; the return value would follow it, if
+ * there was one.
+ *
+ * Note that the initial number (<code>"4"</code> in this case) is the number of
+ * logical arguments, not the number of #gluniversal_t objects which will be
+ * passed to gidispatch_call(). The <function>glk_glomp()</function>
+ * call uses anywhere from four to six #gluniversal_t objects, as demonstrated
+ * above.
+ *
+ * The basic type codes:
+ * <variablelist>
+ * <varlistentry>
+ * <term><code>Iu, Is</code></term>
+ * <listitem><para>Unsigned and signed 32-bit integer.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>Cn, Cu, Cs</code></term>
+ * <listitem><para>Character, #unsigned #char, and #signed #char.</para>
+ * <note><para>Of course <code>Cn</code> will be the same as either
+ * <code>Cu</code> or <code>Cs</code>, depending on the platform. For this
+ * reason, Glk avoids using it, but it is included here for completeness.
+ * </para></note>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>S</code></term>
+ * <listitem><para>A C-style string (null-terminated array of #char). In Glk,
+ * strings are always treated as read-only and used immediately; the library
+ * does not retain a reference to a string between Glk calls. A Glk call that
+ * wants to use writable char arrays will use an array type
+ * (<code>"#C"</code>), not string (<code>"S"</code>).</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>U</code></term>
+ * <listitem><para>A zero-terminated array of 32-bit integers. This is
+ * primarily intended as a Unicode equivalent of <code>"S"</code>. Like
+ * <code>"S"</code> strings, <code>"U"</code> strings are read-only and used
+ * immediately. A Glk call that wants to use writable Unicode arrays will use
+ * an array type (<code>"#Iu"</code>) instead of <code>"U"</code>.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>F</code></term>
+ * <listitem><para>A floating-point value. Glk does not currently use
+ * floating-point values, but we might as well define a code for them.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>Qa, Qb, Qc...</code></term>
+ * <listitem><para>A reference to an opaque object. The second letter
+ * determines which class is involved. (The number of classes can be gleaned
+ * from gidispatch_count_classes(); see <link
+ * linkend="chimara-Interrogating-the-Interface">Interrogating the
+ * Interface</link>).</para>
+ * <note><para>
+ * If Glk expands to have more than 26 classes, we'll think of something.
+ * </para></note></listitem>
+ * </varlistentry>
+ * </variablelist>
+ * Any type code can be prefixed with one or more of the following characters:
+ * <variablelist>
+ * <varlistentry>
+ * <term><code>&</code></term>
+ * <listitem><para>A reference to the type; or, if you like, a variable passed
+ * by reference. The reference is passed both in and out, so you must copy the
+ * value in before calling gidispatch_call() and copy it out afterward.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code><</code></term>
+ * <listitem><para>A reference which is pass-out only. The initial value is
+ * ignored, so you only need copy out the value after the call.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>></code></term>
+ * <listitem><para>A reference which is pass-in only.</para>
+ * <note><para>
+ * This is not generally used for simple types, but is useful for structures
+ * and arrays.
+ * </para></note></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>+</code></term>
+ * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
+ * <code>">"</code>, indicates that a valid reference is mandatory; %NULL
+ * cannot be passed.</para>
+ * <note><para>
+ * Note that even though the @ptrflag #gluniversal_t for a <code>"+"</code>
+ * reference is always %TRUE, it cannot be omitted.
+ * </para></note></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>:</code></term>
+ * <listitem><para>The colon separates the arguments from the return value, or
+ * terminates the string if there is no return value. Since return values are
+ * always non-%NULL pass-out references, you may treat <code>":"</code> as
+ * equivalent to <code>"<+"</code>. The colon is never combined with any
+ * other prefix character.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>[...]</code></term>
+ * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
+ * <code>">"</code>, indicates a structure reference. Between the brackets
+ * is a complete argument list encoding string, including the number of
+ * arguments.</para>
+ * <note><para>
+ * For example, the prototype string for glk_select() is
+ * <code>"1<+[4IuQaIuIu]:"</code> — one argument, which is a
+ * pass-out non-%NULL reference to a structure, which contains four
+ * arguments.
+ * </para></note>
+ * <para>Currently, structures in Glk contain only basic types.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>#</code></term>
+ * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
+ * <code>">"</code>, indicates an array reference. As described above, this
+ * encompasses up to three #gluniversal_t objects — @ptrflag, pointer,
+ * and integer length.</para>
+ * <note><para>
+ * Depending on the design of your program, you may wish to pass a pointer
+ * directly to your program's memory, or allocate an array and copy the
+ * contents in and out. See <link linkend="chimara-Arrays">Arrays</link>.
+ * </para></note></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>!</code></term>
+ * <listitem><para>Combined with <code>"#"</code>, indicates that the
+ * array is retained by the library. The library will keep a reference to the
+ * array; the contents are undefined until further notice. You should not use
+ * or copy the contents of the array out after the call, even for
+ * <code>"&#!"</code> or <code>"<#!"</code> arrays. Instead, do
+ * it when the library releases the array.</para>
+ * <note><para>
+ * For example, glk_stream_open_memory() retains the array that you pass it,
+ * and releases it when the stream is closed. The library can notify you
+ * automatically when arrays are retained and released; see <link
+ * linkend="gidispatch-set-retained-registry">Retained Array
+ * Registry</link>.
+ * </para></note></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * The order of these characters and prefixes is not completely arbitrary. Here
+ * is a formal grammar for the prototype strings.
+ *
+ * <note><para>Thanks to Neil Cerutti for working this out.</para></note>
+ *
+ * <productionset>
+ * <production id="prototype">
+ * <lhs>prototype</lhs>
+ * <rhs>ArgCount [ <nonterminal def="#arg_list">arg_list</nonterminal> ]
+ * ':' [ <nonterminal def="#arg">arg</nonterminal> ] EOL</rhs>
+ * </production>
+ * <production id="arg_list">
+ * <lhs>arg_list</lhs>
+ * <rhs><nonterminal def="#arg">arg</nonterminal> { <nonterminal
+ * def="#arg">arg</nonterminal> }</rhs>
+ * </production>
+ * <production id="arg">
+ * <lhs>arg</lhs>
+ * <rhs>TypeName | <nonterminal def="#ref_type">ref_type</nonterminal>
+ * </rhs>
+ * </production>
+ * <production id="ref_type">
+ * <lhs>ref_type</lhs>
+ * <rhs>RefType [ '+' ] <nonterminal
+ * def="#target_type">target_type</nonterminal></rhs>
+ * </production>
+ * <production id="target_type">
+ * <lhs>target_type</lhs>
+ * <rhs>TypeName | <nonterminal def="#array">array</nonterminal> |
+ * <nonterminal def="#struct">struct</nonterminal></rhs>
+ * </production>
+ * <production id="array">
+ * <lhs>array</lhs>
+ * <rhs>'#' [ '!' ] TypeName</rhs>
+ * </production>
+ * <production id="struct">
+ * <lhs>struct</lhs>
+ * <rhs>'[' ArgCount [ <nonterminal def="#arg_list">arg_list</nonterminal>
+ * ] ']'</rhs>
+ * </production>
+ * </productionset>
+ * <constraintdef id="TypeName">
+ * <para>TypeName is <code>I[us]<!---->|C[nus]<!---->|S|U|F|Q[a-z]</code>
+ * </para>
+ * </constraintdef>
+ * <constraintdef id="ArgCount">
+ * <para>ArgCount is <code>\d+</code></para>
+ * </constraintdef>
+ * <constraintdef id="RefType">
+ * <para>RefType is <code>&|<|></code></para>
+ * </constraintdef>
+ * <constraintdef id="EOL">
+ * <para>EOL is end of input</para>
+ * </constraintdef>
+ *
+ * Returns: A string which encodes the prototype of the specified Glk function.
+ */
+
+/**
+ * gidisp_Class_Window:
+ *
+ * Represents a #winid_t opaque object.
+ */
+
+/**
+ * gidisp_Class_Stream:
+ *
+ * Represents a #strid_t opaque object.
+ */
+
+/**
+ * gidisp_Class_Fileref:
+ *
+ * Represents a #frefid_t opaque object.
+ */
+
+/**
+ * gidisp_Class_Schannel:
+ *
+ * Represents a #schanid_t opaque object.
+ */
+
+/**
+ * gidispatch_rock_t:
+ * @num: Space for storing an integer.
+ * @ptr: Space for storing a pointer.
+ *
+ * You can store any value you want in this object; return it from your object
+ * registry and retained array registry callbacks, and the library will stash it
+ * away. You can retrieve it with gidispatch_get_objrock().
+ */
+
+/*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/
+
+/**
+ * giblorb_err_t:
+ *
+ * An integer type that can hold the Blorb error codes.
+ */
+
+/**
+ * giblorb_err_None:
+ *
+ * No error.
+ */
+
+/**
+ * giblorb_err_CompileTime:
+ *
+ * Something is compiled wrong in the Blorb layer.
+ */
+
+/**
+ * giblorb_err_Alloc:
+ *
+ * Memory could not be allocated.
+ * <note><title>Chimara</title>
+ * <para>
+ * The Blorb layer in the Chimara library should not return this error code;
+ * instead, the program aborts if memory allocation fails, in keeping with
+ * GLib practices.
+ * </para></note>
+ */
+
+/**
+ * giblorb_err_Read:
+ *
+ * Data could not be read from the file.
+ */
+
+/**
+ * giblorb_err_NotAMap:
+ *
+ * The map parameter is invalid.
+ */
+
+/**
+ * giblorb_err_Format:
+ *
+ * The Blorb file is corrupted or invalid.
+ */
+
+/**
+ * giblorb_err_NotFound:
+ *
+ * The requested data could not be found.
+ */
+
+/**
+ * giblorb_method_DontLoad:
+ *
+ * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
+ * giblorb_load_resource() to obtain information about a chunk without actually
+ * loading it.
+ */
+
+/**
+ * giblorb_method_Memory:
+ *
+ * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
+ * giblorb_load_resource() to load a chunk into memory.
+ */
+
+/**
+ * giblorb_method_FilePos:
+ *
+ * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
+ * giblorb_load_resource() to get the position in the Blorb file at which the
+ * chunk data starts.
+ */
+
+/**
+ * giblorb_ID_Snd:
+ *
+ * Resource usage constant representing a sound file.
+ */
+
+/**
+ * giblorb_ID_Exec:
+ *
+ * Resource usage constant representing an executable program.
+ */
+
+/**
+ * giblorb_ID_Pict:
+ *
+ * Resource usage constant representing an image file.
+ */
+
+/**
+ * giblorb_ID_Data:
+ *
+ * Resource usage constant representing a data file.
+ */
+
+/**
+ * giblorb_ID_Copyright:
+ *
+ * Resource usage constant representing the copyright message (date and holder,
+ * without the actual copyright symbol). There should only be one such chunk per
+ * file.
+ */
+
+/**
+ * giblorb_ID_AUTH:
+ *
+ * Resource usage constant representing the name of the author or creator of the
+ * file. This could be a login name on multi-user systems, for example. There
+ * should only be one such chunk per file.
+ */
+
+/**
+ * giblorb_ID_ANNO:
+ *
+ * Resource usage constant representing any textual annotation that the user or
+ * writing program sees fit to include.
+ */
+
+/**
+ * giblorb_ID_TEXT:
+ *
+ * Resource usage constant representing a text data file.
+ */
+
+/**
+ * giblorb_ID_BINA:
+ *
+ * Resource usage constant representing a binary data file.
+ */
+
+/**
+ * giblorb_map_t:
+ *
+ * Holds the complete description of an open Blorb file. This type is opaque for
+ * normal interpreter use.
+ */
+
+/**
+ * giblorb_result_t:
+ * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.)
+ * @length: The length of the data
+ * @chunktype: The type of the chunk.
+ *
+ * Holds information about a chunk loaded from a Blorb file, and the method of
+ * accessing the chunk data. @data is a union of @ptr, a pointer to the data (if
+ * you used %giblorb_method_Memory) and @startpos, the position in the file (if
+ * you used %giblorb_method_FilePos). See giblorb_load_chunk_by_type() and
+ * giblorb_load_chunk_by_number().
+ */
+
+/**
+ * giblorb_create_map:
+ * @file: An input stream pointing to a Blorb file.
+ * @newmap: Return location for a Blorb resource map.
+ *
+ * Reads Blorb data out of a Glk stream. It does not load every resource at
+ * once; instead, it creates a map in memory which makes it easy to find
+ * resources. A pointer to the map is stored in @newmap. This is an opaque
+ * object; you pass it to the other Blorb-layer functions.
+ *
+ * Returns: a Blorb error code.
+ */
+
+/**
+ * giblorb_destroy_map:
+ * @map: A Blorb resource map to deallocate.
+ *
+ * Deallocates @map and all associated memory. This does
+ * <emphasis>not</emphasis> close the original stream.
+ *
+ * Returns: a Blorb error code.
+ */
+
+/**
+ * giblorb_load_chunk_by_type:
+ * @map: The Blorb resource map to load a chunk from.
+ * @method: The loading method to use, one of %giblorb_method_DontLoad,
+ * %giblorb_method_Memory, or %giblorb_method_FilePos.
+ * @res: Return location for the result.
+ * @chunktype: The type of chunk to load.
+ * @count: The chunk number of type @chunktype to load.
+ *
+ * Loads a chunk of a given type. The @count parameter distinguishes between
+ * chunks of the same type. If @count is zero, the first chunk of that type is
+ * loaded, and so on.
+ *
+ * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the
+ * form type, rather than FORM.
+ * <note><para>
+ * This introduces a slight ambiguity — you cannot distiguish between a
+ * FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is
+ * almost certainly a mistake.
+ * </para></note>
+ *
+ * The returned data is written into @res, according to @method.
+ *
+ * The <structfield>chunknum</structfield> field is filled in with the number of
+ * the chunk. (This value can then be passed to giblorb_load_chunk_by_number()
+ * or giblorb_unload_chunk().) The <structfield>length</structfield> field is
+ * filled in with the length of the chunk in bytes. The
+ * <structfield>chunktype</structfield> field is the chunk's type, which of
+ * course will be the type you asked for.
+ *
+ * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You
+ * can use this if you are only interested in whether a chunk exists, or in the
+ * <structfield>chunknum</structfield> and <structfield>length</structfield>
+ * parameters.
+ *
+ * If you specify %giblorb_method_FilePos,
+ * <structfield>data.startpos</structfield> is filled in with the file position
+ * of the chunk data. You can use glk_stream_set_position() to read the data
+ * from the stream.
+ *
+ * If you specify %giblorb_method_Memory, <structfield>data.ptr</structfield> is
+ * filled with a pointer to allocated memory containing the chunk data. This
+ * memory is owned by the map, not you. If you load the chunk more than once
+ * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one
+ * copy in memory. You should not deallocate this memory yourself; call
+ * giblorb_unload_chunk() instead.
+ *
+ * Returns: a Blorb error code.
+ */
+
+/**
+ * giblorb_load_chunk_by_number:
+ * @map: The Blorb resource map to load a chunk from.
+ * @method: The loading method to use, one of %giblorb_method_DontLoad,
+ * %giblorb_method_Memory, or %giblorb_method_FilePos.
+ * @res: Return location for the result.
+ * @chunknum: The chunk number to load.
+ *
+ * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a
+ * given chunk number. The type of the chunk can be found in the
+ * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
+ * the chunk number from the <structfield>chunknum</structfield> field, after
+ * calling one of the other load functions.
+ *
+ * Returns: a Blorb error code.
+ */
+
+/**
+ * giblorb_unload_chunk:
+ * @map: The Blorb resource map to unload a chunk from.
+ * @chunknum: The chunk number to unload.
+ *
+ * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk
+ * has never been loaded into memory, this has no effect.
+ *
+ * Returns: a Blorb error code.
+ */
+
+/**
+ * giblorb_load_resource:
+ * @map: The Blorb resource map to load a resource from.
+ * @method: The loading method to use, one of %giblorb_method_DontLoad,
+ * %giblorb_method_Memory, or %giblorb_method_FilePos.
+ * @res: Return location for the result.
+ * @usage: The type of data resource to load.
+ * @resnum: The resource number to load.
+ *
+ * Loads a resource, given its usage and resource number. Currently, the three
+ * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and
+ * %giblorb_ID_Exec (executable program). See the Blorb specification for more
+ * information about the types of data that can be stored for these usages.
+ *
+ * Note that a resource number is not the same as a chunk number. The resource
+ * number is the sound or image number specified by a Glk program. Chunk number
+ * is arbitrary, since chunks in a Blorb file can be in any order. To find the
+ * chunk number of a given resource, call giblorb_load_resource() and look in
+ * <structfield>res.chunknum</structfield>.
+ *
+ * Returns: a Blorb error code.
+ */
+
+/**
+ * giblorb_count_resources:
+ * @map: The Blorb resource map in which to count the resources.
+ * @usage: The type of data resource to count.
+ * @num: Return location for the number of chunks of @usage.
+ * @min: Return location for the lowest resource number of @usage.
+ * @max: Return location for the highest resource number of @usage.
+ *
+ * Counts the number of chunks with a given usage (image, sound, or executable.)
+ * The total number of chunks of that usage is stored in @num. The lowest and
+ * highest resource number of that usage are stored in @min and @max. You can
+ * leave any of the three pointers %NULL if you don't care about that
+ * information.
+ *
+ * Returns: a Blorb error code.
+ */
+
+/*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/
+
+/**
+ * glkunix_argumentlist_t:
+ * @name: the option as it would appear on the command line (including the
+ * leading dash, if any.)
+ * @desc: a description of the argument; this is used when the library is
+ * printing a list of options.
+ * @argtype: one of the <code>glkunix_arg_</code> constants.
+ *
+ * <variablelist>
+ * <varlistentry>
+ * <term>%glkunix_arg_NoValue</term>
+ * <listitem><para>The argument appears by itself.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_ValueFollows</term>
+ * <listitem><para>The argument must be followed by another argument (the
+ * value).</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_ValueCanFollow</term>
+ * <listitem><para>The argument may be followed by a value, optionally. (If the
+ * next argument starts with a dash, it is taken to be a new argument, not the
+ * value of this one.)</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_NumberValue</term>
+ * <listitem><para>The argument must be followed by a number, which may be the
+ * next argument or part of this one. (That is, either <quote><code>-width
+ * 20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_End</term>
+ * <listitem><para>The <code>glkunix_arguments[]</code> array must be
+ * terminated with an entry containing this value.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * To accept arbitrary arguments which lack dashes, specify a name of
+ * <code>""</code> and an argtype of %glkunix_arg_ValueFollows.
+ *
+ * If you don't care about command-line arguments, you must still define an
+ * empty arguments list, as follows:
+ * |[
+ * glkunix_argumentlist_t glkunix_arguments[] = {
+ * { NULL, glkunix_arg_End, NULL }
+ * };
+ * ]|
+ *
+ * Here is a more complete sample list:
+ * |[
+ * glkunix_argumentlist_t glkunix_arguments[] = {
+ * { "", glkunix_arg_ValueFollows, "filename: The game file to load." },
+ * { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
+ * { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
+ * the NUM, if given)." },
+ * { "-goo", glkunix_arg_NoValue, "-goo: Find goo." },
+ * { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
+ * { NULL, glkunix_arg_End, NULL }
+ * };
+ * ]|
+ * This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum
+ * song</code></quote>.
+ *
+ * After the library parses the command line, it does various occult rituals of
+ * initialization, and then calls glkunix_startup_code().
+ *
+ * |[ int glkunix_startup_code(glkunix_startup_t *data); ]|
+ *
+ * This should return %TRUE if everything initializes properly. If it returns
+ * %FALSE, the library will shut down without ever calling your glk_main()
+ * function.
+ */
+
+/**
+ * glkunix_startup_t:
+ * @argc: The number of arguments in @argv.
+ * @argv: Strings representing command line arguments.
+ *
+ * The fields are a standard Unix <code>(argc, argv)</code> list, which contain
+ * the arguments you requested from the command line. In deference to custom,
+ * <code>argv[0]</code> is always the program name.
+ */
+
+/**
+ * glkunix_arg_End:
+ *
+ * Terminates a list of #glkunix_argumentlist_t.
+ */
+
+/**
+ * glkunix_arg_ValueFollows:
+ *
+ * Indicates an argument which must be followed by a value, as the next
+ * argument.
+ */
+
+/**
+ * glkunix_arg_NoValue:
+ *
+ * Indicates an argument which occurs by itself, without a value.
+ */
+
+/**
+ * glkunix_arg_ValueCanFollow:
+ *
+ * Indicates an argument which may be followed by a value, or may occur by
+ * itself.
+ */
+
+/**
+ * glkunix_arg_NumberValue:
+ *
+ * Indicates an argument which must be followed by a numerical value, either as
+ * the next argument or tacked onto the end of this argument.
+ */