applied syntax patch from Rick Jones and rebuilt the web site. Daniel
* doc/xml.html doc/*.html: applied syntax patch from Rick Jones
and rebuilt the web site.
Daniel
diff --git a/doc/xmldtd.html b/doc/xmldtd.html
index 0cf8ec7..de4f48a 100644
--- a/doc/xmldtd.html
+++ b/doc/xmldtd.html
@@ -90,48 +90,49 @@
<p>Table of Content:</p>
<ol>
<li><a href="#General5">General overview</a></li>
-<li><a href="#definition">The definition</a></li>
-<li>
-<a href="#Simple">Simple rules</a><ol>
+ <li><a href="#definition">The definition</a></li>
+ <li>
+<a href="#Simple">Simple rules</a>
+ <ol>
<li><a href="#reference">How to reference a DTD from a document</a></li>
-<li><a href="#Declaring">Declaring elements</a></li>
-<li><a href="#Declaring1">Declaring attributes</a></li>
-</ol>
+ <li><a href="#Declaring">Declaring elements</a></li>
+ <li><a href="#Declaring1">Declaring attributes</a></li>
+ </ol>
</li>
-<li><a href="#Some">Some examples</a></li>
-<li><a href="#validate">How to validate</a></li>
-<li><a href="#Other">Other resources</a></li>
+ <li><a href="#Some">Some examples</a></li>
+ <li><a href="#validate">How to validate</a></li>
+ <li><a href="#Other">Other resources</a></li>
</ol>
<h3><a name="General5">General overview</a></h3>
<p>Well what is validation and what is a DTD ?</p>
<p>DTD is the acronym for Document Type Definition. This is a description of
the content for a family of XML files. This is part of the XML 1.0
-specification, and allows to describe and check that a given document
-instance conforms to a set of rules detailing its structure and content.</p>
+specification, and allows one to describe and verify that a given document
+instance conforms to the set of rules detailing its structure and content.</p>
<p>Validation is the process of checking a document against a DTD (more
generally against a set of construction rules).</p>
<p>The validation process and building DTDs are the two most difficult parts
-of the XML life cycle. Briefly a DTD defines all the possibles element to be
+of the XML life cycle. Briefly a DTD defines all the possible elements to be
found within your document, what is the formal shape of your document tree
-(by defining the allowed content of an element, either text, a regular
+(by defining the allowed content of an element; either text, a regular
expression for the allowed list of children, or mixed content i.e. both text
-and children). The DTD also defines the allowed attributes for all elements
-and the types of the attributes.</p>
+and children). The DTD also defines the valid attributes for all elements
+and the types of those attributes.</p>
<h3><a name="definition1">The definition</a></h3>
<p>The <a href="http://www.w3.org/TR/REC-xml">W3C XML Recommendation</a> (<a href="http://www.xml.com/axml/axml.html">Tim Bray's annotated version of
Rev1</a>):</p>
<ul>
<li><a href="http://www.w3.org/TR/REC-xml#elemdecls">Declaring
elements</a></li>
-<li><a href="http://www.w3.org/TR/REC-xml#attdecls">Declaring
+ <li><a href="http://www.w3.org/TR/REC-xml#attdecls">Declaring
attributes</a></li>
</ul>
<p>(unfortunately) all this is inherited from the SGML world, the syntax is
ancient...</p>
<h3><a name="Simple1">Simple rules</a></h3>
-<p>Writing DTD can be done in multiple ways, the rules to build them if you
-need something fixed or something which can evolve over time can be radically
-different. Really complex DTD like DocBook ones are flexible but quite harder
+<p>Writing DTDs can be done in many ways. The rules to build them if you
+need something permanent or something which can evolve over time can be radically
+different. Really complex DTDs like DocBook ones are flexible but quite harder
to design. I will just focus on DTDs for a formats with a fixed simple
structure. It is just a set of basic rules, and definitely not exhaustive nor
usable for complex DTD design.</p>
@@ -143,13 +144,13 @@
<p><code><!DOCTYPE spec SYSTEM "dtds/mydtd"></code></p>
<p>Notes:</p>
<ul>
-<li>the system string is actually an URI-Reference (as defined in <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>) so you can use a
- full URL string indicating the location of your DTD on the Web, this is a
- really good thing to do if you want others to validate your document</li>
-<li>it is also possible to associate a <code>PUBLIC</code> identifier (a
+<li>The system string is actually an URI-Reference (as defined in <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>) so you can use a
+ full URL string indicating the location of your DTD on the Web. This is a
+ really good thing to do if you want others to validate your document.</li>
+ <li>It is also possible to associate a <code>PUBLIC</code> identifier (a
magic string) so that the DTD is looked up in catalogs on the client side
- without having to locate it on the web</li>
-<li>a dtd contains a set of elements and attributes declarations, but they
+ without having to locate it on the web.</li>
+ <li>A DTD contains a set of element and attribute declarations, but they
don't define what the root of the document should be. This is explicitly
told to the parser/validator as the first element of the
<code>DOCTYPE</code> declaration.</li>
@@ -158,13 +159,13 @@
<a name="Declaring2">Declaring elements</a>:</h4>
<p>The following declares an element <code>spec</code>:</p>
<p><code><!ELEMENT spec (front, body, back?)></code></p>
-<p>it also expresses that the spec element contains one <code>front</code>,
+<p>It also expresses that the spec element contains one <code>front</code>,
one <code>body</code> and one optional <code>back</code> children elements in
this order. The declaration of one element of the structure and its content
are done in a single declaration. Similarly the following declares
<code>div1</code> elements:</p>
<p><code><!ELEMENT div1 (head, (p | list | note)*, div2?)></code></p>
-<p>means div1 contains one <code>head</code> then a series of optional
+<p>which means div1 contains one <code>head</code> then a series of optional
<code>p</code>, <code>list</code>s and <code>note</code>s and then an
optional <code>div2</code>. And last but not least an element can contain
text:</p>
@@ -179,7 +180,7 @@
order.</p>
<h4>
<a name="Declaring1">Declaring attributes</a>:</h4>
-<p>again the attributes declaration includes their content definition:</p>
+<p>Again the attributes declaration includes their content definition:</p>
<p><code><!ATTLIST termdef name CDATA #IMPLIED></code></p>
<p>means that the element <code>termdef</code> can have a <code>name</code>
attribute containing text (<code>CDATA</code>) and which is optional
@@ -204,36 +205,39 @@
meaning that it is optional, or the default value (possibly prefixed by
<code>#FIXED</code> if it is the only allowed).</p>
<p>Notes:</p>
-<ul><li>usually the attributes pertaining to a given element are declared in a
+<ul>
+<li>Usually the attributes pertaining to a given element are declared in a
single expression, but it is just a convention adopted by a lot of DTD
writers:
<pre><!ATTLIST termdef
id ID #REQUIRED
name CDATA #IMPLIED></pre>
-<p>The previous construct defines both <code>id</code> and
- <code>name</code> attributes for the element <code>termdef</code>
-</p>
-</li></ul>
+ <p>The previous construct defines both <code>id</code> and
+ <code>name</code> attributes for the element <code>termdef</code>.</p>
+ </li>
+</ul>
<h3><a name="Some1">Some examples</a></h3>
<p>The directory <code>test/valid/dtds/</code> in the libxml distribution
-contains some complex DTD examples. The <code>test/valid/dia.xml</code>
-example shows an XML file where the simple DTD is directly included within
+contains some complex DTD examples. The example in the file <code>test/valid/dia.xml</code>
+shows an XML file where the simple DTD is directly included within
the document.</p>
<h3><a name="validate1">How to validate</a></h3>
-<p>The simplest is to use the xmllint program coming with libxml. The
-<code>--valid</code> option turn on validation of the files given as input,
-for example the following validates a copy of the first revision of the XML
+<p>The simplest way is to use the xmllint program included with libxml. The
+<code>--valid</code> option turns-on validation of the files given as input.
+For example the following validates a copy of the first revision of the XML
1.0 specification:</p>
<p><code>xmllint --valid --noout test/valid/REC-xml-19980210.xml</code></p>
-<p>the -- noout is used to not output the resulting tree.</p>
-<p>The <code>--dtdvalid dtd</code> allows to validate the document(s) against
+<p>the -- noout is used to disable output of the resulting tree.</p>
+<p>The <code>--dtdvalid dtd</code> allows validation of the document(s) against
a given DTD.</p>
<p>Libxml exports an API to handle DTDs and validation, check the <a href="http://xmlsoft.org/html/libxml-valid.html">associated
description</a>.</p>
<h3><a name="Other1">Other resources</a></h3>
<p>DTDs are as old as SGML. So there may be a number of examples on-line, I
will just list one for now, others pointers welcome:</p>
-<ul><li><a href="http://www.xml101.com:8081/dtd/">XML-101 DTD</a></li></ul>
+<ul>
+<li><a href="http://www.xml101.com:8081/dtd/">XML-101 DTD</a></li>
+</ul>
<p>I suggest looking at the examples found under test/valid/dtd and any of
the large number of books available on XML. The dia example in test/valid
should be both simple and complete enough to allow you to build your own.</p>