X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fdoc.c;h=3fd18ca0f55778eb8c719b9a28fc5bcc2bd337b8;hb=7e3ce2d0110b47a67b04a457d1ea215ce1bf1078;hp=0f00da92a5a3f06e74225087835a60458f9aa3b8;hpb=0035771513d5c47d963858ef3f31da3ac28f7fc2;p=rodin%2Fchimara.git diff --git a/libchimara/doc.c b/libchimara/doc.c index 0f00da9..3fd18ca 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -157,7 +157,7 @@ * This is how you deal with opaque objects from a C program. If you are using * Glk through a virtual machine, matters will probably be different. Opaque * objects may be represented as integers, or as VM objects of some sort. - * + * * * Rocks * @@ -177,7 +177,7 @@ * For each class of opaque objects, there is an iterate function, which you can * use to obtain a list of all existing objects of that class. It takes the form * |[ - * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, #glui32 *rockptr); + * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, glui32 *rockptr); * ]| * ...where CLASS represents one of the * opaque object classes. @@ -203,10 +203,10 @@ * * You usually use this as follows: * |[ - * obj = glk_CLASS_iterate(NULL, NULL); + * obj = glk_CLASS_iterate(NULL, NULL); * while (obj) { * /* ...do something with obj... */ - * obj = glk_CLASS_iterate(obj, NULL); + * obj = glk_CLASS_iterate(obj, NULL); * } * ]| * @@ -760,6 +760,29 @@ * */ +/** + * SECTION:glk-style-measure + * @short_description: Finding out how the library displays your style hints + * @include: libchimara/glk.h + * + * You can suggest the appearance of a window's style before the window is + * created; after the window is created, you can test the style's actual + * appearance. These functions do not test the style hints; they test the + * attribute of the style as it appears to the player. + * + * Note that although you cannot change the appearance of a window's styles + * after the window is created, the library can. A platform may support dynamic + * preferences, which allow the player to change text formatting while your + * program is running. + * + * Changes that affect window size (such as font size changes) will be + * signalled by an %evtype_Arrange event. However, more subtle changes (such + * as text color differences) are not signalled. If you test the appearance of + * styles at the beginning of your program, you must keep in mind the + * possibility that the player will change them later. + * + */ + /** * SECTION:glk-stream-types * @short_description: Window, memory, and file streams @@ -967,6 +990,39 @@ * There are a few other commands which apply to graphics windows. */ +/** + * SECTION:glk-graphics-text + * @short_description: Drawing graphics inside or beside text + * @include: libchimara/glk.h + * + * A text buffer is a linear text stream. You can draw images in-line with this + * text. If you are familiar with HTML, you already understand this model. You + * draw images with flags indicating alignment. The library takes care of + * scrolling, resizing, and reformatting text buffer windows. + * + * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer + * window, @val1 gives the image alignment. The @val2 argument is currently + * unused, and should always be zero. + * + * The two margin alignments require some care. To allow proper + * positioning, images using %imagealign_MarginLeft and %imagealign_MarginRight + * must be placed at the beginning of a line. That is, you may only call + * glk_image_draw() (with these two alignments) in a window, if you have just + * printed a newline to the window's stream, or if the window is entirely empty. + * If you margin-align an image in a line where text has already appeared, no + * image will appear at all. + * + * Inline-aligned images count as text for the purpose of this + * rule. + * + * You may have images in both margins at the same time. + * + * It is also legal to have more than one image in the same margin (left or + * right.) However, this is not recommended. It is difficult to predict how text + * will wrap in that situation, and libraries may err on the side of + * conservatism. + */ + /** * SECTION:glk-graphics-testing * @short_description: Checking whether the library supports graphics @@ -976,7 +1032,36 @@ * %gestalt_Graphics. To test for additional capabilities, you can also use the * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors. */ - + +/** + * SECTION:glk-sound-channels + * @short_description: Creating new sound channels and closing them + * @include: libchimara/glk.h + */ + +/** + * SECTION:glk-playing-sounds + * @short_description: Producing noise + * @include: libchimara/glk.h + */ + +/** + * SECTION:glk-sound-other + * @short_description: Miscellaneous functions for sound channels + * @include: libchimara/glk.h + */ + +/** + * SECTION:glk-sound-testing + * @short_description: Checking whether the library supports sound + * @include: libchimara/glk.h + * + * Before calling Glk sound functions, you should use the %gestalt_Sound + * selector. To test for additional capabilities, you can use the + * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify + * selectors. + */ + /** * SECTION:glk-creating-hyperlinks * @short_description: Printing text as a hyperlink @@ -1119,12 +1204,13 @@ * 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. + * 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[]; ]| + * |[ 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 @@ -1193,6 +1279,21 @@ * sufficient. * */ + +/** + * GLK_MODULE_SOUND: + * + * If you are writing a C program, there is an additional complication. A + * library which does not support sound may not implement the sound functions at + * all. Even if you put gestalt tests around your sound calls, you may get + * link-time errors. If the glk.h file + * is so old that it does not declare the sound functions and constants, you may + * even get compile-time errors. + * + * To avoid this, you can perform a preprocessor test for the existence of + * %GLK_MODULE_SOUND. If this is defined, so are all the functions and constants + * described in this section. If not, not. + */ /** * GLK_MODULE_HYPERLINKS: @@ -1223,14 +1324,21 @@ * members. */ +/** + * schanid_t: + * + * Opaque structure representing a sound channel. It has no user-accessible + * members. + */ + /** * gestalt_Version: * * For an example of the gestalt mechanism, consider the selector * %gestalt_Version. If you do * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_Version, 0); + * glui32 res; + * res = glk_gestalt(gestalt_Version, 0); * ]| * res will be set to a 32-bit number which encodes the version of * the Glk spec which the library implements. The upper 16 bits stores the major @@ -1245,8 +1353,8 @@ * 0x00000700. * * |[ - * #glui32 res; - * res = #glk_gestalt_ext(#gestalt_Version, 0, NULL, 0); + * glui32 res; + * res = glk_gestalt_ext(gestalt_Version, 0, NULL, 0); * ]| * does exactly the same thing. Note that, in either case, the second argument * is not used; so you should always pass 0 to avoid future surprises. @@ -1258,8 +1366,8 @@ * If you set ch to a character code, or a special code (from * 0xFFFFFFFF down), and call * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_CharInput, ch); + * glui32 res; + * res = glk_gestalt(gestalt_CharInput, ch); * ]| * then res will be %TRUE (1) if that character can be typed by * the player in character input, and %FALSE (0) if not. See ch to a character code, and call * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_LineInput, ch); + * glui32 res; + * res = glk_gestalt(gestalt_LineInput, ch); * ]| * then res will be %TRUE (1) if that character can be typed by the * player in line input, and %FALSE (0) if not. Note that if ch is @@ -1286,8 +1394,8 @@ * * If you set ch to a character code (Latin-1 or higher), and call * |[ - * #glui32 res, len; - * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &len, 1); + * 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 @@ -1315,11 +1423,11 @@ * Make sure you do not get confused by signed byte values. If you set a * char variable ch to 0xFE, the * small-thorn character (þ), and then call - * |[ res = #glk_gestalt(#gestalt_CharOutput, ch); ]| + * |[ res = glk_gestalt(gestalt_CharOutput, ch); ]| * then (by the definition of C/C++) ch will be sign-extended to * 0xFFFFFFFE, which is not a legitimate character, even in Unicode. You * should write - * |[ res = #glk_gestalt(#gestalt_CharOutput, (unsigned char)ch); ]| + * |[ res = glk_gestalt(gestalt_CharOutput, (unsigned char)ch); ]| * instead. * * @@ -1377,7 +1485,7 @@ * gestalt_Timer: * * You can test whether the library supports timer events: - * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]| + * |[ res = glk_gestalt(gestalt_Timer, 0); ]| * This returns 1 if timer events are supported, and 0 if they are not. */ @@ -1387,8 +1495,8 @@ * Before calling Glk graphics functions, you should use the following gestalt * selector: * |[ - * glui32 res; - * res = glk_gestalt(gestalt_Graphics, 0); + * glui32 res; + * res = glk_gestalt(gestalt_Graphics, 0); * ]| * This returns 1 if the overall suite of graphics functions is available. This * includes glk_image_draw(), glk_image_draw_scaled(), glk_image_get_info(), @@ -1409,14 +1517,57 @@ * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries * may implement both, neither, or only one. */ - + +/** + * gestalt_Sound: + * + * You can test whether the library supports sound: + * |[ + * glui32 res; + * res = glk_gestalt(gestalt_Sound, 0); + * ]| + * This returns 1 if the overall suite of sound functions is available. This + * includes glk_schannel_create(), glk_schannel_destroy(), + * glk_schannel_iterate(), glk_schannel_get_rock(), glk_schannel_play(), + * glk_schannel_play_ext(), glk_schannel_stop(), glk_schannel_set_volume(), and + * glk_sound_load_hint(). + * + * If this selector returns 0, you should not try to call these functions. They + * may have no effect, or they may cause a run-time error. + */ + +/** + * gestalt_SoundVolume: + * + * You can test whether the library supports setting the volume of sound + * channels: + * |[ + * glui32 res; + * res = glk_gestalt(gestalt_SoundVolume, 0); + * ]| + * This selector returns 1 if the glk_schannel_set_volume() function works. If + * it returns zero, glk_schannel_set_volume() has no effect. + */ + +/** + * gestalt_SoundNotify: + * + * You can test whether the library supports sound notification events: + * |[ + * glui32 res; + * res = glk_gestalt(gestalt_SoundNotify, 0); + * ]| + * This selector returns 1 if the library supports sound notification events. If + * it returns zero, you will never get such events. + */ + /** * gestalt_Hyperlinks: * * You can test whether the library supports hyperlinks: * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_Hyperlinks, 0); + * glui32 res; + * res = glk_gestalt(gestalt_Hyperlinks, 0); * ]| * This returns 1 if the overall suite of hyperlinks functions is available. * This includes glk_set_hyperlink(), glk_set_hyperlink_stream(), @@ -1431,13 +1582,28 @@ * * You can test whether hyperlinks are supported with the * %gestalt_HyperlinkInput selector: - * |[ res = #glk_gestalt(#gestalt_HyperlinkInput, windowtype); ]| + * |[ res = glk_gestalt(gestalt_HyperlinkInput, windowtype); ]| * This will return %TRUE (1) if windows of the given type support hyperlinks. * If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and * glk_request_hyperlink_event(), but they will have no effect, and you will * never get hyperlink events. */ +/** + * gestalt_SoundMusic: + * + * You can test whether music resources are supported: + * |[ res = glk_gestalt(gestalt_SoundMusic, 0); ]| + * This returns 1 if the library is capable of playing music sound resources. If + * it returns 0, only sampled sounds can be played. + * + * Music sound resources means MOD songs — the only music + * format that Blorb currently supports. The presence of this selector is, of + * course, an ugly hack. It is a concession to the current state of the Glk + * libraries, some of which can handle AIFF but not MOD sounds. + * + */ + /** * gestalt_GraphicsTransparency: * @@ -1459,7 +1625,7 @@ * the following gestalt selector: * |[ * glui32 res; - * res = #glk_gestalt(#gestalt_Unicode, 0); + * res = glk_gestalt(gestalt_Unicode, 0); * ]| * * This returns 1 if the Unicode functions are available. If it returns 0, you @@ -1633,7 +1799,7 @@ * events, this is platform-dependent. See %evtype_Arrange. * * For more about redraw events and how they affect graphics windows, see Graphics Windows. + * linkend="wintype-Graphics">Graphics Windows. */ /** @@ -1821,18 +1987,6 @@ * Represents the F12 key. */ -/** - * keycode_MAXVAL: - * - * This value is equal to the number of special keycodes. The last keycode is - * always - * - * (0x100000000 - keycode_MAXVAL) - * (0x100000000 - keycode_MAXVAL) - * - * . - */ - /** * style_Normal: * @@ -1918,12 +2072,6 @@ * * Another style available for your use. */ - -/** - * style_NUMSTYLES: - * - * The number of styles defined in this library. - */ /** * stream_result_t: @@ -2213,14 +2361,6 @@ * When calling glk_window_open() with this @method, the new window will be * below the old one which was split. */ - -/** - * winmethod_DirMask: - * - * Bitwise AND this value with a window splitting method argument to find - * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or - * %winmethod_Below. - */ /** * winmethod_Fixed: @@ -2236,13 +2376,6 @@ * a given proportion of the old window's size. (See glk_window_open()). */ -/** - * winmethod_DivisionMask: - * - * Bitwise AND this value with a window splitting method argument to find - * whether the new window has %winmethod_Fixed or %winmethod_Proportional. - */ - /** * fileusage_Data: * @@ -2459,12 +2592,6 @@ * others may support both, or neither. * */ - -/** - * stylehint_NUMHINTS: - * - * The number of style hints defined in this library. - */ /** * stylehint_just_LeftFlush: @@ -2490,6 +2617,47 @@ * A value for %stylehint_Justification representing right-justified text. */ +/** + * imagealign_InlineUp: + * + * The image appears at the current point in the text, sticking up. That is, the + * bottom edge of the image is aligned with the baseline of the line of text. + */ + +/** + * imagealign_InlineDown: + * + * The image appears at the current point, and the top edge is aligned with the + * top of the line of text. + */ + +/** + * imagealign_InlineCenter: + * + * The image appears at the current point, and it is centered between the top + * and baseline of the line of text. If the image is taller than the line of + * text, it will stick up and down equally. + */ + +/** + * imagealign_MarginLeft: + * + * The image appears in the left margin. Subsequent text will be displayed to + * the right of the image, and will flow around it — that is, it will be + * left-indented for as many lines as it takes to pass the image. + * + * Margin images are not implemented yet. + */ + +/** + * imagealign_MarginRight: + * + * The image appears in the right margin, and subsequent text will flow around + * it on the left. + * + * Margin images are not implemented yet. + */ + /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/ /** @@ -2627,69 +2795,70 @@ * For example, consider a hypothetical function, with selector * 0xABCD: * |[ - * void glk_glomp(#glui32 num, #winid_t win, #glui32 *numref, #strid_t *strref); + * void glk_glomp(glui32 num, winid_t win, glui32 *numref, strid_t *strref); * ]| * ...and the calls: * |[ - * #glui32 value; - * #winid_t mainwin; - * #strid_t gamefile; + * glui32 value; + * winid_t mainwin; + * strid_t gamefile; * glk_glomp(5, mainwin, &value, &gamefile); * ]| * * To perform this through gidispatch_call(), you would do the following: * |[ - * #gluniversal_t arglist[6]; + * gluniversal_t arglist[6]; * arglist[0].uint = 5; * arglist[1].opaqueref = mainwin; * arglist[2].ptrflag = TRUE; * arglist[3].uint = value; * arglist[4].ptrflag = TRUE; * arglist[5].opaqueref = gamefile; - * #gidispatch_call(0xABCD, 6, arglist); + * gidispatch_call(0xABCD, 6, arglist); * value = arglist[3].uint; * gamefile = arglist[5].opaqueref; * ]| * * Note that you copy the value of the reference arguments into and out of - * @arglist. Of course, it may be that glk_glomp() only uses these as pass-out + * @arglist. Of course, it may be that + * glk_glomp() only uses these as pass-out * references or pass-in references; if so, you could skip copying in or out. * * For further examples: * |[ * glk_glomp(7, mainwin, NULL, NULL); * ...or... - * #gluniversal_t arglist[4]; + * gluniversal_t arglist[4]; * arglist[0].uint = 7; * arglist[1].opaqueref = mainwin; * arglist[2].ptrflag = FALSE; * arglist[3].ptrflag = FALSE; - * #gidispatch_call(0xABCD, 4, arglist); + * gidispatch_call(0xABCD, 4, arglist); * ]| * * |[ * glk_glomp(13, NULL, NULL, &gamefile); * ...or... - * #gluniversal_t arglist[5]; + * gluniversal_t arglist[5]; * arglist[0].uint = 13; * arglist[1].opaqueref = NULL; * arglist[2].ptrflag = FALSE; * arglist[3].ptrflag = TRUE; * arglist[4].opaqueref = gamefile; - * #gidispatch_call(0xABCD, 5, arglist); + * gidispatch_call(0xABCD, 5, arglist); * gamefile = arglist[4].opaqueref; * ]| * * |[ * glk_glomp(17, NULL, &value, NULL); * ...or... - * #gluniversal_t arglist[5]; + * gluniversal_t arglist[5]; * arglist[0].uint = 17; * arglist[1].opaqueref = NULL; * arglist[2].ptrflag = TRUE; * arglist[3].uint = value; * arglist[4].ptrflag = FALSE; - * #gidispatch_call(0xABCD, 5, arglist); + * gidispatch_call(0xABCD, 5, arglist); * value = arglist[3].uint; * ]| * @@ -2705,10 +2874,10 @@ * * For example, the function glk_select() can be invoked as follows: * |[ - * #event_t ev; - * #gluniversal_t arglist[5]; + * event_t ev; + * gluniversal_t arglist[5]; * arglist[0].ptrflag = TRUE; - * #gidispatch_call(0x00C0, 5, arglist); + * gidispatch_call(0x00C0, 5, arglist); * ev.type = arglist[1].uint; * ev.win = arglist[2].opaqueref; * ev.val1 = arglist[3].uint; @@ -2736,15 +2905,15 @@ * * For example, the function glk_put_buffer() can be invoked as follows: * |[ - * #char buf[64]; - * #glui32 len = 64; - * #glk_put_buffer(buf, len); + * char buf[64]; + * glui32 len = 64; + * glk_put_buffer(buf, len); * ...or... - * #gluniversal_t arglist[3]; + * gluniversal_t arglist[3]; * arglist[0].ptrflag = TRUE; * arglist[1].array = buf; * arglist[2].uint = len; - * #gidispatch_call(0x0084, 3, arglist); + * gidispatch_call(0x0084, 3, arglist); * ]| * * Since you are passing a C char array to gidispatch_call(), the contents will @@ -2766,14 +2935,14 @@ * * For example, the function glk_window_get_rock() can be invoked as follows: * |[ - * #glui32 rock; - * #winid_t win; - * rock = #glk_window_get_rock(win); + * glui32 rock; + * winid_t win; + * rock = glk_window_get_rock(win); * ...or... - * #gluniversal_t arglist[3]; + * gluniversal_t arglist[3]; * arglist[0].opaqueref = win; * arglist[1].ptrflag = TRUE; - * #gidispatch_call(0x0021, 3, arglist); + * gidispatch_call(0x0021, 3, arglist); * rock = arglist[2].uint; * ]| * @@ -2787,7 +2956,9 @@ * @uch: Stores an #unsigned #char. * @sch: Stores a #signed #char. * @ch: Stores a #char with the default signedness. - * @charstr: Stores a %NULL-terminated string. + * @charstr: Stores a null-terminated string. + * @unicharstr: Stores a zero-terminated string of #glui32 values representing + * Unicode characters. * @array: Stores a pointer to an array, and should be followed by another * #gluniversal_t with the array length stored in the @uint member. * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL, @@ -2805,11 +2976,11 @@ * This returns a string which encodes the proper argument list for the given * function. If there is no such function in the library, this returns %NULL. * - * The prototype string for the glk_glomp() function described above would be: - * "4IuQa&Iu&Qb:". The "4" is the number of - * arguments (including the return value, if there is one, which in this case - * there isn't.) "Iu" denotes an unsigned integer; - * "Qa" is an opaque object of class 0 (window). + * The prototype string for the glk_glomp() + * function described above would be: "4IuQa&Iu&Qb:". The + * "4" is the number of arguments (including the return value, if + * there is one, which in this case there isn't.) "Iu" denotes an + * unsigned integer; "Qa" is an opaque object of class 0 (window). * "&Iu" is a reference to an unsigned * integer, and "&Qb" is a reference to a stream. The colon at * the end terminates the argument list; the return value would follow it, if @@ -2817,8 +2988,9 @@ * * Note that the initial number ("4" in this case) is the number of * logical arguments, not the number of #gluniversal_t objects which will be - * passed to gidispatch_call(). The glk_glomp() call uses anywhere from four to - * six #gluniversal_t objects, as demonstrated above. + * passed to gidispatch_call(). The glk_glomp() + * call uses anywhere from four to six #gluniversal_t objects, as demonstrated + * above. * * The basic type codes: * @@ -3066,7 +3238,7 @@ */ /** - * giblorb_method_DontLoad: + * giblorb_method_FilePos: * * 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 @@ -3123,6 +3295,12 @@ /** * giblorb_result_t: + * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.) + * @data: A union containing a pointer to the data @ptr (if you used + * %giblorb_method_Memory) and the position in the file @startpos (if you used + * %giblorb_method_FilePos) + * @length: The length of the data + * @chunktype: The type of the chunk. * * 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 @@ -3274,11 +3452,11 @@ /** * 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: + * @name: the option as it would appear on the command line (including the + * leading dash, if any.) + * @desc: a description of the argument; this is used when the library is + * printing a list of options. + * @argtype: one of the glkunix_arg_ constants. * * * @@ -3316,21 +3494,21 @@ * 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 } + * 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 } + * 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 @@ -3339,7 +3517,7 @@ * 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); ]| + * |[ 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() @@ -3348,6 +3526,8 @@ /** * glkunix_startup_t: + * @argc: The number of arguments in @argv. + * @argv: Strings representing command line arguments. * * The fields are a standard Unix (argc, argv) list, which contain * the arguments you requested from the command line. In deference to custom,