From bae31a7df18ecafe05ec1a11b0961708bc3badd6 Mon Sep 17 00:00:00 2001 From: fliep Date: Tue, 26 May 2009 20:07:59 +0000 Subject: [PATCH] Brought all the Gtk-Doc documentation up to date with where we are so far. --- docs/reference/blorb-library.sgml | 31 + docs/reference/blorb.sgml | 37 ++ docs/reference/chimara-docs.sgml | 30 +- docs/reference/chimara-sections.txt | 85 ++- docs/reference/glk-porting.sgml | 178 ++++++ libchimara/chimara-glk.c | 2 +- libchimara/doc.c | 951 +++++++++++++++++++++++++--- libchimara/fileref.c | 16 +- libchimara/input.c | 2 +- libchimara/resource.c | 14 +- libchimara/stream.c | 24 +- libchimara/strio.c | 2 +- libchimara/style.c | 49 +- libchimara/timer.c | 58 +- libchimara/window.c | 36 +- 15 files changed, 1339 insertions(+), 176 deletions(-) create mode 100644 docs/reference/blorb-library.sgml create mode 100644 docs/reference/blorb.sgml create mode 100644 docs/reference/glk-porting.sgml diff --git a/docs/reference/blorb-library.sgml b/docs/reference/blorb-library.sgml new file mode 100644 index 0000000..c333f02 --- /dev/null +++ b/docs/reference/blorb-library.sgml @@ -0,0 +1,31 @@ + + + + +What the Library Does +3 +CHIMARA Library + + +What the Library Does +How to implement the Blorb layer in your library + + +Description + +Each library must implement giblorb_set_resource_map(), if it wishes to support Blorb at all. Generally, this function should create a Blorb map and stash it away somewhere. It may also want to stash the stream itself, so that the library can read data directly from it. + + +giblorb_set_resource_map() should return giblorb_err_None (0) if it succeeded, or the appropriate Blorb error code if not. See Blorb Errors. + + +The library must also link in the gi_blorb.c file. Most of this should compile without difficulty on any platform. However, it does need to allocate memory. As supplied, gi_blorb.c calls the ANSI functions malloc(), realloc(), and free(). If this is not appropriate on your OS, feel free to change these calls. They are isolated at the end of the file. + +Chimara + +The Chimara library uses the GLib functions g_malloc(), g_realloc(), and g_free() because of their additional error-checking features. + + + diff --git a/docs/reference/blorb.sgml b/docs/reference/blorb.sgml new file mode 100644 index 0000000..eeafe8e --- /dev/null +++ b/docs/reference/blorb.sgml @@ -0,0 +1,37 @@ + + + + +The Blorb Layer +3 +CHIMARA Library + + +The Blorb Layer +Loading resources from a Blorb file + + +Description + +The material described in this section is not part of the Glk API per se. It is an external layer which allows the library to load resources (images and sounds) from a file specified by your program. The Blorb file format is a standard IF resource archive. + + +The Glk spec does not require that resources be stored in a Blorb file. It says only that the library knows how to load them and use them, when you so request. However, Blorb is the recommended way to supply portable resources. Most Glk libraries will support Blorb, using the interface defined in this section. + + +For the complete Blorb specification and tools for Blorb file manipulation, see: +http://www.eblong.com/zarf/blorb/ + + +How This Works + +The Blorb layer is implemented in a C source file, gi_blorb.c, and its header, gi_blorb.h. This code is (mostly) platform-independent — it is identical in every library, just as the glk.h header file is identical in every library. Each library author who wants to support Blorb should download the gi_blorb.c and gi_blorb.h files from the Glk web site, and compile them unchanged into the library. + + +Most of the functions defined in gi_blorb.h are intended for the library. If you are writing a Glk program, you can ignore them all, except for giblorb_set_resource_map(); see What the Program Does. If you are implementing a Glk library, you can use this API to find and load resource data. + + + + diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml index d003476..208c237 100644 --- a/docs/reference/chimara-docs.sgml +++ b/docs/reference/chimara-docs.sgml @@ -68,12 +68,8 @@ - - - - - --> @@ -85,7 +81,9 @@ - + + + @@ -125,18 +123,26 @@ --> - + + The Blorb Layer + + + + + + + + + Glk Extensions + + ---> diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index 3b06c4f..2281bfb 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -305,12 +305,6 @@ seekmode_End Styles glk_set_style glk_set_style_stream - -glk_stylehint_set -glk_stylehint_clear - -glk_style_distinguish -glk_style_measure style_Normal style_Emphasized @@ -324,6 +318,14 @@ style_Input style_User1 style_User2 style_NUMSTYLES + + +
+glk-stylehints +Suggesting the Appearance of Styles +glk_stylehint_set +glk_stylehint_clear + stylehint_Indentation stylehint_ParaIndentation stylehint_Justification @@ -341,6 +343,13 @@ stylehint_just_Centered stylehint_just_RightFlush
+
+glk-style-measure +Testing the Appearance of Styles +glk_style_distinguish +glk_style_measure +
+
glk-stream-types The Types of Streams @@ -472,3 +481,67 @@ glk_cancel_hyperlink_event GLK_MODULE_HYPERLINKS
+
+blorb-program +What the Program Does +giblorb_set_resource_map +giblorb_get_resource_map +giblorb_map_t +
+ +
+blorb-layer +What the Blorb Layer Does +giblorb_create_map +giblorb_destroy_map +giblorb_result_t +giblorb_load_chunk_by_type +giblorb_load_chunk_by_number +giblorb_unload_chunk +giblorb_load_resource +giblorb_count_resources + +giblorb_method_DontLoad +giblorb_method_Memory +giblorb_method_FilePos +giblorb_ID_Snd +giblorb_ID_Exec +giblorb_ID_Pict +giblorb_ID_Copyright +giblorb_ID_AUTH +giblorb_ID_ANNO +
+ +
+blorb-errors +Blorb Errors +giblorb_err_t + +giblorb_err_None +giblorb_err_CompileTime +giblorb_err_Alloc +giblorb_err_Read +giblorb_err_NotAMap +giblorb_err_Format +giblorb_err_NotFound +
+ +
+glkext-startup +Startup Code +glkunix_argumentlist_t +glkunix_startup_t + +glkunix_arg_NoValue +glkunix_arg_ValueFollows +glkunix_arg_ValueCanFollow +glkunix_arg_NumberValue +glkunix_arg_End +
+ +
+glkext-unix +Unix Extensions +glkunix_stream_open_pathname +glkunix_set_base_file +
diff --git a/docs/reference/glk-porting.sgml b/docs/reference/glk-porting.sgml new file mode 100644 index 0000000..b90f7c3 --- /dev/null +++ b/docs/reference/glk-porting.sgml @@ -0,0 +1,178 @@ + + + +Porting, Adapting, and Other Messy Bits + +Life is not perfect, and neither are our toys. In a world of perfect toys, a Glk program could compile with any Glk library and run without human intervention. Guess what. + +Startup Options + +One large grey area is starting up, startup files, and other program options. It is easy to assume that all C programs run with the (argc, argv) model — that all the information they need comes as an array of strings at startup time. This is sometimes true. But in a GUI system, files are often opened by clicking, options are specified in dialog boxes, and so on; and this does not necessarily happen at the beginning of main(). + + +Therefore, Glk does not try to pass an (argc, argv) list to your glk_main(). Nor does it provide a portable API for startup files and options. + + +Doing that well would require API calls to parse command-line arguments of various types, and then also design and handle dialog boxes. It would go far beyond the level of complexity which Glk aspires to. + + +Instead, startup files and options are handled in an entirely platform-dependent manner. You, as the author of a Glk program, must describe how your program should behave. As your program is ported to various Glk libraries, each porter must decide how to implement that behavior on the platform in question. The library should store the options and files in global variables, where your glk_main() routine can read them. + + +It is reasonable to modularize this code, and call it the startup code. But the startup code is not necessarily a single function, and it certainly does not have well-defined arguments such as an (argc, argv) list. You can consider that your startup behavior is divided into the messy part, which is nonportable and goes in the startup code, and the clean part, which is entirely Glk-portable and goes at the beginning of glk_main(). + + +This is not as much of a mess as it sounds. Many programs, and almost all IF programs, follow one of a few simple models. + +The simple model: There are no startup files. The program just starts running when invoked. +The game-file model: The program begins running when it is handed a single file of a particular type. On command-line systems, this comes as a filename in a command-line option. On GUI systems, it will usually be a platform-native event which contains a file reference. + + + +Any Glk library will be able to support these two models, probably through compile-time options. The details will vary. + + +For one notable case, the Mac Glk library has two possible behaviors when compiled with the game-file model. If the player double-clicks a game file, the library calls glk_main() immediately. If the player double-clicks the application icon, the library allows the player to wait, perhaps adjusting preferences; it only calls glk_main() after the game file is selected through a file dialog. + + +In fact, if life were this simple, it would be worth adding these models to the Glk API somehow. Unfortunately, it's not. Consider AGT: the game file is actually about ten separate files with related filenames, in the same directory. Glk does not contain API calls to do precise file and pathname manipulation; it is too complicated an area to support. So this situation must be handled non-portably. + + +More complicated models are also possible. You might want to accept files through GUI events at any time, not just at startup. This could be handled by defining a new Glk event type, and having the library send such an event when a platform-native icon-click is detected. You would then have to decide how the situation should be handled in a command-line Glk library. But that is inherent in your task as a program author. + + +Options and preferences are a separate problem. Most often, a command-line library will handle them with command-line arguments, and a GUI library will handle them with a dialog box. Ideally, you should describe how both cases should behave — list the command-line arguments, and perhaps how they could be labelled in a dialog. + + +This is unlikely to be very complicated. Although who knows. + + +Remember that the Glk library is likely to have some options of its own — matters of display styles and so on. A command-line library will probably have a simple API to extract its own options and pass the rest on to the startup code. + + + +Going Outside the Glk API + +Nonportable problems are not limited to the start of execution. There is also the question of OS services which are not represented in Glk. The ANSI C libraries are so familiar that they seem universal, but they are actually not necessarily present. Palmtop platforms such as PalmOS are particularly good at leaving out ANSI libraries. + +Memory Management + +Everyone uses malloc(), realloc(), and free(). However, some platforms have a native memory-management API which may be more suitable in porting your program. + + +The malloc() system is simple; it can probably be implemented as a layer on top of whatever native API is available. So you don't absolutely have to worry about this. However, it can't hurt to group all your malloc() and free() calls in one part of your program, so that a porter can easily change them all if it turns out to be a good idea. + + +String Manipulation + +This is more of a nuisance, because the set of string functions varies quite a bit between platforms. Consider bcopy(), memcpy(), and memmove(); stricmp() and strcasecmp(); strchr() and index(); and so on. And again, on a palmtop machine, none of these may be available. The maximally safe course is to implement what you need yourself. + + +See the model.c program for an example; it implements its own str_eq() and str_len(). + + +The maximally safe course is also a pain in the butt, and may well be inefficient (a platform may have a memcpy() which is highly optimized for large moves.) That's porting in the big city. + + +By the way, the next person I see who #defines memmove() as memcpy() when a real memmove() isn't available, gets slapped in the face with a lead-lined rubber salmon. + + +File Handling + +This is the real nuisance, because Glk provides a limited set of stream and file functions. And yet there are all these beautiful ANSI stdio calls, which have all these clever tricks — ungetc(), fast macro fgetc(), formatted fprintf(), not to mention the joys of direct pathname manipulation. Why bother with the Glk calls? + + +The problem is, the stdio library really isn't always the best choice. PalmOS and Newton simply don't use stdio. The Mac has a stdio library built on top of its native file API, but it's a large extra library which porters may not wish to link in. + + +There's also the problem of hooking into the Glk API. Window output goes through Glk streams. + + +It would have been lovely to use the stdio API for that, but it's not generally possible. + + +As usual, it's a judgement call. If you have a large existing pile of source code which you're porting, and it uses a lot of icky stdio features like ungetc(), it may be better not to bother changing everything to the Glk file API. If you're starting from scratch, using the Glk calls will probably be cleaner. + + + +Private Extensions to Glk + +Sometimes — hopefully rarely — there's stuff you just gotta do. + + +Explicit pathname modification is one possible case. Creating or deleting directories. New Glk event types caused by interface events. Control over pull-down menus. + + +Like startup code, you just have to decide what you want, and ask your porters to port it. These are the non-portable parts of your task. As I said, that's porting in the big city. + + +If an extension or new function is so useful that everyone is implementing it, I'll consider adding it to the Glk API (as an optional capability, with a Gestalt selector and everything.) I'm flexible. In a morally correct manner, of course. + + + + +Glk and the Virtual Machine + +Most IF games are built on a virtual machine, such as the Z-machine or the TADS runtime structure. Building a virtual machine which uses Glk as its interface is somewhat more complicated than writing a single Glk program. + + +The question to ask is: what API will be exported to the game author — the person writing a program to run on the VM? + + +Implementing a Higher Layer over Glk + +Thus far, each virtual machine has had its own built-in I/O API. Most of them have identical basic capabilities — read lines of input, display a stream of output, show a status line of some sort, and so on. This commonality, of course, is the ground from which Glk sprouted in the first place. + + +If the I/O API is a subset of the capabilities of Glk, it can be implemented as a layer on top of Glk. In this way, an existing VM can often be ported to Glk without any change visible to the author. Standard TADS can be ported in this way; the V5/8 Z-machine can as well (with the sole exception, as far as I know, of colored text.) + + + +Glk as a VM's Native API + +The other approach is to use Glk as the virtual machine's own I/O API, and provide it directly to the game author. The Glulx virtual machine is built this way. This is inherently more powerful, since it allows access to all of Glk, instead of a subset. As Glk is designed to be easily expandable, and will gain new (optional) capabilities over time, this approach also allows a VM to gain capabilities over time without much upheaval. + + +To a certain extent, Glk was designed for this use more than any other. For example, this is why all Glk function arguments are either pointers or 32-bit integers, and why all Glk API structures are effectively arrays of same. It is also why the iterator functions exist; a VM's entire memory space may be reset by an undo or restore command, and it would then have to, ah, take inventory of its streams and windows and filerefs. + + +This is also another reason why Glk provides file API calls. A VM can provide Glk as the game author's entire access to the file system, as well as the author's entire access to the display system. The VM will then be simpler, more modular, not as tied into the native OS — all that good stuff. + + +The Society of C Pedants wishes me to point out that the structures in the Glk API aren't really arrays of 32-bit integers. A structure made up entirely of 32-bit integers can still be padded weirdly by a C compiler. This problem is solved cleanly by the dispatch layer; see below. + + +The mechanics of this are tricky, because Glk has many API calls, and more will be added over time. + + +In a VM with a limited number of opcodes, it may be best to allocate a single Glk opcode, with a variable number of arguments, the first of which is a function selector. (Glulx does this.) Allow at least 16 bits for this selector; there may be more than 256 Glk calls someday. (For a list of standard selectors for Glk calls, see Table of Selectors.) + + +In a VM with a large opcode space, you could reserve a 16-bit range of opcodes for Glk. + + +It may also be feasible to extend the function-call mechanism in some way, to include the range of Glk functions. + + +In any case, the API still has to be exported to the game author in whatever language is compiled to the VM. Ideally, this can be done as a set of function calls. + + +But it doesn't have to be. The Inform compiler, for example, can accept assembly opcodes in-line with Inform source code. It's nearly as convenient to let the author type in opcodes as function calls. + + +There is a further complication when new calls are added to Glk. This should not be a major problem. The compiler is mapping Glk calls one-to-one to its own functions or opcodes, so this should be a matter of adding to a fixed list somewhere in the compiler and releasing an upgrade. + + +Alternatively, if the compiler has some way to define new opcodes, even this much effort is not necessary. + + +The Inform compiler is designed this way; the game author can define new opcodes and use them. So if a new call has been added to Glk, and it has been implemented in the interpreter with a known selector, it can be used in Inform immediately, without a compiler upgrade. + + +Or, you can provide a completely dynamic interface to the Glk API. This is the province of the Glk dispatch layer, which is not part of Glk proper; it rests on top. See The Dispatch Layer. + + + + diff --git a/libchimara/chimara-glk.c b/libchimara/chimara-glk.c index 2c61dac..00cc8b4 100644 --- a/libchimara/chimara-glk.c +++ b/libchimara/chimara-glk.c @@ -624,7 +624,7 @@ chimara_glk_class_init(ChimaraGlkClass *klass) * ChimaraGlk:monospace-font-description: * * Pointer to a #PangoFontDescription describing the default monospace font, - * to be used in text grid windows and #style_Preformatted, for example. + * to be used in text grid windows and %style_Preformatted, for example. * * Default value: font description created from the string * Monospace diff --git a/libchimara/doc.c b/libchimara/doc.c index 2b60373..c9c6e33 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -7,7 +7,7 @@ /** * SECTION:glk-exiting * @short_description: How to terminate a Glk program cleanly - * @include: glk.h + * @include: libchimara/glk.h * * A Glk program usually ends when the end of the glk_main() function is * reached. You can also terminate it earlier. @@ -17,7 +17,7 @@ * SECTION:glk-interrupt * @short_description: Specifying an interrupt handler for cleaning up critical * resources - * @include: glk.h + * @include: libchimara/glk.h * * Most platforms have some provision for interrupting a program — * command @@ -34,7 +34,7 @@ /** * SECTION:glk-tick * @short_description: Yielding time to the operating system - * @include: glk.h + * @include: libchimara/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. @@ -48,7 +48,7 @@ /** * SECTION:glk-types * @short_description: Basic types used in Glk - * @include: glk.h + * @include: libchimara/glk.h * * For simplicity, all the arguments used in Glk calls are of a very few types. * @@ -96,7 +96,7 @@ /** * SECTION:glk-opaque-objects * @short_description: Complex objects in Glk - * @include: glk.h + * @include: libchimara/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. @@ -230,7 +230,7 @@ /** * SECTION:glk-gestalt * @short_description: Testing Glk's capabilities - * @include: glk.h + * @include: libchimara/glk.h * * The gestalt mechanism (cheerfully stolen from the Mac OS) is a * system by which the Glk API can be upgraded without making your life @@ -247,7 +247,7 @@ /** * SECTION:glk-character-input * @short_description: Waiting for a single keystroke - * @include: glk.h + * @include: libchimara/glk.h * * You can request that the player hit a single key. See Character Input Events. @@ -277,7 +277,7 @@ * action="simul">controlI * code when the tab key is * pressed. The Glk library, if it can recognize this at all, will generate a - * #keycode_Tab event (value 0xFFFFFFF7) when this occurs. + * %keycode_Tab event (value 0xFFFFFFF7) when this occurs. * Therefore, for these keyboards, no keyboard key will generate a controlI * event (value 9.) The Glk library will probably map many of the @@ -290,7 +290,7 @@ * legal. The idea is, however, that if your program asks the player to * press the tab * key, you should check for a - * #keycode_Tab event as opposed to a %keycode_Tab event as opposed to a control * I event. * @@ -307,7 +307,7 @@ * purposes of the interface. For example, the Mac Glk library reserves the * tab key for switching between different Glk * windows. Therefore, on the Mac, the library will never generate a - * #keycode_Tab event or a + * %keycode_Tab event or a * controlI * event. * @@ -316,8 +316,8 @@ * function="control">controlJ * character, which is the only printable control character, is probably not * typable. This is because, in most libraries, it will be converted to - * #keycode_Return. Again, you should check for - * #keycode_Return if your program asks the player to + * %keycode_Return. Again, you should check for + * %keycode_Return if your program asks the player to * press the return * key. * @@ -334,13 +334,13 @@ * large problem. * * - * You can test for this by using the #gestalt_CharInput selector. + * You can test for this by using the %gestalt_CharInput selector. * * * 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 #keycode_Home + * available, and ask players to use it. If a %keycode_Home * event can only be generated by typing escapecontrolA @@ -348,7 +348,7 @@ * when the game says Press the home key to see the next * hint. It is better for the library to say that it - * cannot generate a #keycode_Home event; that way the game + * cannot generate a %keycode_Home event; that way the game * can detect the situation and ask the user to type H * instead. * @@ -359,14 +359,14 @@ * (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 return, and be prepared to use different keys in - * your interface if #gestalt_CharInput says they are not available. + * your interface if %gestalt_CharInput says they are not available. * */ /** * SECTION:glk-case * @short_description: Changing the case of strings - * @include: glk.h + * @include: libchimara/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 @@ -377,7 +377,7 @@ /** * SECTION:glk-window-opening * @short_description: Creating new windows and closing them - * @include: glk.h + * @include: libchimara/glk.h * * You can open a new window using glk_window_open() and close it again using * glk_window_close(). @@ -386,7 +386,7 @@ /** * SECTION:glk-window-constraints * @short_description: Manipulating the size of a window - * @include: glk.h + * @include: libchimara/glk.h * * There are library functions to change and to measure the size of a window. */ @@ -394,7 +394,7 @@ /** * SECTION:glk-window-types * @short_description: Blank, pair, text grid, text buffer, and graphics windows - * @include: glk.h + * @include: libchimara/glk.h * * A technical description of all the window types, and exactly how they behave. */ @@ -402,7 +402,7 @@ /** * SECTION:glk-echo-streams * @short_description: Creating a copy of a window's output - * @include: glk.h + * @include: libchimara/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 @@ -446,7 +446,7 @@ /** * SECTION:glk-window-other * @short_description: Miscellaneous functions for windows - * @include: glk.h + * @include: libchimara/glk.h * * This section contains functions for windows that don't fit anywhere else. */ @@ -454,7 +454,7 @@ /** * SECTION:glk-events * @short_description: Waiting for events - * @include: glk.h + * @include: libchimara/glk.h * * As described in Your * Program's Main Function, all player input is handed to your program by @@ -465,27 +465,40 @@ /** * SECTION:glk-character-input-events * @short_description: Events representing a single keystroke - * @include: glk.h + * @include: libchimara/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. + * %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 + * @include: libchimara/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. + * %evtype_LineInput. There are separate functions for requesting Latin-1 input + * and Unicode input; see %gestalt_Unicode. */ +/** + * SECTION:glk-timer-events + * @short_description: Events sent at fixed intervals + * @include: libchimara/glk.h + * + * You can request that an event be sent at fixed intervals, regardless of what + * the player does. Unlike input events, timer events can be tested for with + * glk_select_poll() as well as glk_select(). + * + * It is possible that the library does not support timer events. You can check + * this with the %gestalt_Timer selector. + */ + /** * SECTION:glk-streams * @short_description: Input and output abstractions - * @include: glk.h + * @include: libchimara/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 @@ -554,7 +567,7 @@ /** * SECTION:glk-print * @short_description: Printing to streams - * @include: glk.h + * @include: libchimara/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 @@ -564,7 +577,7 @@ /** * SECTION:glk-read * @short_description: Reading from streams - * @include: glk.h + * @include: libchimara/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 @@ -574,7 +587,7 @@ /** * SECTION:glk-closing-streams * @short_description: Closing streams and retrieving their character counts - * @include: glk.h + * @include: libchimara/glk.h * * When you close a Glk stream, you have the opportunity to examine the * character counts — the number of characters written to or read from the @@ -584,7 +597,7 @@ /** * SECTION:glk-stream-positions * @short_description: Moving the read/write mark - * @include: glk.h + * @include: libchimara/glk.h * * You can set the position of the read/write mark in a stream. * @@ -594,15 +607,117 @@ * */ +/** + * SECTION:glk-styles + * @short_description: Changing the appearance of printed text + * @include: libchimara/glk.h + * + * You can send style-changing commands to an output stream. After a style + * change, new text which is printed to that stream will be given the new style, + * whatever that means for the stream in question. For a window stream, the text + * will appear in that style. For a memory stream, style changes have no effect. + * For a file stream, if the machine supports styled text files, the styles may + * be written to the file; more likely the style changes will have no effect. + * + * Styles are exclusive. A character is shown with exactly one style, not a + * subset of the possible styles. + * + * + * Note that every stream and window has its own idea of the current + * style. Sending a style command to one window or stream does not + * affect any others. + * + * + * Except for a window's echo stream; see Echo Streams. + * + * + * The styles are intended to distinguish meaning and use, not formatting. There + * is no standard definition of what each style will look like. That is left up + * to the Glk library, which will choose an appearance appropriate for the + * platform's interface and the player's preferences. + * + * There are currently eleven styles defined. More may be defined in the future. + * + * Styles may be distinguished on screen by font, size, color, indentation, + * justification, and other attributes. Note that some attributes (notably + * justification and indentation) apply to entire paragraphs. If possible and + * relevant, you should apply a style to an entire paragraph — call + * glk_set_style() immediately after printing the newline at the beginning of + * the text, and do the same at the end. + * + * + * For example, %style_Header may well be centered text. If you print + * Welcome to Victim (a short interactive mystery), and only the + * word Victim is in the %style_Header, the center-justification + * attribute will be lost. Similarly, a block quote is usually indented on both + * sides, but indentation is only meaningful when applied to an entire line or + * paragraph, so block quotes should take up an entire paragraph. Contrariwise, + * %style_Emphasized need not be used on an entire paragraph. It is often used + * for single emphasized words in normal text, so you can expect that it will + * appear properly that way; it will be displayed in italics or underlining, + * not center-justified or indented. + * + * + * + * Yes, this is all a matter of mutual agreement between game authors and game + * players. It's not fixed by this specification. That's natural language for + * you. + * + */ + +/** + * SECTION:glk-stylehints + * @short_description: Setting style hints + * @include: libchimara/glk.h + * + * There are no guarantees of how styles will look, but you can make + * suggestions. + * + * Initially, no hints are set for any window type or style. Note that having no + * hint set is not the same as setting a hint with value 0. + * + * These functions do not affect + * existing windows. They affect the windows which you + * create subsequently. If you want to set hints for all your game windows, call + * glk_stylehint_set() before you start creating windows. If you want different + * hints for different windows, change the hints before creating each window. + * + * + * This policy makes life easier for the interpreter. It knows everything about + * a particular window's appearance when the window is created, and it doesn't + * have to change it while the window exists. + * + * + * Hints are hints. The interpreter may ignore them, or give the player a choice + * about whether to accept them. Also, it is never necessary to set hints. You + * don't have to suggest that %style_Preformatted be fixed-width, or + * %style_Emphasized be boldface or italic; they will have appropriate defaults. + * Hints are for situations when you want to change the + * appearance of a style from what it would ordinarily be. The most common case + * when this is appropriate is for the styles %style_User1 and %style_User2. + * + * There are currently ten style hints defined. More may be defined in the + * future. + * + * Again, when passing a style hint to a Glk function, any value is actually + * legal. If the interpreter does not recognize the stylehint value, it will + * ignore it. + * + * This policy allows for the future definition of style hints without breaking + * old Glk libraries. + * + */ + /** * SECTION:glk-stream-types * @short_description: Window, memory, and file streams - * @include: glk.h + * @include: libchimara/glk.h * * Window Streams * * Every window has an output stream associated with it. This is created - * automatically, with #filemode_Write, when you open the window. You get it + * 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 @@ -665,7 +780,7 @@ /** * SECTION:glk-stream-other * @short_description: Miscellaneous functions for streams - * @include: glk.h + * @include: libchimara/glk.h * * This section includes functions for streams that don't fit anywhere else. */ @@ -673,7 +788,7 @@ /** * SECTION:glk-fileref * @short_description: A platform-independent way to refer to disk files - * @include: glk.h + * @include: libchimara/glk.h * * You deal with disk files using file references. Each fileref is an opaque C * structure pointer; see Opaque @@ -701,15 +816,15 @@ * 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 + * 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 + * @include: libchimara/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 @@ -719,12 +834,89 @@ /** * SECTION:glk-fileref-other * @short_description: Miscellaneous functions for file references - * @include: glk.h + * @include: libchimara/glk.h * * This section includes functions for file references that don't fit anywhere * else. */ +/** + * SECTION:blorb-program + * @short_description: How to use the Blorb layer in your program + * @include: libchimara/glk.h, libchimara/gi_blorb.h + * + * If you wish your program to load its resources from a Blorb file, you need to + * find and open that file in your startup code. (See Startup Options.) Each platform will + * have appropriate functions available for finding startup data. Be sure to + * open the file in binary mode, not text mode. Once you have opened the file as + * a Glk stream, pass it to giblorb_set_resource_map(). + * + * If you do not call giblorb_set_resource_map() in your startup code, or if it + * fails, the library is left to its own devices for finding resources. Some + * libraries may try to load resources from individual files — + * PIC1, PIC2, + * PIC3, and so on. (See the Blorb specification for more + * on this approach.) Other libraries will not have any other loading mechanism + * at all; no resources will be available. + */ + +/** + * SECTION:blorb-layer + * @short_description: The platform-independent functions in the Blorb layer + * @include: libchimara/glk.h, libchimara/gi_blorb.h + * + * These are the functions which are implemented in + * gi_blorb.c. They will be compiled into the library, but + * they are the same on every platform. In general, only the library needs to + * call these functions. The Glk program should allow the library to do all the + * resource handling. + */ + +/** + * SECTION:blorb-errors + * @short_description: Error codes returned by the Blorb layer functions + * @include: libchimara/glk.h, libchimara/gi_blorb.h + * + * All Blorb layer functions, including giblorb_set_resource_map(), return the + * following error codes. + */ + +/** + * SECTION:glkext-startup + * @short_description: Parsing startup options + * @include: libchimara/glk.h, libchimara/glkstart.h + * + * This section describes an extension to Glk for parsing command-line startup + * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and + * GlkTerm. + * + * When you compile a Glk program, you may define a function called + * glkunix_startup_code(), and an array glkunix_arguments[]. These + * set up various Unix-specific options used by the Glk library. There is a + * sample glkstart.c file included in this + * package; you should modify it to your needs. + * + * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]| + * + * The glkunix_arguments[] array is a list of command-line + * arguments that your program can accept. The library will sort these out of + * the command line and pass them on to your code. + */ + +/** + * SECTION:glkext-unix + * @short_description: Unix-specific functions + * @include: libchimara/glk.h, libchimara/glkstart.h + * + * This section describes an extension to Glk for various Unix functions. It was + * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm. + * + * You can put other startup code in glkunix_startup_code(). This should + * generally be limited to finding and opening data files. There are a few Unix + * Glk library functions which are convenient for this purpose. + */ + /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/ /** @@ -743,7 +935,7 @@ * GLK_MODULE_UNICODE: * * If this preprocessor symbol is defined, so are all the Unicode functions and - * constants (see #gestalt_Unicode). If not, not. + * constants (see %gestalt_Unicode). If not, not. */ /** @@ -771,7 +963,7 @@ * gestalt_Version: * * For an example of the gestalt mechanism, consider the selector - * #gestalt_Version. If you do + * %gestalt_Version. If you do * |[ * #glui32 res; * res = #glk_gestalt(#gestalt_Version, 0); @@ -833,15 +1025,15 @@ * #glui32 res, len; * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &len, 1); * ]| - * then res will be one of #gestalt_CharOutput_CannotPrint, - * #gestalt_CharOutput_ExactPrint, or #gestalt_CharOutput_ApproxPrint (see + * then res will be one of %gestalt_CharOutput_CannotPrint, + * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see * below.) * * In all cases, len (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 + * 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. * @@ -851,7 +1043,7 @@ * third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead. * * - * This selector will always return #gestalt_CharOutput_CannotPrint if + * This selector will always return %gestalt_CharOutput_CannotPrint if * ch is an unprintable eight-bit character (0 to 9, 11 to 31, 127 * to 159.) * @@ -871,7 +1063,7 @@ * 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 len of 0 or 2 when - * #gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to + * %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to * a policy of simple stuff first. * */ @@ -879,7 +1071,7 @@ /** * gestalt_CharOutput_CannotPrint: * - * When the #gestalt_CharOutput selector returns this for a character, the + * 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. */ @@ -887,7 +1079,7 @@ /** * gestalt_CharOutput_ApproxPrint: * - * When the #gestalt_CharOutput selector returns this for a character, the + * 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: @@ -901,7 +1093,7 @@ /** * gestalt_CharOutput_ExactPrint: * - * When the #gestalt_CharOutput selector returns this for a character, the + * When the %gestalt_CharOutput selector returns this for a character, the * character will be printed exactly as defined. */ @@ -939,6 +1131,14 @@ * #GLK_MODULE_UNICODE. */ +/** + * gestalt_Timer: + * + * You can test whether the library supports timer events: + * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]| + * This returns 1 if timer events are supported, and 0 if they are not. + */ + /** * evtype_None: * @@ -960,7 +1160,7 @@ * * 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 + * %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. * @@ -980,7 +1180,7 @@ * If a window has a pending request for line input, and the player hits * enter 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 + * %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. * @@ -1015,7 +1215,7 @@ * 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 + * 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. * * @@ -1070,7 +1270,7 @@ * * 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. + * 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 @@ -1084,7 +1284,7 @@ * receive the redraw event. * * Redraw events can be returned by glk_select_poll(). But, like arrangement - * events, this is platform-dependent. See #evtype_Arrange. + * events, this is platform-dependent. See %evtype_Arrange. * * For more about redraw events and how they affect graphics windows, see Graphics Windows. @@ -1094,7 +1294,7 @@ * evtype_SoundNotify: * * On platforms that support sound, you can request to receive an - * #evtype_SoundNotify event when a sound finishes playing. See Playing Sounds. */ @@ -1102,7 +1302,7 @@ * evtype_Hyperlink: * * On platforms that support hyperlinks, you can request to receive an - * #evtype_Hyperlink event when the player selects a link. See Accepting Hyperlink * Events. */ @@ -1118,7 +1318,7 @@ * 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 + * 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. */ @@ -1279,14 +1479,106 @@ * keycode_MAXVAL: * * This value is equal to the number of special keycodes. The last keycode is - * The last keycode is always - * + * always + * * (0x100000000 - keycode_MAXVAL) * (0x100000000 - keycode_MAXVAL) - * + * * . */ +/** + * style_Normal: + * + * The style of normal or body text. A new window or stream always starts with + * %style_Normal as the current style. + */ + +/** + * style_Emphasized: + * + * Text which is emphasized. + */ + +/** + * style_Preformatted: + * + * Text which has a particular arrangement of characters. + * + * This style, unlike the others, does have a standard appearance; it will + * always be a fixed-width font. This is a concession to practicality. Games + * often want to display maps or diagrams using character graphics, and this is + * the style for that. + * + */ + +/** + * style_Header: + * + * Text which introduces a large section. This is suitable for the title of an + * entire game, or a major division such as a chapter. + */ + +/** + * style_Subheader: + * + * Text which introduces a smaller section within a large section. + * + * In a Colossal-Cave-style game, this is suitable for the name of a room (when + * the player looks around.) + * + */ + +/** + * style_Alert: + * + * Text which warns of a dangerous condition, or one which the player should pay + * attention to. + */ + +/** + * style_Note: + * + * Text which notifies of an interesting condition. + * + * This is suitable for noting that the player's score has changed. + * + */ + +/** + * style_BlockQuote: + * + * Text which forms a quotation or otherwise abstracted text. + */ + +/** + * style_Input: + * + * Text which the player has entered. You should generally not use this style at + * all; the library uses it for text which is typed during a line-input request. + * One case when it is appropriate for you to use %style_Input is when you are + * simulating player input by reading commands from a text file. + */ + +/** + * style_User1: + * + * This style has no particular semantic meaning. You may define a meaning + * relevant to your own work, and use it as you see fit. + */ + +/** + * style_User2: + * + * Another style available for your use. + */ + +/** + * style_NUMSTYLES: + * + * The number of styles defined in this library. + */ + /** * stream_result_t: * @readcount: Number of characters read from the stream. @@ -1448,7 +1740,7 @@ * larger, the new bottom or right area is filled with blanks. * * - * You may wish to watch for #evtype_Arrange events, and clear-and-redraw your + * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your * text grid windows when you see them change size. * * @@ -1503,11 +1795,11 @@ * larger, the new bottom or right area is filled with the background color. * * - * You may wish to watch for #evtype_Arrange events, and clear-and-redraw your + * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your * graphics windows when you see them change size. * * - * In some libraries, you can receive a graphics-redraw event (#evtype_Redraw) + * 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 must handle these events. @@ -1580,8 +1872,8 @@ * 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. + * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or + * %winmethod_Below. */ /** @@ -1602,7 +1894,7 @@ * winmethod_DivisionMask: * * Bitwise AND this value with a window splitting method argument to find - * whether the new window has #winmethod_Fixed or #winmethod_Proportional. + * whether the new window has %winmethod_Fixed or %winmethod_Proportional. */ /** @@ -1664,8 +1956,8 @@ * 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. + * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord, + * or %fileusage_Data. */ /** @@ -1731,3 +2023,516 @@ * this will move backwards to a position within the file. */ +/** + * stylehint_Indentation: + * + * How much to indent lines of text in the given style. May be a negative + * number, to shift the text out (left) instead of in (right). The exact metric + * isn't precisely specified; you can assume that +1 is the smallest indentation + * possible which is clearly visible to the player. + */ + +/** + * stylehint_ParaIndentation: + * + * How much to indent the first line of each paragraph. This is in addition to + * the indentation specified by %stylehint_Indentation. This too may be + * negative, and is measured in the same units as %stylehint_Indentation. + */ + +/** + * stylehint_Justification: + * + * The value of this hint must be one of the constants + * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification), + * %stylehint_just_Centered, or %stylehint_just_RightFlush. + */ + +/** + * stylehint_Size: + * + * How much to increase or decrease the font size. This is relative; 0 means the + * interpreter's default font size will be used, positive numbers increase it, + * and negative numbers decrease it. Again, +1 is the smallest size increase + * which is easily visible. + * + * The amount of this increase may not be constant. +1 might increase an + * 8-point font to 9-point, but a 16-point font to 18-point. + * + */ + +/** + * stylehint_Weight: + * + * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for + * normal weight, and -1 for light-weight fonts. + */ + +/** + * stylehint_Oblique: + * + * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal + * angle. + */ + +/** + * stylehint_Proportional: + * + * The value of this hint must be 1 for proportional-width fonts, or 0 for + * fixed-width. + */ + +/** + * stylehint_TextColor: + * + * The foreground color of the text. This is encoded in the 32-bit hint value: + * the top 8 bits must be zero, the next 8 bits are the red value, the next 8 + * bits are the green value, and the bottom 8 bits are the blue value. Color + * values range from 0 to 255. + * + * So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red. + * + */ + +/** + * stylehint_BackColor: + * + * The background color behind the text. This is encoded the same way as + * %stylehint_TextColor. + */ + +/** + * stylehint_ReverseColor: + * + * The value of this hint must be 0 for normal printing (%stylehint_TextColor on + * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on + * %stylehint_TextColor). + * + * Some libraries may support this hint but not the %stylehint_TextColor and + * %stylehint_BackColor hints. Other libraries may take the opposite tack; + * others may support both, or neither. + * + */ + +/** + * stylehint_NUMHINTS: + * + * The number of style hints defined in this library. + */ + +/** + * stylehint_just_LeftFlush: + * + * A value for %stylehint_Justification representing left-justified text. + */ + +/** + * stylehint_just_LeftRight: + * + * A value for %stylehint_Justification representing fully justified text. + */ + +/** + * stylehint_just_Centered: + * + * A value for %stylehint_Justification representing centered text. + */ + +/** + * stylehint_just_RightFlush: + * + * A value for %stylehint_Justification representing right-justified text. + */ + +/*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/ + +/** + * giblorb_err_t: + * + * An integer type that can hold the Blorb error codes. + */ + +/** + * giblorb_err_None: + * + * No error. + */ + +/** + * giblorb_err_CompileTime: + * + * Something is compiled wrong in the Blorb layer. + */ + +/** + * giblorb_err_Alloc: + * + * Memory could not be allocated. + * Chimara + * + * The Blorb layer in the Chimara library should not return this error code; + * instead, the program aborts if memory allocation fails, in keeping with + * GLib practices. + * + */ + +/** + * giblorb_err_Read: + * + * Data could not be read from the file. + */ + +/** + * giblorb_err_NotAMap: + * + * The map parameter is invalid. + */ + +/** + * giblorb_err_Format: + * + * The Blorb file is corrupted or invalid. + */ + +/** + * giblorb_err_NotFound: + * + * The requested data could not be found. + */ + +/** + * giblorb_method_DontLoad: + * + * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or + * giblorb_load_resource() to obtain information about a chunk without actually + * loading it. + */ + +/** + * giblorb_method_Memory: + * + * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or + * giblorb_load_resource() to load a chunk into memory. + */ + +/** + * giblorb_method_DontLoad: + * + * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or + * giblorb_load_resource() to get the position in the Blorb file at which the + * chunk data starts. + */ + +/** + * giblorb_ID_Snd: + * + * Resource usage constant representing a sound file. + */ + +/** + * giblorb_ID_Exec: + * + * Resource usage constant representing an executable program. + */ + +/** + * giblorb_ID_Pict: + * + * Resource usage constant representing an image file. + */ + +/** + * giblorb_ID_Copyright: + * + * Resource usage constant representing the copyright message (date and holder, + * without the actual copyright symbol). There should only be one such chunk per + * file. + */ + +/** + * giblorb_ID_AUTH: + * + * Resource usage constant representing the name of the author or creator of the + * file. This could be a login name on multi-user systems, for example. There + * should only be one such chunk per file. + */ + +/** + * giblorb_ID_ANNO: + * + * Resource usage constant representing any textual annotation that the user or + * writing program sees fit to include. + */ + +/** + * giblorb_map_t: + * + * Holds the complete description of an open Blorb file. This type is opaque for + * normal interpreter use. + */ + +/** + * giblorb_result_t: + * + * Holds information about a chunk loaded from a Blorb file, and the method of + * accessing the chunk data. See giblorb_load_chunk_by_type() and + * giblorb_load_chunk_by_number(). + */ + +/** + * giblorb_create_map: + * @file: An input stream pointing to a Blorb file. + * @newmap: Return location for a Blorb resource map. + * + * Reads Blorb data out of a Glk stream. It does not load every resource at + * once; instead, it creates a map in memory which makes it easy to find + * resources. A pointer to the map is stored in @newmap. This is an opaque + * object; you pass it to the other Blorb-layer functions. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_destroy_map: + * @map: A Blorb resource map to deallocate. + * + * Deallocates @map and all associated memory. This does + * not close the original stream. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_load_chunk_by_type: + * @map: The Blorb resource map to load a chunk from. + * @method: The loading method to use, one of %giblorb_method_DontLoad, + * %giblorb_method_Memory, or %giblorb_method_FilePos. + * @res: Return location for the result. + * @chunktype: The type of chunk to load. + * @count: The chunk number of type @chunktype to load. + * + * Loads a chunk of a given type. The @count parameter distinguishes between + * chunks of the same type. If @count is zero, the first chunk of that type is + * loaded, and so on. + * + * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the + * form type, rather than FORM. + * + * This introduces a slight ambiguity — you cannot distiguish between a + * FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is + * almost certainly a mistake. + * + * + * The returned data is written into @res, according to @method. + * + * The chunknum field is filled in with the number of + * the chunk. (This value can then be passed to giblorb_load_chunk_by_number() + * or giblorb_unload_chunk().) The length field is + * filled in with the length of the chunk in bytes. The + * chunktype field is the chunk's type, which of + * course will be the type you asked for. + * + * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You + * can use this if you are only interested in whether a chunk exists, or in the + * chunknum and length + * parameters. + * + * If you specify %giblorb_method_FilePos, + * data.startpos is filled in with the file position + * of the chunk data. You can use glk_stream_set_position() to read the data + * from the stream. + * + * If you specify %giblorb_method_Memory, data.ptr is + * filled with a pointer to allocated memory containing the chunk data. This + * memory is owned by the map, not you. If you load the chunk more than once + * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one + * copy in memory. You should not deallocate this memory yourself; call + * giblorb_unload_chunk() instead. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_load_chunk_by_number: + * @map: The Blorb resource map to load a chunk from. + * @method: The loading method to use, one of %giblorb_method_DontLoad, + * %giblorb_method_Memory, or %giblorb_method_FilePos. + * @res: Return location for the result. + * @chunknum: The chunk number to load. + * + * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a + * given chunk number. The type of the chunk can be found in the + * chunktype field of #giblorb_result_t. You can get + * the chunk number from the chunknum field, after + * calling one of the other load functions. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_unload_chunk: + * @map: The Blorb resource map to unload a chunk from. + * @chunknum: The chunk number to unload. + * + * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk + * has never been loaded into memory, this has no effect. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_load_resource: + * @map: The Blorb resource map to load a resource from. + * @method: The loading method to use, one of %giblorb_method_DontLoad, + * %giblorb_method_Memory, or %giblorb_method_FilePos. + * @res: Return location for the result. + * @usage: The type of data resource to load. + * @resnum: The resource number to load. + * + * Loads a resource, given its usage and resource number. Currently, the three + * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and + * %giblorb_ID_Exec (executable program). See the Blorb specification for more + * information about the types of data that can be stored for these usages. + * + * Note that a resource number is not the same as a chunk number. The resource + * number is the sound or image number specified by a Glk program. Chunk number + * is arbitrary, since chunks in a Blorb file can be in any order. To find the + * chunk number of a given resource, call giblorb_load_resource() and look in + * res.chunknum. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_count_resources: + * @map: The Blorb resource map in which to count the resources. + * @usage: The type of data resource to count. + * @num: Return location for the number of chunks of @usage. + * @min: Return location for the lowest resource number of @usage. + * @max: Return location for the highest resource number of @usage. + * + * Counts the number of chunks with a given usage (image, sound, or executable.) + * The total number of chunks of that usage is stored in @num. The lowest and + * highest resource number of that usage are stored in @min and @max. You can + * leave any of the three pointers %NULL if you don't care about that + * information. + * + * Returns: a Blorb error code. + */ + +/*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/ + +/** + * glkunix_argumentlist_t: + * + * In each entry, name is the option as it would appear on the command line + * (including the leading dash, if any.) The desc is a description of the + * argument; this is used when the library is printing a list of options. And + * argtype is one of the following constants: + * + * + * + * %glkunix_arg_NoValue + * The argument appears by itself. + * + * + * %glkunix_arg_ValueFollows + * The argument must be followed by another argument (the + * value). + * + * + * %glkunix_arg_ValueCanFollow + * The argument may be followed by a value, optionally. (If the + * next argument starts with a dash, it is taken to be a new argument, not the + * value of this one.) + * + * + * %glkunix_arg_NumberValue + * The argument must be followed by a number, which may be the + * next argument or part of this one. (That is, either -width + * 20 or -width20 will be accepted.) + * + * + * + * %glkunix_arg_End + * The glkunix_arguments[] array must be + * terminated with an entry containing this value. + * + * + * + * To accept arbitrary arguments which lack dashes, specify a name of + * "" and an argtype of %glkunix_arg_ValueFollows. + * + * If you don't care about command-line arguments, you must still define an + * empty arguments list, as follows: + * |[ + * #glkunix_argumentlist_t glkunix_arguments[] = { + * { NULL, #glkunix_arg_End, NULL } + * }; + * ]| + * + * Here is a more complete sample list: + * |[ + * #glkunix_argumentlist_t glkunix_arguments[] = { + * { "", #glkunix_arg_ValueFollows, "filename: The game file to load." }, + * { "-hum", #glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." }, + * { "-bom", #glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on + * the NUM, if given)." }, + * { "-goo", #glkunix_arg_NoValue, "-goo: Find goo." }, + * { "-wob", #glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." }, + * { NULL, #glkunix_arg_End, NULL } + * }; + * ]| + * This would match the arguments thingfile -goo -wob8 -bom -hum + * song. + * + * After the library parses the command line, it does various occult rituals of + * initialization, and then calls glkunix_startup_code(). + * + * |[ int glkunix_startup_code(#glkunix_startup_t *data); ]| + * + * This should return %TRUE if everything initializes properly. If it returns + * %FALSE, the library will shut down without ever calling your glk_main() + * function. + */ + +/** + * glkunix_startup_t: + * + * The fields are a standard Unix (argc, argv) list, which contain + * the arguments you requested from the command line. In deference to custom, + * argv[0] is always the program name. + */ + +/** + * glkunix_arg_End: + * + * Terminates a list of #glkunix_argumentlist_t. + */ + +/** + * glkunix_arg_ValueFollows: + * + * Indicates an argument which must be followed by a value, as the next + * argument. + */ + +/** + * glkunix_arg_NoValue: + * + * Indicates an argument which occurs by itself, without a value. + */ + +/** + * glkunix_arg_ValueCanFollow: + * + * Indicates an argument which may be followed by a value, or may occur by + * itself. + */ + +/** + * glkunix_arg_NumberValue: + * + * Indicates an argument which must be followed by a numerical value, either as + * the next argument or tacked onto the end of this argument. + */ diff --git a/libchimara/fileref.c b/libchimara/fileref.c index 516af02..d20e1f2 100644 --- a/libchimara/fileref.c +++ b/libchimara/fileref.c @@ -144,24 +144,24 @@ glk_fileref_create_temp(glui32 usage, glui32 rock) * @fmode must be one of these values: * * - * #filemode_Read + * %filemode_Read * The file must already exist; and the player will be asked * to select from existing files which match the usage. * * - * #filemode_Write + * %filemode_Write * The file should not exist; if the player selects an * existing file, he will be warned that it will be replaced. * * * - * #filemode_ReadWrite + * %filemode_ReadWrite * The file may or may not exist; if it already exists, the * player will be warned that it will be modified. * * - * #filemode_WriteAppend - * Same behavior as #filemode_ReadWrite. + * %filemode_WriteAppend + * Same behavior as %filemode_ReadWrite. * * * @@ -333,7 +333,7 @@ glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock) * 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 + * (%fileusage_Data, %fileusage_SavedGame, etc), the new reference may or may * not point to the same actual disk file. * * @@ -345,8 +345,8 @@ glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock) * 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 + * 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 diff --git a/libchimara/input.c b/libchimara/input.c index 716431b..acd0ae1 100644 --- a/libchimara/input.c +++ b/libchimara/input.c @@ -275,7 +275,7 @@ glk_request_line_event_uni(winid_t win, glui32 *buf, glui32 maxlen, glui32 initl * * For convenience, it is legal to call glk_cancel_line_event() even if there * is no line input request on that window. The event type will be set to - * #evtype_None in this case. + * %evtype_None in this case. */ void glk_cancel_line_event(winid_t win, event_t *event) diff --git a/libchimara/resource.c b/libchimara/resource.c index c6b4d34..ad5dbf1 100644 --- a/libchimara/resource.c +++ b/libchimara/resource.c @@ -4,15 +4,17 @@ extern ChimaraGlkPrivate *glk_data; /** * giblorb_set_resource_map: - * @file The file stream to read the resource map from + * @file: The file stream to read the resource map from * * This function tells the library that the file is indeed the Blorby source * of all resource goodness. Whenever your program calls an image or sound * function, such as glk_image_draw(), the library will search this file for * the resource you request. * - * Do not close the stream after calling this function. The library is - * responsible for closing the stream at shutdown time. + * Do not close the stream after calling this function. + * The library is responsible for closing the stream at shutdown time. + * + * Returns: a Blorb error code. */ giblorb_err_t giblorb_set_resource_map(strid_t file) @@ -40,8 +42,10 @@ giblorb_set_resource_map(strid_t file) /** * giblorb_get_resource_map: * - * This function returns the current resource map being used. Returns NULL - * if #giblorb_set_resource_map() has not been called yet. + * This function returns the current resource map being used. Returns %NULL + * if giblorb_set_resource_map() has not been called yet. + * + * Returns: a resource map, or %NULL. */ giblorb_map_t* giblorb_get_resource_map() diff --git a/libchimara/stream.c b/libchimara/stream.c index 3d72625..aa27a39 100644 --- a/libchimara/stream.c +++ b/libchimara/stream.c @@ -156,7 +156,7 @@ glk_put_char_uni(glui32 ch) * Prints a null-terminated string to the current stream. It is exactly * equivalent to * |[ - * for (ptr = @s; *ptr; ptr++) + * for (ptr = s; *ptr; ptr++) * #glk_put_char(*ptr); * ]| * However, it may be more efficient. @@ -191,8 +191,8 @@ glk_put_string_uni(glui32 *s) * Prints a block of characters to the current stream. It is exactly equivalent * to: * |[ - * for (i = 0; i < @len; i++) - * #glk_put_char(@buf[i]); + * for (i = 0; i < len; i++) + * #glk_put_char(buf[i]); * ]| * However, it may be more efficient. */ @@ -223,7 +223,7 @@ glk_put_buffer_uni(glui32 *buf, glui32 len) * @buf: An allocated buffer, or %NULL. * @buflen: Length of @buf. * @fmode: Mode in which the buffer will be opened. Must be one of - * #filemode_Read, #filemode_Write, or #filemode_ReadWrite. + * %filemode_Read, %filemode_Write, or %filemode_ReadWrite. * @rock: The new stream's rock value. * * Opens a stream which reads from or writes to a space in memory. @buf points @@ -253,7 +253,7 @@ glk_stream_open_memory(char *buf, glui32 buflen, glui32 fmode, glui32 rock) * @buf: An allocated buffer, or %NULL. * @buflen: Length of @buf. * @fmode: Mode in which the buffer will be opened. Must be one of - * #filemode_Read, #filemode_Write, or #filemode_ReadWrite. + * %filemode_Read, %filemode_Write, or %filemode_ReadWrite. * @rock: The new stream's rock value. * * Works just like glk_stream_open_memory(), except that the buffer is an array @@ -353,15 +353,15 @@ file_stream_new(frefid_t fileref, glui32 fmode, glui32 rock, gboolean unicode) /** * glk_stream_open_file: * @fileref: Indicates the file which will be opened. - * @fmode: Mode in which the file will be opened. Can be any of #filemode_Read, - * #filemode_Write, #filemode_WriteAppend, or #filemode_ReadWrite. + * @fmode: Mode in which the file will be opened. Can be any of %filemode_Read, + * %filemode_Write, %filemode_WriteAppend, or %filemode_ReadWrite. * @rock: The new stream's rock value. * * Opens a stream which reads to or writes from a disk file. If @fmode is - * #filemode_Read, the file must already exist; for the other modes, an empty - * file is created if none exists. If @fmode is #filemode_Write, and the file + * %filemode_Read, the file must already exist; for the other modes, an empty + * file is created if none exists. If @fmode is %filemode_Write, and the file * 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 + * @fmode is %filemode_WriteAppend, the file mark is set to the end of the * file. * * When writing in binary mode, Unicode values (characters greater than 255) @@ -381,8 +381,8 @@ glk_stream_open_file(frefid_t fileref, glui32 fmode, glui32 rock) /** * glk_stream_open_file_uni: * @fileref: Indicates the file which will be opened. - * @fmode: Mode in which the file will be opened. Can be any of #filemode_Read, - * #filemode_Write, #filemode_WriteAppend, or #filemode_ReadWrite. + * @fmode: Mode in which the file will be opened. Can be any of %filemode_Read, + * %filemode_Write, %filemode_WriteAppend, or %filemode_ReadWrite. * @rock: The new stream's rock value. * * This works just like glk_stream_open_file(), except that in binary mode, diff --git a/libchimara/strio.c b/libchimara/strio.c index a33f13f..4d410cd 100644 --- a/libchimara/strio.c +++ b/libchimara/strio.c @@ -1109,7 +1109,7 @@ glk_stream_get_position(strid_t str) * glk_stream_set_position: * @str: A file or memory stream. * @pos: The position to set the mark to, relative to @seekmode. - * @seekmode: One of #seekmode_Start, #seekmode_Current, or #seekmode_End. + * @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. See the diff --git a/libchimara/style.c b/libchimara/style.c index c3a8e43..77ef158 100644 --- a/libchimara/style.c +++ b/libchimara/style.c @@ -4,18 +4,22 @@ extern ChimaraGlkPrivate *glk_data; /** * glk_set_style: - * @styl The style to apply + * @styl: The style to apply * - * This changes the style of the current output stream. After a style change, - * new text which is printed to that stream will be given the new style. For a - * window stream, the text will appear in that style. For other types of - * streams, this has no effect. + * Changes the style of the current output stream. @styl should be one of the + * style_ constants listed above. However, any value is actually + * legal; if the interpreter 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 style) +glk_set_style(glui32 styl) { g_return_if_fail(glk_data->current_stream != NULL); - glk_set_style_stream(glk_data->current_stream, style); + glk_set_style_stream(glk_data->current_stream, styl); } /* Internal function: mapping from style enum to tag name */ @@ -40,9 +44,16 @@ get_tag_name(glui32 style) return "normal"; } +/** + * glk_set_style_stream: + * @str: Output stream to change the style of + * @styl: The style to apply + * + * This changes the style of the stream @str. See glk_set_style(). + */ void -glk_set_style_stream(strid_t stream, glui32 style) { - stream->style = get_tag_name(style); +glk_set_style_stream(strid_t str, glui32 styl) { + str->style = get_tag_name(styl); } /* Internal function: call this to initialize the default styles to a textbuffer. */ @@ -173,11 +184,25 @@ apply_stylehint_to_tag(GtkTextTag *tag, glui32 hint, glsi32 val) } } +/** + * glk_stylehint_set: + * @wintype: The window type to set a style hint on, or %wintype_AllTypes. + * @styl: The style to set a hint for. + * @hint: The type of style hint, one of the stylehint_ constants. + * @val: The style hint. The meaning of this depends on @hint. + * + * Sets a hint about the appearance of one style for a particular type of + * window. You can also set wintype to %wintype_AllTypes, which sets a hint for + * all types of window. + * + * There is no equivalent constant to set a hint for all styles of a single + * window type. + * + */ void -glk_stylehint_set(glui32 wintype, glui32 style, glui32 hint, glsi32 val) +glk_stylehint_set(glui32 wintype, glui32 styl, glui32 hint, glsi32 val) { - - gchar *tag_name = get_tag_name(style); + gchar *tag_name = get_tag_name(styl); /* Iterate over all the window and update their styles if nessecary */ winid_t win = glk_window_iterate(NULL, NULL); diff --git a/libchimara/timer.c b/libchimara/timer.c index 8d2087a..f063def 100644 --- a/libchimara/timer.c +++ b/libchimara/timer.c @@ -3,41 +3,45 @@ extern ChimaraGlkPrivate *glk_data; /** - * You can request that an event be sent at fixed intervals, regardless of what - * the player does. Unlike input events, timer events can be tested for with - * glk_select_poll() as well as glk_select(). + * glk_request_timer_events: + * @millisecs: Interval in milliseconds to request timer events for, or 0 to + * stop timer events. * * Initially, there is no timer and you get no timer events. If you call - * glk_request_timer_events(N), with N not 0, you will get timer events about - * every N milliseconds thereafter. (Assuming that they are supported -- if - * not, glk_request_timer_events() has no effect.) Unlike keyboard and mouse - * events, timer events will continue until you shut them off. You do not have - * to re-request them every time you get one. Call glk_request_timer_events(0) - * to stop getting timer events. + * glk_request_timer_events(N), with + * N not 0, you will get timer events about every + * N milliseconds thereafter. (Assuming that they are + * supported — if not, glk_request_timer_events() has no effect.) Unlike + * keyboard and mouse events, timer events will continue until you shut them + * off. You do not have to re-request them every time you get one. Call + * glk_request_timer_events(0) to stop getting timer events. * * The rule is that when you call glk_select() or glk_select_poll(), if it has - * been more than N milliseconds since the last timer event, and (for - * glk_select()) if there is no player input, you will receive an event whose - * type is evtype_Timer. (win, val1, and val2 will all be 0.) + * been more than N milliseconds since the last timer + * event, and (for glk_select()) if there is no player input, you will receive + * an event whose type is %evtype_Timer. (@win, @val1, and @val2 will all be 0.) * - * Timer events do not stack up. If you spend 10N milliseconds doing - * computation, and then call glk_select(), you will not get ten timer events - * in a row. The library will simply note that it has been more than N - * milliseconds, and return a timer event right away. If you call glk_select() - * again immediately, it will be N milliseconds before the next timer event. + * Timer events do not stack up. If you spend 10N + * milliseconds doing computation, and then call glk_select(), you will not get + * ten timer events in a row. The library will simply note that it has been more + * than N milliseconds, and return a timer event right + * away. If you call glk_select() again immediately, it will be + * N milliseconds before the next timer event. * * This means that the timing of timer events is approximate, and the library * will err on the side of being late. If there is a conflict between player - * input events and timer events, the player input takes precedence. [This - * prevents the user from being locked out by overly enthusiastic timer events. - * Unfortunately, it also means that your timer can be locked out on slower - * machines, if the player pounds too enthusiastically on the keyboard. Sorry. - * If you want a real-time operating system, talk to Wind River.] + * input events and timer events, the player input takes precedence. + * + * This prevents the user from being locked out by overly enthusiastic timer + * events. Unfortunately, it also means that your timer can be locked out on + * slower machines, if the player pounds too enthusiastically on the keyboard. + * Sorry. If you want a real-time operating system, talk to Wind River. + * * - * [I don't have to tell you that a millisecond is one thousandth of a second, - * do I?] - * - * NOTE: setting a new timer will overwrite the old timer if one was in place. + * + * I don't have to tell you that a millisecond is one thousandth of a second, + * do I? + * */ void glk_request_timer_events(glui32 millisecs) @@ -54,7 +58,7 @@ glk_request_timer_events(glui32 millisecs) glk_data->timer_id = g_timeout_add(millisecs, push_timer_event, NULL); } -/** +/* * Internal function: push a new timer event on the event stack. * Will always return TRUE */ diff --git a/libchimara/window.c b/libchimara/window.c index 4db7706..dea1fb6 100644 --- a/libchimara/window.c +++ b/libchimara/window.c @@ -73,8 +73,8 @@ glk_window_get_rock(winid_t win) * glk_window_get_type: * @win: A window. * - * Returns @win's type, one of #wintype_Blank, #wintype_Pair, - * #wintype_TextBuffer, #wintype_TextGrid, or #wintype_Graphics. + * Returns @win's type, one of %wintype_Blank, %wintype_Pair, + * %wintype_TextBuffer, %wintype_TextGrid, or %wintype_Graphics. * * Returns: The window's type. */ @@ -145,15 +145,15 @@ glk_window_get_root() * @split: The window to split to create the new window. Must be 0 if there * are no windows yet. * @method: Position of the new window and method of size computation. One of - * #winmethod_Above, #winmethod_Below, #winmethod_Left, or #winmethod_Right - * OR'ed with #winmethod_Fixed or #winmethod_Proportional. If @wintype is - * #wintype_Blank, then #winmethod_Fixed is not allowed. + * %winmethod_Above, %winmethod_Below, %winmethod_Left, or %winmethod_Right + * OR'ed with %winmethod_Fixed or %winmethod_Proportional. If @wintype is + * %wintype_Blank, then %winmethod_Fixed is not allowed. * @size: Size of the new window, in percentage points if @method is - * #winmethod_Proportional, otherwise in characters if @wintype is - * #wintype_TextBuffer or #wintype_TextGrid, or pixels if @wintype is - * #wintype_Graphics. - * @wintype: Type of the new window. One of #wintype_Blank, #wintype_TextGrid, - * #wintype_TextBuffer, or #wintype_Graphics. + * %winmethod_Proportional, otherwise in characters if @wintype is + * %wintype_TextBuffer or %wintype_TextGrid, or pixels if @wintype is + * %wintype_Graphics. + * @wintype: Type of the new window. One of %wintype_Blank, %wintype_TextGrid, + * %wintype_TextBuffer, or %wintype_Graphics. * @rock: The new window's rock value. * * Creates a new window. If there are no windows, the first three arguments are @@ -218,12 +218,12 @@ glk_window_get_root() * |[ newwin = #glk_window_open(win, #winmethod_Below | #winmethod_Fixed, 5, #wintype_TextGrid, 0); ]| * * 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. + * If the method is %winmethod_Fixed, it also depends on the @wintype argument. * The new window is then called the key window of this split, * because its window type determines how the split size is computed. * * - * For #winmethod_Proportional splits, you can still call the new window the + * For %winmethod_Proportional splits, you can still call the new window the * key window. 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. @@ -1026,13 +1026,13 @@ glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr) /** * glk_window_set_arrangement: * @win: a pair window to rearrange. - * @method: new method of size computation. One of #winmethod_Above, - * #winmethod_Below, #winmethod_Left, or #winmethod_Right OR'ed with - * #winmethod_Fixed or #winmethod_Proportional. + * @method: new method of size computation. One of %winmethod_Above, + * %winmethod_Below, %winmethod_Left, or %winmethod_Right OR'ed with + * %winmethod_Fixed or %winmethod_Proportional. * @size: new size constraint, in percentage points if @method is - * #winmethod_Proportional, otherwise in characters if @win's type is - * #wintype_TextBuffer or #wintype_TextGrid, or pixels if @win's type is - * #wintype_Graphics. + * %winmethod_Proportional, otherwise in characters if @win's type is + * %wintype_TextBuffer or %wintype_TextGrid, or pixels if @win's type is + * %wintype_Graphics. * @keywin: new key window, or %NULL to leave the key window unchanged. * * Changes the size of an existing split — that is, it changes the -- 2.30.2