X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fdoc.c;h=277245c452714be615ed09c4525fca0f30282dc8;hb=07959e767424a4779abbac3a73fe626ba89ea566;hp=219992cf22264f6633ec8aecaf8540bf84ff667b;hpb=cae962752aef9b5edd99c7353842d18807d38fa9;p=projects%2Fchimara%2Fchimara.git
diff --git a/libchimara/doc.c b/libchimara/doc.c
index 219992c..277245c 100644
--- a/libchimara/doc.c
+++ b/libchimara/doc.c
@@ -586,6 +586,28 @@
* A stream is opened with a particular file mode, see the
* filemode_ constants below.
*
+ *
+ * In the stdio library, using fopen(), %filemode_Write would be mode
+ * "w"; %filemode_Read would be mode "r";
+ * %filemode_ReadWrite would be mode "r+". Confusingly,
+ * %filemode_WriteAppend cannot be mode "a", because the stdio
+ * spec says that when you open a file with mode "a", then
+ * fseek() doesn't work. So we have to use mode "r+" for
+ * appending. Then we run into the other stdio problem,
+ * which is that "r+" never creates a new file. So
+ * %filemode_WriteAppend has to first open the file with
+ * "a", close it, reopen with "r+", and then
+ * fseek() to the end of the file. For %filemode_ReadWrite, the process is
+ * the same, except without the fseek() — we begin at the beginning of
+ * the file.
+ *
+ *
+ * We must also obey an obscure geas of ANSI C "r+" files: you
+ * can't switch from reading to writing without doing an fseek() in between.
+ * Switching from writing to reading has the same restriction, except that an
+ * fflush() also works.
+ *
+ *
* For information on opening streams, see the discussion of each specific type
* of stream in The Types of
* Streams. Remember that it is always possible that opening a stream
@@ -1045,10 +1067,15 @@
* SECTION:glk-sound-testing
* @short_description: Checking whether the library supports sound
*
- * Before calling Glk sound functions, you should use the %gestalt_Sound
- * selector. To test for additional capabilities, you can use the
- * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify
- * selectors.
+ * Before calling Glk sound functions, you should use the %gestalt_Sound2
+ * selector.
+ *
+ * Earlier versions of the Glk spec defined separate selectors for various
+ * optional capabilities. This has proven to be an unnecessarily confusing
+ * strategy, and is no longer used. The %gestalt_Sound, %gestalt_SoundMusic,
+ * %gestalt_SoundVolume, and %gestalt_SoundNotify selectors still exist, but you
+ * should not need to test them; the %gestalt_Sound2 selector covers all of
+ * them.
*/
/**
@@ -1103,8 +1130,8 @@
* SECTION:glk-clock-testing
* @short_description: Checking whether the library supports the clock functions
*
- * Before calling Glk date and time functions, you should use the following
- * gestalt selector.
+ * Before calling Glk date and time functions, you should use the
+ * %gestalt_DateTime selector.
*/
/**
@@ -1308,7 +1335,7 @@
*/
/**
- * GLK_MODULE_SOUND:
+ * GLK_MODULE_SOUND2:
*
* If you are writing a C program, there is an additional complication. A
* library which does not support sound may not implement the sound functions at
@@ -1318,9 +1345,17 @@
* even get compile-time errors.
*
* To avoid this, you can perform a preprocessor test for the existence of
- * %GLK_MODULE_SOUND. If this is defined, so are all the functions and constants
+ * %GLK_MODULE_SOUND2. If this is defined, so are all the functions and constants
* described in this section. If not, not.
- */
+ */
+
+/**
+ * GLK_MODULE_SOUND:
+ *
+ * You can perform a preprocessor test for the existence of %GLK_MODULE_SOUND.
+ * If this is defined, so are all the functions and constants described in this
+ * section. If not, not.
+ */
/**
* GLK_MODULE_HYPERLINKS:
@@ -1405,8 +1440,8 @@
* So the version number 78.2.11 would be encoded as 0x004E020B.
*
*
- * The current Glk specification version is 0.7.2, so this selector will return
- * 0x00000702.
+ * The current Glk specification version is 0.7.3, so this selector will return
+ * 0x00000703.
*
* |[
* glui32 res;
@@ -1577,10 +1612,24 @@
* may implement both, neither, or only one.
*/
+/**
+ * gestalt_Sound2:
+ *
+ * You can test whether the library supports sound:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Sound2, 0);
+ * ]|
+ * This returns 1 if the overall suite of sound functions is available. This
+ * includes all the functions defined in this chapter. It also includes the
+ * capabilities described below under %gestalt_SoundMusic, %gestalt_SoundVolume,
+ * and %gestalt_SoundNotify.
+ */
+
/**
* gestalt_Sound:
*
- * You can test whether the library supports sound:
* |[
* glui32 res;
* res = glk_gestalt(gestalt_Sound, 0);
@@ -1592,7 +1641,9 @@
* glk_sound_load_hint().
*
* If this selector returns 0, you should not try to call these functions. They
- * may have no effect, or they may cause a run-time error.
+ * may have no effect, or they may cause a run-time error.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
@@ -1600,24 +1651,22 @@
*
* You can test whether the library supports setting the volume of sound
* channels:
- * |[
- * glui32 res;
- * res = glk_gestalt(gestalt_SoundVolume, 0);
- * ]|
+ * |[ res = glk_gestalt(gestalt_SoundVolume, 0); ]|
* This selector returns 1 if the glk_schannel_set_volume() function works. If
- * it returns zero, glk_schannel_set_volume() has no effect.
+ * it returns zero, glk_schannel_set_volume() has no effect.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
* gestalt_SoundNotify:
*
* You can test whether the library supports sound notification events:
- * |[
- * glui32 res;
- * res = glk_gestalt(gestalt_SoundNotify, 0);
- * ]|
+ * |[ res = glk_gestalt(gestalt_SoundNotify, 0); ]|
* This selector returns 1 if the library supports sound notification events. If
- * it returns zero, you will never get such events.
+ * it returns zero, you will never get such events.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
@@ -1661,6 +1710,8 @@
* course, an ugly hack. It is a concession to the current state of the Glk
* libraries, some of which can handle AIFF but not MOD sounds.
*
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
@@ -1772,7 +1823,8 @@
* ]|
*
* This returns 1 if the overall suite of system clock functions, as described
- * in this chapter, is available.
+ * in this chapter, is
+ * available.
*
* If this selector returns 0, you should not try to call these functions. They
* may have no effect, or they may cause a run-time error.
@@ -1943,6 +1995,8 @@
/**
* evtype_SoundNotify:
*
+ * The completion of a sound being played in a sound channel.
+ *
* On platforms that support sound, you can request to receive an
* %evtype_SoundNotify event when a sound finishes playing. See Playing Sounds.
@@ -1950,6 +2004,8 @@
/**
* evtype_Hyperlink:
+ *
+ * The selection of a hyperlink in a window.
*
* On platforms that support hyperlinks, you can request to receive an
* %evtype_Hyperlink event when the player selects a link. See .
*/
+/**
+ * evtype_VolumeNotify:
+ *
+ * The completion of a gradual volume change in a sound channel.
+ *
+ * On platforms that support sound, you can request to receive an
+ * %evtype_VolumeNotify event when a gradual volume change completes. See Playing Sounds.
+ */
+
/**
* event_t:
* @type: the event type
@@ -2531,6 +2597,12 @@
* When calling glk_window_open() with this @method, it specifies that there
* should be a visible window border between the new window and its sibling.
* (This is a hint to the library.)
+ *
+ * Chimara
+ * There will only be a visible border if the #ChimaraGlk:spacing property
+ * is nonzero. Setting #ChimaraGlk:spacing to zero disables all borders on Glk
+ * windows.
+ *
*/
/**
@@ -2575,7 +2647,7 @@
* 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.
+ * character codes may be converted to Latin-1 or UTF-8.
*
*
* Line breaks will always be converted; other conversions are more