Got Gtk-Doc working. Now all the fancy /** comments before the functions
authorfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sun, 29 Mar 2009 01:13:07 +0000 (01:13 +0000)
committerfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sun, 29 Mar 2009 01:13:07 +0000 (01:13 +0000)
actually mean something. To use gtk-doc, invoke configure like this:

./configure --enable-gtk-doc

When you do this, configure will generate makefiles that rebuild the docs
whenever the source is changed. Calling configure without that option
generates makefiles that don't rebuild the docs. Building the docs takes
some time so you probably want to disable it unless you're actively working
on the docs.

The documentation is output as HTML, which you can browse by pointing your
browser to

file:///path/to/chimara/docs/reference/html/index.html

The really cool thing is that the docs are also built as a devhelp module,
so when you make install, the devhelp module is installed and automatically
shows up in Devhelp.

The documentation consists of two sections: one is the API of our widget,
the other is the Glk API specification which we have been working from. I
have obtained permission from Andrew Plotkin to include and alter this spec.
I have changed the order of things around a little bit so it makes more
sense as a Gtk-Doc reference book.

The API spec only contains the parts that we have implemented so far. I
figure if we update the documentation for the Glk API functions as we
implement them, then we'll be able to see at a glance how far we've gotten.

One more change left to describe: the new file src/doc.c consists of only
comments. These comments contain two things. One is the introductory
descriptions of each Gtk-Doc section. I put these in here because they
really bloated the regular C files. The other is the Gtk-Doc comments for
constants and structures that are defined in glk.h. I put these in here
because the spec says glk.h is supposed to be the same on every platform
except for the typedefs of the 32-bit types.

42 files changed:
Makefile.am
autogen.sh
configure.ac
docs/.svnignore [new file with mode: 0644]
docs/Makefile.am [new file with mode: 0644]
docs/reference/.svnignore [new file with mode: 0644]
docs/reference/Makefile.am [new file with mode: 0644]
docs/reference/chimara-docs.sgml [new file with mode: 0644]
docs/reference/chimara-sections.txt [new file with mode: 0644]
docs/reference/chimara.types [new file with mode: 0644]
docs/reference/glk-api-conventions.sgml [new file with mode: 0644]
docs/reference/glk-character-encoding.sgml [new file with mode: 0644]
docs/reference/glk-display-style.sgml [new file with mode: 0644]
docs/reference/glk-front-matter.sgml [new file with mode: 0644]
docs/reference/glk-introduction.sgml [new file with mode: 0644]
docs/reference/glk-line-input.sgml [new file with mode: 0644]
docs/reference/glk-main-function.sgml [new file with mode: 0644]
docs/reference/glk-other-events.sgml [new file with mode: 0644]
docs/reference/glk-output.sgml [new file with mode: 0644]
docs/reference/glk-window-arrangement.sgml [new file with mode: 0644]
docs/reference/glk-windows.sgml [new file with mode: 0644]
docs/reference/version.xml.in [new file with mode: 0644]
po/.ignore [deleted file]
src/Makefile.am
src/abort.c
src/case.c
src/chimara-glk-private.h
src/chimara-glk.c
src/chimara-glk.h
src/doc.c [new file with mode: 0644]
src/event.c
src/fileref.c
src/fileref.h
src/gestalt.c
src/glk.c
src/input.c
src/stream.c
src/stream.h
src/strio.c
src/style.c
src/window.c
src/window.h

index d4c356bcb3d201956c29270221adcecdc7b87c58..4a87cfd403a210164f2f9b089d7529970976acb8 100644 (file)
@@ -1,7 +1,7 @@
 ## Process this file with automake to produce Makefile.in
 ## Created by Anjuta
 
-SUBDIRS = src po
+SUBDIRS = src po docs
 
 chimaradocdir = ${prefix}/doc/chimara
 chimaradoc_DATA = \
@@ -24,3 +24,5 @@ dist-hook:
        done
 
 DISTCLEANFILES = intltool-extract intltool-merge intltool-update
+
+DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc
index 02e7c8908e37fea6cccb938d15d1fb55bfadaa66..49281e569d05009f9605e0b9a78cbf4364c5d39a 100755 (executable)
@@ -4,7 +4,7 @@
 ### GTK-DOC #########################################################
 # Run before autotools
 echo "Setting up Gtk-Doc"
-gtkdocize || exit 1
+gtkdocize --flavour no-tmpl || exit 1
 
 ### AUTOTOOLS #######################################################
 # Runs autoconf, autoheader, aclocal, automake, autopoint, libtoolize
index 855619ae3e79302779b1cee424866ddf40597385..f084467be9fc7d6a548f4102ff61a972c175eee7 100644 (file)
@@ -61,6 +61,9 @@ AC_CONFIG_HEADERS([config.h])
 AC_CONFIG_FILES([
 Makefile
 src/Makefile
+docs/Makefile
+docs/reference/Makefile
+docs/reference/version.xml
 po/Makefile.in
 ])
 # Do it
diff --git a/docs/.svnignore b/docs/.svnignore
new file mode 100644 (file)
index 0000000..22a4e72
--- /dev/null
@@ -0,0 +1,3 @@
+Makefile
+Makefile.in
+
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644 (file)
index 0000000..b68c774
--- /dev/null
@@ -0,0 +1 @@
+SUBDIRS=reference
diff --git a/docs/reference/.svnignore b/docs/reference/.svnignore
new file mode 100644 (file)
index 0000000..7da551f
--- /dev/null
@@ -0,0 +1,18 @@
+.libs
+Makefile
+Makefile.in
+html
+xml
+*.stamp
+version.xml
+chimara.args
+chimara.hierarchy
+chimara.interfaces
+chimara.signals
+chimara.prerequisites
+chimara-decl.txt
+chimara-decl-list.txt
+chimara-overrides.txt
+chimara-undeclared.txt
+chimara-undocumented.txt
+
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644 (file)
index 0000000..4e05bb9
--- /dev/null
@@ -0,0 +1,101 @@
+### Makefile.am for Gtk-Doc directory #########################################
+# Adapted from examples/Makefile.am in Gtk-Doc distribution
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE = chimara
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+# DOC_MODULE_VERSION = 2
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+DOC_SOURCE_DIR = ../../src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS = 
+
+# Extra options to supply to gtkdoc-scan.
+# DO NOT use --rebuild-types, because it will think glk_window_get_type()
+# is a GObject type. That makes it segfault.
+SCAN_OPTIONS = 
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS = --sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+MKTMPL_OPTIONS = 
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS = 
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+FIXXREF_OPTIONS = 
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+HFILE_GLOB = $(top_srcdir)/src/*.h
+CFILE_GLOB = $(top_srcdir)/src/*.c
+
+# Extra headers to include when scanning, which are not under DOC_SOURCE_DIR
+EXTRA_HFILES = 
+
+# Header files to ignore when scanning. Use base file name, no paths
+IGNORE_HFILES = chimara-glk-private.h \
+       abort.h charset.h event.h input.h stream.h window.h \
+       callbacks.h error.h
+
+# Images to copy into HTML directory.
+HTML_IMAGES = 
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+content_files = version.xml \
+       glk-front-matter.sgml \
+       glk-introduction.sgml \
+       glk-main-function.sgml \
+       glk-api-conventions.sgml \
+       glk-character-encoding.sgml \
+       glk-output.sgml \
+       glk-line-input.sgml \
+       glk-windows.sgml \
+       glk-window-arrangement.sgml \
+       glk-display-style.sgml \
+       glk-other-events.sgml
+
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+expand_content_files = \
+       glk-main-function.sgml \
+       glk-api-conventions.sgml \
+       glk-output.sgml \
+       glk-line-input.sgml \
+       glk-window-arrangement.sgml \
+       glk-display-style.sgml \
+       glk-other-events.sgml
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+GTKDOC_CFLAGS = -I$(top_srcdir) $(CHIMARA_CFLAGS)
+GTKDOC_LIBS =  $(top_builddir)/src/libchimara.la
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+EXTRA_DIST += version.xml.in
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS), e.g. $(DOC_MODULE)-sections.txt
+# DISTCLEANFILES +=
+
+# Comment this out if you want your docs-status tested during 'make check'
+# TESTS_ENVIRONMENT = cd $(srcsrc)
+# TESTS = $(GTKDOC_CHECK)
+
diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml
new file mode 100644 (file)
index 0000000..d003476
--- /dev/null
@@ -0,0 +1,142 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>Chimara Reference Manual</title>
+    <releaseinfo>
+      for Chimara &version;. The latest version of this documentation can be 
+      found on-line at <ulink role="online-location" 
+      url="http://[SERVER]/chimara/index.html">http://[SERVER]/chimara/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <reference>
+    <title>Chimara API Reference</title>
+    <xi:include href="xml/chimara-glk.xml"/>
+  </reference>
+  
+  <reference>
+    <title>Glk API Specification, version 0.7.0</title>
+    <xi:include href="glk-front-matter.sgml"/>
+    
+    <!-- Chapter 0. Introduction -->
+    <xi:include href="glk-introduction.sgml"/>
+    
+    <!-- Chapter 1. Overall Structure -->
+    <chapter>
+      <title>Overall Structure</title>
+      <!-- For Gtk-Doc post-processed SGML files, look in the xml directory-->
+      <xi:include href="xml/glk-main-function.sgml"/>
+      <xi:include href="xml/glk-exiting.xml"/>
+      <xi:include href="xml/glk-interrupt.xml"/>
+      <xi:include href="xml/glk-tick.xml"/>
+      <xi:include href="xml/glk-types.xml"/>
+      <xi:include href="xml/glk-opaque-objects.xml"/>
+      <xi:include href="xml/glk-gestalt.xml"/>
+      <xi:include href="xml/glk-api-conventions.sgml"/>
+    </chapter>
+    
+    <!-- Chapter 2. Character Encoding -->
+    <chapter>
+      <title>Character Encoding</title>
+      <xi:include href="glk-character-encoding.sgml"/>
+      <xi:include href="xml/glk-output.sgml"/>
+      <xi:include href="xml/glk-line-input.sgml"/>
+      <xi:include href="xml/glk-character-input.xml"/>
+      <xi:include href="xml/glk-case.xml"/>
+    </chapter>
+    
+    <!-- Chapter 3. Windows -->
+    <chapter>
+      <title>Windows</title>
+      <xi:include href="glk-windows.sgml"/>
+      <xi:include href="xml/glk-window-arrangement.sgml"/>
+      <xi:include href="xml/glk-window-opening.xml"/>
+      <xi:include href="xml/glk-window-constraints.xml"/>
+      <xi:include href="xml/glk-display-style.sgml"/>
+      <xi:include href="xml/glk-window-types.xml"/>
+      <xi:include href="xml/glk-echo-streams.xml"/>
+      <xi:include href="xml/glk-window-other.xml"/>
+    </chapter>
+    
+    <!-- Chapter 4. Events -->
+    <chapter>
+      <title>Events</title>
+      <xi:include href="xml/glk-events.xml"/>
+      <xi:include href="xml/glk-character-input-events.xml"/>
+      <xi:include href="xml/glk-line-input-events.xml"/>
+      <!--<xi:include href="xml/glk-mouse-events.xml"/>
+      <xi:include href="xml/glk-timer-events.xml"/>
+      <xi:include href="xml/glk-arrangement-events.sgml"/>
+      <xi:include href="xml/glk-redraw-events.sgml"/>
+      <xi:include href="xml/glk-sound-notify-events.sgml"/>
+      <xi:include href="xml/glk-hyperlink-events.sgml"/>-->
+      <xi:include href="xml/glk-other-events.sgml"/>
+       </chapter>
+       
+       <!-- Chapter 5. Streams -->
+       <chapter>
+         <title>Streams</title>
+         <xi:include href="xml/glk-streams.xml"/>
+         <xi:include href="xml/glk-print.xml"/>
+         <xi:include href="xml/glk-read.xml"/>
+         <xi:include href="xml/glk-closing-streams.xml"/>
+         <xi:include href="xml/glk-stream-positions.xml"/>
+         <!--<xi:include href="xml/glk-styles.xml"/>-->
+         <xi:include href="xml/glk-stream-types.xml"/>
+         <xi:include href="xml/glk-stream-other.xml"/>
+       </chapter>
+       
+       <!-- Chapter 6. File References -->
+       <chapter>
+         <title>File References</title>
+         <xi:include href="xml/glk-fileref.xml"/>
+         <xi:include href="xml/glk-fileref-types.xml"/>      
+      <xi:include href="xml/glk-fileref-other.xml"/>
+    </chapter>
+    
+    <!-- Chapter 7. Graphics -->
+<!--    <chapter>
+      <title>Graphics</title>
+      <xi:include href="xml/glk-image-resources.xml"/>
+      <xi:include href="xml/glk-graphics-windows.xml"/>
+      <xi:include href="xml/glk-graphics-text.xml"/>
+      <xi:include href="xml/glk-graphics-testing.xml"/>
+    </chapter>
+-->    
+    <!-- Chapter 8. Sound -->
+<!--    <chapter>
+      <title>Sound</title>
+      <xi:include href="xml/glk-sound-channels.xml"/>
+      <xi:include href="xml/glk-playing-sounds.xml"/>
+      <xi:include href="xml/glk-sound-other.xml"/>
+      <xi:include href="xml/glk-sound-testing.xml"/>
+    </chapter>
+-->    
+    <!-- Chapter 9. Hyperlinks -->
+<!--    <chapter>
+      <title>Hyperlinks</title>
+      <xi:include href="xml/glk-creating-hyperlinks.xml"/>
+      <xi:include href="xml/glk-accepting-hyperlinks.xml"/>
+      <xi:include href="xml/glk-hyperlinks-testing.xml"/>
+    </chapter>
+-->    
+    <!-- Chapter 10. Porting, Adapting and Other Messy Bits -->
+<!--    <chapter>
+      <title>Porting, Adapting, and Other Messy Bits</title>
+    </chapter>
+-->    
+    <!-- Chapter 11. Appendices -->
+<!--    <appendix>
+      <title>The Dispatch Layer</title>
+    </appendix>
+    
+    <appendix>
+      <title>The Blorb Layer</title>
+    </appendix>
+-->    
+  </reference>
+</book>
diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt
new file mode 100644 (file)
index 0000000..79094a6
--- /dev/null
@@ -0,0 +1,466 @@
+<SECTION>
+<FILE>chimara-glk</FILE>
+<TITLE>ChimaraGlk</TITLE>
+ChimaraGlk
+chimara_glk_new
+chimara_glk_set_interactive
+chimara_glk_get_interactive
+chimara_glk_set_protect
+chimara_glk_get_protect
+chimara_glk_run
+chimara_glk_stop
+chimara_glk_wait
+<SUBSECTION Standard>
+ChimaraGlkClass
+CHIMARA_GLK
+CHIMARA_IS_GLK
+CHIMARA_TYPE_GLK
+chimara_glk_get_type
+CHIMARA_GLK_CLASS
+CHIMARA_IS_GLK_CLASS
+CHIMARA_GLK_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>glk-exiting</FILE>
+<TITLE>Exiting Your Program</TITLE>
+glk_exit
+<SUBSECTION Private>
+glk_main
+</SECTION>
+
+<SECTION>
+<FILE>glk-interrupt</FILE>
+<TITLE>The Interrupt Handler</TITLE>
+glk_set_interrupt_handler
+</SECTION>
+
+<SECTION>
+<FILE>glk-tick</FILE>
+<TITLE>The Tick Thing</TITLE>
+glk_tick
+</SECTION>
+
+<SECTION>
+<FILE>glk-types</FILE>
+<TITLE>Basic Types</TITLE>
+glui32
+glsi32
+</SECTION>
+
+<SECTION>
+<FILE>glk-opaque-objects</FILE>
+<TITLE>Opaque Objects</TITLE>
+winid_t
+strid_t
+frefid_t
+schanid_t
+</SECTION>
+
+<SECTION>
+<FILE>glk-gestalt</FILE>
+<TITLE>The Gestalt System</TITLE>
+glk_gestalt_ext
+glk_gestalt
+<SUBSECTION The Version Number>
+gestalt_Version
+<SUBSECTION Testing for Unicode Capabilities>
+gestalt_Unicode
+GLK_MODULE_UNICODE
+<SUBSECTION Output>
+gestalt_CharOutput
+gestalt_CharOutput_CannotPrint
+gestalt_CharOutput_ApproxPrint
+gestalt_CharOutput_ExactPrint
+<SUBSECTION Line Input>
+gestalt_LineInput
+<SUBSECTION Character Input>
+gestalt_CharInput
+<SUBSECTION Constants>
+gestalt_MouseInput
+gestalt_Timer
+gestalt_Graphics
+gestalt_DrawImage
+gestalt_Sound
+gestalt_SoundVolume
+gestalt_SoundNotify
+gestalt_Hyperlinks
+gestalt_HyperlinkInput
+gestalt_SoundMusic
+gestalt_GraphicsTransparency
+</SECTION>
+
+<SECTION>
+<FILE>glk-character-input</FILE>
+<TITLE>Character Input</TITLE>
+keycode_Unknown
+keycode_Left
+keycode_Right
+keycode_Up
+keycode_Down
+keycode_Return
+keycode_Delete
+keycode_Escape
+keycode_Tab
+keycode_PageUp
+keycode_PageDown
+keycode_Home
+keycode_End
+keycode_Func1
+keycode_Func2
+keycode_Func3
+keycode_Func4
+keycode_Func5
+keycode_Func6
+keycode_Func7
+keycode_Func8
+keycode_Func9
+keycode_Func10
+keycode_Func11
+keycode_Func12
+keycode_MAXVAL
+</SECTION>
+
+<SECTION>
+<FILE>glk-case</FILE>
+<TITLE>Upper and Lower Case</TITLE>
+glk_char_to_lower
+glk_char_to_upper
+glk_buffer_to_lower_case_uni
+glk_buffer_to_upper_case_uni
+glk_buffer_to_title_case_uni
+</SECTION>
+
+<SECTION>
+<FILE>glk-window-opening</FILE>
+<TITLE>Window Opening, Closing, and Constraints</TITLE>
+glk_window_open
+winmethod_Left
+winmethod_Right
+winmethod_Above
+winmethod_Below
+winmethod_DirMask
+winmethod_Fixed
+winmethod_Proportional
+winmethod_DivisionMask
+glk_window_close
+</SECTION>
+
+<SECTION>
+<FILE>glk-window-constraints</FILE>
+<TITLE>Changing Window Constraints</TITLE>
+glk_window_get_size
+glk_window_set_arrangement
+glk_window_get_arrangement
+</SECTION>
+
+<SECTION>
+<FILE>glk-window-types</FILE>
+<TITLE>The Types of Windows</TITLE>
+wintype_Blank
+wintype_Pair
+wintype_TextBuffer
+wintype_TextGrid
+glk_window_move_cursor
+wintype_Graphics
+wintype_AllTypes
+</SECTION>
+
+<SECTION>
+<FILE>glk-echo-streams</FILE>
+<TITLE>Echo Streams</TITLE>
+glk_window_set_echo_stream
+glk_window_get_echo_stream
+</SECTION>
+
+<SECTION>
+<FILE>glk-window-other</FILE>
+<TITLE>Other Window Functions</TITLE>
+glk_window_iterate
+glk_window_get_rock
+glk_window_get_type
+glk_window_get_parent
+glk_window_get_sibling
+glk_window_get_root
+glk_window_clear
+glk_window_get_stream
+glk_set_window
+</SECTION>
+
+<SECTION>
+<FILE>glk-events</FILE>
+<TITLE>Events</TITLE>
+glk_select
+event_t
+glk_select_poll
+<SUBSECTION Constants>
+evtype_None
+evtype_Timer
+evtype_CharInput
+evtype_LineInput
+evtype_MouseInput
+evtype_Arrange
+evtype_Redraw
+evtype_SoundNotify
+evtype_Hyperlink
+</SECTION>
+
+<SECTION>
+<FILE>glk-character-input-events</FILE>
+<TITLE>Character Input Events</TITLE>
+glk_request_char_event
+glk_request_char_event_uni
+glk_cancel_char_event
+</SECTION>
+
+<SECTION>
+<FILE>glk-line-input-events</FILE>
+<TITLE>Line Input Events</TITLE>
+glk_request_line_event
+glk_request_line_event_uni
+glk_cancel_line_event
+</SECTION>
+
+<SECTION>
+<FILE>glk-mouse-events</FILE>
+<TITLE>Mouse Input Events</TITLE>
+glk_request_mouse_event
+glk_cancel_mouse_event
+</SECTION>
+
+<SECTION>
+<FILE>glk-timer-events</FILE>
+<TITLE>Timer Events</TITLE>
+glk_request_timer_events
+</SECTION>
+
+<SECTION>
+<FILE>glk-streams</FILE>
+<TITLE>Streams</TITLE>
+glk_stream_set_current
+glk_stream_get_current
+<SUBSECTION Constants>
+filemode_Write
+filemode_Read
+filemode_ReadWrite
+filemode_WriteAppend
+</SECTION>
+
+<SECTION>
+<FILE>glk-print</FILE>
+<TITLE>How to Print</TITLE>
+glk_put_char
+glk_put_string
+glk_put_buffer
+glk_put_char_stream
+glk_put_string_stream
+glk_put_buffer_stream
+glk_put_char_uni
+glk_put_string_uni
+glk_put_buffer_uni
+glk_put_char_stream_uni
+glk_put_string_stream_uni
+glk_put_buffer_stream_uni
+</SECTION>
+
+<SECTION>
+<FILE>glk-read</FILE>
+<TITLE>How to Read</TITLE>
+glk_get_char_stream
+glk_get_buffer_stream
+glk_get_line_stream
+glk_get_char_stream_uni
+glk_get_buffer_stream_uni
+glk_get_line_stream_uni
+</SECTION>
+
+<SECTION>
+<FILE>glk-closing-streams</FILE>
+<TITLE>Closing Streams</TITLE>
+glk_stream_close
+stream_result_t
+</SECTION>
+
+<SECTION>
+<FILE>glk-stream-positions</FILE>
+<TITLE>Stream Positions</TITLE>
+glk_stream_set_position
+glk_stream_get_position
+<SUBSECTION Constants>
+seekmode_Start
+seekmode_Current
+seekmode_End
+</SECTION>
+
+<SECTION>
+<FILE>glk-styles</FILE>
+<TITLE>Styles</TITLE>
+glk_set_style
+glk_set_style_stream
+<SUBSECTION Suggesting the Appearance of Styles>
+glk_stylehint_set
+glk_stylehint_clear
+<SUBSECTION Testing the Appearance of Styles>
+glk_style_distinguish
+glk_style_measure
+<SUBSECTION Constants>
+style_Normal
+style_Emphasized
+style_Preformatted
+style_Header
+style_Subheader
+style_Alert
+style_Note
+style_BlockQuote
+style_Input
+style_User1
+style_User2
+style_NUMSTYLES
+stylehint_Indentation
+stylehint_ParaIndentation
+stylehint_Justification
+stylehint_Size
+stylehint_Weight
+stylehint_Oblique
+stylehint_Proportional
+stylehint_TextColor
+stylehint_BackColor
+stylehint_ReverseColor
+stylehint_NUMHINTS
+stylehint_just_LeftFlush
+stylehint_just_LeftRight
+stylehint_just_Centered
+stylehint_just_RightFlush
+</SECTION>
+
+<SECTION>
+<FILE>glk-stream-types</FILE>
+<TITLE>The Types of Streams</TITLE>
+glk_stream_open_memory
+glk_stream_open_memory_uni
+glk_stream_open_file
+glk_stream_open_file_uni
+</SECTION>
+
+<SECTION>
+<FILE>glk-stream-other</FILE>
+<TITLE>Other Stream Functions</TITLE>
+glk_stream_iterate
+glk_stream_get_rock
+</SECTION>
+
+<SECTION>
+<FILE>glk-fileref</FILE>
+<TITLE>File References</TITLE>
+fileusage_Data
+fileusage_SavedGame
+fileusage_Transcript
+fileusage_InputRecord
+fileusage_TypeMask
+fileusage_TextMode
+fileusage_BinaryMode
+</SECTION>
+
+<SECTION>
+<FILE>glk-fileref-types</FILE>
+<TITLE>The Types of File References</TITLE>
+glk_fileref_create_temp
+glk_fileref_create_by_prompt
+glk_fileref_create_by_name
+glk_fileref_create_from_fileref
+</SECTION>
+
+<SECTION>
+<FILE>glk-fileref-other</FILE>
+<TITLE>Other File Reference Functions</TITLE>
+glk_fileref_destroy
+glk_fileref_iterate
+glk_fileref_get_rock
+glk_fileref_delete_file
+glk_fileref_does_file_exist
+</SECTION>
+
+<SECTION>
+<FILE>glk-image-resources</FILE>
+<TITLE>Image Resources</TITLE>
+glk_image_get_info
+glk_image_draw
+glk_image_draw_scaled
+</SECTION>
+
+<SECTION>
+<FILE>glk-graphics-windows</FILE>
+<TITLE>Graphics in Graphics Windows</TITLE>
+glk_window_set_background_color
+glk_window_fill_rect
+glk_window_erase_rect
+</SECTION>
+
+<SECTION>
+<FILE>glk-graphics-text</FILE>
+<TITLE>Graphics in Text Buffer Windows</TITLE>
+glk_window_flow_break
+<SUBSECTION Constants>
+imagealign_InlineUp
+imagealign_InlineDown
+imagealign_InlineCenter
+imagealign_MarginLeft
+imagealign_MarginRight
+</SECTION>
+
+<SECTION>
+<FILE>glk-graphics-testing</FILE>
+<TITLE>Testing for Graphics Capabilities</TITLE>
+GLK_MODULE_IMAGE
+</SECTION>
+
+<SECTION>
+<FILE>glk-sound-channels</FILE>
+<TITLE>Creating and Destroying Sound Channels</TITLE>
+glk_schannel_create
+glk_schannel_destroy
+</SECTION>
+
+<SECTION>
+<FILE>glk-playing-sounds</FILE>
+<TITLE>Playing Sounds</TITLE>
+glk_schannel_play
+glk_schannel_play_ext
+glk_schannel_stop
+glk_schannel_set_volume
+glk_sound_load_hint
+</SECTION>
+
+<SECTION>
+<FILE>glk-sound-other</FILE>
+<TITLE>Other Sound Channel Functions</TITLE>
+glk_schannel_iterate
+glk_schannel_get_rock
+</SECTION>
+
+<SECTION>
+<FILE>glk-sound-testing</FILE>
+<TITLE>Testing for Sound Capabilities</TITLE>
+GLK_MODULE_SOUND
+</SECTION>
+
+<SECTION>
+<FILE>glk-creating-hyperlinks</FILE>
+<TITLE>Creating Hyperlinks</TITLE>
+glk_set_hyperlink
+glk_set_hyperlink_stream
+</SECTION>
+
+<SECTION>
+<FILE>glk-accepting-hyperlinks</FILE>
+<TITLE>Accepting Hyperlink Events</TITLE>
+glk_request_hyperlink_event
+glk_cancel_hyperlink_event
+</SECTION>
+
+<SECTION>
+<FILE>glk-hyperlinks-testing</FILE>
+<TITLE>Testing for Hyperlink Capabilities</TITLE>
+GLK_MODULE_HYPERLINKS
+</SECTION>
+
diff --git a/docs/reference/chimara.types b/docs/reference/chimara.types
new file mode 100644 (file)
index 0000000..6d0bd57
--- /dev/null
@@ -0,0 +1 @@
+chimara_glk_get_type
diff --git a/docs/reference/glk-api-conventions.sgml b/docs/reference/glk-api-conventions.sgml
new file mode 100644 (file)
index 0000000..e796e52
--- /dev/null
@@ -0,0 +1,36 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="chimara-Other-API-Conventions">
+<refmeta>
+<refentrytitle>Other API Conventions</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Other API Conventions</refname>
+<refpurpose>General information about the Glk API</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+The <filename class="headerfile">glk.h</filename> header file is the same on all platforms, with the sole exception of the typedef of #glui32 and #glsi32. These will always be defined as 32-bit unsigned and signed integer types, which may be <quote><type>long</type></quote> or <quote><type>int</type></quote> or some other C definition.
+</para>
+<para>
+Note that all constants are &num;defines, and all functions are actual function declarations (as opposed to macros.)
+</para>
+<note><para>
+There are a few places where macros would be more efficient &mdash; glk_gestalt() and glk_gestalt_ext(), for example &mdash; but they are not likely to be CPU bottlenecks, and clarity seems more important.
+</para></note>
+<para>
+%FALSE is 0; %TRUE is 1. %NULL is also 0.
+</para>
+<para>
+As stated above, it is illegal to pass %NULL to a function which is expecting a valid object reference, unless the function definition says otherwise.
+</para>
+<para>
+Some functions have pointer arguments, acting as <quote>variable</quote> or <quote>reference</quote> arguments; the function's intent is to return some value in the space pointed to by the argument. Unless the function says otherwise, it is legal to pass a %NULL pointer to indicate that you do not care about that value.
+</para>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-character-encoding.sgml b/docs/reference/glk-character-encoding.sgml
new file mode 100644 (file)
index 0000000..dec86f6
--- /dev/null
@@ -0,0 +1,47 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="chimara-Character-Encoding">
+<refmeta>
+<refentrytitle>Character Encoding</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Character Encoding</refname>
+<refpurpose>Latin-1 and Unicode characters</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+Glk has two separate, but parallel, APIs for managing text input and output. The basic functions deal entirely in 8-bit characters; their arguments are arrays of bytes (octets). These functions all assume the Latin-1 character encoding. Equivalently, they may be said to use code points U+00..U+FF of <ulink url="http://unicode.org">Unicode</ulink>.
+</para>
+<para>
+Latin-1 is an 8-bit character encoding; it maps numeric codes in the range 0 to 255 into printed characters. The values from 32 to 126 are the standard printable ASCII characters (<code>' '</code> to <code>'~'</code>). Values 0 to 31 and 127 to 159 are reserved for control characters, and have no printed equivalent.
+</para>
+<note><para>
+Note that the basic Glk text API does not use UTF-8, or any other Unicode character form. Each character is represented by a single byte &mdash; even characters in the 128..255 range.
+</para></note>
+<para>
+The extended, or <quote>Unicode</quote>, Glk functions deal entirely in 32-bit words. They take arrays of words, not bytes, as arguments. They can therefore cope with any Unicode code point. The extended functions have names ending in <quote><code>_uni</code></quote>.
+</para>
+<note><para>
+Since these functions deal in arrays of 32-bit words, they can be said to use the UTF-32 character encoding form. (But <emphasis>not</emphasis> the UTF-32 character encoding <emphasis>scheme</emphasis> &mdash; that's a stream of bytes which must be interpreted in big-endian or little-endian mode. Glk Unicode functions operate on long integers, not bytes.) UTF-32 is also known as UCS-4, according to the Unicode spec (appendix C.2), modulo some semantic requirements which we will not deal with here. For practical purposes, we can ignore the whole encoding issue, and assume that we are dealing with sequences of numeric code points.
+</para></note>
+<note><para>
+Why not UTF-8? It is a reasonable bare-bones compression algorithm for Unicode character streams; but IF systems typically have their own compression models for text. Compositing the two ideas causes more problems than it solves. The other advantage of UTF-8 is that 7-bit ASCII is automatically valid UTF-8; but this is not compelling for IF systems, in which the compiler can be tasked with generating consistent textual data. And UTF-8 is a variable-width encoding. Nobody ever wept at the prospect of avoiding that kettle of eels.
+</para></note>
+<note>
+<para>
+What about bi-directional text? It's a good idea, and may show up in future versions of this document. It is not in this version because we want to get something simple implemented soon. For the moment, print out all text in reading order (not necessarily left-to-right) and hope for the best. Current suggestions include a <code>stylehint_Direction</code>, which the game can set to indicate that text in the given style should be laid out right-to-left. Top-to-bottom (or bottom-to-top) may be desirable too. The direction stylehints might only apply to full paragraphs (like justification stylehints); or they might apply to any text, thus requiring the library to lay out <quote>zig-zag</quote> blocks. The possibilities remain to be explored. Page layout is hard.
+</para>
+<para>
+Another possibility is to let the library determine the directionality of text from the character set. This is not impossible &mdash; MacOSX text widgets do it. It may be too difficult.
+</para>
+<para>
+In the meantime, it is worth noting that the Windows Glk library does not autodetect directionality, but the CheapGlk library running on MacOSX does. Therefore, there is no platform-independent way to handle right-to-left fonts at present.
+</para>
+</note>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-display-style.sgml b/docs/reference/glk-display-style.sgml
new file mode 100644 (file)
index 0000000..d119c24
--- /dev/null
@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="chimara-A-Note-on-Display-Style">
+<refmeta>
+<refentrytitle>A Note on Display Style</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>A Note on Display Style</refname>
+<refpurpose>How windows may be displayed on different platforms</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+The way windows are displayed is, of course, entirely up to the Glk library; it depends on what is natural for the player's machine. The borders between windows may be black lines, 3-D bars, rows of <quote><computeroutput>&num;</computeroutput></quote> characters; there may even be no borders at all. 
+</para>
+<note><para>
+This is an important possibility to keep in mind.
+</para></note>
+<para>
+There may be other decorations as well. A text buffer window will often have a scroll bar. The library (or player) may prefer wide margins around each text window. And so on.
+</para>
+<para>
+The library is reponsible for handling these decorations, margins, spaces, and borders. You should never worry about them. You are guaranteed that if you request a fixed size of two rows, your text grid window will have room for two rows of characters &mdash; if there is enough total space. Any margins or borders will be allowed for already. If there <emphasis>isn't</emphasis> enough total space (as in stages 4 and 5 of <link linkend="chimara-Figure-Squeezing-Window">this figure</link>), you lose, of course.
+</para>
+<para>
+How do you know when you're losing? You can call glk_window_get_size() to determine the window size you really got. Obviously, you should draw into your windows based on their real size, not the size you requested. If there's enough space, the requested size and the real size will be identical; but you should not rely on this. Call glk_window_get_size() and check.
+</para>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-front-matter.sgml b/docs/reference/glk-front-matter.sgml
new file mode 100644 (file)
index 0000000..2abdbc2
--- /dev/null
@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<referenceinfo>
+<title>Glk API Specification</title>
+<subtitle>API version 0.7.0</subtitle>
+<author>
+  <personname>
+    <firstname>Andrew</firstname>
+    <surname>Plotkin</surname>
+  </personname>
+  <email>erkyrath@eblong.com</email>
+</author>
+<copyright>
+  <year>1998&ndash;2004</year>
+  <holder>Andrew Plotkin</holder>
+</copyright>
+<legalnotice>
+You have permission to display, download, and print this document, provided that you do so for personal, non-commercial use only. You may not modify or distribute this document without the author's written permission.
+</legalnotice>
+<releaseinfo>
+The authors of the Chimara library have adapted this document to better fit the format of a GtkDoc reference manual. They have also added notes specific to Chimara's implementation of the Glk API. The original API specification and further Glk information can be found at: <ulink url="http://www.eblong.com/zarf/glk/">http://www.eblong.com/zarf/glk/</ulink>
+</releaseinfo>
+</referenceinfo>
diff --git a/docs/reference/glk-introduction.sgml b/docs/reference/glk-introduction.sgml
new file mode 100644 (file)
index 0000000..d7c317b
--- /dev/null
@@ -0,0 +1,106 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter id="chimara-Introduction"><title>Introduction</title>
+<sect1 id="chimara-What-Glk-Is"><title>What Glk Is</title>
+<para>
+Glk is an attempt to define a portable API (programming interface) for applications with text UIs (user interfaces.)
+</para>
+<para>
+Rather than go into a detailed explanation of what that means, let me give examples from the world of text adventures. TADS and Infocom's Z-machine have nearly identical interface capabilities; each allows a program to...
+<itemizedlist>
+       <listitem><para>print an indefinite stream of text into an output buffer, with some style control</para></listitem>
+       <listitem><para>input a line of text</para></listitem>
+       <listitem><para>display a few lines of text in a small separate window</para></listitem>
+       <listitem><para>store information in a file, or read it in</para></listitem>
+</itemizedlist>
+and so on. However, the implementation of these capabilities vary widely between platforms and operating systems. Furthermore, this variance is transparent to the program (the adventure game.) The game does not care whether output is displayed via a character terminal emulator or a GUI window; nor whether input uses Mac-style mouse editing or EMACS-style control key editing.
+</para>
+<para>
+On the third hand, the user is likely to care deeply about these interface decisions. This is why there are Mac-native interpreters on Macintoshes, pen-controlled interpreters on Newtons and PalmOS PDAs, and so on &mdash; and (ultimately) why there Macintoshes and Palms and X-windows platforms in the first place.
+</para>
+<para>
+On the <emphasis>fourth</emphasis> hand, TADS and Inform are not alone; there is historically a large number of text adventure systems. Most are obsolete or effectively dead; but it is inevitable that more will appear. Users want each living system ported to all the platforms in use. Users also prefer these ports to use the same interface, as much as possible.
+</para>
+<para>
+This all adds up to a pain in the ass.
+</para>
+<para>
+Glk tries to draw a line between the parts of the text adventure world which are identical on all IF systems, and different on different operating systems, from the parts which are unique to each IF system but identical in all OSs. The border between these two worlds is the Glk API.
+</para>
+<para>
+My hope is that a new IF system, or existing ones which are less-supported (Hugo, AGT, etc) can be written using Glk for all input and output function. The IF system would then be in <emphasis>truly</emphasis> portable C. On the other side of the line, there would be a Glk library for each operating system and interface (Macintosh, X-windows, curses-terminal, etc.) Porting the IF system to every platform would be trivial; compile the system, and link in the library.
+</para>
+<para>
+Glk can also serve as a nice interface for applications other than games &mdash; data manglers, quick hacks, or anything else which would normally lack niceties such as editable input, macros, scrolling, or whatever is native to your machine's interface idiom.
+</para>
+</sect1>
+<sect1 id="chimara-What-About-the-Virtual-Machine"><title>What About the Virtual Machine?</title>
+<para>
+You can think of Glk as an IF virtual machine, without the virtual machine part. The <quote>machine</quote> is just portable C code.
+</para>
+<para>
+An IF virtual machine has been designed specifically to go along with Glk. This VM, called Glulx, uses Glk as its interface; each Glk call corresponds to an input/output opcode of the VM.
+</para>
+<para>
+For more discussion of this approach, see <link linkend="chimara-Glk-and-the-Virtual-Machine">Glk and the Virtual Machine</link>. Glulx is documented at <ulink url="http://www.eblong.com/zarf/glulx/">http://www.eblong.com/zarf/glulx</ulink>.
+</para>
+<para>
+Of course, Glk can be used with other IF systems. The advantage of Glulx is that it provides the game author with direct and complete access to the Glk API. Other IF systems typically have an built-in abstract I/O API, which maps only partially onto Glk. For these systems, Glk tends to be a least-common-denominator interface: highly portable, but not necessarily featureful. (Even if Glk has a feature, it may not be available through the layers of abstraction.) 
+</para>
+</sect1>
+<sect1 id="chimara-What-Does-Glk-Not-Do"><title>What Does Glk Not Do?</title>
+<para>
+Glk does not handle the things which should be handled by the program (or the IF system, or the virtual machine) which is linked to Glk. This means that Glk does not address
+<itemizedlist>
+       <listitem><para>parsing</para></listitem>
+       <listitem><para>game object storage</para></listitem>
+       <listitem><para>computation</para></listitem>
+       <listitem><para>text compression</para></listitem>
+</itemizedlist>
+</para>
+</sect1>
+<sect1 id="chimara-Conventions-of-This-Document"><title>Conventions of This Document</title>
+<para>
+This document defines the Glk API. I have tried to specify exactly what everything does, what is legal, what is illegal, and why.
+</para>
+<note><para>
+Sections labeled like this are notes. They do not define anything; they clarify or explain what has already been defined. If there seems to be a conflict, ignore the note and follow the definition.
+</para></note>
+<note><title>WORK</title>
+<para>
+Notes with the label <quote>WORK</quote> are things which I have not yet fully resolved. Your comments requested and welcome.
+</para></note>
+<note><title>Chimara</title>
+<para>
+Notes labeled <quote>Chimara</quote> are specific to Chimara's implementation of the Glk API and are not part of the original Glk API specification.
+</para></note>
+<para>
+This document is written for the point of view of the game programmer &mdash; the person who wants to use the Glk library to print text, input text, and so on. By saying what the Glk library does, of course, this document also defines the task of the Glk programmer &mdash; the person who wants to port the Glk library to a new platform or operating system. If the Glk library guarantees something, the game programmer can rely on it, and the Glk programmer is required to support it. Contrariwise, if the library does not guarantee something, the Glk programmer may handle it however he likes, and the game programmer must not rely on it. If something is illegal, the game programmer must not do it, and the Glk programmer is not required to worry about it. 
+</para>
+<note><para>
+It is preferable, but not required, that the Glk library detect illegal requests and display error messages. The Glk library may simply crash when the game program does something illegal. This is why the game programmer must not do it. Right?
+</para></note>
+<note><title>Chimara</title>
+<para>
+Wherever possible, Chimara checks for anything defined as illegal, and prints a
+warning message to standard error. It tries to recover as gracefully as possible
+so that the program can continue.
+</para></note>
+<para>
+Hereafter, <quote>Glk</quote> or <quote>the library</quote> refers to the Glk library, and <quote>the program</quote> is the game program (or whatever) which is using the Glk library to print text, input text, or whatever. <quote>You</quote> are the person writing the program. <quote>The player</quote> is the person who will use the program/Glk library combination to actually play a game. Or whatever.
+</para>
+<para>
+The Glk API is declared in a C header file called <quote><filename class="headerfile">glk.h</filename></quote>. Please refer to that file when reading this one. 
+</para>
+</sect1>
+<sect1 id="chimara-Credits"><title>Credits</title>
+<para>
+Glk has been a work of many years and many people. If I tried to list everyone who has offered comments and suggestions, I would immediately go blank, forget everyone's name, and become a mute hermit-like creature living in a train tunnel under Oakland. But I must thank those people who have written Glk libraries and linking systems: Matt Kimball, Ross Raszewski, David Kinder, John Elliott, Joe Mason, Stark Springs, and, er, anyone I missed. Look! A train!
+</para>
+<para>
+Evin Robertson wrote the original proposal for the Glk Unicode functions, which I imported nearly verbatim into this document. Thank you.
+</para>
+</sect1>
+</chapter>
diff --git a/docs/reference/glk-line-input.sgml b/docs/reference/glk-line-input.sgml
new file mode 100644 (file)
index 0000000..f88692c
--- /dev/null
@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="chimara-Line-Input">
+<refmeta>
+<refentrytitle>Line Input</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Line Input</refname>
+<refpurpose>Reading lines of text</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+You can request that the player enter a line of text. See <link linkend="chimara-Line-Input-Events">Line Input Events</link>.
+</para>
+<para>
+This text will be placed in a buffer of your choice. There is no length field or null terminator in the buffer. (The length of the text is returned as part of the line-input event.)
+</para>
+<para>
+If you use the basic text API, the buffer will contain only printable Latin-1 characters (32 to 126, 160 to 255).
+</para>
+<para>
+A particular implementation of Glk may not be able to accept all Latin-1 printable characters as input. It is guaranteed to be able to accept the ASCII characters (32 to 126.)
+</para>
+<para>
+You can test for this by using the #gestalt_LineInput selector.
+</para>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-main-function.sgml b/docs/reference/glk-main-function.sgml
new file mode 100644 (file)
index 0000000..e6f33e7
--- /dev/null
@@ -0,0 +1,69 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="chimara-Your-Programs-Main-Function">
+<refmeta>
+<refentrytitle>Your Program's Main Function</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Your Program's Main Function</refname>
+<refpurpose>How Glk starts your program</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+The top level of the program &mdash; the <function>main()</function> function in C, for example &mdash; belongs to Glk.
+</para>
+<note><para>
+This means that Glk isn't really a library. In a sense, you are writing a library, which is linked into Glk. This is bizarre to think about, so forget it.
+</para></note>
+<note><title>Chimara</title>
+<para>
+In Chimara, the arrangement is even more bizarre. Chimara <emphasis>is</emphasis> a library, and it runs your Glk program from within a GTK+ graphical application (the <quote>host program</quote>). Chimara treats your program as a plugin, or shared library, and it executes your program in its own thread, displaying windows and output in the GTK+ program.
+</para>
+<para>
+This makes absolutely no difference to you, the Glk <emphasis>programmer</emphasis>; if your program works correctly with a <quote>regular</quote> Glk library, it will also work properly with Chimara. The only difference is in compiling your Glk program.
+</para></note>
+<para>
+You define a function called glk_main(), which the library calls to begin running your program. glk_main() should run until your program is finished, and then return.
+</para>
+<para>
+Glk does all its user-interface work in a function called glk_select(). This function waits for an event &mdash; typically the player's input &mdash; and returns an structure representing that event. This means that your program must have an event loop. In the very simplest case, you could write
+</para>
+<informalexample>
+<programlisting>
+void glk_main()
+{
+    #event_t ev;
+    while (1) {
+        #glk_select(&amp;ev);
+        switch (ev.type) {
+            default:
+                /* do nothing */
+                break;
+        }
+    }
+}
+</programlisting>
+</informalexample>
+<para>
+This is a legal Glk-compatible program. As you might expect, it doesn't do anything. The player will see an empty window, which he can only stare at, or destroy in a platform-defined standard manner.
+</para>
+<note><para>
+<keycombo action="simul"><keycap function="command">Command</keycap><keycap>period</keycap></keycombo> on the Macintosh; a <guimenuitem>kill-window</guimenuitem> menu option in an X window manager; <keycombo action="simul"><keycap function="control">control</keycap><keycap>C</keycap></keycombo> in a curses terminal window.
+</para></note>
+<note><title>Chimara</title>
+<para>
+In Chimara, there is no standard way; the program will stop when the host program calls chimara_glk_stop(). The host program might have a <quote>Stop</quote> button which does this, for example, but it will also generally happen when the #ChimaraGlk widget is destroyed or when the host program ends.
+</para></note>
+<note><para>
+However, this program does not spin wildly and burn CPU time. The glk_select() function waits for an event it can return. Since it only returns events which you have requested, it will wait forever, and grant CPU time to other processes if that's meaningful on the player's machine.
+</para></note>
+<note><para>
+Actually, there are some events which are always reported. More may be defined in future versions of the Glk API. This is why the default response to an event is to do nothing. If you don't recognize the event, ignore it.
+</para></note>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-other-events.sgml b/docs/reference/glk-other-events.sgml
new file mode 100644 (file)
index 0000000..b60a33f
--- /dev/null
@@ -0,0 +1,46 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="chimara-Other-Events">
+<refmeta>
+<refentrytitle>Other Events</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Other Events</refname>
+<refpurpose>Events in future versions of Glk</refpurpose>
+</refnamediv>
+<refsect1>
+<para>
+There are currently no other event types defined by Glk. (The <quote>#evtype_None</quote> constant is a placeholder, and is never returned by glk_select().)
+</para>
+<para>
+It is possible that new event types will be defined in the future. 
+</para>
+<note><para>For example, if video or animation capabilities are added to Glk, there would probably be some sort of completion event for them.
+</para></note>
+<note><para>
+This is also why you must put calls to glk_select() in loops. If you tried to read a character by simply writing
+<informalexample><programlisting>
+#glk_request_char_event(win);
+#glk_select(&amp;ev);
+</programlisting></informalexample>
+you might not get a CharInput event back. You could get some not-yet-defined event which happened to occur before the player hit a key. Or, for that matter, a window arrangement event.
+</para></note>
+<note><para>
+It is not generally necessary to put a call to glk_select_poll() in a loop. You usually call glk_select_poll() to update the display or test if an event is available, not to wait for a particular event. However, if you are using sound notification events, and several sounds are playing, it might be important to make sure you knew about all sounds completed at any particular time. You would do this with
+<informalexample><programlisting>
+#glk_select_poll(&amp;ev);
+while (ev.type != #evtype_None) {
+    /* handle event */
+    #glk_select_poll(&amp;ev);
+}
+</programlisting></informalexample>
+</para>
+<para>
+Once glk_select_poll() returns #evtype_None, you should not call it again immediately. Do some work first. If you want to wait for an event, use glk_select(), not a loop of glk_select_poll().
+</para></note>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-output.sgml b/docs/reference/glk-output.sgml
new file mode 100644 (file)
index 0000000..c0d8a5d
--- /dev/null
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="chimara-Output">
+<refmeta>
+<refentrytitle>Output</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Output</refname>
+<refpurpose>Printing basics</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+When you are sending text to a window, or to a file open in text mode, you can print any of the printable Latin-1 characters: 32 to 126, 160 to 255. You can also print the newline character (linefeed, <keycombo action="simul"><keycap function="control">control</keycap><keycap>J</keycap></keycombo>, decimal 10, hex 0x0A.)
+</para>
+<para>
+It is <emphasis>not</emphasis> legal to print any other control characters (0 to 9, 11 to 31, 127 to 159). You may not print even common formatting characters such as tab (<keycombo action="simul"><keycap function="control">control</keycap><keycap>I</keycap></keycombo>), carriage return (<keycombo action="simul"><keycap function="control">control</keycap><keycap>M</keycap></keycombo>), or page break (<keycombo action="simul"><keycap function="control">control</keycap><keycap>L</keycap></keycombo>).
+</para>
+<note><para>
+As usual, the behavior of the library when you print an illegal character is undefined. It is preferable that the library display a numeric code, such as <quote><computeroutput>\177</computeroutput></quote> or <quote><computeroutput>0x7F</computeroutput></quote>, to warn the user that something illegal has occurred. The library may skip illegal characters entirely; but you should not rely on this.
+</para></note>
+<para>
+Printing Unicode characters above 255 is a more complicated matter &mdash; too complicated to be covered precisely by this specification. Refer to the Unicode specification, and good luck to you.
+</para>
+<note><para>
+Unicode combining characters are a particular nuisance. Printing a combining character may alter the appearance of the previous character printed. The library should be prepared to cope with this &mdash; even if the characters are printed by two separate glk_put_char_uni() calls.
+</para></note>
+<para>
+Note that when you are sending data to a file open in binary mode, you can print any byte value, without restriction. See <link linkend="chimara-File-Streams">File Streams</link>.
+</para>
+<para>
+A particular implementation of Glk may not be able to display all the printable characters. It is guaranteed to be able to display the ASCII characters (32 to 126, and the newline 10.) Other characters may be printed correctly, printed as multi-character combinations (such as <quote><computeroutput>ae</computeroutput></quote> for the <quote>&aelig;</quote> ligature), or printed as some placeholder character (such as a bullet or question mark, or even an octal code.) You can test for this using #gestalt_CharOutput.
+</para>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-window-arrangement.sgml b/docs/reference/glk-window-arrangement.sgml
new file mode 100644 (file)
index 0000000..9926d81
--- /dev/null
@@ -0,0 +1,73 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<refentry id="chimara-Window-Arrangement">
+<refmeta>
+<refentrytitle>Window Arrangement</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Window Arrangement</refname>
+<refpurpose>The Way of Window Arrangement</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+The Way of Window Arrangement is fairly complicated. I'll try to explain it coherently.
+</para>
+<note><para>If you are reading this document to get an overview of Glk, by all means skip forward to <link linkend="chimara-The-Types-of-Windows">The Types of Windows</link>. Come back here later.
+</para></note>
+<para>
+Originally, there are no windows. You can create a window, which will take up the entire available screen area. You can then split this window in two. One of the halves is the original window; the other half is new, and can be of any type you want. You can control whether the new window is left, right, above, or below the original one. You can also control how the split occurs. It can be 50-50, or 70-30, or any other percentage split. Or, you can give a fixed width to the new window, and allow the old one to take up the rest of the available space. Or you can give a fixed width to the old window, and let the new one take up the rest of the space.
+</para>
+<para>
+Now you have two windows. In exactly the same way, you can split either of them &mdash; the original window, or the one you just created. Whichever one you split becomes two, which together take up the same space that the one did before.
+</para>
+<para>
+You can repeat this as often as you want. Every time you split a window, one new window is created. Therefore, the call that does this is called glk_window_open().
+</para>
+<note><para>
+It might have been less confusing to call it <quote>glk_split_window()</quote> &mdash; or it might have been more confusing. I picked one.
+</para></note>
+<para>
+It is important to remember that the order of splitting matters. If you split twice, you don't have a trio of windows; you have a pair with another pair on one side. Mathematically, the window structure is a binary tree.
+</para>
+<para>
+Example time. Say you do two splits, each a 50-50 percentage split. You start with the original window A, and split that into A and B; then you split B into B and C.
+<mediaobject><textobject><phrase>Screen shot 1</phrase></textobject></mediaobject>
+Or, you could split A into A and B, and then split A again into A and C.
+<mediaobject><textobject><phrase>Screen shot 2</phrase></textobject></mediaobject>
+I'm using the simplest possible splits in the examples above. Every split is 50-50, and the new window of the pair is always below the original one (the one that gets split.) You can get fancier than that. Here are three more ways to perform the first example; all of them have the same tree structure, but look different on the screen.
+<mediaobject><textobject><phrase>Screen shot 3</phrase></textobject></mediaobject>
+On the left, we turn the second split (B into B/C) upside down; we put the new window (C) above the old window (B).
+</para>
+<para>
+In the center, we mess with the percentages. The first split (A into A/B) is a 25-75 split, which makes B three times the size of A. The second (B into B/C) is a 33-66 split, which makes C twice the size of B. This looks rather like the second example above, but has a different internal structure.
+</para>
+<para>
+On the right, the second split (B into B/C) is vertical instead of horizontal, with the new window (C) on the left of the old one.
+</para>
+<para>
+The visible windows on the Glk screen are <quote>leaf nodes</quote> of the binary tree; they hang off the ends of the branches in the diagram. There are also the <quote>internal nodes</quote>, the ones at the forks, which are marked as <quote>O</quote>. These are the mysterious pair windows.
+</para>
+<para>
+You don't create pair windows directly; they are created as a consequence of window splits. Whenever you create a new window, a new pair window is also created automatically. In the following two-split process, you can see that when a window is split, it is replaced by a new pair window, and moves down to become one of that <quote>O</quote>'s two children.
+<mediaobject><textobject><phrase>Screen shot 4</phrase></textobject></mediaobject>
+</para>
+<para>
+You can't draw into a pair window. It's completely filled up with the two windows it contains. They're what you should be drawing into.
+</para>
+<para>
+Why have pair windows in the system at all? They're convenient for certain operations. For example, you can close any window at any time; but sometimes you want to close an entire nest of windows at once. In the third stage shown, if you close the lower pair window, it blows away all its descendents &mdash; both B and C &mdash; and leaves just a single window, A, which is what you started with.
+</para>
+<para>
+I'm using some math terminology already, so I'll explain it briefly. The <quote>root</quote> of the tree is the top (math trees, like family trees, grow upside down.) If there's only one window, it's the root; otherwise the root is the topmost <quote>O</quote>. Every pair window has exactly two <quote>children</quote>. Other kinds of windows are leaves on the tree, and have no children. A window's <quote>descendants</quote>, obviously, are its children and grandchildren and great-grandchildren and so on. The <quote>parent</quote> and <quote>ancestors</quote> of a window are exactly what you'd expect. So the root window is the ancestor of every other window.
+</para>
+<para>
+There are Glk functions to determine the root window, and to determine the parent of any given window. Note that every window's parent is a pair window. (Except for the root window, which has no parent.)
+</para>
+</refsect1>
+</refentry>
diff --git a/docs/reference/glk-windows.sgml b/docs/reference/glk-windows.sgml
new file mode 100644 (file)
index 0000000..60f3615
--- /dev/null
@@ -0,0 +1,94 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<refentry id="chimara-Windows">
+<refmeta>
+<refentrytitle>Windows</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>CHIMARA Library</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Windows</refname>
+<refpurpose>Introduction to Glk windows</refpurpose>
+</refnamediv>
+<refsect1>
+<title>Description</title>
+<para>
+On most platforms, the program/library combination will appear to the player in a window &mdash; either a window which covers the entire screen, or one which shares screen space with other windows in a multi-programming environment. Obviously your program does not have worry about the details of this. The Glk screen space is a rectangle, which you can divide into panels for various purposes. It is these panels which I will refer to as <quote>windows</quote> hereafter.
+</para>
+<para>
+You refer to a window using an opaque C structure pointer. See <link linkend="chimara-Opaque-Objects">Opaque Objects</link>.
+</para>
+<para>
+A window has a type. Currently there are four window types:
+<variablelist>
+<varlistentry>
+       <term>Text buffer windows</term>
+       <listitem><para>
+       A stream of text.
+       </para>
+       <note><para>The <quote>story window</quote> of an Infocom game.
+       </para></note>
+       <para>
+       You can only print at the end of the stream, and input a line of text at the end of the stream.
+       </para></listitem>
+</varlistentry>
+<varlistentry>
+       <term>Text grid windows</term>
+       <listitem><para>
+       A grid of characters in a fixed-width font.
+       </para>
+       <note><para>The <quote>status window</quote> of an Infocom game.
+       </para></note>
+       <para>
+       You can print anywhere in the grid.
+       </para></listitem>
+</varlistentry>
+<varlistentry>
+       <term>Graphics windows</term>
+       <listitem><para>
+       A grid of colored pixels. Graphics windows do not support text input or output, but there are image commands to draw in them.
+       </para>
+       <note><para>This is an optional capability; not all Glk libraries support graphics. See <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics Capabilities</link>.
+       </para></note></listitem>
+</varlistentry>
+<varlistentry>
+       <term>Blank windows</term>
+       <listitem><para>A blank window. Blank windows support neither input nor output.
+       </para>
+       <note><para>They exist mostly to be an example of a <quote>generic</quote> window. You are unlikely to want to use them.
+       </para></note></listitem>
+</varlistentry>
+</variablelist>
+</para>
+<para>
+As Glk is an expanding system, more window types may be added in the future. Therefore, it is important to remember that not all window types will necessarily be available under all Glk libraries.
+</para>
+<para>
+There is one other special type of window, the pair window. Pair windows are created by Glk as part of the system of window arrangement. You cannot create them yourself. See <link linkend="wintype-Pair">Pair Windows</link>.
+</para>
+<para>
+Every window has a rock. This is a value you provide when the window is created; you can use it however you want. See <link linkend="chimara-Rocks">Rocks</link>.
+</para>
+<para>
+When Glk starts up, there are no windows.
+</para>
+<note><para>
+When I say there are no windows, I mean there are no Glk windows. In a multiprogramming environment, such as X or MacOS, there may be an application window visible; this is the screen space that will contain all the Glk windows that you create. But at first, this screen space is empty and unused.
+</para></note>
+<para>
+Without a window, you cannot do any kind of input or output; so the first thing you'll want to do is create one. See <link linkend="chimara-Window-Opening-Closing-and-Constraints">Window Opening, Closing, and Constraints</link>.
+</para>
+<para>
+You can create as many windows as you want, of any types. You control their arrangement and sizes through a fairly flexible system of calls. See <link linkend="chimara-Window-Arrangement">Window Arrangement</link>.
+</para>
+<para>
+You can close any windows you want. You can even close all the windows, which returns you to the original startup state.
+</para>
+<para>
+You can request input from any or all windows. Input can be mouse input (on platforms which support a mouse), single-character input, or input of an entire line of text. It is legal to request input from several windows at the same time. The library will have some interface mechanism for the player to control which window he is typing in.
+</para>
+</refsect1>
+</refentry>
diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in
new file mode 100644 (file)
index 0000000..a24f987
--- /dev/null
@@ -0,0 +1 @@
+@PACKAGE_VERSION@
diff --git a/po/.ignore b/po/.ignore
deleted file mode 100755 (executable)
index e69b061..0000000
+++ /dev/null
@@ -1,23 +0,0 @@
-.libs
-.deps
-.*swp
-.nautilus-metafile.xml
-*.autosave
-*.gmo
-*.mo
-*.pot
-*~
-#*#
-*.bak
-*.o
-*.lo
-*.la
-cat-id-tbl.c
-stamp-cat-id
-messages
-missing
-POTFILES
-Makefile
-Makefile.in
-Makefile.in.in
-translations.xml
index e34db8b40e4436a336126f7fcf7b6025a3778580..b50428730353754d30dcafb443c6612934615fa0 100644 (file)
@@ -37,11 +37,11 @@ libchimara_la_SOURCES = \
        window.c window.h 
 
 libchimara_la_LIBADD = @CHIMARA_LIBS@
-libchimara_la_LDFLAGS = -no-undefined -export-symbols-regex "^chimara_glk_.*|^glk_.*"
+libchimara_la_LDFLAGS = -no-undefined -export-symbols-regex "^chimara_glk_|^glk_"
 libchimara_includedir = $(includedir)/chimara/chimara
 libchimara_include_HEADERS = chimara-glk.h
 
-PLUGIN_LDFLAGS = -module -shared -avoid-version -export-symbols-regex "glk_main"
+PLUGIN_LDFLAGS = -module -shared -avoid-version -export-symbols-regex "^glk_main$$"
 pkglib_LTLIBRARIES = first.la model.la gridtest.la splittest.la
 first_la_SOURCES = first.c
 first_la_LDFLAGS = $(PLUGIN_LDFLAGS)
index 4580c0f6ad82d8ce6b7037046bccdefef857c26a..4ae157addacc1eeed2b0ac92710c2d04cc8a446e 100644 (file)
@@ -8,14 +8,15 @@ extern ChimaraGlkPrivate *glk_data;
 
 /**
  * glk_set_interrupt_handler:
- * @func: A pointer to a function which takes no argument and returns no result.
+ * @func: A pointer to an interrupt handler function.
  *
- * Specifies an interrupt handler function for cleaning up critical resources.
- * If Glk receives an interrupt, and you have set an interrupt handler, your
- * handler will be called, before the process is shut down.
+ * Sets @func to be the interrupt handler. @func should be a pointer to a 
+ * function which takes no argument and returns no result. If Glk receives an
+ * interrupt, and you have set an interrupt handler, your handler will be 
+ * called, before the process is shut down.
  * 
  * Initially there is no interrupt handler. You can reset to not having any by
- * calling glk_set_interrupt_handler(%NULL).
+ * calling <code>#glk_set_interrupt_handler(%NULL)</code>.
  * 
  * If you call glk_set_interrupt_handler() with a new handler function while an
  * older one is set, the new one replaces the old one. Glk does not try to queue
index 9e73de10240413aa315dae16a94e27c8887ab89c..47086e15ba9e92d19a386ef575f74ef26dd97bd9 100644 (file)
@@ -5,8 +5,21 @@
  * glk_char_to_lower:
  * @ch: A Latin-1 character.
  *
- * If @ch is an uppercase character in the Latin-1 character set, converts it
- * to lowercase. Otherwise, leaves it unchanged.
+ * You can convert Latin-1 characters between upper and lower case with two Glk
+ * utility functions, glk_char_to_lower() and glk_char_to_upper(). These have a
+ * few advantages over the standard ANSI <function>tolower()</function> and
+ * <function>toupper()</function> macros. They work for the entire Latin-1
+ * character set, including accented letters; they behave consistently on all
+ * platforms, since they're part of the Glk library; and they are safe for all
+ * characters. That is, if you call glk_char_to_lower() on a lower-case
+ * character, or a character which is not a letter, you'll get the argument
+ * back unchanged.
+ * 
+ * The case-sensitive characters in Latin-1 are the ranges 0x41..0x5A,
+ * 0xC0..0xD6, 0xD8..0xDE (upper case) and the ranges 0x61..0x7A, 0xE0..0xF6,
+ * 0xF8..0xFE (lower case). These are arranged in parallel; so 
+ * glk_char_to_lower() will add 0x20 to values in the upper-case ranges, and
+ * glk_char_to_upper() will subtract 0x20 from values in the lower-case ranges. 
  *
  * Returns: A lowercase or non-letter Latin-1 character.
  */
@@ -23,7 +36,7 @@ glk_char_to_lower(unsigned char ch)
  * @ch: A Latin-1 character.
  *
  * If @ch is a lowercase character in the Latin-1 character set, converts it to
- * uppercase. Otherwise, leaves it unchanged.
+ * uppercase. Otherwise, leaves it unchanged. See glk_char_to_lower().
  *
  * Returns: An uppercase or non-letter Latin-1 character.
  */
@@ -41,18 +54,39 @@ glk_char_to_upper(unsigned char ch)
  * @len: Available length of @buf.
  * @numchars: Number of characters in @buf.
  *
- * Converts the first @numchars characters of @buf to their lowercase 
- * equivalents, if there is such a thing. These functions provide two length
- * arguments because a string of Unicode characters may expand when its case
- * changes. The @len argument is the available length of the buffer; @numchars
- * is the number of characters in the buffer initially. (So @numchars must be
- * less than or equal to @len. The contents of the buffer after @numchars do
- * not affect the operation.)
+ * Unicode character conversion is trickier, and must be applied to character
+ * arrays, not single characters. These functions 
+ * (glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(), and
+ * glk_buffer_to_title_case_uni()) provide two length arguments because a
+ * string of Unicode characters may expand when its case changes. The @len
+ * argument is the available length of the buffer; @numchars is the number of
+ * characters in the buffer initially. (So @numchars must be less than or equal
+ * to @len. The contents of the buffer after @numchars do not affect the
+ * operation.)
  *
- * Returns: The number of characters after conversion. If this is greater than
- * @len, the characters in the array will be safely truncated at len, but the
- * true count will be returned. (The contents of the buffer after the returned
- * count are undefined.)
+ * The functions return the number of characters after conversion. If this is
+ * greater than @len, the characters in the array will be safely truncated at
+ * @len, but the true count will be returned. (The contents of the buffer after
+ * the returned count are undefined.)
+ *
+ * The <code>lower_case</code> and <code>upper_case</code> functions do what
+ * you'd expect: they convert every character in the buffer (the first @numchars
+ * of them) to its upper or lower-case equivalent, if there is such a thing.
+ * 
+ * See the Unicode spec (chapter 3.13, chapter 4.2, etc) for the exact
+ * definitions of upper, lower, and title-case mapping.
+ * 
+ * <note><para>
+ *   Unicode has some strange case cases. For example, a combined character
+ *   that looks like <quote>ss</quote> might properly be upper-cased into 
+ *   <emphasis>two</emphasis> characters <quote>S</quote>. Title-casing is even
+ *   stranger; <quote>ss</quote> (at the beginning of a word) might be 
+ *   title-cased into a different combined character that looks like 
+ *   <quote>Ss</quote>. The glk_buffer_to_title_case_uni() function is actually
+ *   title-casing the first character of the buffer. If it makes a difference.
+ * </para></note>
+ *
+ * Returns: The number of characters after conversion.
  */
 glui32
 glk_buffer_to_lower_case_uni(glui32 *buf, glui32 len, glui32 numchars)
