some fixups, mention that changing scanner config during the parsing phase

Fri Mar 16 16:04:42 2007  Tim Janik  <timj@gtk.org>

        * glib/tmpl/scanner.sgml: some fixups, mention that changing scanner
        config during the parsing phase is supported behavior.

svn path=/trunk/; revision=5416

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index eb7cffc..d6d8c28 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+Fri Mar 16 16:04:42 2007  Tim Janik  <timj@gtk.org>
+
+       * glib/tmpl/scanner.sgml: some fixups, mention that changing scanner 
+       config during the parsing phase is supported behavior.
+
 2007-03-15  Marco Barisione <marco@barisione.org>
 
        Add GRegex for regular expression matching.  (#50075)

diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 3cb40a3..af54d1f 100644 (file)
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1444,8 +1444,9 @@ ATEXIT
 <TITLE>Lexical Scanner</TITLE>
 <FILE>scanner</FILE>
 GScanner
-g_scanner_new
 GScannerConfig
+g_scanner_new
+g_scanner_destroy
 
 <SUBSECTION>
 g_scanner_input_file
@@ -1453,13 +1454,13 @@ g_scanner_sync_file_offset
 g_scanner_input_text
 g_scanner_peek_next_token
 g_scanner_get_next_token
+g_scanner_eof
 
 <SUBSECTION>
 g_scanner_cur_line
 g_scanner_cur_position
 g_scanner_cur_token
 g_scanner_cur_value
-g_scanner_eof
 
 <SUBSECTION>
 g_scanner_set_scope
@@ -1467,6 +1468,9 @@ g_scanner_scope_add_symbol
 g_scanner_scope_foreach_symbol
 g_scanner_scope_lookup_symbol
 g_scanner_scope_remove_symbol
+g_scanner_add_symbol
+g_scanner_remove_symbol
+g_scanner_foreach_symbol
 
 <SUBSECTION>
 g_scanner_freeze_symbol_table
@@ -1480,22 +1484,15 @@ g_scanner_unexp_token
 GScannerMsgFunc
 
 <SUBSECTION>
-g_scanner_destroy
-
-<SUBSECTION>
-GTokenType
-GTokenValue
-GErrorType
 G_CSET_a_2_z
 G_CSET_A_2_Z
 G_CSET_DIGITS
 G_CSET_LATINC
 G_CSET_LATINS
+GTokenType
+GTokenValue
+GErrorType
 
-<SUBSECTION>
-g_scanner_add_symbol
-g_scanner_remove_symbol
-g_scanner_foreach_symbol
 </SECTION>
 
 <SECTION>

diff --git a/docs/reference/glib/tmpl/scanner.sgml b/docs/reference/glib/tmpl/scanner.sgml
index c40a3e5..550eb7a 100644 (file)
--- a/docs/reference/glib/tmpl/scanner.sgml
+++ b/docs/reference/glib/tmpl/scanner.sgml
@@ -50,37 +50,26 @@ handler function is declared by #GScannerMsgFunc.
 @input_name: 
 @qdata: 
 @config: 
-@token: 
-@value: 
-@line: 
-@position: 
-@next_token: 
-@next_value: 
-@next_line: 
-@next_position: 
+@token:       token parsed by the last g_scanner_get_next_token()
+@value:       value of the last token from g_scanner_get_next_token()
+@line:        line number of the last token from g_scanner_get_next_token()
+@position:    char number of the last token from g_scanner_get_next_token()
+@next_token:    token parsed by the last g_scanner_peek_next_token()
+@next_value:    value of the last token from g_scanner_peek_next_token()
+@next_line:     line number of the last token from g_scanner_peek_next_token()
+@next_position: char number of the last token from g_scanner_peek_next_token()
 @symbol_table: 
 @input_fd: 
 @text: 
 @text_end: 
 @buffer: 
 @scope_id: 
-@msg_handler: 
-
-<!-- ##### FUNCTION g_scanner_new ##### -->
-<para>
-Creates a new #GScanner.
-The @config_templ structure specifies the initial settings of the scanner,
-which are copied into the #GScanner <structfield>config</structfield> field.
-If you pass %NULL then the default settings are used.
-</para>
-
-@config_templ: the initial scanner settings.
-@Returns: the new #GScanner.
-
+@msg_handler: function to handle GScanner message output
 
 <!-- ##### STRUCT GScannerConfig ##### -->
 <para>
-Specifies the #GScanner settings.
+Specifies the #GScanner parser configuration. Most settings can be changed during
+the parsing phase and will affect the lexical parsing of the next unpeeked token.
 </para>
 <para>
 <structfield>cset_skip_characters</structfield> specifies which characters
@@ -221,6 +210,18 @@ is searched for in the default scope in addition to the current scope
 @store_int64: 
 @padding_dummy: 
 
+<!-- ##### FUNCTION g_scanner_new ##### -->
+<para>
+Creates a new #GScanner.
+The @config_templ structure specifies the initial settings of the scanner,
+which are copied into the #GScanner <structfield>config</structfield> field.
+If you pass %NULL then the default settings are used.
+</para>
+
+@config_templ: the initial scanner settings.
+@Returns: the new #GScanner.
+
+
 <!-- ##### FUNCTION g_scanner_input_file ##### -->
 <para>
 Prepares to scan a file.
@@ -253,7 +254,7 @@ Prepares to scan a text buffer.
 
 <!-- ##### FUNCTION g_scanner_peek_next_token ##### -->
 <para>
-Gets the next token, without removing it from the input stream.
+Parses the next token, without removing it from the input stream.
 The token data is placed in the
 <structfield>next_token</structfield>,
 <structfield>next_value</structfield>,
@@ -264,10 +265,10 @@ The token data is placed in the
 Note that, while the token is not removed from the input stream (i.e.
 the next call to g_scanner_get_next_token() will return the same token),
 it will not be reevaluated. This can lead to surprising results when
-changing scope after peeking for the next token. Getting the next token
-after switching the scope will return whatever was peeked before, 
-regardless of any symbols that may have been added or removed in the
-new scope. 
+changing scope or the scanner configuration after peeking the next token.
+Getting the next token after switching the scope or configuration will
+return whatever was peeked before, regardless of any symbols that may
+have been added or removed in the new scope. 
 </para>
 
 @scanner: a #GScanner.
@@ -276,7 +277,8 @@ new scope.
 
 <!-- ##### FUNCTION g_scanner_get_next_token ##### -->
 <para>
-Gets the next token, removing it from the input stream.
+Parses the next token just like g_scanner_peek_next_token() and also
+removes it from the input stream.
 The token data is placed in the
 <structfield>token</structfield>,
 <structfield>value</structfield>,
@@ -290,7 +292,8 @@ The token data is placed in the
 
 <!-- ##### FUNCTION g_scanner_cur_line ##### -->
 <para>
-Gets the current line in the input stream (counting from 1).
+Returns the current line in the input stream (counting from 1).
+This is the line of the last token parsed via g_scanner_get_next_token().
 </para>
 
 @scanner: a #GScanner.
@@ -299,7 +302,8 @@ Gets the current line in the input stream (counting from 1).
 
 <!-- ##### FUNCTION g_scanner_cur_position ##### -->
 <para>
-Gets the current position in the current line (counting from 0).
+Returns the current position in the current line (counting from 0).
+This is the position of the last token parsed via g_scanner_get_next_token().
 </para>
 
 @scanner: a #GScanner.