+ * Creates a new window. If there are no windows, the first three arguments are
+ * meaningless. @split <emphasis>must</emphasis> be 0, and @method and @size
+ * are ignored. @wintype is the type of window you're creating, and @rock is
+ * the rock (see <link linkend="chimara-Rocks">Rocks</link>).
+ *
+ * If any windows exist, new windows must be created by splitting existing
+ * ones. @split is the window you want to split; this <emphasis>must
+ * not</emphasis> be zero. @method is a mask of constants to specify the
+ * direction and the split method (see below). @size is the size of the split.
+ * @wintype is the type of window you're creating, and @rock is the rock.
+ *
+ * Remember that it is possible that the library will be unable to create a new
+ * window, in which case glk_window_open() will return %NULL.
+ *
+ * <note><para>
+ * It is acceptable to gracefully exit, if the window you are creating is an
+ * important one — such as your first window. But you should not try to
+ * perform any window operation on the id until you have tested to make sure
+ * it is non-zero.
+ * </para></note>
+ *
+ * The examples we've seen so far have the simplest kind of size control. (Yes,
+ * this is <quote>below</quote>.) Every pair is a percentage split, with
+ * <inlineequation>
+ * <alt>X</alt>
+ * <mathphrase>X</mathphrase>
+ * </inlineequation>
+ * percent going to one side, and
+ * <inlineequation>
+ * <alt>(100-X)</alt>
+ * <mathphrase>(100 - X)</mathphrase>
+ * </inlineequation>
+ * percent going to the other side. If the player resizes the window, the whole
+ * mess expands, contracts, or stretches in a uniform way.
+ *
+ * As I said above, you can also make fixed-size splits. This is a little more
+ * complicated, because you have to know how this fixed size is measured.
+ *
+ * Sizes are measured in a way which is different for each window type. For
+ * example, a text grid window is measured by the size of its fixed-width font.
+ * You can make a text grid window which is fixed at a height of four rows, or
+ * ten columns. A text buffer window is measured by the size of its font.
+ *
+ * <note><para>
+ * Remember that different windows may use different size fonts. Even two
+ * text grid windows may use fixed-size fonts of different sizes.
+ * </para></note>
+ *
+ * Graphics windows are measured in pixels, not characters. Blank windows
+ * aren't measured at all; there's no meaningful way to measure them, and
+ * therefore you can't create a blank window of a fixed size, only of a
+ * proportional (percentage) size.
+ *
+ * So to create a text buffer window which takes the top 40% of the original
+ * window's space, you would execute
+ * <informalexample><programlisting>
+ * newwin = #glk_window_open(win, #winmethod_Above | #winmethod_Proportional, 40, #wintype_TextBuffer, 0);
+ * </programlisting></informalexample>
+ *
+ * To create a text grid which is always five lines high, at the bottom of the
+ * original window, you would do
+ * <informalexample><programlisting>
+ * newwin = #glk_window_open(win, #winmethod_Below | #winmethod_Fixed, 5, #wintype_TextGrid, 0);
+ * </programlisting></informalexample>
+ *
+ * Note that the meaning of the @size argument depends on the @method argument.
+ * If the method is #winmethod_Fixed, it also depends on the @wintype argument.
+ * The new window is then called the <quote>key window</quote> of this split,
+ * because its window type determines how the split size is computed.
+ *
+ * <note><para>
+ * For #winmethod_Proportional splits, you can still call the new window the
+ * <quote>key window</quote>. But the key window is not important for
+ * proportional splits, because the size will always be computed as a simple
+ * ratio of the available space, not a fixed size of one child window.
+ * </para></note>
+ *
+ * This system is more or less peachy as long as all the constraints work out.
+ * What happens when there is a conflict? The rules are simple. Size control
+ * always flows down the tree, and the player is at the top. Let's bring out an
+ * example:
+ * <mediaobject><textobject><phrase>Screen shot 5</phrase></textobject>
+ * </mediaobject>
+ *
+ * First we split A into A and B, with a 50% proportional split. Then we split
+ * A into A and C, with C above, C being a text grid window, and C gets a fixed
+ * size of two rows (as measured in its own font size). A gets whatever remains
+ * of the 50% it had before.
+ *
+ * Now the player stretches the window vertically.
+ * <mediaobject><textobject><phrase>Screen shot 6</phrase></textobject>
+ * </mediaobject>
+ *
+ * The library figures: the topmost split, the original A/B split, is 50-50. So
+ * B gets half the screen space, and the pair window next to it (the lower
+ * <quote>O</quote>) gets the other half. Then it looks at the lower
+ * <quote>O</quote>. C gets two rows; A gets the rest. All done.
+ *
+ * Then the user maliciously starts squeezing the window down, in stages:
+ * <mediaobject id="chimara-Figure-Squeezing-Window"><textobject><phrase>
+ * Screen shot 7</phrase></textobject></mediaobject>
+ *
+ * The logic remains the same. B always gets half the space. At stage 3,
+ * there's no room left for A, so it winds up with zero height. Nothing
+ * displayed in A will be visible. At stage 4, there isn't even room in the
+ * upper 50% to give C its two rows; so it only gets one. Finally, C is
+ * squashed out of existence as well.
+ *
+ * When a window winds up undersized, it remembers what size it should be. In
+ * the example above, A remembers that it should be two rows; if the user
+ * expands the window to the original size, it would return to the original
+ * layout.
+ *
+ * The downward flow of control is a bit harsh. After all, in stage 4, there's
+ * room for C to have its two rows if only B would give up some of its 50%. But
+ * this does not happen.
+ *
+ * <note><para>
+ * This makes life much easier for the Glk library. To determine the
+ * configuration of a window, it only needs to look at the window's
+ * ancestors, never at its descendants. So window layout is a simple
+ * recursive algorithm, no backtracking.
+ * </para></note>
+ *
+ * What happens when you split a fixed-size window? The resulting pair window
+ * — that is, the two new parts together — retain the same size
+ * constraint as the original window that was split. The key window for the
+ * original split is still the key window for that split, even though it's now
+ * a grandchild instead of a child.
+ *
+ * The easy, and correct, way to think about this is that the size constraint
+ * is stored by a window's parent, not the window itself; and a constraint
+ * consists of a pointer to a key window plus a size value.
+ *
+ * <mediaobject><textobject><phrase>Screen shot 8</phrase></textobject>
+ * </mediaobject>
+ * After the first split, the new pair window (O1, which covers the whole
+ * screen) knows that its first child (A) is above the second, and gets 50% of
+ * its own area. (A is the key window for this split, but a proportional split
+ * doesn't care about key windows.)
+ *
+ * After the second split, all this remains true; O1 knows that its first child
+ * gets 50% of its space, and A is O1's key window. But now O1's first child is
+ * O2 instead of A. The newer pair window (O2) knows that its first child (C)
+ * is above the second, and gets a fixed size of two rows. (As measured in C's
+ * font, because C is O2's key window.)
+ *
+ * If we split C, now, the resulting pair will still be two C-font rows high
+ * — that is, tall enough for two lines of whatever font C displays. For
+ * the sake of example, we'll do this vertically.
+ * <mediaobject><textobject><phrase>Screen shot 9</phrase></textobject>
+ * </mediaobject>
+ *
+ * O3 now knows that its children have a 50-50 left-right split. O2 is still
+ * committed to giving its upper child, O3, two C-font rows. Again, this is
+ * because C is O2's key window.
+ *
+ * <note><para>
+ * This turns out to be a good idea, because it means that C, the text grid
+ * window, is still two rows high. If O3 had been a upper-lower split, things
+ * wouldn't work out so neatly. But the rules would still apply. If you don't
+ * like this, don't do it.
+ * </para></note>