@@ -105,10 +139,19 @@ glk_buffer_to_upper_case_uni(glui32 *buf, glui32 len, glui32 numchars)
  * @lowerrest: %TRUE if the rest of @buf should be lowercased, %FALSE 
  * otherwise.
  *
- * Converts the first character of @buf to uppercase, if there is such a thing.
- * See glk_buffer_to_lower_case_uni(). If @lowerrest is %TRUE, then the
- * remainder of @buf is lowercased.
+ * See glk_buffer_to_lower_case_uni(). The <code>title_case</code> function has
+ * an additional (boolean) flag. Its basic function is to change the first
+ * character of the buffer to upper-case, and leave the rest of the buffer
+ * unchanged. If @lowerrest is true, it changes all the non-first characters to
+ * lower-case (instead of leaving them alone.) 
  *
+ * <note><para>
+ *   Earlier drafts of this spec had a separate function which title-cased the
+ *   first character of every <emphasis>word</emphasis> in the buffer. I took
+ *   this out after reading Unicode Standard Annex &num;29, which explains how
+ *   to divide a string into words. If you want it, feel free to implement it.
+ * </para></note>
+ * 
  * Returns: The number of characters after conversion.
  */
 glui32
index dea8999a211fb1029ff66a8e5e5f0290299a0d3d..9395b40a46f38fc903cd914f73834aef43098a03 100644 (file)
@@ -46,4 +46,4 @@ struct _ChimaraGlkPrivate {
        
 G_END_DECLS
 
-#endif /* __CHIMARA_GLK_PRIVATE_H__ */
\ No newline at end of file
+#endif /* __CHIMARA_GLK_PRIVATE_H__ */
index 5a62517a584a0378e278e2407030b808ca98e4e4..4bc1c156bc83f6e75148faa3876460f5b8934416 100644 (file)
 #define CHIMARA_GLK_MIN_WIDTH 0
 #define CHIMARA_GLK_MIN_HEIGHT 0
 
+/**
+ * SECTION:chimara-glk
+ * @short_description: Widget which executes a Glk program
+ * @stability: Unstable
+ * @include: chimara/chimara-glk.h
+ * 
+ * The ChimaraGlk widget opens and runs a Glk program. The program must be
+ * compiled as a plugin module, with a function <function>glk_main()</function>
+ * that the Glk library can hook into.
+ *
+ * On Linux systems, this is a file with a name like 
+ * <filename>plugin.so</filename>. For portability, you can use libtool and 
+ * automake:
+ * <informalexample><programlisting>
+ * pkglib_LTLIBRARIES = plugin.la
+ * plugin_la_SOURCES = plugin.c foo.c bar.c
+ * plugin_la_LDFLAGS = -module -shared -avoid-version -export-symbols-regex "^glk_main$$"
+ * </programlisting></informalexample>
+ * This will produce <filename>plugin.la</filename> which is a text file 
+ * containing the correct plugin file to open (see the relevant section of the
+ * <ulink 
+ * url="http://www.gnu.org/software/libtool/manual/html_node/Finding-the-dlname.html">
+ * Libtool manual</ulink>).
+ */
+
 typedef void (* glk_main_t) (void);
 
 enum {
@@ -206,10 +231,24 @@ chimara_glk_class_init(ChimaraGlkClass *klass)
     /* Signals */
     klass->stopped = chimara_glk_stopped;
     klass->started = chimara_glk_started;
+    /**
+     * ChimaraGlk::stopped:
+     * @glk: The widget that received the signal
+     *
+     * The ::stopped signal is emitted when the a Glk program finishes
+     * executing in the widget, whether it ended normally, or was interrupted.
+     */ 
     chimara_glk_signals[STOPPED] = g_signal_new("stopped", 
         G_OBJECT_CLASS_TYPE(klass), 0, 
         G_STRUCT_OFFSET(ChimaraGlkClass, stopped), NULL, NULL,
                g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
+       /**
+        * ChimaraGlk::started:
+        * @glk: The widget that received the signal
+        *
+        * The ::started signal is emitted when a Glk program starts executing in
+        * the widget.
+        */
        chimara_glk_signals[STARTED] = g_signal_new ("started",
                G_OBJECT_CLASS_TYPE (klass), 0,
                G_STRUCT_OFFSET(ChimaraGlkClass, started), NULL, NULL,
@@ -222,12 +261,28 @@ chimara_glk_class_init(ChimaraGlkClass *klass)
         TRUE,
         G_PARAM_READABLE | G_PARAM_WRITABLE | G_PARAM_LAX_VALIDATION |
         G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB);
+    /**
+     * ChimaraGlk:interactive:
+     *
+     * Sets whether the widget is interactive. A Glk widget is normally 
+     * interactive, but in non-interactive mode, keyboard and mouse input are 
+     * ignored and the Glk program is controlled by chimara_glk_feed_text(). 
+     * "More" prompts when a lot of text is printed to a text buffer are also 
+     * disabled. This is typically used when you wish to control an interpreter 
+     * program by feeding it a predefined list of commands.
+     */
     g_object_class_install_property(object_class, PROP_INTERACTIVE, pspec);
     pspec = g_param_spec_boolean("protect", _("Protected"),
         _("Whether the Glk program is barred from doing file operations"),
         FALSE,
         G_PARAM_READABLE | G_PARAM_WRITABLE | G_PARAM_LAX_VALIDATION |
         G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB);
+    /**
+     * ChimaraGlk:protect:
+     *
+     * Sets whether the Glk program is allowed to do file operations. In protect
+     * mode, all file operations will fail.
+     */
     g_object_class_install_property(object_class, PROP_PROTECT, pspec);
     
     /* Private data */
@@ -263,12 +318,7 @@ chimara_glk_new(void)
  * @glk: a #ChimaraGlk widget
  * @interactive: whether the widget should expect user input
  *
- * Sets the #ChimaraGlk:interactive property of @glk. A Glk widget is normally 
- * interactive, but in non-interactive mode, keyboard and mouse input is ignored
- * and the Glk program is controlled by chimara_glk_feed_text(). "More" prompts
- * when a lot of text is printed to a text buffer are also disabled. This is 
- * typically used when you wish to control an interpreter program by feeding it
- * a predefined list of commands.
+ * Sets the #ChimaraGlk:interactive property of @glk. 
  */
 void 
 chimara_glk_set_interactive(ChimaraGlk *glk, gboolean interactive)
@@ -284,7 +334,7 @@ chimara_glk_set_interactive(ChimaraGlk *glk, gboolean interactive)
  * @glk: a #ChimaraGlk widget
  *
  * Returns whether @glk is interactive (expecting user input). See 
- * chimara_glk_set_interactive().
+ * #ChimaraGlk:interactive.
  *
  * Return value: %TRUE if @glk is interactive.
  */
@@ -320,7 +370,7 @@ chimara_glk_set_protect(ChimaraGlk *glk, gboolean protect)
  * @glk: a #ChimaraGlk widget
  *
  * Returns whether @glk is in protect mode (banned from doing file operations).
- * See chimara_glk_set_protect().
+ * See #ChimaraGlk:protect.
  *
  * Return value: %TRUE if @glk is in protect mode.
  */
@@ -347,8 +397,10 @@ glk_enter(gpointer glk_main)
 /**
  * chimara_glk_run:
  * @glk: a #ChimaraGlk widget
- * @plugin: path to a plugin module compiled with glk.h
- * @error: location to store a #GError, or %NULL
+ * @plugin: path to a plugin module compiled with <filename 
+ * class="header">glk.h</filename>
+ * @error: location to store a <link linkend="glib-GError">GError</link>, or 
+ * %NULL
  *
  * Opens a Glk program compiled as a plugin and runs its glk_main() function in
  * a separate thread. On failure, returns %FALSE and sets @error.
@@ -420,4 +472,4 @@ chimara_glk_wait(ChimaraGlk *glk)
     
     ChimaraGlkPrivate *priv = CHIMARA_GLK_PRIVATE(glk);
     g_thread_join(priv->thread);
-}
\ No newline at end of file
+}
index 2f419722bd44e07c3480acdb6c4ebbd767ec3ebd..94ee6c59f97b3b8300b54b2e566b49272340ea0c 100644 (file)
@@ -20,22 +20,23 @@ G_BEGIN_DECLS
 #define CHIMARA_GLK_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), \
                                      CHIMARA_TYPE_GLK, ChimaraGlkClass))
 
-typedef struct _ChimaraGlk ChimaraGlk;
-typedef struct _ChimaraGlkClass ChimaraGlkClass;
-
-struct _ChimaraGlk {
-    GtkContainer parent_instance;
+/**
+ * ChimaraGlk:
+ * 
+ * This structure contains no public members.
+ */
+typedef struct _ChimaraGlk {
+       GtkContainer parent_instance;
     
-    /* Public members */
-};
+       /*< public >*/
+} ChimaraGlk;
 
-struct _ChimaraGlkClass {
-    GtkContainerClass parent_class;
-    
-    /* Signals */
+typedef struct _ChimaraGlkClass {
+       GtkContainerClass parent_class;
+       /* Signals */
        void(* stopped) (ChimaraGlk *self);
        void(* started) (ChimaraGlk *self);
-};
+} ChimaraGlkClass;
 
 GType chimara_glk_get_type(void) G_GNUC_CONST;
 GtkWidget *chimara_glk_new(void);
@@ -49,4 +50,4 @@ void chimara_glk_wait(ChimaraGlk *glk);
 
 G_END_DECLS
 
-#endif /* __CHIMARA_GLK_H__ */
\ No newline at end of file
+#endif /* __CHIMARA_GLK_H__ */
diff --git a/src/doc.c b/src/doc.c
new file mode 100644 (file)
index 0000000..5881072
--- /dev/null
+++ b/src/doc.c
@@ -0,0 +1,1737 @@
+/*
+ * doc.c - Contains the short and long descriptions of all the documentation
+ *         sections in the Glk spec, as well as the GtkDoc comments for symbols
+ *         defined only in glk.h.
+ */
+
+/**
+ * SECTION:glk-exiting
+ * @short_description: How to terminate a Glk program cleanly
+ * @include: glk.h
+ *
+ * A Glk program usually ends when the end of the glk_main() function is 
+ * reached. You can also terminate it earlier.
+ */ 
+
+/**
+ * SECTION:glk-interrupt
+ * @short_description: Specifying an interrupt handler for cleaning up critical
+ * resources
+ * @include: glk.h
+ *
+ * Most platforms have some provision for interrupting a program &mdash;
+ * <keycombo action="simul"><keycap function="command">command</keycap>
+ * <keycap>period</keycap></keycombo> on the Macintosh, <keycombo 
+ * action="simul"><keycap function="control">control</keycap><keycap>C</keycap>
+ * </keycombo> in Unix, possibly a window manager item, or other possibilities.
+ * This can happen at any time, including while execution is nested inside one 
+ * of your own functions, or inside a Glk library function.
+ *
+ * If you need to clean up critical resources, you can specify an interrupt
+ * handler function.
+ */
+
+/**
+ * SECTION:glk-tick
+ * @short_description: Yielding time to the operating system
+ * @include: glk.h
+ *
+ * Many platforms have some annoying thing that has to be done every so often,
+ * or the gnurrs come from the voodvork out and eat your computer.
+ * 
+ * Well, not really. But you should call glk_tick() every so often, just in
+ * case. It may be necessary to yield time to other applications in a
+ * cooperative-multitasking OS, or to check for player interrupts in an infinite
+ * loop.
+ */
+
+/**
+ * SECTION:glk-types
+ * @short_description: Basic types used in Glk
+ * @include: glk.h
+ *
+ * For simplicity, all the arguments used in Glk calls are of a very few types.
+ * <variablelist>
+ *  <varlistentry>
+ *    <term>32-bit unsigned integer</term>
+ *    <listitem><para>Unsigned integers are used wherever possible, which is
+ *    nearly everywhere. This type is called #glui32.</para></listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>32-bit signed integer</term>
+ *    <listitem><para>This type is called #glsi32. Rarely used.</para>
+ *    </listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>References to library objects</term>
+ *    <listitem><para>These are pointers to opaque C structures; each library
+ *    will use different structures, so you can not and should not try to
+ *    manipulate their contents. See <link 
+ *    linkend="chimara-Opaque-Objects">Opaque Objects</link>.</para></listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>Pointer to one of the above types</term>
+ *    <listitem><para>Pointer to a structure which consists entirely of the
+ *    above types.</para></listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term><type>unsigned char</type></term> 
+ *    <listitem><para>This is used only for Latin-1 text characters; see 
+ *    <link linkend="chimara-Character-Encoding">Character Encoding</link>.
+ *    </para></listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>Pointer to <type>char</type></term> 
+ *    <listitem><para>Sometimes this means a null-terminated string; sometimes
+ *    an unterminated buffer, with length as a separate #glui32 argument. The
+ *    documentation says which.</para></listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>Pointer to <type>void</type></term> 
+ *    <listitem><para>When nothing else will do.</para></listitem>
+ *  </varlistentry>
+ * </variablelist>
+ */
+
+/**
+ * SECTION:glk-opaque-objects
+ * @short_description: Complex objects in Glk
+ * @include: glk.h
+ *
+ * Glk keeps track of a few classes of special objects. These are opaque to your
+ * program; you always refer to them using pointers to opaque C structures.
+ * 
+ * Currently, these classes are:
+ * <variablelist>
+ *  <varlistentry>
+ *    <term>Windows</term>
+ *    <listitem><para>Screen panels, used to input or output information.
+ *    </para></listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>Streams</term>
+ *    <listitem><para>Data streams, to which you can input or output text.
+ *    </para>
+ *    <note><para>There are file streams and window streams, since you can
+ *    output data to windows or files.</para></note>
+ *    </listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>File references</term>
+ *    <listitem><para>Pointers to files in permanent storage.</para>
+ *    <note><para>In Unix a file reference is a pathname; on the Mac, an
+ *    <type>FSSpec</type>. Actually there's a little more information included,
+ *    such as file type and whether it is a text or binary file.</para></note>
+ *    </listitem>
+ *  </varlistentry>
+ *  <varlistentry>
+ *    <term>Sound channels</term>
+ *    <listitem><para>Audio output channels.</para>
+ *    <note><para>Not all Glk libraries support sound.</para></note>
+ *    </listitem>
+ *  </varlistentry>
+ * </variablelist>
+ *
+ * <note><para>
+ * Note that there may be more object classes in future versions of the Glk API.
+ * </para></note>
+ * 
+ * When you create one of these objects, it is always possible that the creation
+ * will fail (due to lack of memory, or some other OS error.) When this happens,
+ * the allocation function will return %NULL (0) instead of a valid pointer. You
+ * should always test for this possibility.
+ * 
+ * %NULL is never the identifier of any object (window, stream, file reference,
+ * or sound channel). The value %NULL is often used to indicate <quote>no
+ * object</quote> or <quote>nothing</quote>, but it is not a valid reference. If
+ * a Glk function takes an object reference as an argument, it is illegal to
+ * pass in %NULL unless the function definition says otherwise.
+ * 
+ * The <filename class="headerfile">glk.h</filename> file defines types
+ * #winid_t, #strid_t, #frefid_t, #schanid_t to store references. These are
+ * pointers to struct #glk_window_struct, #glk_stream_struct, 
+ * #glk_fileref_struct, and #glk_schannel_struct respectively. It is, of course,
+ * illegal to pass one kind of pointer to a function which expects another.
+ * 
+ * <note><para>
+ * This is how you deal with opaque objects from a C program. If you are using
+ * Glk through a virtual machine, matters will probably be different. Opaque
+ * objects may be represented as integers, or as VM objects of some sort.
+ * </para></note>
+ * <refsect2 id="chimara-Rocks"><!-- Indeed it does. -->
+ * <title>Rocks</title>
+ * <para>
+ * Every one of these objects (window, stream, file reference, or sound channel)
+ * has a <quote>rock</quote> value. This is simply a 32-bit integer value which
+ * you provide, for your own purposes, when you create the object.
+ * </para>
+ * <note><para>The library &mdash; so to speak &mdash; stuffs this value under a
+ * rock for safe-keeping, and gives it back to you when you ask for it.
+ * </para></note>
+ * <note><para>If you don't know what to use the rocks for, provide 0 and forget
+ * about it.</para></note>
+ * </refsect2>
+ * <refsect2 id="chimara-Iterating-Through-Opaque-Objects">
+ * <title>Iteration Through Opaque Objects</title>
+ * <para>
+ * For each class of opaque objects, there is an iterate function, which you can
+ * use to obtain a list of all existing objects of that class. It takes the form
+ * <informalexample><programlisting>
+ * <replaceable>CLASS</replaceable>id_t glk_<replaceable>CLASS</replaceable>_iterate(<replaceable>CLASS</replaceable>id_t <parameter>obj</parameter>, #glui32 *<parameter>rockptr</parameter>);
+ * </programlisting></informalexample>
+ * ...where <code><replaceable>CLASS</replaceable></code> represents one of the
+ * opaque object classes. 
+ * </para>
+ * <note><para>
+ *   So, at the current time, these are the functions glk_window_iterate(),
+ *   glk_stream_iterate(), glk_fileref_iterate(), and glk_schannel_iterate().  
+ *   There may be more classes in future versions of the spec; they all behave
+ *   the same.
+ * </para></note>
+ * <para>
+ * Calling <code>glk_<replaceable>CLASS</replaceable>_iterate(%NULL, r)</code>
+ * returns the first object; calling 
+ * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> returns
+ * the next object, until there aren't any more, at which time it returns %NULL.
+ * </para>
+ * <para>
+ * The @rockptr argument is a pointer to a location; whenever  
+ * <code>glk_<replaceable>CLASS</replaceable>_iterate()</code> returns an
+ * object, the object's rock is stored in the location <code>(*@rockptr)</code>.
+ * If you don't want the rocks to be returned, you may set @rockptr to %NULL.
+ * </para>
+ * <para>
+ * You usually use this as follows:
+ * <informalexample><programlisting>
+ * obj = glk_<replaceable>CLASS</replaceable>_iterate(NULL, NULL);
+ * while (obj) {
+ *    /* ...do something with obj... *<!-- -->/
+ *    obj = glk_<replaceable>CLASS</replaceable>_iterate(obj, NULL);
+ * }
+ * </programlisting></informalexample>
+ * </para>
+ * <para>
+ * If you create or destroy objects inside this loop, obviously, the results are
+ * unpredictable. However it is always legal to call 
+ * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> as long as
+ * @obj is a valid object id, or %NULL.
+ * </para>
+ * <para>
+ * The order in which objects are returned is entirely arbitrary. The library
+ * may even rearrange the order every time you create or destroy an object of
+ * the given class. As long as you do not create or destroy any object, the rule
+ * is that <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> has
+ * a fixed result, and iterating through the results as above will list every
+ * object exactly once. 
+ * </para>
+ * </refsect2>
+ */
+
+/**
+ * SECTION:glk-gestalt
+ * @short_description: Testing Glk's capabilities
+ * @include: glk.h
+ *
+ * The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
+ * system by which the Glk API can be upgraded without making your life
+ * impossible. New capabilities (graphics, sound, or so on) can be added without
+ * changing the basic specification. The system also allows for 
+ * <quote>optional</quote> capabilities &mdash; those which not all Glk library
+ * implementations will support &mdash; and allows you to check for their
+ * presence without trying to infer them from a version number.
+ * 
+ * The basic idea is that you can request information about the capabilities of
+ * the API, by calling the gestalt functions.
+ */
+
+/**
+ * SECTION:glk-character-input
+ * @short_description: Waiting for a single keystroke
+ * @include: glk.h
+ *
+ * You can request that the player hit a single key. See <link 
+ * linkend="chimara-Character-Input-Events">Character Input Events</link>.
+ * 
+ * If you use the basic text API, the character code which is returned can be
+ * any value from 0 to 255. The printable character codes have already been
+ * described. The remaining codes are typically control codes: <keycombo  
+ * action="simul"><keycap function="control">control</keycap>
+ * <keycap>A</keycap></keycombo> to <keycombo action="simul"><keycap 
+ * function="control">control</keycap><keycap>Z</keycap></keycombo> and a few
+ * others.
+ * 
+ * There are also a number of special codes, representing special keyboard
+ * keys, which can be returned from a char-input event. These are represented
+ * as 32-bit integers, starting with 4294967295 (0xFFFFFFFF) and working down.
+ * The special key codes are defined in the <filename 
+ * class="headerfile">glk.h</filename> file. They include one code for <keycap
+ * function="enter">return</keycap> or <keycap function="enter">enter</keycap>,
+ * one for <keycap function="delete">delete</keycap> or <keycap
+ * function="backspace">backspace</keycap>, twelve function keys, and one code
+ * for any key which has no Latin-1 or special code. The full list of key codes
+ * is included below.
+ * 
+ * Various implementations of Glk will vary widely in which characters the
+ * player can enter. The most obvious limitation is that some characters are
+ * mapped to others. For example, most keyboards return a <keycombo
+ * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
+ * </keycombo> code when the <keycap function="tab">tab</keycap> key is
+ * pressed. The Glk library, if it can recognize this at all, will generate a
+ * <keysym>#keycode_Tab</keysym> event (value 0xFFFFFFF7) when this occurs.
+ * Therefore, for these keyboards, no keyboard key will generate a <keycombo
+ * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
+ * </keycombo> event (value 9.) The Glk library will probably map many of the
+ * control codes to the other special keycodes.
+ * 
+ * <note><para>
+ *   On the other hand, the library may be very clever and discriminate between
+ *   <keycap>tab</keycap> and <keycombo action="simul"><keycap
+ *   function="control">control</keycap><keycap>I</keycap></keycombo>. This is
+ *   legal. The idea is, however, that if your program asks the player to
+ *   <quote><computeroutput>press the <keycap function="tab">tab</keycap>
+ *   key</computeroutput></quote>, you should check for a 
+ *   <keysym>#keycode_Tab</keysym> event as opposed to a <keycombo 
+ *   action="simul"><keycap function="control">control</keycap>
+ *   <keycap>I</keycap></keycombo> event.
+ * </para></note>
+ * 
+ * Some characters may not be enterable simply because they do not exist.
+ * 
+ * <note><para>
+ *   Not all keyboards have a <keycap function="home">home</keycap> or <keycap
+ *   function="end">end</keycap> key. A pen-based platform may not recognize
+ *   any control characters at all.
+ * </para></note>
+ * 
+ * Some characters may not be enterable because they are reserved for the
+ * purposes of the interface. For example, the Mac Glk library reserves the 
+ * <keycap function="tab">tab</keycap> key for switching between different Glk
+ * windows. Therefore, on the Mac, the library will never generate a
+ * <keysym>#keycode_Tab</keysym> event or a <keycombo action="simul">
+ * <keycap function="control">control</keycap><keycap>I</keycap></keycombo>
+ * event.
+ * 
+ * <note><para>
+ *   Note that the linefeed or <keycombo action="simul"><keycap  
+ *   function="control">control</keycap><keycap>J</keycap></keycombo> 
+ *   character, which is the only printable control character, is probably not
+ *   typable. This is because, in most libraries, it will be converted to
+ *   <keysym>#keycode_Return</keysym>. Again, you should check for
+ *   <keysym>#keycode_Return</keysym> if your program asks the player to 
+ *   <quote><computeroutput>press the <keycap function="enter">return</keycap>
+ *   key</computeroutput></quote>.
+ * </para></note>
+ * 
+ * <note><para>
+ *   The <keycap function="delete">delete</keycap> and <keycap
+ *   function="backspace">backspace</keycap> keys are merged into a single
+ *   keycode because they have such an astonishing history of being confused in
+ *   the first place... this spec formally waives any desire to define the
+ *   difference. Of course, a library is free to distinguish <keycap
+ *   function="delete">delete</keycap> and <keycap
+ *   function="backspace">backspace</keycap> during line input. This is when it
+ *   matters most; conflating the two during character input should not be a
+ *   large problem.
+ * </para></note>
+ *
+ * You can test for this by using the #gestalt_CharInput selector.
+ * 
+ * <note><para>
+ *   Glk porters take note: it is not a goal to be able to generate every
+ *   single possible key event. If the library says that it can generate a
+ *   particular keycode, then game programmers will assume that it is
+ *   available, and ask players to use it. If a <keysym>#keycode_Home</keysym>
+ *   event can only be generated by typing <keycombo action="seq"><keycap
+ *   function="escape">escape</keycap><keycombo action="simul"><keycap
+ *   function="control">control</keycap><keycap>A</keycap></keycombo>
+ *   </keycombo>, and the player does not know this, the player will be lost
+ *   when the game says <quote><computeroutput>Press the <keycap
+ *   function="home">home</keycap> key to see the next 
+ *   hint.</computeroutput></quote> It is better for the library to say that it
+ *   cannot generate a <keysym>#keycode_Home</keysym> event; that way the game
+ *   can detect the situation and ask the user to type <keycap>H</keycap>
+ *   instead.
+ * </para>
+ * <para>
+ *   Of course, it is better not to rely on obscure keys in any case. The arrow
+ *   keys and <keycap function="enter">return</keycap> are nearly certain to be
+ *   available; the others are of gradually decreasing reliability, and you
+ *   (the game programmer) should not depend on them. You must be certain to
+ *   check for the ones you want to use, including the arrow keys and <keycap
+ *   function="enter">return</keycap>, and be prepared to use different keys in
+ *   your interface if #gestalt_CharInput says they are not available.
+ * </para></note>
+ */
+
+/**
+ * SECTION:glk-case
+ * @short_description: Changing the case of strings
+ * @include: glk.h
+ *
+ * Glk has functions to manipulate the case of both Latin-1 and Unicode strings.
+ * One Latin-1 lowercase character corresponds to one uppercase character, and
+ * vice versa, so the Latin-1 functions act on single characters. The Unicode
+ * functions act on whole strings, since the length of the string may change.
+ */
+
+/**
+ * SECTION:glk-window-opening
+ * @short_description: Creating new windows and closing them
+ * @include: glk.h
+ *
+ * You can open a new window using glk_window_open() and close it again using
+ * glk_window_close().
+ */
+
+/**
+ * SECTION:glk-window-constraints
+ * @short_description: Manipulating the size of a window
+ * @include: glk.h
+ *
+ * There are library functions to change and to measure the size of a window.
+ */
+
+/**
+ * SECTION:glk-window-types
+ * @short_description: Blank, pair, text grid, text buffer, and graphics windows
+ * @include: glk.h
+ * 
+ * A technical description of all the window types, and exactly how they behave.
+ */
+
+/**
+ * SECTION:glk-echo-streams
+ * @short_description: Creating a copy of a window's output
+ * @include: glk.h
+ *
+ * Every window has an associated window stream; you print to the window by
+ * printing to this stream. However, it is possible to attach a second stream to
+ * a window. Any text printed to the window is also echoed to this second
+ * stream, which is called the window's <quote>echo stream.</quote>
+ * 
+ * Effectively, any call to glk_put_char() (or the other output commands) which
+ * is directed to the window's window stream, is replicated to the window's echo
+ * stream. This also goes for the style commands such as glk_set_style().
+ * 
+ * Note that the echoing is one-way. You can still print text directly to the
+ * echo stream, and it will go wherever the stream is bound, but it does not
+ * back up and appear in the window. 
+ *
+ * An echo stream can be of any type, even another window's window stream.
+ * 
+ * <note><para>
+ *   This would be somewhat silly, since it would mean that any text printed to
+ *   the window would be duplicated in another window. More commonly, you would
+ *   set a window's echo stream to be a file stream, in order to create a
+ *   transcript file from that window.
+ * </para></note>
+ *
+ * A window can only have one echo stream. But a single stream can be the echo
+ * stream of any number of windows, sequentially or simultaneously.
+ *
+ * If a window is closed, its echo stream remains open; it is not automatically
+ * closed. 
+ *
+ * <note><para>
+ *   Do not confuse the window's window stream with its echo stream. The window
+ *   stream is <quote>owned</quote> by the window, and dies with it. The echo
+ *   stream is merely temporarily associated with the window.
+ * </para></note>
+ * 
+ * If a stream is closed, and it is the echo stream of one or more windows,
+ * those windows are reset to not echo anymore. (So then calling
+ * glk_window_get_echo_stream() on them will return %NULL.) 
+ */
+
+/**
+ * SECTION:glk-window-other
+ * @short_description: Miscellaneous functions for windows
+ * @include: glk.h
+ *
+ * This section contains functions for windows that don't fit anywhere else.
+ */
+
+/**
+ * SECTION:glk-events
+ * @short_description: Waiting for events
+ * @include: glk.h
+ *
+ * As described in <link linkend="chimara-Your-Programs-Main-Function">Your
+ * Program's Main Function</link>, all player input is handed to your program by
+ * the glk_select() call, in the form of events. You should write at least one
+ * event loop to retrieve these events.
+ */
+
+/**
+ * SECTION:glk-character-input-events
+ * @short_description: Events representing a single keystroke
+ * @include: glk.h
+ *
+ * You can request character input from text buffer and text grid windows. See 
+ * #evtype_CharInput. There are separate functions for requesting Latin-1 input
+ * and Unicode input; see #gestalt_Unicode.
+ */
+
+/**
+ * SECTION:glk-line-input-events
+ * @short_description: Events representing a line of user input
+ * @include: glk.h
+ *
+ * You can request line input from text buffer and text grid windows. See
+ * #evtype_LineInput. There are separate functions for requesting Latin-1 input
+ * and Unicode input; see #gestalt_Unicode.
+ */
+
+/**
+ * SECTION:glk-streams
+ * @short_description: Input and output abstractions
+ * @include: glk.h
+ *
+ * All character output in Glk is done through streams. Every window has an
+ * output stream associated with it. You can also write to files on disk; every
+ * open file is represented by an output stream as well.
+ *
+ * There are also input streams; these are used for reading from files on disk.
+ * It is possible for a stream to be both an input and an output stream. 
+ *
+ * <note><para>
+ *   Player input is done through line and character input events, not streams.
+ *   This is a small inelegance in theory. In practice, player input is slow and
+ *   things can interrupt it, whereas file input is immediate. If a network
+ *   extension to Glk were proposed, it would probably use events and not
+ *   streams, since network communication is not immediate.
+ * </para></note>
+ *
+ * It is also possible to create a stream that reads or writes to a buffer in
+ * memory.
+ * 
+ * Finally, there may be platform-specific types of streams, which are created
+ * before your program starts running. 
+ *
+ * <note><para>
+ *   For example, a program running under Unix may have access to standard input
+ *   as a stream, even though there is no Glk call to explicitly open standard
+ *   input. On the Mac, data in a Mac resource may be available through a
+ *   resource-reading stream.
+ * </para></note>
+ *
+ * You do not need to worry about the origin of such streams; just read or write
+ * them as usual. For information about how platform-specific streams come to
+ * be, see <link linkend="chimara-Startup-Options">Startup Options</link>.
+ * 
+ * A stream is opened with a particular file mode, see the 
+ * <code>filemode_</code> constants below.
+ *
+ * For information on opening streams, see the discussion of each specific type
+ * of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
+ * Streams</link>. Remember that it is always possible that opening a stream
+ * will fail, in which case the creation function will return %NULL.
+ * 
+ * Each stream remembers two character counts, the number of characters printed
+ * to and read from that stream. The write-count is exactly one per 
+ * glk_put_char() call; it is figured before any platform-dependent character
+ * cookery. 
+ *
+ * <note><para>
+ *   For example, if a newline character is converted to 
+ *   linefeed-plus-carriage-return, the stream's count still only goes up by
+ *   one; similarly if an accented character is displayed as two characters.
+ * </para></note>
+ * 
+ * The read-count is exactly one per glk_get_char_stream() call, as long as the
+ * call returns an actual character (as opposed to an end-of-file token.) 
+ *
+ * Glk has a notion of the <quote>current (output) stream</quote>. If you print
+ * text without specifying a stream, it goes to the current output stream. The
+ * current output stream may be %NULL, meaning that there isn't one. It is
+ * illegal to print text to stream %NULL, or to print to the current stream when
+ * there isn't one.
+ *
+ * If the stream which is the current stream is closed, the current stream
+ * becomes %NULL. 
+ */
+/**
+ * SECTION:glk-print
+ * @short_description: Printing to streams
+ * @include: glk.h
+ *
+ * You can print Latin-1 and Unicode characters, null-terminated strings, or
+ * buffers to any stream. The characters will be converted into the appropriate
+ * format for that stream.
+ */
+/**
+ * SECTION:glk-read
+ * @short_description: Reading from streams
+ * @include: glk.h
+ *
+ * You can read Latin-1 or Unicode characters, buffers, or whole lines from any
+ * stream. The characters will be converted into the form in which you request
+ * them.
+ */
+/**
+ * SECTION:glk-closing-streams
+ * @short_description: Closing streams and retrieving their character counts
+ * @include: glk.h
+ *
+ * When you close a Glk stream, you have the opportunity to examine the
+ * character counts &mdash; the number of characters written to or read from the
+ * stream.
+ */
+
+/**
+ * SECTION:glk-stream-positions
+ * @short_description: Moving the read/write mark
+ * @include: glk.h
+ *
+ * You can set the position of the read/write mark in a stream.
+ *
+ * <note><para>
+ *   Which makes one wonder why they're called <quote>streams</quote> in the
+ *   first place. Oh well.
+ * </para></note>
+ */
+
+/**
+ * SECTION:glk-stream-types
+ * @short_description: Window, memory, and file streams
+ * @include: glk.h
+ *
+ * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
+ * <para>
+ * Every window has an output stream associated with it. This is created
+ * automatically, with #filemode_Write, when you open the window. You get it
+ * with glk_window_get_stream().
+ * 
+ * A window stream cannot be closed with glk_stream_close(). It is closed
+ * automatically when you close its window with glk_window_close().
+ * 
+ * Only printable characters (including newline) may be printed to a window
+ * stream. See <link linkend="chimara-Character-Encoding">Character 
+ * Encoding</link>.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="chimara-Memory-Streams"><title>Memory Streams</title>
+ * <para>
+ * You can open a stream which reads from or writes to a space in memory. See
+ * glk_stream_open_memory() and glk_stream_open_memory_uni(). When opening a
+ * memory stream, you specify a buffer to which the stream's output will be
+ * written, and its length @buflen.
+ *
+ * When outputting, if more than @buflen characters are written to the stream,
+ * all of them beyond the buffer length will be thrown away, so as not to
+ * overwrite the buffer. (The character count of the stream will still be
+ * maintained correctly. That is, it will count the number of characters written
+ * into the stream, not the number that fit into the buffer.)
+ *
+ * If the buffer is %NULL, or for that matter if @buflen is zero, then 
+ * <emphasis>everything</emphasis> written to the stream is thrown away. This
+ * may be useful if you are interested in the character count.
+ *
+ * When inputting, if more than @buflen characters are read from the stream, the
+ * stream will start returning -1 (signalling end-of-file.) If the buffer is 
+ * %NULL, the stream will always return end-of-file.
+ *
+ * The data is written to the buffer exactly as it was passed to the printing
+ * functions (glk_put_char(), etc.); input functions will read the data exactly
+ * as it exists in memory. No platform-dependent cookery will be done on it.
+ *
+ * <note><para>
+ *   You can write a disk file in text mode, but a memory stream is effectively
+ *   always in binary mode.
+ * </para></note>
+ * 
+ * Whether reading or writing, the contents of the buffer are undefined until
+ * the stream is closed. The library may store the data there as it is written,
+ * or deposit it all in a lump when the stream is closed. It is illegal to
+ * change the contents of the buffer while the stream is open.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="chimara-File-Streams"><title>File Streams</title>
+ * <para>
+ * You can open a stream which reads from or writes to a disk file. See 
+ * glk_stream_open_file() and glk_stream_open_file_uni().
+ *
+ * The file may be written in text or binary mode; this is determined by the
+ * file reference you open the stream with. Similarly, platform-dependent
+ * attributes such as file type are determined by the file reference. See <link
+ * linkend="chimara-File-References">File References</link>.
+ * </para>
+ * </refsect2>
+ */
+/**
+ * SECTION:glk-stream-other
+ * @short_description: Miscellaneous functions for streams
+ * @include: glk.h
+ *
+ * This section includes functions for streams that don't fit anywhere else.
+ */
+
+/**
+ * SECTION:glk-fileref
+ * @short_description: A platform-independent way to refer to disk files
+ * @include: glk.h
+ *
+ * You deal with disk files using file references. Each fileref is an opaque C
+ * structure pointer; see <link linkend="chimara-Opaque-Objects">Opaque 
+ * Objects</link>.
+ * 
+ * A file reference contains platform-specific information about the name and
+ * location of the file, and possibly its type, if the platform has a notion of
+ * file type. It also includes a flag indication whether the file is a text file
+ * or binary file. 
+ *
+ * <note><para>
+ *   Note that this is different from the standard C I/O library, in which you
+ *   specify text or binary mode when the file is opened.
+ * </para></note>
+ * 
+ * A fileref does not have to refer to a file which actually exists. You can
+ * create a fileref for a nonexistent file, and then open it in write mode to
+ * create a new file.
+ * 
+ * You always provide a usage argument when you create a fileref. The usage is a
+ * mask of constants (see below) to indicate the file type and the mode (text or
+ * binary.) These values are used when you create a new file, and also to filter
+ * file lists when the player is selecting a file to load. 
+ * 
+ * In general, you should use text mode if the player expects to read the file
+ * with a platform-native text editor; you should use binary mode if the file is
+ * to be read back by your program, or if the data must be stored exactly. Text
+ * mode is appropriate for #fileusage_Transcript; binary mode is appropriate for
+ * #fileusage_SavedGame and probably for #fileusage_InputRecord. #fileusage_Data
+ * files may be text or binary, depending on what you use them for. 
+ */
+/**
+ * SECTION:glk-fileref-types
+ * @short_description: Four different ways to create a file reference
+ * @include: glk.h
+ *
+ * There are four different functions for creating a fileref, depending on how
+ * you wish to specify it. Remember that it is always possible that a fileref
+ * creation will fail and return %NULL.
+ */
+/**
+ * SECTION:glk-fileref-other
+ * @short_description: Miscellaneous functions for file references
+ * @include: glk.h
+ *
+ * This section includes functions for file references that don't fit anywhere
+ * else.
+ */
+
+/*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/
+
+/**
+ * glui32:
+ *
+ * A 32-bit unsigned integer type, used wherever possible in Glk.
+ */
+/**
+ * glsi32:
+ *
+ * A 32-bit signed integer type, rarely used.
+ */
+
+/**
+ * GLK_MODULE_UNICODE:
+ *
+ * If this preprocessor symbol is defined, so are all the Unicode functions and
+ * constants (see #gestalt_Unicode). If not, not.
+ */
+
+/**
+ * winid_t:
+ *
+ * Opaque structure representing a Glk window. It has no user-accessible 
+ * members.
+ */
+/**
+ * strid_t:
+ *
+ * Opaque structure representing an input or output stream. It has no
+ * user-accessible members.
+ */
+/**
+ * frefid_t:
+ * 
+ * Opaque structure representing a file reference. It has no user-accessible
+ * members.
+ */
+
+/**
+ * gestalt_Version:
+ *
+ * For an example of the gestalt mechanism, consider the selector
+ * #gestalt_Version. If you do
+ * <informalexample><programlisting>
+ * #glui32 res;
+ * res = #glk_gestalt(#gestalt_Version, 0);
+ * </programlisting></informalexample>
+ * <code>res</code> will be set to a 32-bit number which encodes the version of
+ * the Glk spec which the library implements. The upper 16 bits stores the major
+ * version number; the next 8 bits stores the minor version number; the low 8 
+ * bits stores an even more minor version number, if any.
+ *
+ * <note><para>
+ *   So the version number 78.2.11 would be encoded as 0x004E020B.
+ * </para></note>
+ *
+ * The current Glk specification version is 0.7.0, so this selector will return
+ * 0x00000700.
+ *
+ * <informalexample><programlisting>
+ * #glui32 res;
+ * res = #glk_gestalt_ext(#gestalt_Version, 0, NULL, 0);
+ * </programlisting></informalexample>
+ * does exactly the same thing. Note that, in either case, the second argument 
+ * is not used; so you should always pass 0 to avoid future surprises.
+ */
+
+/**
+ * gestalt_CharInput:
+ *
+ * If you set <code>ch</code> to a character code, or a special code (from
+ * 0xFFFFFFFF down), and call
+ * <informalexample><programlisting>
+ * #glui32 res;
+ * res = #glk_gestalt(#gestalt_CharInput, ch);
+ * </programlisting></informalexample>
+ * then <code>res</code> will be %TRUE (1) if that character can be typed by
+ * the player in character input, and %FALSE (0) if not. See <link
+ * linkend="chimara-Character-Input">Character Input</link>.
+ */
+
+/**
+ * gestalt_LineInput:
+ *
+ * If you set <code>ch</code> to a character code, and call
+ * <informalexample><programlisting>
+ * #glui32 res;
+ * res = #glk_gestalt(#gestalt_LineInput, ch);
+ * </programlisting></informalexample>
+ * then <code>res</code> will be %TRUE (1) if that character can be typed by the
+ * player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is 
+ * a nonprintable Latin-1 character (0 to 31, 127 to 159), then this is 
+ * guaranteed to return %FALSE. See <link linkend="chimara-Line-Input">Line
+ * Input</link>.
+ */
+
+/**
+ * gestalt_CharOutput:
+ *
+ * If you set <code>ch</code> to a character code (Latin-1 or higher), and call
+ * <informalexample><programlisting>
+ * #glui32 res, len;
+ * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &amp;len, 1);
+ * </programlisting></informalexample>
+ * then <code>res</code> will be one of #gestalt_CharOutput_CannotPrint,
+ * #gestalt_CharOutput_ExactPrint, or #gestalt_CharOutput_ApproxPrint (see 
+ * below.)
+ * 
+ * In all cases, <code>len</code> (the #glui32 value pointed at by the third
+ * argument) will be the number of actual glyphs which will be used to represent
+ * the character. In the case of #gestalt_CharOutput_ExactPrint, this will 
+ * always be 1; for #gestalt_CharOutput_CannotPrint, it may be 0 (nothing 
+ * printed) or higher; for #gestalt_CharOutput_ApproxPrint, it may be 1 or 
+ * higher. This information may be useful when printing text in a fixed-width 
+ * font.
+ *
+ * <note><para>
+ *   As described in <link linkend="chimara-Other-API-Conventions">Other API
+ *   Conventions</link>, you may skip this information by passing %NULL as the
+ *   third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
+ * </para></note>
+ *
+ * This selector will always return #gestalt_CharOutput_CannotPrint if 
+ * <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127 
+ * to 159.)
+ *
+ * <note><para>
+ *   Make sure you do not get confused by signed byte values. If you set a
+ *   <quote><type>char</type></quote> variable <code>ch</code> to 0xFE, the 
+ *   small-thorn character (&thorn;), and then call
+ *   <informalexample><programlisting>
+ *   res = #glk_gestalt(#gestalt_CharOutput, ch);
+ *   </programlisting></informalexample>
+ *   then (by the definition of C/C++) <code>ch</code> will be sign-extended to
+ *   0xFFFFFFFE, which is not a legitimate character, even in Unicode. You 
+ *   should write
+ *   <informalexample><programlisting>
+ *   res = #glk_gestalt(#gestalt_CharOutput, (unsigned char)ch);
+ *   </programlisting></informalexample>
+ *   instead.
+ * </para></note>
+ * <note><para>
+ *   Unicode includes the concept of non-spacing or combining characters, which 
+ *   do not represent glyphs; and double-width characters, whose glyphs take up
+ *   two spaces in a fixed-width font. Future versions of this spec may 
+ *   recognize these concepts by returning a <code>len</code> of 0 or 2 when
+ *   #gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to 
+ *   a policy of <quote>simple stuff first</quote>.
+ * </para></note>
+ */
+/**
+ * gestalt_CharOutput_CannotPrint:
+ *
+ * When the #gestalt_CharOutput selector returns this for a character, the
+ * character cannot be meaningfully printed. If you try, the player may see
+ * nothing, or may see a placeholder.
+ */
+
+/**
+ * gestalt_CharOutput_ApproxPrint:
+ *
+ * When the #gestalt_CharOutput selector returns this for a character, the 
+ * library will print some approximation of the character. It will be more or 
+ * less right, but it may not be precise, and it may not be distinguishable from
+ * other, similar characters. (Examples: 
+ * <quote><computeroutput>ae</computeroutput></quote> for the one-character
+ * <quote>&aelig;</quote> ligature, 
+ * <quote><computeroutput>e</computeroutput></quote> for 
+ * <quote>&egrave;</quote>, <quote><computeroutput>|</computeroutput></quote> 
+ * for a broken vertical bar (&brvbar;).)
+ */
+/**
+ * gestalt_CharOutput_ExactPrint:
+ *
+ * When the #gestalt_CharOutput selector returns this for a character, the
+ * character will be printed exactly as defined.
+ */
+
+/**
+ * gestalt_Unicode:
+ *
+ * The basic text functions will be available in every Glk library. The Unicode
+ * functions may or may not be available. Before calling them, you should use
+ * the following gestalt selector:
+ * <informalexample><programlisting>
+ * glui32 res;
+ * res = #glk_gestalt(#gestalt_Unicode, 0);
+ * </programlisting></informalexample>
+ * 
+ * This returns 1 if the Unicode functions are available. If it returns 0, you
+ * should not try to call them. They may print nothing, print gibberish, or
+ * cause a run-time error. The Unicode functions include
+ * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),  
+ * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
+ * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
+ * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
+ * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
+ * glk_request_char_event_uni(), glk_request_line_event_uni(),
+ * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
+ * 
+ * If you are writing a C program, there is an additional complication. A
+ * library which does not support Unicode may not implement the Unicode
+ * functions at all. Even if you put gestalt tests around your Unicode calls,
+ * you may get link-time errors. If the 
+ * <filename class="headerfile">glk.h</filename> file is so old that it does not
+ * declare the Unicode functions and constants, you may even get compile-time
+ * errors.
+ * 
+ * To avoid this, you can perform a preprocessor test for the existence of
+ * #GLK_MODULE_UNICODE. 
+ */
+
+/**
+ * evtype_None:
+ *
+ * No event. This is a placeholder, and glk_select() never returns it.
+ */
+
+/**
+ * evtype_Timer:
+ *
+ * An event that repeats at fixed intervals. See <link 
+ * linkend="chimara-Timer-Events">Timer Events</link>.
+ */
+/**
+ * evtype_CharInput:
+ *
+ * A keystroke event in a window. See <link 
+ * linkend="chimara-Character-Input-Events">Character Input Events</link>.
+ *
+ * If a window has a pending request for character input, and the player hits a
+ * key in that window, glk_select() will return an event whose type is
+ * #evtype_CharInput. Once this happens, the request is complete; it is no 
+ * longer pending. You must call glk_request_char_event() or
+ * glk_request_char_event_uni() if you want another character from that window.
+ * 
+ * In the event structure, @win tells what window the event came from. @val1 
+ * tells what character was entered; this will be a character code, or a special
+ * keycode. (See <link linkend="chimara-Character-Input">Character 
+ * Input</link>.) If you called glk_request_char_event(), @val1 will be in 
+ * 0..255, or else a special keycode. In any case, @val2 will be 0.
+ */
+
+/**
+ * evtype_LineInput:
+ *
+ * A full line of input completed in a window. See <link 
+ * linkend="chimara-Line-Input-Events">Line Input Events</link>.
+ *
+ * If a window has a pending request for line input, and the player hits
+ * <keycap>enter</keycap> in that window (or whatever action is appropriate to
+ * enter his input), glk_select() will return an event whose type is
+ * #evtype_LineInput. Once this happens, the request is complete; it is no 
+ * longer pending. You must call glk_request_line_event() if you want another 
+ * line of text from that window.
+ * 
+ * In the event structure, @win tells what window the event came from. @val1 
+ * tells how many characters were entered. @val2 will be 0. The characters
+ * themselves are stored in the buffer specified in the original
+ * glk_request_line_event() or glk_request_line_event_uni() call. 
+ *
+ * <note><para>There is no null terminator stored in the buffer.</para></note>
+ * 
+ * It is illegal to print anything to a window which has line input pending. 
+ *
+ * <note><para>
+ *   This is because the window may be displaying and editing the player's 
+ *   input, and printing anything would make life unnecessarily complicated for
+ *   the library.
+ * </para></note>
+ */
+
+/**
+ * evtype_MouseInput:
+ *
+ * A mouse click in a window. See <link 
+ * linkend="chimara-Mouse-Input-Events">Mouse Input Events</link>.
+ */
+/**
+ * evtype_Arrange:
+ *
+ * An event signalling that the sizes of some windows have changed. 
+ * 
+ * Some platforms allow the player to resize the Glk window during play. This 
+ * will naturally change the sizes of your windows. If this occurs, then
+ * immediately after all the rearrangement, glk_select() will return an event
+ * whose type is #evtype_Arrange. You can use this notification to redisplay the
+ * contents of a graphics or text grid window whose size has changed.
+ *
+ * <note><para>
+ *   The display of a text buffer window is entirely up to the library, so you
+ *   don't need to worry about those.
+ * </para></note>
+ * 
+ * In the event structure, @win will be %NULL if all windows are affected. If 
+ * only some windows are affected, @win will refer to a window which contains 
+ * all the affected windows. @val1 and @val2 will be 0.
+ *
+ * <note><para>
+ *   You can always play it safe, ignore @win, and redraw every graphics and 
+ *   text grid window.
+ * </para></note>
+ *
+ * An arrangement event is guaranteed to occur whenever the player causes any
+ * window to change size, as measured by its own metric. 
+ *
+ * <note><para>
+ *   Size changes caused by you &mdash; for example, if you open, close, or 
+ *   resize a window &mdash; do not trigger arrangement events. You must be 
+ *   aware of the effects of your window management, and redraw the windows that
+ *   you affect.
+ * </para></note>
+ * 
+ * <note><para>
+ *   It is possible that several different player actions can cause windows to
+ *   change size. For example, if the player changes the screen resolution, an
+ *   arrangement event might be triggered. This might also happen if the player
+ *   changes his display font to a different size; the windows would then be
+ *   different <quote>sizes</quote> in the metric of rows and columns, which is
+ *   the important metric and the only one you have access to.
+ * </para></note>
+ * 
+ * Arrangement events, like timer events, can be returned by glk_select_poll().
+ * But this will not occur on all platforms. You must be ready to receive an
+ * arrangement event when you call glk_select_poll(), but it is possible that it
+ * will not arrive until the next time you call glk_select(). 
+ *
+ * <note><para>
+ *   This is because on some platforms, window resizing is handled as part of
+ *   player input; on others, it can be triggered by an external process such as 
+ *   a window manager.
+ * </para></note>
+ */
+
+/**
+ * evtype_Redraw:
+ *
+ * An event signalling that graphics windows must be redrawn.
+ *
+ * On platforms that support graphics, it is possible that the contents of a
+ * graphics window will be lost, and have to be redrawn from scratch. If this
+ * occurs, then glk_select() will return an event whose type is #evtype_Redraw.
+ *
+ * In the event structure, @win will be %NULL if all windows are affected. If 
+ * only some windows are affected, @win will refer to a window which contains 
+ * all the affected windows. @val1 and @val2 will be 0.
+ *
+ * <note><para>
+ *   You can always play it safe, ignore @win, and redraw every graphics window.
+ * </para></note>
+ *
+ * Affected windows are already cleared to their background color when you 
+ * receive the redraw event.
+ * 
+ * Redraw events can be returned by glk_select_poll(). But, like arrangement
+ * events, this is platform-dependent. See #evtype_Arrange.
+ *
+ * For more about redraw events and how they affect graphics windows, see <link
+ * linkend="chimara-Graphics-Windows">Graphics Windows</link>.
+ */
+
+/**
+ * evtype_SoundNotify:
+ *
+ * On platforms that support sound, you can request to receive an 
+ * #evtype_SoundNotify event when a sound finishes playing. See <link
+ * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
+ */
+/**
+ * evtype_Hyperlink:
+ * 
+ * On platforms that support hyperlinks, you can request to receive an
+ * #evtype_Hyperlink event when the player selects a link. See <link
+ * linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink 
+ * Events</link>.
+ */
+
+/**
+ * event_t:
+ * @type: the event type
+ * @win: the window that spawned the event, or %NULL
+ * @val1: information, the meaning of which depends on the type of event
+ * @val2: more information, the meaning of which depends on the type of event
+ *
+ * The event structure is self-explanatory. @type is the event type. The window
+ * that spawned the event, if relevant, is in @win. The remaining fields contain
+ * more information specific to the event.
+ *
+ * The event types are described below. Note that #evtype_None is zero, and the
+ * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF) 
+ * are reserved for implementation-defined events. 
+ */
+
+/**
+ * keycode_Unknown:
+ *
+ * Represents any key that has no Latin-1 or special code.
+ */
+
+/**
+ * keycode_Left:
+ *
+ * Represents the <keycap function="left">left arrow</keycap> key.
+ */
+/**
+ * keycode_Right:
+ *
+ * Represents the <keycap function="right">right arrow</keycap> key.
+ */
+/**
+ * keycode_Up:
+ *
+ * Represents the <keycap function="up">up arrow</keycap> key.
+ */
+/**
+ * keycode_Down:
+ *
+ * Represents the <keycap function="down">down arrow</keycap> key.
+ */
+/**
+ * keycode_Return:
+ *
+ * Represents the <keycap function="enter">return</keycap> or <keycap 
+ * function="enter">enter</keycap> keys.
+ */
+
+/**
+ * keycode_Delete:
+ *
+ * Represents the <keycap function="delete">delete</keycap> or <keycap
+ * function="backspace">backspace</keycap> keys.
+ */
+/**
+ * keycode_Escape:
+ *
+ * Represents the <keycap function="escape">escape</keycap> key.
+ */
+/**
+ * keycode_Tab:
+ *
+ * Represents the <keycap function="tab">tab</keycap> key.
+ */
+
+/**
+ * keycode_PageUp:
+ *
+ * Represents the <keycap function="pageup">page up</keycap> key.
+ */
+
+/**
+ * keycode_PageDown:
+ *
+ * Represents the <keycap function="pagedown">page down</keycap> key.
+ */
+
+/**
+ * keycode_Home:
+ *
+ * Represents the <keycap function="home">home</keycap> key.
+ */
+/**
+ * keycode_End:
+ *
+ * Represents the <keycap function="end">end</keycap> key.
+ */
+
+/**
+ * keycode_Func1:
+ *
+ * Represents the <keycap>F1</keycap> key.
+ */
+/**
+ * keycode_Func2:
+ *
+ * Represents the <keycap>F2</keycap> key.
+ */
+
+/**
+ * keycode_Func3:
+ *
+ * Represents the <keycap>F3</keycap> key.
+ */
+
+/**
+ * keycode_Func4:
+ *
+ * Represents the <keycap>F4</keycap> key.
+ */
+
+/**
+ * keycode_Func5:
+ *
+ * Represents the <keycap>F5</keycap> key.
+ */
+/**
+ * keycode_Func6:
+ *
+ * Represents the <keycap>F6</keycap> key.
+ */
+
+/**
+ * keycode_Func7:
+ *
+ * Represents the <keycap>F7</keycap> key.
+ */
+
+/**
+ * keycode_Func8:
+ *
+ * Represents the <keycap>F8</keycap> key.
+ */
+
+/**
+ * keycode_Func9:
+ *
+ * Represents the <keycap>F9</keycap> key.
+ */
+
+/**
+ * keycode_Func10:
+ *
+ * Represents the <keycap>F10</keycap> key.
+ */
+
+/**
+ * keycode_Func11:
+ *
+ * Represents the <keycap>F11</keycap> key.
+ */
+
+/**
+ * keycode_Func12:
+ *
+ * Represents the <keycap>F12</keycap> key.
+ */
+
+/**
+ * keycode_MAXVAL:
+ *
+ * This value is equal to the number of special keycodes. The last keycode is
+ * The last keycode is always 
+ * <informalequation>
+ *   <alt>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</alt>
+ *   <mathphrase>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</mathphrase>
+ * </informalequation>
+ * .
+ */
+
+/**
+ * stream_result_t:
+ * @readcount: Number of characters read from the stream.
+ * @writecount: Number of characters printed to the stream, including ones that
+ * were thrown away.
+ *
+ * If you are interested in the character counts of a stream (see <link
+ * linkend="chimara-Streams">Streams</link>), then you can pass a pointer to
+ * #stream_result_t as an argument of glk_stream_close() or glk_window_close().
+ * The structure will be filled with the stream's final character counts.
+ */
+
+/**
+ * wintype_AllTypes:
+ *
+ * A constant representing all window types, which may be used as the @wintype
+ * argument in glk_stylehint_set().
+ */
+
+/** 
+ * wintype_Pair:
+ * 
+ * A pair window is completely filled by the two windows it contains. It
+ * supports no input and no output, and it has no size.
+ * 
+ * You cannot directly create a pair window; one is automatically created
+ * every time you split a window with glk_window_open(). Pair windows are
+ * always created with a rock value of 0.
+ * 
+ * You can close a pair window with glk_window_close(); this also closes every
+ * window contained within the pair window.
+ * 
+ * It is legal to split a pair window when you call glk_window_open().
+ */
+/**
+ * wintype_Blank:
+ * 
+ * A blank window is always blank. It supports no input and no output. (You
+ * can call glk_window_get_stream() on it, as you can with any window, but
+ * printing to the resulting stream has no effect.) A blank window has no
+ * size; glk_window_get_size() will return (0,0), and it is illegal to set a
+ * window split with a fixed size in the measurement system of a blank window.
+ * 
+ * <note><para>
+ *   A blank window is not the same as there being no windows. When Glk starts
+ *   up, there are no windows at all, not even a window of the blank type.
+ * </para></note>
+ */
+/**
+ * wintype_TextBuffer: 
+ *
+ * A text buffer window contains a linear stream of text. It supports output;
+ * when you print to it, the new text is added to the end. There is no way for
+ * you to affect text which has already been printed. There are no guarantees
+ * about how much text the window keeps; old text may be stored forever, so
+ * that the user can scroll back to it, or it may be thrown away as soon as it
+ * scrolls out of the window. 
+ * 
+ * <note><para>
+ *   Therefore, there may or may not be a player-controllable scroll bar or
+ *   other scrolling widget.
+ * </para></note>
+ * 
+ * The display of the text in a text buffer is up to the library. Lines will
+ * probably not be broken in the middles of words &mdash; but if they are, the
+ * library is not doing anything illegal, only ugly. Text selection and copying
+ * to a clipboard, if available, are handled however is best on the player's
+ * machine. Paragraphs (as defined by newline characters in the output) may be
+ * indented. 
+ * 
+ * <note><para>
+ *   You should not, in general, fake this by printing spaces before each
+ *   paragraph of prose text. Let the library and player preferences handle
+ *   that. Special cases (like indented lists) are of course up to you.
+ * </para></note>
+ * 
+ * When a text buffer is cleared (with glk_window_clear()), the library will do
+ * something appropriate; the details may vary. It may clear the window, with
+ * later text appearing at the top &mdash; or the bottom. It may simply print
+ * enough blank lines to scroll the current text out of the window. It may
+ * display a distinctive page-break symbol or divider.
+ * 
+ * The size of a text buffer window is necessarily imprecise. Calling
+ * glk_window_get_size() will return the number of rows and columns that would
+ * be available <emphasis>if</emphasis> the window was filled with 
+ * <quote>0</quote> (zero) characters in the <quote>normal</quote> font.
+ * However, the window may use a non-fixed-width font, so that number of
+ * characters in a line could vary. The window might even support 
+ * variable-height text (say, if the player is using large text for emphasis);
+ * that would make the number of lines in the window vary as well.
+ * 
+ * Similarly, when you set a fixed-size split in the measurement system of a
+ * text buffer, you are setting a window which can handle a fixed number of rows
+ * (or columns) of <quote>0</quote> characters. The number of rows (or
+ * characters) that will actually be displayed depends on font variances.
+ * 
+ * A text buffer window supports both character and line input, but not mouse
+ * input.
+ * 
+ * In character input, there will be some visible signal that the window is
+ * waiting for a keystroke. (Typically, a cursor at the end of the text.) When
+ * the player hits a key in that window, an event is generated, but the key is
+ * <emphasis>not</emphasis> printed in the window.
+ * 
+ * In line input, again, there will be some visible signal. It is most common
+ * for the player to compose input in the window itself, at the end of the text.
+ * (This is how IF story input usually looks.) But it's not strictly required.
+ * An alternative approach is the way MUD clients usually work: there is a
+ * dedicated one-line input window, outside of Glk's window space, and the user
+ * composes input there.
+ * 
+ * <note><para>
+ *   If this approach is used, there will still be some way to handle input from
+ *   two windows at once. It is the library's responsibility to make this
+ *   available to the player. You only need request line input and  wait for the
+ *   result.
+ * </para></note>
+ * 
+ * When the player finishes his line of input, the library will display the
+ * input text at the end of the buffer text (if it wasn't there already.) It
+ * will be followed by a newline, so that the next text you print will start a
+ * new line (paragraph) after the input.
+ * 
+ * If you call glk_cancel_line_event(), the same thing happens; whatever text
+ * the user was composing is visible at the end of the buffer text, followed by
+ * a newline.
+ */
+/**
+ * wintype_TextGrid: 
+ * 
+ * A text grid contains a rectangular array of characters, in a fixed-width
+ * font. Its size is the number of columns and rows of the array.
+ * 
+ * A text grid window supports output. It maintains knowledge of an output
+ * cursor position. When the window is opened, it is filled with blanks (space
+ * characters), and the output cursor starts in the top left corner &mdash;
+ * character (0,0). If the window is cleared with glk_window_clear(), the window
+ * is filled with blanks again, and the cursor returns to the top left corner.
+ * 
+ * When you print, the characters of the output are laid into the array in
+ * order, left to right and top to bottom. When the cursor reaches the end of a
+ * line, it goes to the beginning of the next line. The library makes no attempt
+ * to wrap lines at word breaks.
+ * 
+ * <note><para>
+ *   Note that printing fancy characters may cause the cursor to advance more
+ *   than one position per character. (For example, the <quote>&aelig;</quote>
+ *   ligature may print as two characters.) See <link 
+ *   linkend="chimara-Output">Output</link>, for how to test this situation.
+ * </para></note>
+ * 
+ * You can set the cursor position with glk_window_move_cursor().
+ * 
+ * When a text grid window is resized smaller, the bottom or right area is
+ * thrown away, but the remaining area stays unchanged. When it is resized
+ * larger, the new bottom or right area is filled with blanks.
+ * 
+ * <note><para>
+ *   You may wish to watch for #evtype_Arrange events, and clear-and-redraw your
+ *   text grid windows when you see them change size.
+ * </para></note>
+ * 
+ * Text grid window support character and line input, as well as mouse input (if
+ * a mouse is available.)
+ * 
+ * Mouse input returns the position of the character that was touched, from
+ * (0,0) to 
+ * <inlineequation>
+ *   <alt>(width-1,height-1)</alt>
+ *   <mathphrase>(width - 1, height - 1)</mathphrase>
+ * </inlineequation>
+ * .
+ * 
+ * Character input is as described in the previous section.
+ * 
+ * Line input is slightly different; it is guaranteed to take place in the
+ * window, at the output cursor position. The player can compose input only to
+ * the right edge of the window; therefore, the maximum input length is
+ * <inlineequation>
+ *   <alt>(windowwidth - 1 - cursorposition)</alt>
+ *   <mathphrase>(windowwidth - 1 - cursorposition)</mathphrase>
+ * </inlineequation>
+ * . If the maxlen argument of glk_request_line_event() is smaller than this,
+ * the library will not allow the input cursor to go more than maxlen characters
+ * past its start point. 
+ * 
+ * <note><para>
+ *   This allows you to enter text in a fixed-width field, without the player
+ *   being able to overwrite other parts of the window.
+ * </para></note>
+ * 
+ * When the player finishes his line of input, it will remain visible in the
+ * window, and the output cursor will be positioned at the beginning of the 
+ * <emphasis>next</emphasis> row. Again, if you glk_cancel_line_event(), the
+ * same thing happens.
+ */
+/**
+ * wintype_Graphics: 
+ * 
+ * A graphics window contains a rectangular array of pixels. Its size is the
+ * number of columns and rows of the array.
+ * 
+ * Each graphics window has a background color, which is initially white. You
+ * can change this; see <link 
+ * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics 
+ * Windows</link>.
+ * 
+ * When a text grid window is resized smaller, the bottom or right area is
+ * thrown away, but the remaining area stays unchanged. When it is resized
+ * larger, the new bottom or right area is filled with the background color.
+ * 
+ * <note><para>
+ *   You may wish to watch for #evtype_Arrange events, and clear-and-redraw your
+ *   graphics windows when you see them change size.
+ * </para></note>
+ * 
+ * In some libraries, you can receive a graphics-redraw event (#evtype_Redraw)
+ * at any time. This signifies that the window in question has been cleared to
+ * its background color, and must be redrawn. If you create any graphics
+ * windows, you <emphasis>must</emphasis> handle these events.
+ * 
+ * <note><para>
+ *   Redraw events can be triggered when a Glk window is uncovered or made
+ *   visible by the platform's window manager. On the other hand, some Glk
+ *   libraries handle these problem automatically &mdash; for example, with a
+ *   backing store &mdash; and do not send you redraw events. On the third hand,
+ *   the backing store may be discarded if memory is low, or for other reasons
+ *   &mdash; perhaps the screen's color depth has changed. So redraw events are
+ *   always a possibility, even in clever libraries. This is why you must be
+ *   prepared to handle them.
+ * 
+ *   However, you will not receive a redraw event when you create a graphics
+ *   window. It is assumed that you will do the initial drawing of your own
+ *   accord. You also do not get redraw events when a graphics window is
+ *   enlarged. If you ordered the enlargement, you already know about it; if the
+ *   player is responsible, you receive a window-arrangement event, which covers
+ *   the situation.
+ * </para></note>
+ * 
+ * For a description of the drawing functions that apply to graphics windows,
+ * see <link linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
+ * Windows</link>.
+ * 
+ * Graphics windows support no text input or output.
+ * 
+ * Not all libraries support graphics windows. You can test whether Glk graphics
+ * are available using the gestalt system. In a C program, you can also test
+ * whether the graphics functions are defined at compile-time. See <link 
+ * linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics
+ * Capabilities</link>. 
+ *
+ * <note><para>
+ *   As with all windows, you should also test for %NULL when you create a
+ *   graphics window.
+ * </para></note>
+ */
+/**
+ * winmethod_Left:
+ *
+ * When calling glk_window_open() with this @method, the new window will be 
+ * to the left of the old one which was split.
+ */
+
+/**
+ * winmethod_Right:
+ *
+ * When calling glk_window_open() with this @method, the new window will be 
+ * to the right of the old one which was split.
+ */
+
+/**
+ * winmethod_Above:
+ *
+ * When calling glk_window_open() with this @method, the new window will be 
+ * above the old one which was split.
+ */
+/**
+ * winmethod_Below:
+ *
+ * When calling glk_window_open() with this @method, the new window will be 
+ * below the old one which was split.
+ */
+
+/**
+ * winmethod_DirMask:
+ *
+ * Bitwise AND this value with a window splitting method argument to find
+ * whether the split is #winmethod_Left, #winmethod_Right, #winmethod_Above, or
+ * #winmethod_Below.
+ */
+/**
+ * winmethod_Fixed:
+ *
+ * When calling glk_window_open() with this @method, the new window will be 
+ * a fixed size. (See glk_window_open()).
+ */
+
+/**
+ * winmethod_Proportional:
+ *
+ * When calling glk_window_open() with this @method, the new window will be 
+ * a given proportion of the old window's size. (See glk_window_open()).
+ */
+/**
+ * winmethod_DivisionMask:
+ *
+ * Bitwise AND this value with a window splitting method argument to find
+ * whether the new window has #winmethod_Fixed or #winmethod_Proportional.
+ */
+/** 
+ * fileusage_Data: 
+ *
+ * Any other kind of file (preferences, statistics, arbitrary data.) 
+ */
+
+/**
+ * fileusage_SavedGame: 
+ * 
+ * A file which stores game state.
+ */
+
+/**
+ * fileusage_Transcript: 
+ * 
+ * A file which contains a stream of text from the game (often an echo stream
+ * from a window.)
+ */
+/** 
+ * fileusage_InputRecord: 
+ * 
+ * A file which records player input.
+ */
+
+/** 
+ * fileusage_TextMode: 
+ *
+ * The file contents will be transformed to a platform-native text file as they
+ * are written out. Newlines may be converted to linefeeds or 
+ * linefeed-plus-carriage-return combinations; Latin-1 characters may be
+ * converted to native character codes. When reading a file in text mode, native
+ * line breaks will be converted back to newline (0x0A) characters, and native
+ * character codes may be converted to Latin-1. 
+ *
+ * <note><para>
+ *   Line breaks will always be converted; other conversions are more
+ *   questionable. If you write out a file in text mode, and then read it back
+ *   in text mode, high-bit characters (128 to 255) may be transformed or lost.
+ * </para></note>
+ * <note><title>Chimara</title>
+ * <para>
+ * Text mode files in Chimara are in UTF-8, which is GTK+'s native file
+ * encoding.
+ * </para></note>
+ */
+
+/**
+ * fileusage_BinaryMode: 
+ *
+ * The file contents will be stored exactly as they are written, and read back
+ * in the same way. The resulting file may not be viewable on platform-native
+ * text file viewers.
+ */
+
+/**
+ * fileusage_TypeMask:
+ *
+ * Bitwise AND this value with a file usage argument to find whether the file
+ * type is #fileusage_SavedGame, #fileusage_Transcript, #fileusage_InputRecord,
+ * or #fileusage_Data.
+ */
+
+/**
+ * filemode_Write: 
+ *
+ * An output stream.
+ *
+ * <note><para>
+ *   Corresponds to mode <code>"w"</code> in the stdio library, using fopen().
+ * </para></note>
+ */
+
+/** 
+ * filemode_Read: 
+ *
+ * An input stream.
+ *
+ * <note><para>
+ *   Corresponds to mode <code>"r"</code> in the stdio library, using fopen().
+ * </para></note>
+ */
+
+/**
+ * filemode_ReadWrite: 
+ *
+ * Both an input and an output stream.
+ *
+ * <note><para>
+ *   Corresponds to mode <code>"r+"</code> in the stdio library, using fopen().
+ * </para></note>
+ */
+
+/**
+ * filemode_WriteAppend: 
+ *
+ * An output stream, but the data will added to the end of whatever already
+ * existed in the destination, instead of replacing it. 
+ *
+ * <note><para>
+ *   Corresponds to mode <code>"a"</code> in the stdio library, using fopen().
+ * </para></note>
+ */
+/**
+ * seekmode_Start:
+ *
+ * In glk_stream_set_position(), signifies that @pos is counted in characters
+ * after the beginning of the file.
+ */
+/**
+ * seekmode_Current: 
+ *
+ * In glk_stream_set_position(), signifies that @pos is counted in characters
+ * after the current position (moving backwards if @pos is negative.)
+ */
+
+/** 
+ * seekmode_End: 
+ *
+ * In glk_stream_set_position(), signifies that @pos is counted in characters
+ * after the end of the file. (@pos should always be zero or negative, so that
+ * this will move backwards to a  position within the file.
+ */
+
index a6837b14568bca3682d97ecbf5c049822a01a919..8f34f6f1a5fc1ae35bdeb21ef9e63bf5a6898424 100644 (file)
@@ -90,3 +90,4 @@ glk_select(event_t *event)
        /* If an abort event was generated, the thread should have exited by now */
        g_assert(event->type != evtype_Abort);
 }
+
index be4f23f816aa1783c82f6419cef3d2da3168d73b..1486e14e068bc1ba93ff9aeb921e5db8e4f455a4 100644 (file)
@@ -9,20 +9,14 @@ extern ChimaraGlkPrivate *glk_data;
 
 /**
  * glk_fileref_iterate:
- * @fref: A file reference, or #NULL.
- * @rockptr: Return location for the next window's rock, or #NULL.
+ * @fref: A file reference, or %NULL.
+ * @rockptr: Return location for the next fileref's rock, or %NULL.
  *
- * Iterates over the list of file references; if @fref is #NULL, it returns the
- * first file reference, otherwise the next file reference after @fref. If 
- * there are no more, it returns #NULL. The file reference's rock is stored in
- * @rockptr. If you don't want the rocks to be returned, you may set @rockptr 
- * to #NULL.
+ * Iterates through all the existing filerefs. See <link
+ * linkend="chimara-Iterating-Through-Opaque-Objects">Iterating Through Opaque
+ * Objects</link>.
  *
- * The order in which file references are returned is arbitrary. The order may
- * change every time you create or destroy a file reference, invalidating the 
- * iteration.
- *
- * Returns: the next file reference, or #NULL if there are no more.
+ * Returns: the next file reference, or %NULL if there are no more.
  */
 frefid_t
 glk_fileref_iterate(frefid_t fref, glui32 *rockptr)
@@ -46,7 +40,8 @@ glk_fileref_iterate(frefid_t fref, glui32 *rockptr)
  * glk_fileref_get_rock:
  * @fref: A file reference.
  * 
- * Returns the file reference @fref's rock value.
+ * Retrieves the file reference @fref's rock value. See <link 
+ * linkend="chimara-Rocks">Rocks</link>.
  *
  * Returns: A rock value.
  */
@@ -78,13 +73,17 @@ fileref_new(gchar *filename, glui32 rock, glui32 usage, glui32 orig_filemode)
 
 /**
  * glk_fileref_create_temp:
- * @usage: Bitfield with one or more of the #fileusage_ constants.
+ * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
  * @rock: The new fileref's rock value.
  *
  * Creates a reference to a temporary file. It is always a new file (one which
  * does not yet exist). The file (once created) will be somewhere out of the
  * player's way.
  *
+ * <note><para>
+ *   This is why no name is specified; the player will never need to know it.
+ * </para></note>
+ *
  * A temporary file should never be used for long-term storage. It may be
  * deleted automatically when the program exits, or at some later time, say
  * when the machine is turned off or rebooted. You do not have to worry about
@@ -121,18 +120,54 @@ glk_fileref_create_temp(glui32 usage, glui32 rock)
 
 /**
  * glk_fileref_create_by_prompt:
- * @usage: Bitfield with one or more of the #fileusage_ constants.
+ * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
  * @fmode: File mode, contolling the dialog's behavior.
  * @rock: The new fileref's rock value.
  *
- * Creates a reference to a file by opening a file chooser dialog. If @fmode is
- * #filemode_Read, then the file must already exist and the user will be asked
- * to select from existing files. If @fmode is #filemode_Write, then the file
- * should not exist; if the user selects an existing file, he or she will be
- * warned that it will be replaced. If @fmode is #filemode_ReadWrite, then the
- * file may or may not exist; if it already exists, the user will be warned
- * that it will be modified. The @fmode argument should generally match the
- * @fmode which will be used to open the file.
+ * Creates a reference to a file by asking the player to locate it. The library
+ * may simply prompt the player to type a name, or may use a platform-native
+ * file navigation tool. (The prompt, if any, is inferred from the usage
+ * argument.)
+ *
+ * <note><title>Chimara</title>
+ * <para>
+ * Chimara uses a <link 
+ * linkend="gtk-GtkFileChooserDialog">GtkFileChooserDialog</link>.
+ * </para></note>
+ *
+ * @fmode must be one of these values:
+ * <variablelist>
+ * <varlistentry>
+ *   <term>#filemode_Read</term>
+ *   <listitem><para>The file must already exist; and the player will be asked
+ *   to select from existing files which match the usage.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>#filemode_Write</term>
+ *   <listitem><para>The file should not exist; if the player selects an
+ *   existing file, he will be warned that it will be replaced.
+ *   </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>#filemode_ReadWrite</term>
+ *   <listitem><para>The file may or may not exist; if it already exists, the
+ *   player will be warned that it will be modified.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>#filemode_WriteAppend</term>
+ *   <listitem><para>Same behavior as #filemode_ReadWrite.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * The @fmode argument should generally match the @fmode which will be used to
+ * open the file.
+ *
+ * <note><para>
+ *   It is possible that the prompt or file tool will have a 
+ *   <quote>cancel</quote> option. If the player chooses this,
+ *   glk_fileref_create_by_prompt() will return %NULL. This is a major reason
+ *   why you should make sure the return value is valid before you use it.
+ * </para></note>
  *
  * Returns: A new fileref, or #NULL if the fileref creation failed or the
  * dialog was canceled.
@@ -202,14 +237,42 @@ glk_fileref_create_by_prompt(glui32 usage, glui32 fmode, glui32 rock)
 
 /**
  * glk_fileref_create_by_name:
- * @usage: Bitfield with one or more of the #fileusage_ constants.
+ * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
  * @name: A filename.
  * @rock: The new fileref's rock value.
  *
  * This creates a reference to a file with a specific name. The file will be
- * in the same directory as your program, and visible to the player.
+ * in a fixed location relevant to your program, and visible to the player.
+ *
+ * <note><para>
+ *   This usually means <quote>in the same directory as your program.</quote>
+ * </para></note>
+ * <note><title>Chimara</title>
+ * <para>
+ * In Chimara, the file is created in the current working directory.
+ * </para></note>
  *
- * Returns: A new fileref, or #NULL if the fileref creation failed. 
+ * Since filenames are highly platform-specific, you should use
+ * glk_fileref_create_by_name() with care. It is legal to pass any string in the
+ * name argument. However, the library may have to mangle, transform, or
+ * truncate the string to make it a legal native filename. 
+ *
+ * <note><para>
+ *   For example, if you create two filerefs with the names <quote>File</quote>
+ *   and <quote>FILE</quote>, they may wind up pointing to the same file; the
+ *   platform may not support case distinctions in file names. Another example:
+ *   on a platform where file type is specified by filename suffix, the library
+ *   will add an appropriate suffix based on the usage; any suffix in the string
+ *   will be overwritten or added to. For that matter, remember that the period
+ *   is not a legal character in Acorn filenames...
+ * </para></note>
+ *
+ * The most conservative approach is to pass a string of no more than 8
+ * characters, consisting entirely of upper-case letters and numbers, starting
+ * with a letter. You can then be reasonably sure that the resulting filename
+ * will display all the characters you specify &mdash; in some form. 
+ *
+ * Returns: A new fileref, or %NULL if the fileref creation failed. 
  */
 frefid_t
 glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock)
