more docu

src/xml-cxx/xml.hxx

@@ -15,17 +15,72 @@
 #include <map>
 #include <memory>
 
-/*! @page limitations Known Limitations
+/*! @mainpage
 
-    - Templates cannot specify number of sub-elements.
-    - XML-Comments are only ignored.
+    @section maintitle C++ XML Class Library
+
+    - Specify your XML schema in C++ using common C++ syntax,
+      such as shift, dereference, etc.
+    - Verify the schema of XML files while they are read from a stream.
+
+    From the README file:
+    @include README
+
+    @page Known Limitations
+
+    - XML-Comments are only ignored, not read, not stored.
     - Mixed tags and text is not supported. Tags may either contain
       other tags only (type xml::Node) or text only (type
-      xml::String).
+      xml::String). -> This is intended behaviour!
     - Unlimited recursion is not possible
       (e.g. &ltp&gt;&ltp&gt;&ltp&gt;&lt/p&gt;&lt/p&gt;&lt/p&gt;)
-    - No check yet for optional and mandatory attributes in xml::Factory
-    - Exceptions should be optional, best effort otherwise (option "strict") */
+    - Exceptions should be optional, best effort otherwise (option "strict")
+
+    @page rationale Rationale - Limitations of other libraries
+
+    The initial idea was to map C++ data structures to XML files
+    (e.g. for configuration files) that can easily be edited by
+    hand. This library does not need any kind of C++ code parser or
+    proprietary pre compiler. You can specify a schema entirly in
+    native C++. Access to the XML structures is through typical C++
+    operators which rresults in a simple and intuitive syntax. The
+    schema is verified when XML is read and exceptions are thrown when
+    the XML to be pares is invalid. Exceptions specify exactly the
+    location and reason of the problem, so that the editor of the XML
+    file can easily find and correct the problem. Due to the
+    verification, it is not necessary to check every access: Only
+    optional attributes and tags must be tested for their existence,
+    before they can be accessed.
+
+    There are a lot of different approaches for using XML in C++, all
+    of them have their specific limitations. This library should be
+    better.
+
+    The design is based on my experiance with gsoap
+    (http://gsoap.sf.net), boost serialization (http://boost.org) and
+    Qt XML (http://qtsoftware.com).
+    
+    @section Qt XML, a typical DOM approach
+
+    One is the XML part of the Qt library. These classes can read XML
+    into a DOM tree, but then the user has to check for every detail.
+    This looks like:
+
+    @code
+      QDomDocument doc;
+      if (!doc.setContent(_http.readAll())); // error
+      QDomNodeList releases(doc.elementsByTagName("release"));
+      for(int i(0); i<releases.size(); ++i)
+        if (releases.at(i).attributes().contains("type") &&
+            releases.at(i).attributes().namedItem("type").nodeValue()==_name) {
+          _software = releases.at(i).firstChildElement("software");
+          _firmware = releases.at(i).firstChildElement("firmware");
+          if (_software.isNull() || _firmware.isNull() ||
+              releases.at(i).firstChildElement("notes").isNull()); // error
+        ...
+    @endcode
+
+    @example doc/examples/address.cxx */
 
 //! Represents classes for handling C++ access to XML files with strict schema.
 /*! The schema ist not presented through xsd, but it can be declared in C++.