Write README files for examples

8 files changed, 44 insertions, 1 deletions

diff --git a/README b/README
index 3be3fb7..e9b66d7 100644
--- a/README
+++ b/README
@@ -13,7 +13,9 @@ See the INSTALL file for prerequisites and installation instructions.
 
 See the doc/ directory for the API documentation.
 
-See the examples/ directory for examples.
+See the examples/ directory for examples. See examples/README for an
+overview of the provided examples as well as the README file in each
+example directory for more details on any particular example.
 
 See the tests/ directory for the test suite.
 
diff --git a/examples/README b/examples/README
new file mode 100644
index 0000000..1a55867
--- /dev/null
+++ b/examples/README
@@ -0,0 +1,21 @@
+processing
+  Shows how to parse a specific XML vocabulary, extract the data, and store
+  it back to XML.
+
+persistence
+  Shows how to implement C++ classes that know how to persist themselves in
+  XML.
+
+inheritance
+  Shows how to implement XML persistence for C++ classes that use inheritance.
+
+roundtrip
+  Shows how to "roundtrip" an XML document, that is, parse it and serialize
+  it back to XML.
+
+hybrid
+  Shows how to implement hybrid, partially in-memory, partially streaming
+  parsing and serialization.
+
+performance
+  Measures the performance of the parser.
diff --git a/examples/hybrid/README b/examples/hybrid/README
index e69de29..89ad83a 100644
--- a/examples/hybrid/README
+++ b/examples/hybrid/README
@@ -0,0 +1,3 @@
+This example shows how to implement hybrid, partially in-memory, partially
+streaming parsing and serialization. It includes a sample implementation
+of a DOM-like representation of raw XML (dom.?xx).
diff --git a/examples/inheritance/README b/examples/inheritance/README
index e69de29..c74510b 100644
--- a/examples/inheritance/README
+++ b/examples/inheritance/README
@@ -0,0 +1,3 @@
+This example shows how to implement XML persistence for C++ classes that use
+inheritance. For the simple case without inheritance see the 'persistence'
+example.
diff --git a/examples/performance/README b/examples/performance/README
index e69de29..1ec5a9f 100644
--- a/examples/performance/README
+++ b/examples/performance/README
@@ -0,0 +1,4 @@
+This example measures the performance of the parser. You can generate smaller
+or larger test files using the gen.cxx program. You can also compare the
+result to the no-op Expat implementation by compiling and running the
+expat.cxx program.
diff --git a/examples/persistence/README b/examples/persistence/README
index e69de29..14b9acc 100644
--- a/examples/persistence/README
+++ b/examples/persistence/README
@@ -0,0 +1,3 @@
+This example shows how to implement C++ classes that know how to persist
+themselves in XML. This is the simple case that doesn't involve inheritance.
+For inheritance support see the 'inheritance' example.
\ No newline at end of file
diff --git a/examples/processing/README b/examples/processing/README
index e69de29..fb48877 100644
--- a/examples/processing/README
+++ b/examples/processing/README
@@ -0,0 +1,4 @@
+This example shows how to parse a specific XML vocabulary, extract the
+data, and store it back to XML. This example can be used as a base for
+applications that need to process the data without creating any kind of
+object model.
diff --git a/examples/roundtrip/README b/examples/roundtrip/README
index e69de29..3df848e 100644
--- a/examples/roundtrip/README
+++ b/examples/roundtrip/README
@@ -0,0 +1,3 @@
+This example shows how to "roundtrip" an XML document, that is, parse it
+and serialize it back to XML. It can be used as a base for converters and
+filters.