More bits on documentation.

2003-06-24 Dodji Seketeli <dodji@spam_sucks.seketeli.org>
* docs/design/parser-architecture.txt,docs/examples/sac-example-1.c:
  More bits on documentation.

Dodji.

2 files changed, 42 insertions, 35 deletions

diff --git a/docs/design/parser-architecture.txt b/docs/design/parser-architecture.txt
index e86fe33..1891381 100644
--- a/docs/design/parser-architecture.txt
+++ b/docs/design/parser-architecture.txt
@@ -14,12 +14,12 @@ conformance.
 
 Simplicity
 -----------
-We want the code to be maintainable by anyone who knows the css spec
+We want the code to be maintainable by anyone who knows the CSS spec
 and who knows how to code in C. Therefore, we avoid to overuse
-the C preprocessor magic and all the tricks that tends to turn C into
+the C preprocessor magic and all the tricks that tend to turn C into
 a maintainance nightmare.
 
-We also try to adhere to the gnome coding guidelines specified
+We also try to adhere to the Gnome coding guidelines specified
 at http://developer.gnome.org/doc/guides/programming-guidelines.
 
 
@@ -27,17 +27,17 @@ Reliability
 -----------
 Each single function of the libcroco library should never crash, 
 and this, whatever the arguments it takes.
-As a consequence we tend to be paranoic when it comes to check
+As a consequence we tend to be paranoid when it comes to check
 pointers values before dereferencing them for example...
 
 Conformance
 -----------
-We try to stick to the css spec. We now this is almost impossible to achieve
-given the ressource we have but we think it is a sane target to chase.
+We try to stick to the CSS spec. We know this is almost impossible to achieve
+given the ressources we have but we think it is a sane target to chase.
 
 II) Overall architecture
 =========================
-The parser is organized around several main classes :
+The parser is organized around several main classes:
 
 1/ CRInput
 2/ CRTknzr (Tokenizer or lexer)
@@ -46,13 +46,13 @@ The parser is organized around several main classes :
 
 II.1 The CRInput class
 -----------------------
-The CRInput class provides the abstraction of  
+The CRInput class provides the abstraction of
 an utf8-encoded character stream. 
 
-Ideally, it should abstracts local data sources 
+Ideally, it should abstract local data sources 
 (local files and in-memory buffers)
-and remote data sources (sockets, url-identified ressources) but at the
-moment, it abstracts local data sources only.
+and remote data sources (sockets, url-identified ressources) but for the
+moment, it can only abstract local data sources.
 
 Adding a new type of data source should be transparent for the
 classes that already use CRInput. After all, this is what abstraction is about :)
@@ -61,11 +61,11 @@ classes that already use CRInput. After all, this is what abstraction is about :
 II.2 The CRTknzr class
 ----------------------
 The main job of the tokenizer (or lexer) is to
-provide a get_next_token () method.
-This methods returns the next css token found in the input stream.
+provide a get_next_token() method.
+This methods returns the next CSS token found in the input stream.
 (Note that the input stream here is an instance of CRInput).
 
-This provides an extremely usefull facility to the parser.
+This provides an extremely useful facility to the parser.
 
 II.3 The CRParser class
 -------------------------
@@ -74,24 +74,24 @@ The core of the parser.
 The main job of this class is to provide a cr_parser_parse_stylesheet() 
 method. During the parsing (the execution of the cr_parser_stylesheet())
 the parser sents events to notify the application when it encounters
-remarquable css constructions. This is the SAC (Simple api for CSS) api model.
+remarquable CSS constructions. This is the SAC (Simple API for CSS) API model.
 
-To achieve that task, almost each production of the css grammar 
+To achieve that task, almost each production of the CSS grammar 
 has a matching parsing function (or method) in this class.
 
-For example, the following  production named "ruleset" (specified in the 
-css2 spec in appendix D.1):
+For example, the following production named "ruleset" (specified in the 
+CSS2 spec in appendix D.1):
 
 ruleset : selector [ ',' S* selector ]*
         '{' S* declaration [ ';' S* declaration ]* '}' S*
 