@@ -242,17 +305,34 @@ glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock)
 
 /**
  * glk_fileref_create_from_fileref:
- * @usage: Bitfield with one or more of the #fileusage_ constants.
+ * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
  * @fref: Fileref to copy.
  * @rock: The new fileref's rock value.
  *
  * This copies an existing file reference @fref, but changes the usage. (The
- * original @fref is not modified.)
+ * original fileref is not modified.)
+ *
+ * The use of this function can be tricky. If you change the type of the fileref
+ * (#fileusage_Data, #fileusage_SavedGame, etc), the new reference may or may
+ * not point to the same actual disk file.
  *
- * If you write to a file in text mode and then read from it in binary mode,
- * the results are platform-dependent.
+ * <note><para>
+ *   This generally depends on whether the platform uses suffixes to indicate
+ *   file type.
+ * </para></note>
+ *
+ * If you do this, and open both file references for writing, the results are
+ * unpredictable. It is safest to change the type of a fileref only if it refers
+ * to a nonexistent file.
+ *
+ * If you change the mode of a fileref (#fileusage_TextMode,
+ * #fileusage_BinaryMode), but leave the rest of the type unchanged, the new
+ * fileref will definitely point to the same disk file as the old one.
+ * 
+ * Obviously, if you write to a file in text mode and then read from it in
+ * binary mode, the results are platform-dependent. 
  *
- * Returns: A new fileref, or #NULL if the fileref creation failed. 
+ * Returns: A new fileref, or %NULL if the fileref creation failed. 
  */
 frefid_t
 glk_fileref_create_from_fileref(glui32 usage, frefid_t fref, glui32 rock)
