From c4142afddd5b220686eb64c4bd346a722f9e20c1 Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Sat, 11 Feb 2012 15:20:35 +0100 Subject: [PATCH] Update documentation to match Glk 0.7.4 spec --- docs/reference/blorb.sgml | 2 +- docs/reference/chimara-sections.txt | 4 ++ docs/reference/glk-front-matter.sgml | 6 +- docs/reference/glk-introduction.sgml | 2 +- libchimara/doc.c | 42 ++++++++++- libchimara/fileref.c | 103 ++++++++++++++++++++++----- 6 files changed, 134 insertions(+), 25 deletions(-) diff --git a/docs/reference/blorb.sgml b/docs/reference/blorb.sgml index 28659f8..fb0cdf8 100644 --- a/docs/reference/blorb.sgml +++ b/docs/reference/blorb.sgml @@ -29,7 +29,7 @@ This is for historical reasons; Infocom's Z-machine architecture used this schem For the complete Blorb specification and tools for Blorb file manipulation, see: -http://www.eblong.com/zarf/blorb/ + How This Works diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index d7aa8e3..8668f38 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -141,6 +141,8 @@ gestalt_HyperlinkInput gestalt_SoundMusic gestalt_GraphicsTransparency gestalt_DateTime +gestalt_ResourceStream +GLK_MODULE_RESOURCE_STREAM
@@ -419,6 +421,8 @@ glk_stream_open_memory glk_stream_open_memory_uni glk_stream_open_file glk_stream_open_file_uni +glk_stream_open_resource +glk_stream_open_resource_uni
diff --git a/docs/reference/glk-front-matter.sgml b/docs/reference/glk-front-matter.sgml index 0359a44..102fa0c 100644 --- a/docs/reference/glk-front-matter.sgml +++ b/docs/reference/glk-front-matter.sgml @@ -4,7 +4,7 @@ ]> Glk API Specification -API version 0.7.3 +API version 0.7.4 Andrew @@ -13,7 +13,7 @@ erkyrath@eblong.com - 1998–2011 + 1998–2012 Andrew Plotkin @@ -26,6 +26,6 @@ Anyone is free to write programs that use the Glk API or libraries that implemen -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: http://www.eblong.com/zarf/glk/ +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: diff --git a/docs/reference/glk-introduction.sgml b/docs/reference/glk-introduction.sgml index ec28979..aeacbec 100644 --- a/docs/reference/glk-introduction.sgml +++ b/docs/reference/glk-introduction.sgml @@ -45,7 +45,7 @@ You can think of Glk as an IF virtual machine, without the virtual machine part. 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. -For more discussion of this approach, see Glk and the Virtual Machine. Glulx is documented at http://www.eblong.com/zarf/glulx. +For more discussion of this approach, see Glk and the Virtual Machine. Glulx is documented at http://eblong.com/zarf/glulx. 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.) diff --git a/libchimara/doc.c b/libchimara/doc.c index 277245c..ab842bb 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -800,7 +800,7 @@ /** * SECTION:glk-stream-types - * @short_description: Window, memory, and file streams + * @short_description: Window, memory, file, and resource streams * * Window Streams * @@ -863,6 +863,30 @@ * linkend="chimara-File-References">File References. * * + * Resource Streams + * + * You can open a stream which reads from (but not writes to) a resource file. + * + * + * Typically this is embedded in a Blorb file, as Blorb is the official + * resource-storage format of Glk. A Blorb file can contain images and sounds, + * but it can also contain raw data files, which are accessed by + * glk_stream_open_resource() and glk_stream_open_resource_uni(). A data file + * is identified by number, not by a filename. The Blorb usage field will be + * 'Data'. The chunk type will be 'TEXT' for text + * resources, 'BINA' for binary resources. + * + * + * + * If the running program is not associated with a Blorb file, the library may + * look for data files as actual files instead. These would be named + * DATA1, DATA2, etc, with a suffix + * distinguishing text and binary files. See Other Resource + * Arrangements in the Blorb spec: + * + * + * */ /** @@ -1440,8 +1464,8 @@ * So the version number 78.2.11 would be encoded as 0x004E020B. * * - * The current Glk specification version is 0.7.3, so this selector will return - * 0x00000703. + * The current Glk specification version is 0.7.4, so this selector will return + * 0x00000704. * * |[ * glui32 res; @@ -1834,6 +1858,18 @@ * */ +/** + * gestalt_ResourceStream: + * + * |[ + * res = glk_gestalt(gestalt_ResourceStream, 0); + * ]| + * + * This returns 1 if the glk_stream_open_resource() and + * glk_stream_open_resource_uni() functions are available. If it returns 0, you + * should not call them. + */ + /** * evtype_None: * diff --git a/libchimara/fileref.c b/libchimara/fileref.c index 24e96eb..3db89a2 100644 --- a/libchimara/fileref.c +++ b/libchimara/fileref.c @@ -204,6 +204,11 @@ glk_fileref_create_temp(glui32 usage, glui32 rock) * value is valid before you use it. * * + * The recommended file suffixes for files are .glkdata for + * %fileusage_Data, .glksave for %fileusage_SavedGame, + * .txt for %fileusage_Transcript and + * %fileusage_InputRecord. + * * Returns: A new fileref, or #NULL if the fileref creation failed or the * dialog was canceled. */ @@ -292,25 +297,89 @@ glk_fileref_create_by_prompt(glui32 usage, glui32 fmode, glui32 rock) * glkunix_set_base_file(), and otherwise in the current working directory. * * - * 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. + * Earlier versions of the Glk spec specified that the library may have to + * extend, truncate, or change your name argument in order to produce a legal + * native filename. This remains true. However, since Glk was originally + * proposed, the world has largely reached consensus about what a filename looks + * like. Therefore, it is worth including some recommended library behavior + * here. Libraries that share this behavior will more easily be able to exchange + * files, which may be valuable both to authors (distributing data files for + * games) and for players (moving data between different computers or different + * applications). + * + * The library should take the given filename argument, and delete any + * characters illegal for a filename. This will include all of the following + * characters (and more, if the OS requires it): slash, backslash, angle + * brackets (less-than and greater-than), colon, double-quote, pipe (vertical + * bar), question-mark, asterisk. The library should also truncate the argument + * at the first period (delete the first period and any following characters). + * If the result is the empty string, change it to the string + * "null". + * + * It should then append an appropriate suffix, depending on the usage: + * .glkdata for %fileusage_Data, + * .glksave for %fileusage_SavedGame, + * .txt for %fileusage_Transcript and + * %fileusage_InputRecord. + * + * The above behavior is not a requirement of the Glk spec. Older + * implementations can continue doing what they do. Some programs (e.g. + * web-based interpreters) may not have access to a traditional filesystem at + * all, and to them these recommendations will be meaningless. + * + * On the other side of the coin, the game file should not press these + * limitations. Best practice is for the game to pass a filename containing only + * letters and digits, beginning with a letter, and not mixing upper and lower + * case. Avoid overly-long filenames. * * - * For example, if you create two filerefs with the names File - * and FILE, 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... + * The earlier Glk spec gave more stringent recommendations: No more + * than 8 characters, consisting entirely of upper-case letters and numbers, + * starting with a letter. The DOS era is safely contained, if not + * over, so this has been relaxed. The I7 manual recommends 23 + * characters or fewer. * * - * 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 — in some form. + * + * To address other complications: + * + * + * Some filesystems are case-insensitive. If you create two filerefs with + * the names File and FILE, they + * may wind up pointing to the same file, or they may not. Avoid doing + * this. + * + * + * Some programs will look for all files in the same directory as the + * program itself (or, for interpreted games, in the same directory as the + * game file). Others may keep files in a data-specific directory + * appropriate for the user (e.g., ~/Library on MacOS). + * + * + * If a game interpreter uses a data-specific directory, there is a + * question of whether to use a common location, or divide it into + * game-specific subdirectories. (Or to put it another way: should the + * namespace of named files be per-game or app-wide?) Since data files may + * be exchanged between games, they should be given an app-wide namespace. + * In contrast, saved games should be per-game, as they can never be + * exchanged. Transcripts and input records can go either way. + * + * + * When updating an older library to follow these recommendations, + * consider backwards compatibility for games already installed. When + * opening an existing file (that is, not in a write-only mode) it may be + * worth looking under the older name (suffix) if the newer one does not + * already exist. + * + * + * Game-save files are already stored with a variety of file suffixes, + * since that usage goes back to the oldest IF interpreters, long + * predating Glk. It is reasonable to treat them in some special way, + * while hewing closer to these recommendations for data files. + * + * + * * * Returns: A new fileref, or %NULL if the fileref creation failed. */ @@ -365,8 +434,8 @@ glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock) * not point to the same actual disk file. * * - * This generally depends on whether the platform uses suffixes to indicate - * file type. + * Most platforms use suffixes to indicate file type, so it typically will + * not. See the earlier comments about recommended file suffixes. * * * If you do this, and open both file references for writing, the results are -- 2.30.2