Added a small DTD related page following the IRC help needed by maciej on the
topic, Daniel
diff --git a/ChangeLog b/ChangeLog
index afbf195..7a3a23a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Fri Nov 24 14:01:44 CET 2000 Daniel Veillard <Daniel.Veillard@w3.org>
+
+ * doc/xmldtd.html doc/xml.html: following a short step by step
+ guidance on IRC to help maciej with DTDs I started a small
+ page on the subject.
+
Fri Nov 17 17:28:06 CET 2000 Daniel Veillard <Daniel.Veillard@w3.org>
* HTMLparser.c: fixed handling of broken charrefs
diff --git a/doc/xml.html b/doc/xml.html
index 58794e5..e46d5f6 100644
--- a/doc/xml.html
+++ b/doc/xml.html
@@ -1,7 +1,9 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>The XML C library for Gnome</title>
- <meta name="GENERATOR" content="amaya V4.0">
+ <meta name="GENERATOR" content="amaya V4.1">
<meta http-equiv="Content-Type" content="text/html">
</head>
@@ -52,6 +54,8 @@
<li><a href="encoding.html">libxml Internationalization support</a></li>
<li><a href="xmlio.html">libxml Input/Output interfaces</a></li>
<li><a href="xmlmem.html">libxml Memory interfaces</a></li>
+ <li><a href="xmldtd.html">a short introduction about DTDs and
+ libxml</a></li>
</ul>
<h2><a name="Introducti">Introduction</a></h2>
@@ -1374,6 +1378,6 @@
<p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p>
-<p>$Id: xml.html,v 1.57 2000/10/25 13:32:38 veillard Exp $</p>
+<p>$Id: xml.html,v 1.58 2000/11/13 18:22:47 veillard Exp $</p>
</body>
</html>
diff --git a/doc/xmldtd.html b/doc/xmldtd.html
new file mode 100644
index 0000000..b526c63
--- /dev/null
+++ b/doc/xmldtd.html
@@ -0,0 +1,191 @@
+<html>
+<head>
+ <title>Libxml Input/Output handling</title>
+ <meta name="GENERATOR" content="amaya V4.0">
+ <meta http-equiv="Content-Type" content="text/html">
+</head>
+
+<body bgcolor="#ffffff">
+<h1 align="center">Libxml DTD support</h1>
+
+<p>Location: <a
+href="http://xmlsoft.org/xmlio.html">http://xmlsoft.org/xmldtd.html</a></p>
+
+<p>Libxml home page: <a href="http://xmlsoft.org/">http://xmlsoft.org/</a></p>
+
+<p>Mailing-list archive: <a
+href="http://xmlsoft.org/messages/">http://xmlsoft.org/messages/</a></p>
+
+<p>Version: $Revision$</p>
+
+<p>Table of Content:</p>
+<ol>
+ <li><a href="#General">General overview</a></li>
+ <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>
+ <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>
+
+<h2><a name="General">General overview</a></h2>
+
+<p>DTD is the acronym for Document Type Definition. This is a description of
+the content for a familly of XML files. This is part of the XML 1.0
+specification, and alows to describe and check that a given document instance
+conforms to a set of rules detailing its structure and content. </p>
+
+<h2><a name="definition">The definition</a></h2>
+
+<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
+ attributes</a></li>
+</ul>
+
+<p>(unfortunately) all this is inherited from the SGML world, the syntax is
+ancient...</p>
+
+<h2><a name="Simple">Simple rules</a></h2>
+
+<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
+to design. I will just focuse on DTDs for a formats with a fixed simple
+structure. It is just a set of basic rules, and definitely not exhaustive nor
+useable for complex DTD design.</p>
+
+<h3><a name="reference">How to reference a DTD from a document</a>:</h3>
+
+<p>Assuming the top element of the document is <code>spec</code> and the dtd
+is placed in the file <code>mydtd</code> in the subdirectory <code>dtds</code>
+of the directory from where the document were loaded:</p>
+
+<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 RFC 2396)
+ 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
+ don't define what the root of the document should be. This is explicitely
+ told to the parser/validator as the first element of the
+ <code>DOCTYPE</code> declaration.</li>
+</ul>
+
+<h3><a name="Declaring">Declaring elements</a>:</h3>
+
+<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 front, one body and
+one optionnal back in this order. The declaration of one element of the
+structure and its content are done in a single declaration. Similary the
+following declares <code>div1</code> elements:</p>
+
+<p><code><!ELEMENT div1 (head, (p | list | note)*, div2*)></code></p>
+
+<p>means div1 contains one head then a series of optional p, lists and notes
+and then an optional div2. And last but not least an element can contain
+text:</p>
+
+<p><code><!ELEMENT b (#PCDATA)></code></p>
+
+<p><code>b</code> contains text or being of mixed content (text and elements
+in no particular order):</p>
+
+<p><code><!ELEMENT p (#PCDATA|a|ul|b|i|em)*></code></p>
+
+<p> <code>p </code>can contain text or <code>a</code>, <code>ul</code>,
+<code>b</code>, <code>i </code>or <code>em</code> elements in no particular
+order.</p>
+
+<h3><a name="Declaring1">Declaring attributes</a>:</h3>
+
+<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 optionnal
+(<code>#IMPLIED</code>). The attribute value can also be defined within a
+set:</p>
+
+<p><code><!ATTLIST list type (bullets|ordered|glossary)
+"ordered"></code></p>
+
+<p>means <code>list</code> element have a <code>type</code> attribute with 3
+allowed values "bullets", "ordered" or "glossary" and which default to
+"ordered" if the attribute is not explicitely specified. </p>
+
+<p>The content type of an attribute can be text (<code>CDATA</code>),
+anchor/reference/references
+(<code>ID</code>/<code>IDREF</code>/<code>IDREFS</code>), entity(ies)
+(<code>ENTITY</code>/<code>ENTITIES</code>) or name(s)
+(<code>NMTOKEN</code>/<code>NMTOKENS</code>). The following defines that a
+<code>chapter</code> element can have an optional <code>id</code> attribute of
+type <code>ID</code>, usable for reference from attribute of type IDREF:</p>
+
+<p><code><!ATTLIST chapter id ID #IMPLIED></code></p>
+
+<p>The last value of an attribute definition can be <code>#REQUIRED
+</code>meaning that the attribute has to be given, <code>#IMPLIED</code>
+meaning that it is optional, or the default value (possibly prefixed by
+<code>#FIXED</code> if it is the only allowed).</p>
+
+<h2><a name="Some">Some examples</a></h2>
+
+<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 the
+document.</p>
+
+<h2><a name="validate">How to validate</a></h2>
+
+<p>The simplest is to use the xmllint program comming 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
+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
+a given DTD.</p>
+
+<p>Libxml exports an API to handle DTDs and validation, check the <a
+href="http://xmlsoft.org/html/gnome-xml-valid.html">associated
+description</a>.</p>
+
+<h2><a name="Other">Other resources</a></h2>
+
+<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>
+
+<p></p>
+
+<p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p>
+
+<p>$Id$</p>
+</body>
+</html>