@@ -264,8 +344,9 @@ glk_fileref_create_from_fileref(glui32 usage, frefid_t fref, glui32 rock)
  * glk_fileref_destroy:
  * @fref: Fileref to destroy.
  * 
- * Destroys a fileref which you have created. This does not affect the disk
- * file.
+ * Destroys a fileref which you have created. This does <emphasis>not</emphasis>
+ * affect the disk file; it just reclaims the resources allocated by the
+ * <code>glk_fileref_create...</code> function.
  *
  * It is legal to destroy a fileref after opening a file with it (while the
  * file is still open.) The fileref is only used for the opening operation,
@@ -284,7 +365,7 @@ glk_fileref_destroy(frefid_t fref)
  * glk_fileref_delete_file:
  * @fref: A refrence to the file to delete.
  *
- * Deletes the file referred to by @fref. Does not destroy @fref itself.
+ * Deletes the file referred to by @fref. It does not destroy @fref itself.
  */
 void
 glk_fileref_delete_file(frefid_t fref)
@@ -300,7 +381,8 @@ glk_fileref_delete_file(frefid_t fref)
  *
  * Checks whether the file referred to by @fref exists.
  *
- * Returns: #TRUE (1) if @fref refers to an existing file, #FALSE (0) if not.
+ * Returns: %TRUE (1) if @fref refers to an existing file, and %FALSE (0) if 
+ * not.
  */
 glui32
 glk_fileref_does_file_exist(frefid_t fref)
