diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 4c43999de..e07713bb3 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +2001-09-27 Matthias Clasen + + * glib/tmpl/macros.sgml, glib/tmpl/macros_misc.sgml, + glib/tmpl/scanner.sgml: Additions and markup fixes. + 2001-09-27 Matthias Clasen * glib/tmpl/warnings.sgml, glib/tmpl/linked_lists_double.sgml, diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml index 59cd352b5..87a6b6030 100644 --- a/docs/reference/glib/tmpl/macros.sgml +++ b/docs/reference/glib/tmpl/macros.sgml @@ -240,12 +240,13 @@ current platform. If %G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing. -By default, the macro expands to "const". The macro should be used -in place of "const" for functions that return a value that should not -be modified. The purpose of this macro is to allow us to turn on -"const" for returned constant strings by default, while allowing programmers -who find that annoying to turn it off. This macro should only be used -for return values, it doesn't make sense for function arguments. +By default, the macro expands to const. The macro +should be used in place of const for functions that +return a value that should not be modified. The purpose of this macro is +to allow us to turn on const for returned constant +strings by default, while allowing programmers who find that annoying to +turn it off. This macro should only be used for return values, it doesn't +make sense for function arguments. diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index a7a948c1a..2133f92a8 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -2,7 +2,7 @@ Miscellaneous Macros -specialised macros which are not used often. +specialized macros which are not used often. @@ -50,7 +50,8 @@ compiler in use is a C++ compiler, adds 'extern "C"' around the header. Used (along with #G_BEGIN_DECLS) to bracket header files. If the -compiler in use is a C++ compiler, adds 'extern "C"' around the header. +compiler in use is a C++ compiler, adds extern "C" +around the header. @@ -71,29 +72,28 @@ arrays or arrays on the stack. Portable way to copy va_list variables. -In order to use this function, you must include string.h yourself, -because this macro may use memmove() and GLib does not include -string.h for you. +In order to use this function, you must include string.h +yourself, because this macro may use memmove() and GLib +does not include string.h for you. - @ap1: the va_list variable to place a copy of @ap2 in. @ap2: a va_list. - +Accepts a macro or a string and converts it into a string. -@macro_or_string: +@macro_or_string: a macro or a string. -Expands to "__extension__" when GNU C is used as the compiler. +Expands to __extension__ when GNU C is used as the compiler. This simply tells GNU C not to warn about the following non-standard code -when compiling with the -pedantic option. +when compiling with the -pedantic option. @@ -128,7 +128,10 @@ It avoids possible compiler warnings. See the GNU C documentation for details. +Expands to the GNU C pure function attribute if the compiler is GNU C. +See the GNU C documentation for details. +FIXME: Explain what pure functions are. @@ -176,36 +179,41 @@ FIXME: I can't find this in my GNU C documentation. Take out? -Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C, -or "" if it isn't. -The GNU C __FUNCTION__ variable contains the name of the current function. -See the GNU C documentation for details. +Expands to the GNU C __FUNCTION__ variable if the +compiler is GNU C, or "" if it isn't. The GNU C +__FUNCTION__ variable contains the name of the +current function. See the GNU C documentation for details. -Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C, -or "" if it isn't. -The GNU C __PRETTY_FUNCTION__ variable contains the name of the current -function. For a C program this is the same as the __FUNCTION__ variable -but for C++ it also includes extra information such as the class -and function prototype. See the GNU C documentation for details. +Expands to the GNU C __PRETTY_FUNCTION__ variable +if the compiler is GNU C, or "" if it isn't. +The GNU C __PRETTY_FUNCTION__ variable contains the +name of the current function. For a C program this is the same as the +__FUNCTION__ variable but for C++ it also includes +extra information such as the class and function prototype. See the +GNU C documentation for details. +Expands to the GNU C no_instrument_function function attribute if +the compiler is GNU C. +See the GNU C documentation for details. +FIXME: Explain no_instrument_function. - +Expands to a string identifying the current code position. @@ -265,7 +273,7 @@ printing values of type #gint64. See also #G_GINT16_FORMAT. Some platforms do not support scanning and printing 64 bit integers, -even though the types are supported. On such platforms G_GINT64_FORMAT +even though the types are supported. On such platforms #G_GINT64_FORMAT is not defined. @@ -281,7 +289,7 @@ printing values of type #guint64. See also #G_GINT16_FORMAT. Some platforms do not support scanning and printing 64 bit integers, -even though the types are supported. On such platforms G_GUINT64_FORMAT +even though the types are supported. On such platforms #G_GUINT64_FORMAT is not defined. diff --git a/docs/reference/glib/tmpl/scanner.sgml b/docs/reference/glib/tmpl/scanner.sgml index 7a67888c2..47fe157f2 100644 --- a/docs/reference/glib/tmpl/scanner.sgml +++ b/docs/reference/glib/tmpl/scanner.sgml @@ -24,9 +24,10 @@ understand it myself. Look at gtkrc.c for some code using the scanner. The data structure representing a lexical scanner. -You should set input_name after creating the scanner, since it is used -by the default message handler when displaying warnings and errors. -If you are scanning a file, the file name would be a good choice. +You should set input_name after creating +the scanner, since it is used by the default message handler when +displaying warnings and errors. If you are scanning a file, the file +name would be a good choice. The user_data and @@ -66,8 +67,7 @@ handler function is declared by #GScannerMsgFunc. Creates a new #GScanner. The @config_templ structure specifies the initial settings of the scanner, which are copied into the #GScanner config field. -If you pass NULL then the default settings are used. -(See g_scanner_config_template in gscanner.c for the defaults.) +If you pass %NULL then the default settings are used. @config_templ: the initial scanner settings. @@ -85,14 +85,14 @@ space, tab, carriage-return and line-feed). cset_identifier_first specifies the characters -which can start identifiers. -(the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). +which can start identifiers (the default is #G_CSET_a_2_z, "_", and +#G_CSET_A_2_Z). cset_identifier_nth specifies the characters -which can be used in identifiers, after the first character. -The default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, -#G_CSET_LATINC. +which can be used in identifiers, after the first character (the default +is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, +#G_CSET_LATINC). cpair_comment_single specifies the characters @@ -102,11 +102,91 @@ means that single-line comments start with a '#' and continue until a '\n' case_sensitive specifies if symbols are -case sensitive. +case sensitive (the default is %FALSE). -The rest of the fields are flags which turn features on or off. -FIXME: should describe these. +skip_comment_multi specifies if multi-line +comments are skipped and not returned as tokens (the default is %TRUE). + + +skip_comment_single specifies if single-line +comments are skipped and not returned as tokens (the default is %TRUE). + + +scan_comment_multi specifies if multi-line +comments are recognized (the default is %TRUE). + + +scan_identifier specifies if identifiers +are recognized (the default is %TRUE). + + +scan_identifier_1char specifies if single-character +identifiers are recognized (the default is %FALSE). + + +scan_identifier_NULL specifies if +NULL is reported as #G_TOKEN_IDENTIFIER_NULL. +(the default is %FALSE). + + +scan_symbols specifies if symbols are +recognized (the default is %TRUE). + + +scan_binary specifies if binary numbers +are recognized (the default is %FALSE). + + +scan_octal specifies if octal numbers +are recognized (the default is %TRUE). + + +scan_float specifies if floating point numbers +are recognized (the default is %TRUE). + + +scan_hex specifies if hexadecimal numbers +are recognized (the default is %TRUE). + + +scan_hex_dollar specifies if '$' is recognized +as a prefix for hexadecimal numbers (the default is %FALSE). + + +scan_string_sq specifies if strings can be +enclosed in single quotes (the default is %TRUE). + + +scan_string_dq specifies if strings can be +enclosed in double quotes (the default is %TRUE). + + +numbers_2_int specifies if binary, octal and +hexadecimal numbers are reported as #G_TOKEN_INT (the default is %TRUE). + + +int_2_float specifies if all numbers are +reported as #G_TOKEN_FLOAT (the default is %FALSE). + + +identifier_2_string specifies if identifiers +are reported as strings (the default is %FALSE). + + +char_2_token specifies if characters +are reported by setting token = ch or as #G_TOKEN_CHAR +(the default is %TRUE). + + +symbol_2_token specifies if symbols +are reported by setting token = v_symbol or as +#G_TOKEN_SYMBOL (the default is %FALSE). + + +scope_0_fallback specifies if a symbol +is searched for in the default scope in addition to the current scope +(the default is %FALSE). @cset_skip_characters: @@ -146,10 +226,13 @@ Prepares to scan a file. - +Rewinds the filedescriptor to the current buffer position and blows +the file read ahead buffer. This is useful for third party uses of +the scanners filedescriptor, which hooks onto the current scanning +position. -@scanner: +@scanner: a #GScanner. @@ -232,11 +315,11 @@ structure. -Returns TRUE if the scanner has reached the end of the file or text buffer. +Returns %TRUE if the scanner has reached the end of the file or text buffer. @scanner: a #GScanner. -@Returns: TRUE if the scanner has reached the end of the file or text buffer. +@Returns: %TRUE if the scanner has reached the end of the file or text buffer. @@ -262,34 +345,39 @@ Adds a symbol to the given scope. - +Calls the given function for each of the symbol/value pairs in the +given scope of the #GScanner. The function is passed the symbol and +value of each pair, and the given @user_data parameter. -@scanner: -@scope_id: -@func: -@user_data: +@scanner: a #GScanner. +@scope_id: the scope id. +@func: the function to call for each symbol/value pair. +@user_data: user data to pass to the function. + - +Looks up a symbol in a scope and return its value. If the +symbol is not bound in the scope, %NULL is returned. -@scanner: -@scope_id: -@symbol: -@Returns: +@scanner: a #GScanner. +@scope_id: the scope id. +@symbol: the symbol to look up. +@Returns: the value of @symbol in the given scope, or %NULL +if @symbol is not bound in the given scope. - +Removes a symbol from a scope. -@scanner: -@scope_id: -@symbol: +@scanner: a #GScanner. +@scope_id: the scope id. +@symbol: the symbol to remove. @@ -298,7 +386,7 @@ This function is deprecated and will be removed in the next major release of GLib. It does nothing. -@scanner: +@scanner: a #GScanner. @@ -307,17 +395,19 @@ This function is deprecated and will be removed in the next major release of GLib. It does nothing. -@scanner: +@scanner: a #GScanner. - +Looks up a symbol in the current scope and return its value. If the +symbol is not bound in the current scope, %NULL is returned. -@scanner: -@symbol: -@Returns: +@scanner: a #GScanner. +@symbol: the symbol to look up. +@Returns: the value of @symbol in the current scope, or %NULL +if @symbol is not bound in the current scope. @@ -345,29 +435,32 @@ documentation. Outputs a message resulting from an unexpected token in the input stream. -FIXME: I don't understand the arguments here. @scanner: a #GScanner. @expected_token: the expected token. @identifier_spec: a string describing the expected type of identifier, -or NULL to use the default "identifier" string. -@symbol_spec: a string describing the expected type of identifier, -or NULL to use the default "symbol" string. -@symbol_name: -@message: a message string to output at the end of the warning/error, or NULL. -@is_error: if TRUE it is output as an error. If False it is output as a + or %NULL to use the default "identifier" string. This is used if + @expected_token is #G_TOKEN_IDENTIFIER or #G_TOKEN_IDENTIFIER_NULL. +@symbol_spec: a string describing the expected type of symbol, + or %NULL to use the default "symbol" string. This is used if + @expected_token is #G_TOKEN_SYMBOL. +@symbol_name: the name of the expected symbol. This is used if + @expected_token is #G_TOKEN_SYMBOL. +@message: a message string to output at the end of the warning/error, or %NULL. +@is_error: if %TRUE it is output as an error. If %FALSE it is output as a warning. - +Specifies the type of the message handler function. -@scanner: -@message: -@error: +@scanner: a #GScanner. +@message: the message. +@error: %TRUE if the message signals an error, %FALSE if it + signals a warning. @@ -383,10 +476,32 @@ Frees all memory used by the #GScanner. The possible types of token returned from each g_scanner_get_next_token() call. -@G_TOKEN_EOF: -@G_TOKEN_LEFT_PAREN: -@G_TOKEN_LEFT_CURLY: -@G_TOKEN_RIGHT_CURLY: +@G_TOKEN_EOF: the end of the file. +@G_TOKEN_LEFT_PAREN: a '(' character. +@G_TOKEN_RIGHT_PAREN: a ')' character. +@G_TOKEN_LEFT_CURLY: a '{' character. +@G_TOKEN_RIGHT_CURLY: a '}' character. +@G_TOKEN_LEFT_BRACE: a '[' character. +@G_TOKEN_RIGHT_BRACE: a ']' character. +@G_TOKEN_EQUAL_SIGN: a '=' character. +@G_TOKEN_COMMA: a ',' character. +@G_TOKEN_NONE: no token. +@G_TOKEN_ERROR: an error. See #GErrorType for a list of possible errors. +@G_TOKEN_CHAR: a character without special meaning. +@G_TOKEN_BINARY: an integer, specified in binary notation with a '0b' prefix. +@G_TOKEN_OCTAL: an integer, specified in octal notation with a '0' prefix. +@G_TOKEN_INT: an integer, specified in the usual decimal notation. +@G_TOKEN_HEX: an integer, specified in hexadecimal notation with a '0x' or '$' prefix. +@G_TOKEN_FLOAT: a floating point number. +@G_TOKEN_STRING: a string enclosed in single or double quotes. +@G_TOKEN_SYMBOL: a symbol which has been defined before. +@G_TOKEN_IDENTIFIER: an identifier. +@G_TOKEN_IDENTIFIER_NULL: the special identifier NULL. +@G_TOKEN_COMMENT_SINGLE: a single-line comment enclosed in the delimiters + specified by cpair_comment_single. +@G_TOKEN_COMMENT_MULTI: a multi-line comment enclosed in '/*' and '*/'. +@G_TOKEN_LAST: + @@ -397,21 +512,21 @@ A union holding the value of the token. The possible errors, used in the v_error field -of #GTokenValue, when the token is a G_TOKEN_ERROR. +of #GTokenValue, when the token is a #G_TOKEN_ERROR. -@G_ERR_UNKNOWN: -@G_ERR_UNEXP_EOF: -@G_ERR_UNEXP_EOF_IN_STRING: -@G_ERR_UNEXP_EOF_IN_COMMENT: -@G_ERR_NON_DIGIT_IN_CONST: -@G_ERR_DIGIT_RADIX: -@G_ERR_FLOAT_RADIX: -@G_ERR_FLOAT_MALFORMED: +@G_ERR_UNKNOWN: unknown error. +@G_ERR_UNEXP_EOF: unexpected end of file. +@G_ERR_UNEXP_EOF_IN_STRING: unterminated string constant. +@G_ERR_UNEXP_EOF_IN_COMMENT: unterminated comment. +@G_ERR_NON_DIGIT_IN_CONST: non-digit character in a number. +@G_ERR_DIGIT_RADIX: digit beyond radix in a number. +@G_ERR_FLOAT_RADIX: non-decimal floating point number. +@G_ERR_FLOAT_MALFORMED: malformed floating point number. -The set of lower-case ASCII alphabet characters. +The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig. @@ -419,7 +534,7 @@ Used for specifying valid identifier characters in #GScannerConfig. -The set of upper-case ASCII alphabet characters. +The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in #GScannerConfig. @@ -427,15 +542,16 @@ Used for specifying valid identifier characters in #GScannerConfig. - +The set of digits. +Used for specifying valid identifier characters in #GScannerConfig. -Part of the set of extended characters in the Latin character sets. -FIXME: lower case? +The set of uppercase ISO 8859-1 alphabet characters which are +not ASCII characters. Used for specifying valid identifier characters in #GScannerConfig. @@ -443,8 +559,8 @@ Used for specifying valid identifier characters in #GScannerConfig. -Part of the set of extended characters in the Latin character sets. -FIXME: upper case? +The set of lowercase ISO 8859-1 alphabet characters which are +not ASCII characters. Used for specifying valid identifier characters in #GScannerConfig.