RubyGems - mega - Versions diffs - 0.3.1 - Mend

mega 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1502) hide show

data/pub/xml/xmlproof/xmlproof.html ADDED

@@ -0,0 +1,501 @@
+<html>
+<head>
+  <title>XML:Proof Documentation</title>
+  <style>
+    p { font-family: arial }
+    h1 { font-family: arial }
+    h2 { font-family: arial }
+    h3 { font-family: arial }
+    h4 { font-family: arial }
+  </style>
+</head>
+<body>
+<table width="100%" cellspacing="0" cellpadding="0">
+<tr>
+	<td>
+		<font size="10">xml:Proof</font><br/>
+		<font size="4">&lt;a schema for the rest of us/&gt;</font>
+	</td>
+	<td align="right">
+		<font size="2">v.02.06.10 Beta</font><br/>
+		<font size="2">&nbsp;Thomas Sawyer (c)2002</font>
+	</td>
+</tr>
+</table>
+<br/>
+<h1>Introduction</h1>
+<p>A standard extensible and potable data language is extremely important to the IT community, thus
+the importance of XML technology, and its oft mention, as it has become that defacto standard in this regard.
+Yet it is widely held that XML is a bulky, less than optimal, implementation of such a standard. Fortunately
+there are ways in which the community itself can go about improving XML. xml:Proof is, in part, such an improvement.</p>
+<p>XML, in and of itself, is simply a general data/metadata format --a way to organize data such that both the content and
+description of that content are bound together. But in itself it does not dictate the validity of that data.
+To patch this "hole" in XML, DTD or the Document Type Definition was made part of the XML specification.
+DTD has advantages. It is actually broader in applicability as it's syntax is not XML, but a superset, SGML.
+Yet this is also its disadvantage. The optimal solution would use XML itself as the base syntax,
+so that the same tools can be utilized for both the data/metadata markup and the validity markup.
+This is where schemas come into play. Schemas are XML document validity definitions, just as DTDs are,
+but they keep to the boundries of XML itself, i.e. schemas are marked-up with XML.</p>
+<p>There are a number of schemas already available for XML, like TREX, RELAX, RELAX-NG, and Schematron.
+Offically the W3C has offered up their own XML-Schema. Should you place examples of all of these schemas side-by-side,
+along with an example of xml:Proof, xml:Proof will immediately distinguish itself from the rest.
+This is due to the fact that xml:Proof, unlike the others, actually utilizes the very tag names it intends to formalize,
+rather then invent a whole new set of its own. In fact xml:Proof has only two specially defined elements, the root tag
+and the arbit tag. As you can imagine this makes xml:Proof mark-up rather trivial to read and write.
+Additionly xml:Proof manages to do with so few speciality tags and attributes because it utilizes existing standard
+technologies to do much of its dirty work, that is Regular Expressions. Regular Expressions are well battle tested
+in the field, and there is little good reason to reinvent the wheel. Regular Expressions are a schema, using a
+broader sense of the word, in their own right, applicable to strings of text. As there are plenty of strings of
+text in XML documents, it isn't too hard to see how this might be useful. xml:Proof intends useage of
+Regular Expression insofar as is applicable in the context of XML. Utilizing this well known pre-existing technology,
+among its other features, XMProof is able to offer a unique and powerful schema to the XML community.</p>
+<br/>
+<h1>Overview</h1>
+<h2>File Extension and Namespace</h2>
+<p>Personally I hate file extensions. Why file systems do not include a place for this description as they do for
+the file name and last modified date is beyond me. I tend to blame MS-DOS. Oh well.
+The extension for xml:Proof proofsheets, as they are called, is <code>.xps</code>.</p>
+<p>xml:Proof is fully namespace aware, both in functionality and in application to an XML Document.
+This requires further explination. Namespace prefixes serve as mere proxies to actual namespaces.
+So while any arbitrary prefix can be used, a namespace itself, i.e. the uri, must be unique and persistent.
+The namespace uri for xml:Proof is <code>http://www.transami.net/namespace/xmlproof</code>.
+This namespace must be used on all of xml:Proof's special tags in order for any xml:Proof processor to function.
+Further, when creating xml:Proof proofsheets, the namespaces of the elements and attributes being described must also be
+taken into consideration with regards to the target XML document's. The elements and attributes of the XML document,
+in other words, must partake of the same namespaces as their counterparts within the proofsheet.
+This will become clearer as you read the rest of this document.
+</p>
+<br/>
+<h2>Root and Arbit Tags</h2>
+<p>There are only two special tags in xml:Proof.</p>
+<p>The first is the <code>&lt;proofsheet&gt;</code> tag. It is the root element of any xml:Proof schema document,
+i.e. the proofsheet. The special root tag can take the alternate form of <code>&lt;schema&gt;</code>.
+Both serve the same purpose.</p>
+<p>The second special tag is the <code>&lt;arbit&gt;</code> tag. This tag is used to indicate an arbitrary
+location in the XML document. It has a single valid attribute, <code>xpath</code>, which specifies the
+the matching XML document nodes to which its <i>die</i> corresponds (see below).
+</p>
+<p>Both of these special element tags and the special attrribute should always be prefixed with
+reference to the xml:Proof namespace. While any arbitrary, but valid, prefix will do,
+it is recommended that you use <code>xp:</code> for consistancy and clearity.</p>
+<br/>
+<h2>The Die is Cast</h2>
+<p>Witch exception to the special tags, all other tag and attribute names of an xml:Proof proofsheet
+are the same as those of the target XML documents it intends to model. The hiearchy of those elements
+are also the same. Thus the proofsheet is nearly as readable as any applicable target document.
+The text, or content, of elements and attributes is, in xml:Proof nomeclature, called a <i>die</i>.
+It may also be refered to as a <i>cast</i> and the act of writing or applying them, <i>casting</i>.
+A die consists of the following optional <i>markers</i> seperated by spaces:
+<ul>
+  <li><code><b>=<i>name</i>=</b></code>
+    <p>The <code><i>name</i></code> is an identitier which names the die
+    such that it can be reused later in the proofsheet. This
+    provides a convenient means of die reuse. An element or attribute having
+    only this marker and no other will gain its die characteristics from any other die
+    identically named which has other markers within its die.</p>
+	</li>
+  <li><code><b>/<i>regular expression</i>/</b></code>
+    <p>The <code><i>regular expression</i></code> marker is dictates that the content
+    of an element or attribute must match against it to be considered valid.
+    The regular expression of a die effectively defaults to <code>.*</code> if excluded.
+	</li>
+  <li><code><b>:<i>datatype</i>:</b></code>
+    <p>The <code><i>datatype</i></code> name is actually arbitrary, and can be anything desired.
+    xml:Proof itself dosen't care, but the utilization of an xml:Proof processor will!
+    Any given xml:Proof processor will generally "understand" the majority of common datatypes
+    and thus is able to typecast XML content into its underlying language of implementation.
+    Such is the main intent of datatype names in addition to validating content in simular fashion
+    to regular expressions. A good xml:Proof processor should also provide a means to add and alter
+    its internally recogzined datatypes.  Any datatype it does not recognize will be treated as
+    <code>CDATA</code>, otherwise known as <code>string</code> or <code>text</code>.</p>
+	</li>
+  <li><code><b>@<i>order</i>@</b></code>
+		<p>The value of order may be <code>tag</code>, <code>content-a..z</code>, </code>content-z..a></code>, or <code>none</code>.
+    If <code>tag</code> then all child elements of the casted element must appear in sequence as given within the proofsheet.
+    if <code>content-a..z</code> or <code>content-z..a</code>, then the content of all child elements of the casted element
+    must appear in alpahnumrical order, descending or ascending, respectively. The value <code>none</code> specifies that
+    no specific sort order is required and is the default if the marker is not given within the die.
+    Keep in mind this marker does not specify that each of the children elements must occur or that
+    one and only one of said children may appear. Rather, it only specifies that, should they appear,
+    they do so in the given order. An element thus cast must have child elements.
+    This marker is not applicable to attributes and will be ignored if used thus.</p>
+	</li>
+  <li><code><b>+<i>closure</i>+</b></code>
+		<p>The value of closure can be <code>inclusive</code>, <code>exclusive</code>, or <code>none</code>.
+    Inclusivity means that all child elements of the cast element must appear as given in the proofsheet,
+    but other elements may appear as thier siblings. Exclusivity means that all child elements of the cast element
+    must appear as given in the proofsheet and that no other elements may appear as thier siblings.
+    If this marker is not present within the die, the default value of <code>none</code> is assumed, which
+    relinquishes any neccessary closure on an elements child elemets.	An element thus cast as
+    <code>inclusive</code> or <code>exclusive</code> must have children elements.
+    This marker is not applicable to attributes and will be ignored if used thus.</p>
+	</li>
+  <li><code><b>#<i>range</i>#</b></code>
+		<p>Specifies a <code><i>range</i></code> of how many of a given element or attribute may appear.
+		For elements, a valid <code><i>range</i></code> can be <code>m..n</code> or <code>m...n</code>,
+    inclusive and exclusive of <code>n</code>, respectively,
+		where <code>m</code> and <code>n</code> are unsigned integers
+		and <code>m</code> &lt; <code>n</code>. This notation was borrowed from the Ruby programming language.
+		There is also the special case <code>m..*</code> (same as <code>m...*</code>) which of course means unbound.
+		<code>0..*</code> is the default, meaning none or any number of the element may appear within the document.
+    For attributes, only <code>0..1</code> and <code>1..1</code> are valid, as an attribute may appear no more
+    than once in any given element, with 0..1 being the default.</p>
+	</li>
+  <li><code><b>?<i>option1,option2,...</i>?</b></code>
+		<p>Where <code><i>optionN</i></code> is set to an arbitrary group name.
+     This option name defines an option group to which the the element belongs.
+		 This specifies that one and only one of the elements sharing the same option group name
+     may appear within the target document. This can provide interesting relationships in that
+     elements and/or attributes having the same group names do not need to belong to the same parent!
+     But be warned: this can create a contridiction should an ancestor and one of its
+		 children partake of the same group. Do not do this as it will render your documents
+     invalid by definition.</p>
+	</li>
+  <li><code><b>!<i>collection</i>!</b></code>
+		<p>Where <code><i>collection</i></code> is set to an arbitrary collection name.
+     This collection name defines a collective group to which the element belongs,
+		 and specifies that all of suich elements and/or attrributes must appear together
+     within the document. Any given attribute or element can only belong to a single collection.</p>
+	</li>
+  <li><b><code>*<i>track</i>*</code></b>
+		<p>This is a special marker which does not dictate structure or content.
+		It has a special purpose for XML datastores, like that implemented in DBXML.
+		It specifies that this element should be specifically indexed.
+		Tracking of particular XML elements in a datastore
+		allows for fast search and retirieval, and more importantly
+		fast aggregate functions to be applied to their values.</p>
+	</li>
+</ul>
+<br/>
+<p>Here's an example of a die:
+<pre>
+	&lt;Nword&gt; =nword= #1..2# /^N/ :varchar: &lt;/Nword&gt;
+</pre>
+</p>
+<p>This die defines an xml tag named "Nword" to be any varchar beginning with the letter N and ooccuring
+only once or twice.</p>
+<br/>
+<h1>Namespaces and Schema Declerations</h1>
+<p>We have mentioned above xml:Proof's use of namespaces. In fact they are so fundemental, xml:Proof offers
+a variant notation for namespace declarations differing from the one recommened by the W3C.
+The W3C's recommendation is rather nebulous and clumsy, and further, clutters and obscures the information
+of relevance in an XML document. Therefore namespace declarations can be defined by document level
+processing instructions instead of within general element tags. Because XML processing instructions can
+be freely defined we have not violated any of the W3C standard by doing this,
+yet we have made our lives much improved!* This notation actually peacefully coexists with the
+standrard notation because it in effect does nothing more then insert a document level
+ATTRLIST for the namespaces defined.</p>
+<p>Here is the top of an XML document using this alternate notation:
+<pre>
+  &lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
+  &lt;?xml:ns prefix="example" uri="http://www.transami.net/namespace/testing"?&gt;
+</pre>
+This is effectively translated by the XML Processor into:
+<pre>
+  &lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
+  &lt;!DocType <i>docname</i> [
+    &lt;!ATTLIST <i>docname</i> xmlns:example 'http://www.transami.net/namespace/testing' CDATA&gt;
+  ]&gt;
+</pre>
+Thus the processing instruction <code>xml:ns</code> defines a namespace. The <code>prefix</code> and <code>uri</code>
+attributes can also be labeled <code>name</code> and <code>space</code>, respectively. Subsequently any tag
+or attribute prefixed with the <code>prefix</code> or <code>name</code> value will
+thus be associated to this declared namespace.
+<p>Obviously, to date, XML Processors generally do not support
+this processing instruction, but it is hoped that this alternate notation will
+catch on in the XML community and will be generally adopted as a new standard.
+In the mean time all xml:Proof processors should provide a means to convert between
+the two different notations.</p>
+<p>Schema declarations are similar to namespace declarations.
+They are declared via processing instructions as well. For example:
+<xmp>
+  <?xml version="1.0" encoding="ISO-8859-1"?>
+  <?xml:ns prefix="example" uri="http://www.transami.net/namespace/testing"?>
+  <?xml:schema uri="http://www.transami.net/namespace/xmlproof" url="example1.xsp"?>
+  <?xml:schema uri="http://www.transami.net/namespace/xmlproof" url="example2.xsp"?>
+</xmp>
+The <code>uri</code> attribute, or its synonym </code>space</code>, define the kind of schema that is being utilized.
+This is the specific namespace uri as defined by the schema's designers. In the case of xml:Proof, it
+is "http://www.transami.net/namespace/xmlproof". It would be another string for, say, RELAX-NG or Schematron.</p>
+<p>The <code>url</code> attribute, or its synonym </code>source</code> is a path name to
+the .xps file. In this example case, it is a local file in the same location as the XML document itself.
+This is neccessary since proofsheets can not be embedded in the document like DTDs can.</p>
+<p>Interestingly, more than one schema can be declared. In so doing, schema declarations appearing higher
+in the document have precedence over the later. This allows for a means of cast overiding. In our example,
+for any given tag within the document, a matching die will first be searched for in </code>example1.xps</code>.
+Only if it is not found there will <code>example2.xps</code> be searched. This can be quite useful in using borrowed
+schemas. You can add new entries or overide existing entries without actually changing the original's.</p>
+<p><font size="2">*Note: In fact one rule has been violated: the reserved use of an instruction name matching /^xml/i. well, :-p</font></p>
+<br/>
+<h1> Example </h1>
+<p>First let us look at a "traditional", "simple" XML-Schema example:</p>
+<xmp>
+  <?xml version="1.0" encoding="ISO-8859-1"?>
+  <shiporder orderid="889923"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:noNamespaceSchemaLocation="shiporder.xsd">
+    <orderperson>John Smith</orderperson>
+    <shipto>
+      <name>Ola Nordmann</name>
+      <address>Langgt 23</address>
+      <city>4000 Stavanger</city>
+      <country>Norway</country>
+    </shipto>
+    <item>
+      <title>Empire Burlesque</title>
+      <note>Special Edition</note>
+      <quantity>1</quantity>
+      <price>10.90</price>
+    </item>
+    <item>
+      <title>Hide your heart</title>
+      <quantity>1</quantity>
+      <price>9.90</price>
+    </item>
+  </shiporder>
+</xmp>
+<xmp>
+  <?xml version="1.0" encoding="ISO-8859-1" ?>
+  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+    <xs:element name="shiporder">
+      <xs:complexType>
+        <xs:sequence>
+          <xs:element name="orderperson" type="xs:string"/>
+          <xs:element name="shipto">
+            <xs:complexType>
+              <xs:sequence>
+                <xs:element name="name" type="xs:string"/>
+                <xs:element name="address" type="xs:string"/>
+                <xs:element name="city" type="xs:string"/>
+                <xs:element name="country" type="xs:string"/>
+              </xs:sequence>
+            </xs:complexType>
+          </xs:element>
+          <xs:element name="item" maxOccurs="unbounded">
+            <xs:complexType>
+              <xs:sequence>
+                <xs:element name="title" type="xs:string"/>
+                <xs:element name="note" type="xs:string" minOccurs="0"/>
+                <xs:element name="quantity" type="xs:positiveInteger"/>
+                <xs:element name="prize" type="xs:decimal"/>
+              </xs:sequence>
+            </xs:complexType>
+          </xs:element>
+        </xs:sequence>
+        <xs:attribute name="orderid" type="xs:string" use="required"/>
+      </xs:complexType>
+    </xs:element>
+  </xs:schema>
+</xmp>
+<br/>
+<p>Now here's the near equivalent in xml:Proof, with a little extra added to show-off:</p>
+<xmp>
+  <?xml version="1.0" encoding="ISO-8859-1"?>
+  <?xml:ns name="example" space="http://www.transami.net/namespace/testing"?>
+  <?xml:schema source="example1.xsp" space="http://www.transami.net/namespace/xmlproof"?>
+  <example:shiporder orderid="889923">
+    <orderperson>John Smith</orderperson>
+    <shipto>
+      <name>Ola Nordmann</name>
+      <address>Langgt 23</address>
+      <city>4000 Stavanger</city>
+      <country>Norway</country>
+    </shipto>
+    <item>
+      <title>Empire Burlesque</title>
+      <note>Special Edition</note>
+      <quantity>1</quantity>
+      <price>10.90</price>
+    </item>
+    <item>
+      <title>Hide your heart</title>
+      <quantity>1</quantity>
+      <price>9.90</price>
+    </item>
+  </example:shiporder>
+</xmp>
+<xmp>
+  <?xml version="1.0" encoding="ISO-8859-1" ?>
+  <?xml:ns name="example" space="http://www.transami.net/namespace/testing" ?>
+  <?xml:ns name="xp" space="http://www.transami.net/namespace/xmlproof" ?>
+  <xp:proofsheet>
+    <example:shiporder orderid=":int:">
+      <orderperson> :text: ?bywho? </orderperson>
+      <orderclerk> :text: ?bywho? </orderclerk>
+      <shipto> #1..1# @true@
+        <name> :text: </name>
+        <address> :text: </address>
+        <city> :text: </city>
+        <country> :text: </country>
+      </shipto>
+      <item> #1..*# @true@
+        <title> :text: </title>
+        <note> :text: </note>
+        <quantity> =use_again= :unsigned: </quantity>
+        <overstock> =use_again= </overstock>
+        <price> :float: </price>
+      </item>
+    </example:shiporder>
+  </xp:proofsheet>
+</xmp>
+<br/>
+<p>Notice the difference in the way namespaces are used. XML-Schema has its own namespace for every tag,
+seperate from the XML document's, which makes sense, since it uses its own set of tag names. Furthermore the document
+itself is forced to use an "instance" of the schema as the namespace of its elements and attributes.
+Thus the document is "confined" to the schema. xml:Proof on the other hand uses the same tag and attribute names
+as the document itself and thus the same freely defined namespace. Using the same namespace gives the two sets of
+data a greater association, without the limitations imposed by XML-Schema, and, last but certainly not least,
+is far easier to comprehend.</p>
+<br/>
+<h1>Functionality</h1>
+<p>So all this is well and fine, but how does xml:Proof actually work? Well, that is farily simple really.
+xml:Proof simply matches XPaths between the proofsheet and the document sharing the same namespace,
+such that a particular die is applied to any corresponding document element or attribute. From the example given above,
+you'll notice that the <code>item</code> element appears twice within the XML document. These two elements
+match to the single proofsheet element of the same name. For instance the absolute XPath,
+<code>example:shiporder/item/quantity</code>, containing <code>1</code> in the document, matches the same
+absolute XPath, <code>example:shiporder/item/quantity</code>, containing <code>=use_again= :unsigned:</code> in the proofsheet.
+This points out an important restriction to proofsheets: any possible absolute XPath within a proofsheet should only
+be accounted for once.*</p>
+<p>Arbitrary dies, cast via the <code>&lt;arbit&gt;</code> tag, overlap in applicability with the general absolute dies.
+Thus if an element or attribute in a target XML document matches against an absolute XPath in the proofsheet and also
+matches against an arbitrary XPath, it must conform to both dies. Further arbitrary dies themselves may overlap in
+applicability.</p>
+<p><font size="2">*Note: If this is not adhered to it is not likely to cause a problem.
+The first occurance of a die will be matched and that will be that.</font></p>
+<br/>
+<h1>XMLProof/Ruby API</h1>
+<p>The XMLProof/Ruby API is a Ruby library for using xml:Proof.
+You can find documentation for its use here: <a href="doc/index.html">xml:Proof/Ruby API Documentation</a>.</p>
+<br/>
+<h1>Conclusion</h1>
+<p>xml:Proof, like all other schemas, is not a cure all for schema definition.
+It has its strengths and weaknesses. But no other schema, of which we are aware,
+matches its capabilites or ease of use. In the end, we believe, and we hope others will agree,
+xml:Proof is by far and away a better way to schema XML. It solves the majority of the requirements of a
+schematic meta-language while minimizing the complexity assocciated with them.
+Best of all it won't give you headaches.</p>
+ <li>xml:Proof, like all other schemas, is not a cure all for schema definition.
+It has its strengths and weaknesses. But we beleive that an analysis of the schematic problem set indicates
+that no other schema matches xml:Proofs capabilites or ease of use.</li>
+  <li>xml:Proof is a better way to schema XML. It solves the majority of the requirements of a
+schematic meta-language while minimizing the complexity assocciated with them.</li>
+<br/>
+<hr/>
+<h1>After Thoughts</h1>
+Honestly I wish prefixes and namespaces were inherited, such that a non-prefixed tag inherits the prefix of its
+closest prefixed ancestor. Thus in the example:
+<pre>
+  &lt;p:a&gt;
+    &lt;b/&gt;
+  &lt;/p:a&gt;
+</pre>
+<code>&lt;b&gt;</code> inherits the prefix <code>p</code> from <code>&lt;p:a&gt;</code>.</p>
+<p>Further, the root tag of a document, without a given prefix, would inherit the prefix of the first appearing namespace.
+Thus, with this new notation, there is no such beast called the <i>default namespace</i>.
+All tags and attributes, in the same fashion, either have a prefix or inherit one. The only exception is when no
+namespaces are declared. In this case all tags and attributes, "erroneously" prefixed or not
+belong to the <i>null-namespace</i>, or <i>empty-namespace</i>. Effectively this means no namespace.
+The null-namespace can be referenced by a prefix by setting the namespace uri to an empty string.</p>
+<p>Dosen't this just make more sense? This seems so appealing to me that I almost made this
+a requirement of xml:Proof!. Oh well, the W3C keeps us working hard.</p>
+<br/>
+<br/>
+<br/>
+</body>
+</html>