index 6dcefeddf693d6ac11ba6e60e1c0803c3309ad15..0ee0c47807fa0e597ae55184ed8362a87a731741 100644 (file)
@@ -4,8 +4,15 @@
 #include <gtk/gtk.h>
 #include "glk.h"
 
+/**
+ * glk_fileref_struct:
+ *
+ * This is an opaque structure (see <link linkend="chimara-Opaque-Structures">
+ * Opaque Structures</link> and should not be accessed directly.
+ */
 struct glk_fileref_struct
 {
+       /*< private >*/
        glui32 rock;
        /* Pointer to the list node in the global fileref list that contains this
        fileref */
index 0c3d27b855d8a917f545c218b550c0239008acd1..4b3b19c0a3e5af913fdd06b75dea46c78062c0d9 100644 (file)
@@ -33,32 +33,31 @@ glk_gestalt(glui32 sel, glui32 val)
  * Calls the gestalt system to request information about the capabilities of the
  * API. The selector @sel tells which capability you are requesting information
  * about; the other three arguments are additional information, which may or may
- * not be meaningful. The @arr and @arrlen arguments are always optional; you
- * may always pass %NULL and 0, if you do not want whatever information they
- * represent. glk_gestalt() is simply a shortcut for this; glk_gestalt(x, y) is
- * exactly the same as glk_gestalt_ext(x, y, NULL, 0).
+ * not be meaningful. The @arr and @arrlen arguments of glk_gestalt_ext() are
+ * always optional; you may always pass %NULL and 0, if you do not want whatever
+ * information they represent. glk_gestalt() is simply a shortcut for this;
+ * <code>#glk_gestalt(x, y)</code> is exactly the same as 
+ * <code>#glk_gestalt_ext(x, y, %NULL, 0)</code>.
  *
  * The critical point is that if the Glk library has never heard of the selector
- * sel, it will return 0. It is always safe to call glk_gestalt(x, y) (or
- * glk_gestalt_ext(x, y, NULL, 0)). Even if you are using an old library, which
- * was compiled before the given capability was imagined, you can test for the
- * capability by calling glk_gestalt(); the library will correctly indicate that
- * it does not support it, by returning 0.
+ * @sel, it will return 0. It is <emphasis>always</emphasis> safe to call 
+ * <code>#glk_gestalt(x, y)</code> (or <code>#glk_gestalt_ext(x, y, %NULL, 
+ * 0)</code>). Even if you are using an old library, which was compiled before
+ * the given capability was imagined, you can test for the capability by calling
+ * glk_gestalt(); the library will correctly indicate that it does not support
+ * it, by returning 0.
  *