-is "implemented" by the cr_parser_parse_ruleset () method. 
+is "implemented" by the cr_parser_parse_ruleset() method. 
 
 The same thing applies for the "selector" production:
 
 selector : simple_selector [ combinator simple_selector ]*
 
-which is implemented by the  cr_parser_parse_selector() method... and so on
+which is implemented by the cr_parser_parse_selector() method... and so on
 and so forth.
 
 II.3.1 Structure of a parsing method.
@@ -100,11 +100,11 @@ A parsing method (e.g cr_parser_parse_ruleset()) is there
 to:
 
              * try to recognize a substring of the incoming character string
-	     as something that matches a given css grammar production.
+	     as something that matches a given CSS grammar production.
 
              e.g: the job of the cr_parser_parse_ruleset() is to try 
-	     to recognize if "what" comes next in the input strean 
-	     is a css2 "ruleset".
+	     to recognize if "what" comes next in the input stream 
+	     is a CSS2 "ruleset".
 
              * build a basic abstract data structure to 
 	     store the information encountered
@@ -116,27 +116,27 @@ to:
 	     cr_parser_parse_declaration (CRParser *a_this, GString **a_property,
 					  CRTerm **a_value) ;
 
-             In case of successfull parsing, this method returns 
-	     (via its parameters) the  property _and_ the 
-	     value of the css2 declaration.
-	     Note that a css2 declaration is specified as follows:
+             In case of successful parsing, this method returns 
+	     (via its parameters) the property _and_ the 
+	     value of the CSS2 declaration.
+	     Note that a CSS2 declaration is specified as follows:
 
 	     declaration : property ':' S* expr prio?
 	                  | /* empty */
 
-	     * After completion, say if the parsing has succeed or not.	
+	     * After completion, say if the parsing has succeeded or not.	
 	     
 	     eg: cr_parser_parse_declaration() returns CR_OK if the
-	     parsing has succeed, and error code otherwise. Obviously,
-	     the a_property and a_value out parameter are valid if and only
-	     if the function return value is CR_OK.
+	     parsing has succeeded, and error code otherwise. Obviously,
+	     the out parameters "a_property" and "a_value" are valid if and only
+	     if the return value is CR_OK.
 
 	     * whenever the function is parsing a construct that must
-	     be notified to the user as part of the SAC api spec, notify
+	     be notified to the user as part of the SAC API spec, notify
 	     the user by calling the right SAC callback.
 
 	     * if the parsing failed, leave the position in the stream unchanged.
-	     That is the position in the character stream should be as if
+	     That is, the position in the character stream should be as if
 	     the parsing function hasn't been called at all.
 
 	     
diff --git a/docs/examples/sac-example-1.c b/docs/examples/sac-example-1.c
index c72fd70..ded16f0 100644
--- a/docs/examples/sac-example-1.c
+++ b/docs/examples/sac-example-1.c
@@ -4,7 +4,8 @@
  *This test example shows how to use the SAC api.
  *
  *This features a simple parser that says "hey" when
- *it encounters a css ruleset :)
+ *it encounters the beginning of a CSS ruleset, and "woohoo"
+ *at the end of a CSS ruleset.
  *
  *To compile this file, type:
  *
@@ -13,6 +14,12 @@
  *Make sure you have compiled and installed libcroco prior to trying to
  *compile this file :)
  *
+ *Once you have compiled it, type:
+ *
+ *./sac-example-1 <a-path-to-a-css-file>
+ *
+ *to try it on a CSS file of your choice.
+ *
  *Initial Author: Dodji Seketeli <Dodji 47 seketeli dot org>
  */
 
@@ -42,7 +49,7 @@ static void
 end_selector_cb (CRDocHandler *a_handler,
 		 CRSelector *a_selector)
 {
-	printf ("Hey, this is the end of a ruleset\n") ;
+	printf ("Woohoo, this is the end of a ruleset\n") ;
 	printf ("======================================\n\n") ;
 }