tests/Makefile.am tests/Makefile.in :

some minor bug fix to correctly handle the libs and include paths.

docs/usage.txt docs/examples/cssom-example.c :
Added these files for documentation purpose.

2 files changed, 169 insertions, 0 deletions

diff --git a/docs/examples/cssom-example.c b/docs/examples/cssom-example.c
new file mode 100644
index 0000000..9acffcb
--- /dev/null
+++ b/docs/examples/cssom-example.c
@@ -0,0 +1,122 @@
+/* -*- Mode: C; indent-tabs-mode:nil; c-basic-offset:8 -*- */
+
+/**
+ *This is an example that shows how to use
+ *the libcroco css2 parsing library.
+ *
+ *To compile it using gcc, type
+ *
+ *gcc `croco-config --cflags`  `croco-config --libs` -o cssom-example cssom-example.c
+ *
+ *Prior to that, you must have compiled and installed libcroco, of course.
+ *
+ *@author Dodji Seketeli <dodji@seketeli.org>
+ */
+
+/*
+ *$Id$
+ */
+
+#include <string.h>
+#include <libcroco.h>
+
+/**
+ *Displays the usage of this program.
+ *@param prg_name the name of the program.
+ */
+void
+display_usage (char *prg_name)
+{
+	printf ("\nusage: %s [options] <css file to parse>\n\n", prg_name) ;
+	printf ("\twhere options are:\n") ;
+	printf ("\t--help|h\tdisplays this help\n") ;
+	printf ("\n") ;
+}
+
+
+/**
+ *Main entry point.
+ *This function illustrates a way to use libcroco.
+ *In this example, we will use a CSS Object Model parser
+ *to parse a cascading style sheet and dump what we have parsed on stdout.
+ *
+ *The goal of the object model parser is to parse a css and build
+ *an abstract tree out of it. One can then walk the tree to perform
+ *whatever action he wants. In our case, the function used to
+ *dump the tree on stdout will walk the tree and dump each one of its
+ *components (a.k.a. css statements).
+ */
+int
+main (int argc, char **argv)
+{
+	short i = 0 ;
+	enum CRStatus status = CR_OK ;
+	CROMParser *parser = NULL ;
+	CRStyleSheet *stylesheet = NULL ;
+
+	/*first parse command line arguments*/
+	for (i = 1 ; i < argc ; i++)
+	{
+		if (argv[i][0] != '-')
+			break ;
+		if (!strcmp (argv[i],"--help") 
+		    || !strcmp (argv[i], "-h"))
+		{
+			display_usage (argv[0]) ;
+			return 0 ;
+		}
+		else
+		{
+			display_usage (argv[0]) ;
+			return 0 ;
+		}
+	}
+	if (i >= argc)
+	{
+		display_usage (argv[0]) ;
+		return 0;
+	}
+
+	/*
+	 *instanciate a new css object model parser.
+	 */	
+	parser = cr_om_parser_new (NULL) ;
+
+	if (!parser)
+	{
+		fprintf (stderr, 
+			 "Arrgh!!! Couldn't instanciate the parser.\n");
+		return -1 ;
+	}
+
+	status = cr_om_parser_parse_file (parser, 
+					  argv[i] /*the style sheet 
+						    file path*/, 
+					  CR_ASCII /*the encoding*/,
+					  &stylesheet) ;
+
+	if (status == CR_OK && stylesheet)
+	{
+		/*
+		 *everything went well, 
+		 *so dump the stylesheet on stdout.
+		 */
+		cr_stylesheet_dump (stylesheet, stdout) ;
+	}
+
+	if (stylesheet)
+	{
+		/*
+		 *free the the memory used to hold the css
+		 *object model
+		 */
+		cr_stylesheet_destroy (stylesheet) ;
+		stylesheet = NULL ;
+	}
+
+	/*free the memory used by the parser*/
+	cr_om_parser_destroy (parser) ;
+	parser = NULL ;
+
+	return 0 ;
+}
diff --git a/docs/usage.txt b/docs/usage.txt
new file mode 100644
index 0000000..c8b5b59
--- /dev/null
+++ b/docs/usage.txt
@@ -0,0 +1,47 @@
+initial author: Dodji Seketeli <dodji@seketeli.org>
+
+Note: 
+----
+Users can generate an html doc of all the functions of libcroco.
+This is documentation is an unvaluable tool to master the libcroco
+usage and internals.
+To generate the documentation, just cd into the libcroco project
+directory and type 'make apidoc' ;
+This will generate the documenation in the docs/api directory.
+
+
+Usage of the libcroco css2 parsing library
+===========================================
+
+libcroco has two main user programming interfaces:
+the SAC parser, and the CSSOM parser.
+
+
+The SAC parser
+''''''''''''''''
+
+The SAC (Simple Api for CSS) is the lowest level parsing api
+provided by libcroco.
+It is an event driven api in which the parser notifies the
+caller whenever it encounters a remarquable css construction.
+
+The SAC parser is implemented in the CRParser class.
+To use it, one must first instanciate a CRParser.
+
+I said earlier the the SAC parser notifies it caller
+whenever it encounters certain css language constructions during
+the parsing. "Notifies" actually means that it calls a subset of given
+callback function pointers set. This set of function pointers is
+called a "Document Handler". So, by overriding some function pointers
+of the document handler, the user can define the actions to be
+performed when a given css language construction is encountered.
+
+The SAC parser's api is defined in cr-parser.h and
+the document handler's api is defined in cr-doc-handler.h .
+
+
+The CSSOM parser
+'''''''''''''''''
+
+
+