- * <note><para>
- *  It is also safe to call glk_gestalt_ext(x, y, z, zlen) for an unknown 
- *  selector x, where z is not %NULL, as long as z points at an array of at 
- *  least zlen elements. The selector will be careful not to write beyond that  
- *  point in the array, if it writes to the array at all.
- * </para></note>
+ * (It is also safe to call <code>#glk_gestalt_ext(x, y, z, zlen)</code> for an
+ * unknown selector <code>x</code>, where <code>z</code> is not %NULL, as long
+ * as <code>z</code> points at an array of at least <code>zlen</code> elements.
+ * The selector will be careful not to write beyond that point in the array, if
+ * it writes to the array at all.)
  *
- * <note><para>
- *  If a selector does not use the second argument, you should always pass 0; do
- *  not assume that the second argument is simply ignored. This is because the
- *  selector may be extended in the future. You will continue to get the current
- *  behavior if you pass 0 as the second argument, but other values may produce
- *  other behavior.
- * </para></note>
+ * (If a selector does not use the second argument, you should always pass 0; do
+ * not assume that the second argument is simply ignored. This is because the
+ * selector may be extended in the future. You will continue to get the current
+ * behavior if you pass 0 as the second argument, but other values may produce
+ * other behavior.)
  *
  * Returns: an integer, depending on what selector was called.
  */
