Well-formed XML docs

591dc752 · Goik Martin · 415552bc · 591dc752 · 591dc752 · 591dc752
Commit 591dc752 authored 7 years ago by Goik Martin
--- a/Sda1/XmlSchema/Ref/Fig/oxygenCheckWellformed.png
+++ b/Sda1/XmlSchema/Ref/Fig/oxygenCheckWellformed.png
--- a/Sda1/XmlSchema/Ref/Fig/wellformedAttribQuote.svg
+++ b/Sda1/XmlSchema/Ref/Fig/wellformedAttribQuote.svg
--- a/Sda1/XmlSchema/Ref/Fig/wellformedProperNesting.svg
+++ b/Sda1/XmlSchema/Ref/Fig/wellformedProperNesting.svg
--- a/Sda1/XmlSchema/xmlschema.xml
+++ b/Sda1/XmlSchema/xmlschema.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter annotations="slide" version="5.1" xml:id="sda1_xmlschema" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:trans="http://docbook.org/ns/transclusion" xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook">
+  <title>XML Schema</title>
+
+  <figure xml:id="sda1_xmlschema_recommendedReading">
+    <title>Recommended Reading</title>
+
+    <itemizedlist>
+      <listitem>
+        <para><xref linkend="bib_fawcett2012"/></para>
+      </listitem>
+
+      <listitem>
+        <para><xref linkend="bib_Walmsley02"/></para>
+      </listitem>
+
+      <listitem>
+        <para><link xlink:href="https://www.w3schools.com/xml/schema_intro.asp">XML Schema Tutorial</link></para>
+      </listitem>
+    </itemizedlist>
+  </figure>
+
+  <section xml:id="sda1_xmlschema_wellFormed">
+    <title>Well formed XML documents</title>
+
+    <para><xref linkend="glo_XML"/> allows for inventing arbitrary dialects. We consider an address database:</para>
+
+    <figure xml:id="sda1_xmlschema_inventDialect">
+      <title>Inventing an address format</title>
+
+      <programlisting language="xml">&lt;?xml version="1.0"  encoding="UTF-8"? &gt; <co linkends="sda1_xmlschema_inventDialect-2" xml:id="sda1_xmlschema_inventDialect-2-co"/>
+&lt;contacts&gt; <co linkends="sda1_xmlschema_inventDialect-3" xml:id="sda1_xmlschema_inventDialect-3-co"/>
+  &lt;person&gt; <co linkends="sda1_xmlschema_inventDialect-4" xml:id="sda1_xmlschema_inventDialect-4-co"/>
+    &lt;firstName&gt;Jeff&lt;/firstName&gt;
+    &lt;lastName&gt;Smith&lt;/lastName&gt;
+    &lt;mail&gt;jeff@smith.com&lt;/mail&gt;
+    &lt;birth day="22" <co linkends="sda1_xmlschema_inventDialect-5" xml:id="sda1_xmlschema_inventDialect-5-co"/> month="11" year="1997"/&gt;
+  &lt;/person&gt;
+    ...
+&lt;/contacts&gt;</programlisting>
+    </figure>
+
+    <para>We explain some conventions:</para>
+
+    <calloutlist>
+      <callout arearefs="sda1_xmlschema_inventDialect-2-co" xml:id="sda1_xmlschema_inventDialect-2">
+        <para>Optional header providing the documents <xref linkend="glo_XML"/> compatibility version and its internal font encoding.</para>
+      </callout>
+
+      <callout arearefs="sda1_xmlschema_inventDialect-3-co" xml:id="sda1_xmlschema_inventDialect-3">
+        <para>The documents unique root element. <tag class="starttag">contacts</tag> does have exactly one child element <tag class="starttag">person</tag>.</para>
+      </callout>
+
+      <callout arearefs="sda1_xmlschema_inventDialect-4-co" xml:id="sda1_xmlschema_inventDialect-4">
+        <para>The <tag class="starttag">person</tag> element has got the parent element <tag class="starttag">contacts</tag>. It also has got three child elements (or children for short) <tag class="starttag">firstName</tag>, <tag class="starttag">lastName</tag> and <tag class="starttag">birth</tag>.</para>
+      </callout>
+
+      <callout arearefs="sda1_xmlschema_inventDialect-5-co" xml:id="sda1_xmlschema_inventDialect-5">
+        <para>Like its predecessors <tag class="starttag">firstName</tag> and <tag class="starttag">lastName</tag> the element <tag class="starttag">birth</tag> is said to have <tag class="starttag">person</tag> as its parent element. In addition <tag class="starttag">birth</tag> does have three attributes <property>day</property>, <property>month</property> and <property>year</property>.</para>
+
+        <para>Attribute names must be unique within a given element's scope. Consider the following <xref linkend="glo_Java"/> class analogy:</para>
+
+        <programlisting language="java">public class Birth {
+   int day=22, month=11, year=1997;
+     ...
+}</programlisting>
+      </callout>
+    </calloutlist>
+
+    <figure xml:id="sda1_xmlschema_wellFormed_Constraints">
+      <title>Constraints of well- formedness</title>
+
+      <itemizedlist>
+        <listitem>
+          <para>Specification <link xlink:href="https://www.w3.org/TR/2006/REC-xml-20060816/#sec-well-formed">at W3C</link>.</para>
+        </listitem>
+
+        <listitem>
+          <para/>
+        </listitem>
+      </itemizedlist>
+    </figure>
+
+    <figure xml:id="sda1_xmlschema_wellFormed_nesting">
+      <title>Proper nesting</title>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="Ref/Fig/wellformedProperNesting.svg"/>
+        </imageobject>
+      </mediaobject>
+    </figure>
+
+    <figure xml:id="sda1_xmlschema_wellFormed_quotes">
+      <title>Attribute quotes</title>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="Ref/Fig/wellformedAttribQuote.svg"/>
+        </imageobject>
+      </mediaobject>
+    </figure>
+
+    <figure xml:id="sda1_xmlschema_wellFormed_oneRoot">
+      <title>Exactly one root element</title>
+
+      <glosslist>
+        <glossentry>
+          <glossterm>Correct: Exactly one root element</glossterm>
+
+          <glossdef>
+            <programlisting language="xml">&lt;iAmRootElement/&gt;</programlisting>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Wrong: Two root elements</glossterm>
+
+          <glossdef>
+            <programlisting language="xml">&lt;iAmRootElement/&gt;
+&lt;iAmYourSibling /&gt;</programlisting>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Wrong: No root element at all</glossterm>
+
+          <glossdef>
+            <programlisting language="xml">&lt;?xml version="1.0"  encoding="UTF-8"? &gt;
+&lt;!-- Noting here but a lousy comment! --&gt;</programlisting>
+          </glossdef>
+        </glossentry>
+      </glosslist>
+    </figure>
+
+    <figure xml:id="sda1_xmlschema_wellFormed_attribNameUnique">
+      <title>Unique attribute names</title>
+
+      <glosslist>
+        <glossentry>
+          <glossterm>Correct: unique attribute names within an element's scope </glossterm>
+
+          <glossdef>
+            <programlisting language="xml">&lt;meeting day="22" hour="4 PM"/&gt;</programlisting>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>Wrong: Duplicate attribute names within an element's scope </glossterm>
+
+          <glossdef>
+            <programlisting language="xml">&lt;meeting day="22" hour="4 PM" day="22"/&gt;</programlisting>
+          </glossdef>
+        </glossentry>
+      </glosslist>
+
+      <para>See <link xlink:href="https://www.w3.org/TR/2006/REC-xml-20060816/#uniqattspec">W3C specification</link>.</para>
+    </figure>
+
+    <figure xml:id="sda1_xmlschema_wellFormed_attribNoOpenBracket">
+      <title>Attribute value disallows <quote>&lt;</quote></title>
+
+      <programlisting language="xml">&lt;boolean term="2 &lt; 3" /&gt;</programlisting>
+
+      <para>Parser error: <code>The value of attribute "term" associated with an element type "boolean" must not contain the '&lt;' character.</code></para>
+
+      <para>See <link xlink:href="https://www.w3.org/TR/2006/REC-xml-20060816/#CleanAttrVals">W3C specification</link>.</para>
+    </figure>
+
+    <qandaset defaultlabel="qanda" xml:id="sda1_qanda_xmlschema_wellFormed_attribNoOpenBracket">
+      <title>Legal attribute values</title>
+
+      <qandadiv>
+        <qandaentry>
+          <question>
+            <para>What about <quote>&gt;</quote> in attribute values? Set up a test file and let your parser of choice doing the work.</para>
+
+            <tip>
+              <para>The Oxygen XML <xref linkend="glo_IDE"/>'s icon:</para>
+            </tip>
+
+            <mediaobject>
+              <imageobjectco>
+                <areaspec otherunits="imagemap" units="other">
+                  <area coords="-3,255,189,301" linkends="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-1" xml:id="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-1-co"/>
+
+                  <area coords="33,142,364,175" linkends="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-2" xml:id="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-2-co"/>
+
+                  <area coords="0,50,42,93" linkends="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-3" xml:id="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-3-co"/>
+                </areaspec>
+
+                <imageobject>
+                  <imagedata fileref="Ref/Fig/oxygenCheckWellformed.png"/>
+                </imageobject>
+
+                <calloutlist>
+                  <callout arearefs="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-1-co" xml:id="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-1">
+                    <para>Icon checking for well-formedness and validity.</para>
+                  </callout>
+
+                  <callout arearefs="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-2-co" xml:id="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-2">
+                    <para>Sub menu choosing between checking for well- formedness and validation.</para>
+                  </callout>
+
+                  <callout arearefs="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-3-co" xml:id="sda1_co_xmlschema_wellFormed_attribNoOpenBracket-3">
+                    <para>Result message well- formed / not well- formed or valid / not valid respectively.</para>
+                  </callout>
+                </calloutlist>
+              </imageobjectco>
+            </mediaobject>
+          </question>
+        </qandaentry>
+      </qandadiv>
+    </qandaset>
+  </section>
+</chapter>
--- a/Sda1/sda1.xml
+++ b/Sda1/sda1.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<book version="5.1" xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:trans="http://docbook.org/ns/transclusion"
+      xmlns:svg="http://www.w3.org/2000/svg"
+      xmlns:m="http://www.w3.org/1998/Math/MathML"
+      xmlns:html="http://www.w3.org/1999/xhtml"
+      xmlns:db="http://docbook.org/ns/docbook">
+  <info>
+    <title/>
+
+    <author>
+      <personname><firstname/><surname/></personname>
+
+      <affiliation>
+        <orgname/>
+      </affiliation>
+    </author>
+
+    <pubdate/>
+  </info>
+
+  <xi:include href="XmlSchema/xmlschema.xml" xpointer="element(/1)"/>
+
+  <xi:include href="../Doc/Common/bibliography.xml" xpointer="element(/1)"/>
+
+  <xi:include href="../Doc/Common/glossary.xml" xpointer="element(/1)"/>
+</book>