Initial revision

[helm.git] / helm / DEVEL / pxp / pxp / doc / EXTENSIONS.xml

diff --git a/helm/DEVEL/pxp/pxp/doc/EXTENSIONS.xml b/helm/DEVEL/pxp/pxp/doc/EXTENSIONS.xml
new file mode 100644 (file)
index 0000000..e64d061
--- /dev/null
+++ b/helm/DEVEL/pxp/pxp/doc/EXTENSIONS.xml
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE readme SYSTEM "readme.dtd" [
+
+<!ENTITY % common SYSTEM "common.xml">
+%common;
+
+<!-- Special HTML config: -->
+<!ENTITY % readme:html:up '<a href="../..">up</a>'>
+
+<!ENTITY % config SYSTEM "config.xml">
+%config;
+
+]>
+
+<readme title="Extensions of the XML specification">
+
+  <sect1>
+    <title>This document</title>
+    <p>This parser has some options extending the XML specification. Here, the 
+options are explained.
+</p>
+  </sect1>
+
+  <sect1>
+    <title>Optional declarations instead of mandatory declarations</title>
+
+<p>The XML spec demands that elements, notations, and attributes must be
+declared. However, there are sometimes situations where a different rule would
+be better: <em>If</em> there is a declaration, the actual instance of the
+element type, notation reference or attribute must match the pattern of the
+declaration; but if the declaration is missing, a reasonable default declaration
+should be assumed.</p> 
+
+<p>I have an example that seems to be typical: The inclusion of HTML into a
+meta language. Imagine you have defined some type of "generator" or other tool
+working with HTML fragments, and your document contains two types of elements:
+The generating elements (with a name like "gen:xxx"), and the object elements
+which are HTML. As HTML is still evolving, you do not want to declare the HTML
+elements; the HTML fragments should be treated as well-formed XML fragments. In
+contrast to this, the elements of the generator should be declared and
+validated because you can more easily detect errors.</p> 
+
+<p>The following two processing instructions can be included into the DTD:</p>
+    <ul>
+      <li><p><code><![CDATA[<?pxp:dtd optional-element-and-notation-declarations?>]]></code>
+       References to unknown element types and notations no longer cause an
+       error. The element may contain everything, but it must be still
+       well-formed. It may have arbitrary attributes, and every attribute is
+       treated as an #IMPLIED CDATA attribute.</p>
+      </li>
+      <li><p><code><![CDATA[<?pxp:dtd optional-attribute-declarations elements="x y ..."?>]]></code>
+        References to unknown attributes inside one of the enumerated elements
+        no longer cause an error. Such an attribute is treated as an #IMPLIED
+        CDATA attribute.
+</p>
+
+<p>If there are several "optional-attribute-declarations" PIs, they are all
+interpreted (implicitly merged).</p>
+      </li>
+    </ul>
+  </sect1>
+</readme>