index 97673ac4ca11e13bb6d2450f193affbd8a544850..6077dd542d02029a699e3797586d922816de2f5c 100644 (file)
--- a/src/glk.c
+++ b/src/glk.c
@@ -10,18 +10,32 @@ ChimaraGlkPrivate *glk_data = NULL;
 /**
  * glk_exit:
  * 
- * Shuts down the Glk program. This function does not return.
+ * If you want to shut down your program in the middle of your <function>
+ * glk_main()</function> function, you can call glk_exit().
+ *
+ * This function does not return.
  *
  * If you print some text to a window and then shut down your program, you can
- * assume that the player will be able to read it.
+ * assume that the player will be able to read it. Most likely the Glk library
+ * will give a <quote><computeroutput>Hit any key to 
+ * exit</computeroutput></quote> prompt. (There are other possiblities, however.
+ * A terminal-window version of Glk might simply exit and leave the last screen
+ * state visible in the terminal window.)
  *
  * <note><para>
- *  You should only shut down your program with glk_exit() or by returning from
- *  your glk_main() function. If you call the ANSI <function>exit()</function> 
- *  function, bad things may happen. This Glk library is designed for multiple 
- *  sessions, for example, and you would be cutting off all the sessions instead
- *  of just yours. You would also prevent final text from being visible to the 
- *  player.
+ * You should only shut down your program with glk_exit() or by returning from
+ * your <function>glk_main()</function> function. If you call the ANSI 
+ * <function>exit()</function> function, bad things may happen. Some versions of
+ * the Glk library may be designed for multiple sessions, for example, and you
+ * would be cutting off all the sessions instead of just yours. You would 
+ * probably also prevent final text from being visible to the player.
+ * </para></note>
+ * <note><title>Chimara</title>
+ * <para>
+ * If there are any windows open at the time glk_exit() is called, then Chimara
+ * will leave them open. This way, the final text remains visible. Note that bad  
+ * things most definitely <emphasis>will</emphasis> happen if you use the ANSI
+ * <function>exit()</function>.
  * </para></note>
  */
 void
@@ -35,26 +49,39 @@ glk_exit(void)
 /**
  * glk_tick:
  *
- * Many platforms have some annoying thing that has to be done every so often,
- * or the gnurrs come from the voodvork out and eat your computer.
- * 
- * Well, not really. But you should call glk_tick() every so often, just in
- * case. It may be necessary to yield time to other applications in a
- * cooperative-multitasking OS, or to check for player interrupts in an infinite
- * loop.
- * 
- * This call is fast; in fact, on average, it does nothing at all. So you can
- * call it often. (In a virtual machine interpreter, once per opcode is
- * appropriate. In a program with lots of computation, pick a comparable rate.)
+ * Carries out platform-dependent actions such as yielding time to the operating
+ * system and checking for interrupts. glk_tick() should be called every so 
+ * often when there is a long interval between calls of glk_select() or 
+ * glk_select_poll(). This call is fast; in fact, on average, it does nothing at
+ * all. So you can call it often.
+ *
+ * <note><para>
+ *   In a virtual machine interpreter, once per opcode is appropriate. In a
+ *   program with lots of computation, pick a comparable rate.
+ * </para></note>
  * 
  * glk_tick() does not try to update the screen, or check for player input, or
  * any other interface task. For that, you should call glk_select() or 
- * glk_select_poll().
+ * glk_select_poll(). See <link linkend="chimara-Events">Events</link>.
  * 
- * Basically, you must ensure there's some fixed upper bound on the amount of
- * computation that can occur before a glk_tick() (or glk_select()) occurs. In a
- * VM interpreter, where the VM code might contain an infinite loop, this is
- * critical. In a C program, you can often eyeball it.
+ * <note>
+ *   <para>Captious critics have pointed out that in the sample program
+ *   <filename>model.c</filename>, I do not call glk_tick() at all. This is
+ *   because <filename>model.c</filename> has no heavy loops. It does a bit of
+ *   work for each command, and then cycles back to the top of the event loop.
+ *   The glk_select() call, of course, blocks waiting for input, so it does all
+ *   the yielding and interrupt-checking one could imagine.
+ *   </para>
+ *   <para>Basically, you must ensure there's some fixed upper bound on the
+ *   amount of computation that can occur before a glk_tick() (or glk_select())
+ *   occurs. In a VM interpreter, where the VM code might contain an infinite
+ *   loop, this is critical. In a C program, you can often eyeball it.
+ *   </para>
+ *   <para>But the next version of <filename>model.c</filename> will have a
+ *   glk_tick() in the ornate printing loop of <function>verb_yada()</function>.
+ *   Just to make the point.
+ *   </para>
+ * </note>
  */
 void
 glk_tick()
@@ -67,3 +94,4 @@ glk_tick()
                gtk_main_iteration();
        gdk_threads_leave();
 }
+
index 8956c2c53438dad52dd3446d88acd3012c54a1f3..c9775fc77623465c2172ff31b1347aa724375dad 100644 (file)
@@ -1,7 +1,8 @@
 #include "charset.h"
 #include "input.h"
 
-/** glk_request_char_event:
+/** 
+ * glk_request_char_event:
  * @win: A window to request char events from.
  *
  * Request input of a Latin-1 character or special key. A window cannot have 
@@ -21,7 +22,8 @@ glk_request_char_event(winid_t win)
        g_signal_handler_unblock( G_OBJECT(win->widget), win->keypress_handler );
 }
 
-/** glk_request_char_event_uni:
+/** 
+ * glk_request_char_event_uni:
  * @win: A window to request char events from.
  *
  * Request input of a Unicode character or special key. See 
@@ -431,3 +433,4 @@ on_input_entry_activate(GtkEntry *input_entry, winid_t win)
     end_line_input_request(win, text);
        g_free(text);
 }
+
index 7e61dc93b9a4b5183b8e99cc3b9c82571aea6546..bab5b5a2ebc8895eb7facb81d13da2d0e59a9615 100644 (file)
@@ -28,13 +28,9 @@ window_stream_new(winid_t window)
  * @str: A stream, or %NULL.
  * @rockptr: Return location for the next window's rock, or %NULL.
  *
- * Iterates over the list of streams; if @str is %NULL, it returns the first
- * stream, otherwise the next stream after @str. If there are no more, it
- * returns %NULL. The stream's rock is stored in @rockptr. If you don't want
- * the rocks to be returned, you may set @rockptr to %NULL.
- *
- * The order in which streams are returned is arbitrary. The order may change
- * every time you create or destroy a stream, invalidating the iteration.
+ * Iterates through all the existing streams. See <link
+ * linkend="chimara-Iterating-Through-Opaque-Objects">Iterating Through Opaque
+ * Objects</link>.
  *
  * Returns: the next stream, or %NULL if there are no more.
  */
@@ -60,7 +56,8 @@ glk_stream_iterate(strid_t str, glui32 *rockptr)
  * glk_stream_get_rock:
  * @str: A stream.
  * 
- * Returns the stream @str's rock value.
+ * Retrieves the stream @str's rock value. See <link 
+ * linkend="chimara-Rocks">Rocks</link>.
  *
  * Returns: A rock value.
  */
@@ -96,7 +93,7 @@ glk_stream_set_current(strid_t str)
  * 
  * Returns the current stream, or %NULL if there is none.
  *
- * Returns: A stream.
+ * Returns: A stream, or %NULL.
  */
 strid_t
 glk_stream_get_current()
@@ -109,7 +106,8 @@ glk_stream_get_current()
  * @ch: A character in Latin-1 encoding.
  *
  * Prints one character to the current stream. As with all basic functions, the
- * character is assumed to be in the Latin-1 character encoding.
+ * character is assumed to be in the Latin-1 character encoding. See <link
+ * linkend="chimara-Character-Encoding">Character Encoding</link>.
  */
 void
 glk_put_char(unsigned char ch)
@@ -123,7 +121,8 @@ glk_put_char(unsigned char ch)
  * @ch: A Unicode code point.
  *
  * Prints one character to the current stream. The character is assumed to be a
- * Unicode code point.
+ * Unicode code point. See <link linkend="chimara-Character-Encoding">Character
+ * Encoding</link>.
  */
 void
 glk_put_char_uni(glui32 ch)
@@ -137,10 +136,10 @@ glk_put_char_uni(glui32 ch)
  * @s: A null-terminated string in Latin-1 encoding.
  *
  * Prints a null-terminated string to the current stream. It is exactly
- * equivalent to:
+ * equivalent to
  * <informalexample><programlisting>
- * for (ptr = s; *ptr; ptr++)
- *     glk_put_char(*ptr);
+ * for (ptr = @s; *ptr; ptr++)
+ *     #glk_put_char(*ptr);
  * </programlisting></informalexample>
  * However, it may be more efficient.
  */
@@ -174,8 +173,8 @@ glk_put_string_uni(glui32 *s)
  * Prints a block of characters to the current stream. It is exactly equivalent
  * to:
  * <informalexample><programlisting>
- * for (i = 0; i < len; i++)
- *     glk_put_char(buf[i]);
+ * for (i = 0; i < @len; i++)
+ *     #glk_put_char(@buf[i]);
  * </programlisting></informalexample>
  * However, it may be more efficient.
  */
@@ -213,33 +212,10 @@ glk_put_buffer_uni(glui32 *buf, glui32 len)
  * to the buffer where output will be read from or written to. @buflen is the
  * length of the buffer.
  *
- * When outputting, if more than @buflen characters are written to the stream,
- * all of them beyond the buffer length will be thrown away, so as not to
- * overwrite the buffer. (The character count of the stream will still be
- * maintained correctly. That is, it will count the number of characters written
- * into the stream, not the number that fit into the buffer.)
- *
- * If @buf is %NULL, or for that matter if @buflen is zero, then <emphasis>
- * everything</emphasis> written to the stream is thrown away. This may be
- * useful if you are interested in the character count.
- *
- * When inputting, if more than @buflen characters are read from the stream, the
- * stream will start returning -1 (signalling end-of-file.) If @buf is %NULL,
- * the stream will always return end-of-file.
- *
- * The data is written to the buffer exactly as it was passed to the printing
- * functions (glk_put_char(), etc.); input functions will read the data exactly
- * as it exists in memory. No platform-dependent cookery will be done on it.
- * (You can write a disk file in text mode, but a memory stream is effectively
- * always in binary mode.)
- *
  * Unicode values (characters greater than 255) cannot be written to the buffer.
- * If you try, they will be stored as 0x3F ("?") characters.
+ * If you try, they will be stored as 0x3F (<code>"?"</code>) characters.
  *
- * Whether reading or writing, the contents of the buffer are undefined until
- * the stream is closed. The library may store the data there as it is written,
- * or deposit it all in a lump when the stream is closed. It is illegal to
- * change the contents of the buffer while the stream is open.
+ * Returns: the new stream, or %NULL on error.
  */
 strid_t
 glk_stream_open_memory(char *buf, glui32 buflen, glui32 fmode, glui32 rock)
@@ -274,6 +250,8 @@ glk_stream_open_memory(char *buf, glui32 buflen, glui32 fmode, glui32 rock)
  * of 32-bit words, instead of bytes. This allows you to write and read any
  * Unicode character. The @buflen is the number of words, not the number of
  * bytes.
+ * 
+ * Returns: the new stream, or %NULL on error.
  */
 strid_t
 glk_stream_open_memory_uni(glui32 *buf, glui32 buflen, glui32 fmode, glui32 rock)
@@ -389,14 +367,12 @@ file_stream_new(frefid_t fileref, glui32 fmode, glui32 rock, gboolean unicode)
  * already exists, it is truncated down to zero length (an empty file). If
  * @fmode is #filemode_WriteAppend, the file mark is set to the end of the 
  * file.
- * 
- * The file may be written in text or binary mode; this is determined by the
- * @fileref argument. Similarly, platform-dependent attributes such as file 
- * type are determined by @fileref.
  *
  * When writing in binary mode, Unicode values (characters greater than 255)
- * cannot be written to the file. If you try, they will be stored as 0x3F ("?")
- * characters. In text mode, Unicode values are stored in UTF-8.
+ * cannot be written to the file. If you try, they will be stored as 0x3F
+ * (<code>"?"</code>) characters. In text mode, Unicode values may be stored
+ * exactly, approximated, or abbreviated, depending on what the platform's text
+ * files support.
  *
  * Returns: A new stream, or %NULL if the file operation failed.
  */
@@ -417,7 +393,11 @@ glk_stream_open_file(frefid_t fileref, glui32 fmode, glui32 rock)
  * characters are written and read as four-byte (big-endian) values. This
  * allows you to write any Unicode character.
  *
- * In text mode, the file is written and read in UTF-8.
+ * In text mode, the file is written and read in a platform-dependent way, which
+ * may or may not handle all Unicode characters. A text-mode file created with
+ * glk_stream_open_file_uni() may have the same format as a text-mode file
+ * created with glk_stream_open_file(); or it may use a more Unicode-friendly
+ * format.
  *
  * Returns: A new stream, or %NULL if the file operation failed.
  */
@@ -439,7 +419,9 @@ glk_stream_open_file_uni(frefid_t fileref, glui32 fmode, glui32 rock)
  * If @str is the current output stream, the current output stream is set to
  * %NULL.
  *
- * You cannot close window streams; use glk_window_close() instead.
+ * You cannot close window streams; use glk_window_close() instead. See <link
+ * linkend="chimara-Window-Opening-Closing-and-Constraints">Window Opening,
+ * Closing, and Constraints</link>.
  */
 void 
 glk_stream_close(strid_t str, stream_result_t *result)
index 04134f5807f307b592adc5779eaca1208743bc00..25c052e072fc968dae7d2c5d39dc55259d5d6aa8 100644 (file)
@@ -12,8 +12,15 @@ enum StreamType
        STREAM_TYPE_FILE
 };
 
+/**
+ * glk_stream_struct:
+ *
+ * This is an opaque structure (see <link linkend="chimara-Opaque-Structures">
+ * Opaque Structures</link> and should not be accessed directly.
+ */
 struct glk_stream_struct
 {
+       /*< private >*/
        glui32 rock;
        /* Pointer to the list node in the global stream list that contains this
        stream */
index 98140ada9fd1891656722a00d04719440b2332eb..5fa395e855f0f32698eb985244ac7deb51964061 100644 (file)
@@ -279,8 +279,9 @@ write_buffer_to_stream_uni(strid_t str, glui32 *buf, glui32 len)
  * @str: An output stream.
  * @ch: A character in Latin-1 encoding.
  *
- * Prints one character @ch to the stream @str. It is illegal for @str to be
- * %NULL, or an input-only stream.
+ * The same as glk_put_char(), except that you specify a stream @str to print 
+ * to, instead of using the current stream. It is illegal for @str to be %NULL,
+ * or an input-only stream.
  */
 void
 glk_put_char_stream(strid_t str, unsigned char ch)
@@ -296,7 +297,8 @@ glk_put_char_stream(strid_t str, unsigned char ch)
  * @str: An output stream.
  * @ch: A Unicode code point.
  *
- * Prints one character @ch to the stream @str. It is illegal for @str to be
+ * The same as glk_put_char_uni(), except that you specify a stream @str to
+ * print to, instead of using the current stream. It is illegal for @str to be 
  * %NULL, or an input-only stream.
  */
 void
@@ -313,8 +315,9 @@ glk_put_char_stream_uni(strid_t str, glui32 ch)
  * @str: An output stream.
  * @s: A null-terminated string in Latin-1 encoding.
  *
- * Prints @s to the stream @str. It is illegal for @str to be %NULL, or an
- * input-only stream.
+ * The same as glk_put_string(), except that you specify a stream @str to print 
+ * to, instead of using the current stream. It is illegal for @str to be %NULL,
+ * or an input-only stream.
  */
 void
 glk_put_string_stream(strid_t str, char *s)
@@ -330,8 +333,9 @@ glk_put_string_stream(strid_t str, char *s)
  * @str: An output stream.
  * @s: A null-terminated array of Unicode code points.
  *
- * Prints @s to the stream @str. It is illegal for @str to be %NULL, or an
- * input-only stream.
+ * The same as glk_put_string_uni(), except that you specify a stream @str to
+ * print to, instead of using the current stream. It is illegal for @str to be 
+ * %NULL, or an input-only stream.
  */
 void
 glk_put_string_stream_uni(strid_t str, glui32 *s)
@@ -353,8 +357,9 @@ glk_put_string_stream_uni(strid_t str, glui32 *s)
  * @buf: An array of characters in Latin-1 encoding.
  * @len: Length of @buf.
  *
- * Prints @buf to the stream @str. It is illegal for @str to be %NULL, or an
- * input-only stream.
+ * The same as glk_put_buffer(), except that you specify a stream @str to print 
+ * to, instead of using the current stream. It is illegal for @str to be %NULL,
+ * or an input-only stream.
  */
 void
 glk_put_buffer_stream(strid_t str, char *buf, glui32 len)
@@ -371,8 +376,9 @@ glk_put_buffer_stream(strid_t str, char *buf, glui32 len)
  * @buf: An array of Unicode code points.
  * @len: Length of @buf.
  *
- * Prints @buf to the stream @str. It is illegal for @str to be %NULL, or an
- * input-only stream.
+ * The same as glk_put_buffer_uni(), except that you specify a stream @str to
+ * print to, instead of using the current stream. It is illegal for @str to be 
+ * %NULL, or an input-only stream.
  */
 void
 glk_put_buffer_stream_uni(strid_t str, glui32 *buf, glui32 len)
@@ -514,18 +520,27 @@ get_char_stream_common(strid_t str)
  * glk_get_char_stream:
  * @str: An input stream.
  *
- * Reads one character from the stream @str. (There is no notion of a ``current
- * input stream.'') It is illegal for @str to be %NULL, or an output-only
- * stream.
+ * Reads one character from the stream @str. (There is no notion of a
+ * <quote>current input stream.</quote>) It is illegal for @str to be %NULL, or
+ * an output-only stream.
  *
  * The result will be between 0 and 255. As with all basic text functions, Glk
- * assumes the Latin-1 encoding. If the end of the stream has been reached, the
- * result will be -1. Note that high-bit characters (128..255) are
- * <emphasis>not</emphasis> returned as negative numbers.
+ * assumes the Latin-1 encoding. See <link 
+ * linkend="chimara-Character-Encoding">Character Encoding</link>. If the end
+ * of the stream has been reached, the result will be -1. 
+ *
+ * <note><para>
+ *   Note that high-bit characters (128..255) are <emphasis>not</emphasis>
+ *   returned as negative numbers.
+ * </para></note>
  *
- * If the stream contains Unicode data --- for example, if it was created with
- * glk_stream_open_file_uni() or glk_stream_open_memory_uni() --- then
- * characters beyond 255 will be returned as 0x3F ("?").
+ * If the stream contains Unicode data &mdash; for example, if it was created
+ * with glk_stream_open_file_uni() or glk_stream_open_memory_uni() &mdash; then
+ * characters beyond 255 will be returned as 0x3F (<code>"?"</code>).
+ *
+ * It is usually more efficient to read several characters at once with
+ * glk_get_buffer_stream() or glk_get_line_stream(), as opposed to calling
+ * glk_get_char_stream() several times.
  *
  * Returns: A character value between 0 and 255, or -1 on end of stream.
  */
@@ -546,7 +561,7 @@ glk_get_char_stream(strid_t str)
  * Reads one character from the stream @str. The result will be between 0 and 
  * 0x7FFFFFFF. If the end of the stream has been reached, the result will be -1.
  *
- * Returns: A character value between 0 and 255, or -1 on end of stream.
+ * Returns: A value between 0 and 0x7FFFFFFF, or -1 on end of stream.
  */
 glsi32
 glk_get_char_stream_uni(strid_t str)
@@ -759,15 +774,16 @@ glk_get_buffer_stream_uni(strid_t str, glui32 *buf, glui32 len)
  * @buf: A buffer with space for at least @len characters.
  * @len: The number of characters to read, plus one.
  *
- * Reads characters from @str, until either @len - 1 characters have been read
- * or a newline has been read. It then puts a terminal null ('\0') aracter on
+ * Reads characters from @str, until either 
+ * <inlineequation>
+ *   <alt>@len - 1</alt>
+ *   <mathphrase>@len - 1</mathphrase>
+ * </inlineequation>
+ * characters have been read or a newline has been read. It then puts a
+ * terminal null (<code>'\0'</code>) aracter on
  * the end. It returns the number of characters actually read, including the
  * newline (if there is one) but not including the terminal null.
  *
- * It is usually more efficient to read several characters at once with
- * glk_get_buffer_stream() or glk_get_line_stream(), as opposed to calling
- * glk_get_char_stream() several times.
- *
  * Returns: The number of characters actually read.
  */
 glui32
@@ -890,9 +906,13 @@ glk_get_line_stream(strid_t str, char *buf, glui32 len)
  * @buf: A buffer with space for at least @len Unicode code points.
  * @len: The number of characters to read, plus one.
  *
- * Reads Unicode characters from @str, until either @len - 1 Unicode characters
- * have been read or a newline has been read. It then puts a terminal null (a
- * zero value) on the end.
+ * Reads Unicode characters from @str, until either 
+ * <inlineequation>
+ *   <alt>@len - 1</alt>
+ *   <mathphrase>@len - 1</mathphrase>
+ * </inlineequation> 
+ * Unicode characters have been read or a newline has been read. It then puts a
+ * terminal null (a zero value) on the end.
  *
  * Returns: The number of characters actually read, including the newline (if
  * there is one) but not including the terminal null.
@@ -1046,6 +1066,11 @@ glk_get_line_stream_uni(strid_t str, glui32 *buf, glui32 len)
  * a 32-bit word. So in a binary Unicode file, positions are multiples of four
  * bytes.
  *
+ * <note><para>
+ *   If this bothers you, don't use binary Unicode files. I don't think they're
+ *   good for much anyhow.
+ * </para></note>
+ *
  * Returns: position of the read/write mark in @str.
  */
 glui32
@@ -1073,27 +1098,21 @@ glk_stream_get_position(strid_t str)
  * @seekmode: One of #seekmode_Start, #seekmode_Current, or #seekmode_End.
  *
  * Sets the position of the read/write mark in @str. The position is controlled
- * by @pos, and the meaning of @pos is controlled by @seekmode:
- * <itemizedlist>
- *  <listitem>#seekmode_Start: @pos characters after the beginning of the file.
- *  </listitem>
- *  <listitem>#seekmode_Current: @pos characters after the current position
- *  (moving backwards if @pos is negative.)</listitem>
- *  <listitem>#seekmode_End: @pos characters after the end of the file. (@pos
- *  should always be zero or negative, so that this will move backwards to a
- *  position within the file.</listitem>
- * </itemizedlist>
+ * by @pos, and the meaning of @pos is controlled by @seekmode. See the
+ * <code>seekmode_</code> constants below.
+ *
  * It is illegal to specify a position before the beginning or after the end of
  * the file.
  *
- * In binary files, the mark position is exact --- it corresponds with the
+ * In binary files, the mark position is exact &mdash; it corresponds with the
  * number of characters you have read or written. In text files, this mapping 
  * can vary, because of linefeed conventions or other character-set 
- * approximations. glk_stream_set_position() and glk_stream_get_position()
- * measure positions in the platform's native encoding --- after character
- * cookery. Therefore, in a text stream, it is safest to use
- * glk_stream_set_position() only to move to the beginning or end of a file, or
- * to a position determined by glk_stream_get_position().
+ * approximations. See <link linkend="chimara-Streams">Streams</link>.
+ * glk_stream_set_position() and glk_stream_get_position() measure positions in
+ * the platform's native encoding &mdash; after character cookery. Therefore,
+ * in a text stream, it is safest to use glk_stream_set_position() only to move
+ * to the beginning or end of a file, or to a position determined by
+ * glk_stream_get_position().
  *
  * Again, in Latin-1 streams, characters are bytes. In Unicode streams,
  * characters are 32-bit words, or four bytes each.
@@ -1138,4 +1157,4 @@ glk_stream_set_position(strid_t str, glsi32 pos, glui32 seekmode)
                        return;
        }
 }
+
index 54b8aa2d687a47c93f76936cf7e58b809e9ecf9b..bce151662326275c8c91563f92a33fe3b7a9e24b 100644 (file)
@@ -1,19 +1,7 @@
 #include "glk.h"
 
-/**
- * glk_set_style:
- * @val: A style.
- *
- * Changes the style of the current output stream. @val should be one of 
- * #style_Normal, #style_Emphasized, #style_Preformatted, #style_Header,
- * #style_Subheader, #style_Alert, #style_Note, #style_BlockQuote, #style_Input,
- * #style_User1, or #style_User2. However, any value is actually legal; if the
- * library does not recognize the style value, it will treat it as
- * #style_Normal. (This policy allows for the future definition of styles
- * without breaking old Glk libraries.) 
- */
 void
-glk_set_style(glui32 val)
+glk_set_style(glui32 styl)
 {
        /* No nothing yet */
        return;
index 204daa566c8868714d98d18e5ddf9a856f20b8e2..f533cc73da389cc5d5879b29571561fb53af648c 100644 (file)
@@ -8,14 +8,14 @@ extern ChimaraGlkPrivate *glk_data;
  * @win: A window, or %NULL.
  * @rockptr: Return location for the next window's rock, or %NULL.
  *
- * Iterates over the list of windows; if @win is %NULL, it returns the first
- * window, otherwise the next window after @win. If there are no more, it
- * returns #NULL. The window's rock is stored in @rockptr. If you don't want
- * the rocks to be returned, you may set @rockptr to %NULL.
+ * This function can be used to iterate through the list of all open windows
+ * (including pair windows.) See <link 
+ * linkend="chimara-Iterating-Through-Opaque-Objects">Iterating Through Opaque
+ * Objects</link>.
  *
- * The order in which windows are returned is arbitrary. The root window is
- * not necessarily first, nor is it necessarily last. The order may change
- * every time you create or destroy a window, invalidating the iteration.
+ * As that section describes, the order in which windows are returned is
+ * arbitrary. The root window is not necessarily first, nor is it necessarily
+ * last.
  *
  * Returns: the next window, or %NULL if there are no more.
  */
@@ -55,7 +55,7 @@ glk_window_iterate(winid_t win, glui32 *rockptr)
  * @win: A window.
  * 
  * Returns @win's rock value. Pair windows always have rock 0; all other windows
- * have the rock value you created them with.
+ * return whatever rock value you created them with.
  *
  * Returns: A rock value.
  */
@@ -86,9 +86,10 @@ glk_window_get_type(winid_t win)
  * glk_window_get_parent:
  * @win: A window.
  *
- * Returns the window @win's parent window. If @win is the root window, this
- * returns %NULL, since the root window has no parent. Remember that the parent
- * of every window is a pair window; other window types are always childless.
+ * Returns the window which is the parent of @win. If @win is the root window,
+ * this returns %NULL, since the root window has no parent. Remember that the
+ * parent of every window is a pair window; other window types are always
+ * childless.
  *
  * Returns: A window, or %NULL.
  */
@@ -104,8 +105,8 @@ glk_window_get_parent(winid_t win)
  * glk_window_get_sibling:
  * @win: A window.
  *
- * Returns the other child of the window @win's parent. If @win is the
- * root window, this returns %NULL.
+ * Returns the other child of @win's parent. If @win is the root window, this
+ * returns %NULL.
  *
  * Returns: A window, or %NULL.
  */
@@ -161,10 +162,169 @@ text_window_get_char_size(GtkWidget *textview, int *width, int *height)
  * #wintype_TextBuffer, or #wintype_Graphics.
  * @rock: The new window's rock value.
  *
- * If there are no windows, create a new root window. @split must be 0, and
- * @method and @size are ignored. Otherwise, split window @split into two, with
- * position, size, and type specified by @method, @size, and @wintype. See the
- * Glk documentation for the window placement algorithm.
+ * 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 &mdash; 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
+ * &mdash; that is, the two new parts together &mdash; 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
+ * &mdash; 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>
  *
  * Returns: the new window, or %NULL on error.
  */
@@ -416,7 +576,39 @@ glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype,
  * the same thing.) 
  *
  * The @result argument is filled with the output character count of the window
- * stream.
+ * stream. See <link linkend="chimara-Streams">Streams</link> and <link
+ * linkend="chimara-Closing-Streams">Closing Streams</link>.
+ * 
+ * When you close a window (and it is not the root window), the other window
+ * in its pair takes over all the freed-up area. Let's close D, in the current
+ * example:
+ * <mediaobject><textobject><phrase>Screen shot 10</phrase></textobject>
+ * </mediaobject>
+ * 
+ * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right
+ * split has gone with it. The other size constraints are unchanged; O2 is
+ * still committed to giving its upper child two rows, as measured in the font
+ * of O2's key window, which is C. Conveniently, O2's upper child is C, just as
+ * it was before we created D. In fact, now that D is gone, everything is back
+ * to the way it was before we created D.
+ * 
+ * But what if we had closed C instead of D? We would have gotten this:
+ * <mediaobject><textobject><phrase>Screen shot 11</phrase></textobject>
+ * </mediaobject>
+ * 
+ * Again, O3 is gone. But D has collapsed to zero height. This is because its
+ * height is controlled by O2, and O2's key window was C, and C is now gone. O2
+ * no longer has a key window at all, so it cannot compute a height for its
+ * upper child, so it defaults to zero.
+ * 
+ * <note><para>
+ *   This may seem to be an inconvenient choice. That is deliberate. You should
+ *   not leave a pair window with no key, and the zero-height default reminds
+ *   you not to. You can use glk_window_set_arrangement() to set a new split
+ *   measurement and key window. See <link 
+ *   linkend="chimara-Changing-Window-Constraints">Changing Window
+ *   Constraints</link>.
+ * </para></note>
  */
 void
 glk_window_close(winid_t win, stream_result_t *result)
@@ -490,26 +682,36 @@ glk_window_close(winid_t win, stream_result_t *result)
  * glk_window_clear:
  * @win: A window.
  *
- * Erases the window @win. The meaning of this depends on the window type.
- *
- * <itemizedlist>
- *  <listitem><para>
- *   Text buffer: This may do any number of things, such as delete all text in 
- *   the window, or print enough blank lines to scroll all text beyond 
- *   visibility, or insert a page-break marker which is treated specially by the
- *   display part of the library.
- *  </para></listitem>
+ * Erases @win. The meaning of this depends on the window type.
+ * <variablelist>
+ * <varlistentry>
+ *  <term>Text buffer</term>
  *  <listitem><para>
- *   Text grid: This will clear the window, filling all positions with blanks.
- *   The window cursor is moved to the top left corner (position 0,0).
+ *   This may do any number of things, such as delete all text in the window, or
+ *   print enough blank lines to scroll all text beyond visibility, or insert a
+ *   page-break marker which is treated specially by the display part of the
+ *   library.
  *  </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *  <term>Text grid</term>
  *  <listitem><para>
- *   Graphics: Clears the entire window to its current background color.
+ *   This will clear the window, filling all positions with blanks. The window
+ *   cursor is moved to the top left corner (position 0,0).
  *  </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *  <term>Graphics</term>
  *  <listitem><para>
- *   Other window types: No effect. 
+ *   Clears the entire window to its current background color. See <link
+ *   linkend="chimara-Graphics-Windows">Graphics Windows</link>.
  *  </para></listitem>
- * </itemizedlist>
+ * </varlistentry>
+ * <varlistentry>
+ *  <term>Other window types</term>
+ *  <listitem><para>No effect.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
  *
  * It is illegal to erase a window which has line input pending. 
  */
@@ -578,9 +780,7 @@ glk_window_clear(winid_t win)
  * @win: A window.
  *
  * Sets the current stream to @win's window stream. It is exactly equivalent to
- * <informalexample><programlisting>
- *  glk_stream_set_current(glk_window_get_stream(win))
- * </programlisting></informalexample>
+ * <code>#glk_stream_set_current(#glk_window_get_stream(@win))</code>.
  */
 void
 glk_set_window(winid_t win)
@@ -592,11 +792,16 @@ glk_set_window(winid_t win)
  * glk_window_get_stream:
  * @win: A window.
  *
- * Returns the stream which is associated with @win. Every window has a stream
- * which can be printed to, but this may not be useful, depending on the window
- * type. (For example, printing to a blank window's stream has no effect.)
+ * Returns the stream which is associated with @win. (See <link 
+ * linkend="chimara-Window-Streams">Window Streams</link>.) Every window has a
+ * stream which can be printed to, but this may not be useful, depending on the
+ * window type.
+ * 
+ * <note><para>
+ *   For example, printing to a blank window's stream has no effect.
+ * </para></note>
  *
- * Returns: The window stream.
+ * Returns: A window stream.
  */
 strid_t glk_window_get_stream(winid_t win)
 {
@@ -609,23 +814,14 @@ strid_t glk_window_get_stream(winid_t win)
  * @win: A window.
  * @str: A stream to attach to the window, or %NULL.
  *
- * Attaches the stream @str to @win as a second stream. Any text printed to the
- * window is also echoed to this second stream, which is called the window's
- * "echo stream."
- *
- * Effectively, any call to glk_put_char() (or the other output commands) which
- * is directed to @win's window stream, is replicated to @win's echo stream.
- * This also goes for the style commands such as glk_set_style().
- *
- * Note that the echoing is one-way. You can still print text directly to the
- * echo stream, and it will go wherever the stream is bound, but it does not
- * back up and appear in the window.
- *
- * It is illegal to set a window's echo stream to be its own window stream,
- * which would create an infinite loop. It is similarly illegal to create a
- * longer loop (two or more windows echoing to each other.)
+ * Sets @win's echo stream to @str, which can be any valid output stream. You
+ * can reset a window to stop echoing by calling 
+ * <code>#glk_window_set_echo_stream(@win, %NULL)</code>.
  *
- * You can reset a window to stop echoing by setting @str to %NULL.
+ * It is illegal to set a window's echo stream to be its 
+ * <emphasis>own</emphasis> window stream. That would create an infinite loop,
+ * and is nearly certain to crash the Glk library. It is similarly illegal to
+ * create a longer loop (two or more windows echoing to each other.)
  */
 void
 glk_window_set_echo_stream(winid_t win, strid_t str)
@@ -651,8 +847,8 @@ glk_window_set_echo_stream(winid_t win, strid_t str)
  * glk_window_get_echo_stream:
  * @win: A window.
  *
- * Returns the echo stream of window @win. If the window has no echo stream (as
- * is initially the case) then this returns %NULL.
+ * Returns the echo stream of window @win. Initially, a window has no echo
+ * stream, so <code>#glk_window_get_echo_stream(@win)</code> will return %NULL.
  *
  * Returns: A stream, or %NULL.
  */
@@ -670,8 +866,11 @@ glk_window_get_echo_stream(winid_t win)
  * @heightptr: Pointer to a location to store the window's height, or %NULL.
  *
  * Simply returns the actual size of the window, in its measurement system.
- * Either @widthptr or @heightptr can be %NULL, if you only want one 
- * measurement. (Or, in fact, both, if you want to waste time.)
+ * As described in <link linkend="chimara-Other-API-Conventions">Other API 
+ * Conventions</link>, either @widthptr or @heightptr can be %NULL, if you
+ * only want one measurement. 
+ *
+ * <note><para>Or, in fact, both, if you want to waste time.</para></note>
  */
 void
 glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr)
@@ -727,7 +926,7 @@ glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr)
             g_warning("glk_window_get_size: Unsupported window type");
     }
 }
-
 /**
  * glk_window_move_cursor:
  * @win: A text grid window.
@@ -739,9 +938,9 @@ glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr)
  * beginning of the next line.
  * 
  * If you move the cursor below the last line, or when the cursor reaches the
- * end of the last line, it goes "off the screen" and further output has no
- * effect. You must call glk_window_move_cursor() or glk_window_clear() to move
- * the cursor back into the visible region.
+ * end of the last line, it goes <quote>off the screen</quote> and further
+ * output has no effect. You must call glk_window_move_cursor() or
+ * glk_window_clear() to move the cursor back into the visible region.
  * 
  * <note><para>
  *  Note that the arguments of glk_window_move_cursor() are <type>unsigned 
@@ -754,8 +953,8 @@ glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr)
  *  Also note that the output cursor is not necessarily visible. In particular,
  *  when you are requesting line or character input in a grid window, you cannot
  *  rely on the cursor position to prompt the player where input is indicated.
- *  You should print some character prompt at that spot -- a ">" character, for
- *  example.
+ *  You should print some character prompt at that spot &mdash; a 
+ *  <quote>&gt;</quote> character, for example.
  * </para></note>
  */
 void
@@ -787,3 +986,4 @@ glk_window_move_cursor(winid_t win, glui32 xpos, glui32 ypos)
        
        gdk_threads_leave();
 }
+
index 7a140991e171bbf0be467b2441e151091dc14e36..30fe53d8834b3d2237bd1c2c4205699d6c827a33 100644 (file)
@@ -18,8 +18,15 @@ enum InputRequestType
        INPUT_REQUEST_LINE_UNICODE
 };
 
+/**
+ * glk_window_struct:
+ *
+ * This is an opaque structure (see <link linkend="chimara-Opaque-Structures">
+ * Opaque Structures</link> and should not be accessed directly.
+ */
 struct glk_window_struct
 {
+       /*< private >*/
        glui32 rock;
        /* Pointer to the node in the global tree that contains this window */
        GNode *window_node;