Merging from branch validator-0_6_0-branch, at tag validator-0_6_5-release.

1 files changed, 58 insertions, 198 deletions

diff --git a/htdocs/docs/devel.html b/htdocs/docs/devel.html
index cb0cd2d..25a4eae 100755
--- a/htdocs/docs/devel.html
+++ b/htdocs/docs/devel.html
@@ -1,198 +1,68 @@
-<!--#set var="revision" value="\$Id: devel.html,v 1.15 2003-05-24 20:32:46 link Exp $"
---><!--#set var="date" value="\$Date: 2003-05-24 20:32:46 $"
+<!--#set var="revision" value="\$Id: devel.html,v 1.16 2004-05-09 15:56:50 link Exp $"
+--><!--#set var="date" value="\$Date: 2004-05-09 15:56:50 $"
 --><!--#set var="title" value="Developer Documentation for The W3C Markup Validation Service"
 --><!--#set var="relroot" value="../"
 --><!--#include virtual="../header.html" -->
 
-    <p id="skip">
-      The W3C Markup Validation Service consists of an SGML Parser, an SGML
-      catalog, a CGI program and it's configuration files. In addition it
-      relies on a moderately large set of Perl modules for it's operation.
-    </p>
+<div class="doc">
+<h2>Installation and development information <br />for the W3C Markup Validator</h2>
+
+<h3 id="TableOfContents">Table of Contents</h3>
+
+    <div id="toc">
+      <ul>
+	<li><a href="#participate">Participate</a></li>
+        <li><a href="devel-frame">Development Framework</a>
+	  <ul>
+		<li><a href="#bug">Bugs and Issue Tracking</a></li>
+		<li><a href="#test">Test suite</a></li>
+        	<li><a href="#todo">TODO</a></li>
+	  </ul>
+	</li>
+      </ul>
+    </div>
+    
     <p>
-      This document tries to draw a road map of the prerequisites and what the
-      different parts of the system do. It is intended for system
-      administrators and people interested in helping developing the validator.
-      This is not end user documentation. See the
-      <a href="users.html">User Manual</a> for usage instructions.
+    <a id="skip" name="skip"></a>
+      This document is an overview of how developers can modify the Markup Validator, and how to contribute
+      to the development of the project. It is intended for system administrators and developers.
+      <strong>This is not end user documentation</strong>. See the <a href="users.html">User Manual</a> for usage instructions.
     </p>
+	
+     <h3><a id="participate" name="participate"></a>Participating in the development of the Markup Validator</h3>
+     <p>The Markup Validator is managed as an open source project by a <a href="http://www.w3.org/QA/Tools/qa-dev">team 
+     of volunteer developers and people from the W3C Team</a>.</p>
+     <p> Help on this project is always welcome, usually as <a href="../feedback.html">feedback</a>,
+     but developers may also be interested in working directly on the code, which is certainly encouraged.</p>
 
-    <div id="prereq" class="stb">
-      <h2>Prerequisites</h2>
-      <p>
-        Apart from a properly configured web server, the Validator needs a
-        SGML parser -- that does all the hard work -- and several Perl
-        modules used by the "check" CGI script.
-      </p>
-      <p>
-        The SGML parser we're currently using is <code>OpenSP 1.5</code>,
-        which can be found on the
-        <a href="http://openjade.sourceforge.net/">OpenJade home page</a>.
-      </p>
-      <p>
-        The canonical list of Perl modules we use can be found in the source
-        for the "check" CGI script. There is a bunch of lines that of the form
-        "use Foo::Bar" where each "Foo::Bar" represents a module. Most modules
-        can be found on <a href="http://www.cpan.org/">CPAN</a> (minimum
-        versions in parenthesis after the name). The following
-        list was complete when CVS spit out:
-        <code>$Date: 2003-05-24 20:32:46 $</code>. <tt>:-)</tt>
-      </p>
-      <dl>
-        <dt><code>CGI (2.81)</code></dt>
-        <dd>
-          The all-singing, all-dancing,
-          everything-<em>and</em>-the-kitchen-sink, Perl CGI library. This
-          takes care of all those niggly little bits of CGI for us and make
-          options parsing and file upload a breeze.
-        </dd>
-        <dt><code>CGI::Carp</code></dt>
-        <dd>CGI-aware warn()/die()</dd>
-        <dt><code>File::Spec</code></dt><dd>Portable filespecs.</dd>
-        <dt><code>HTML::Parser (3.25)</code></dt>
-        <dd>Minimal HTML Parser used for preparse and finding metadata.</dd>
-        <dt><code>LWP::UserAgent (1.90)</code></dt>
-        <dd>
-          Gisle Aas' most excellent WWW library for Perl. This is where our
-          support for downloading pages off the net comes from.
-        </dd>
-        <dt><code>Set::IntSpan</code></dt><dd>Efficient Set operations.</dd>
-        <dt><code>Text::Iconv</code></dt>
-        <dd>
-          Perl-native interface to the (g)libc iconv(3) library. Handles
-          charset conversion issues.
-        </dd>
-        <dt><code>Text::Wrap</code></dt>
-        <dd>Wrap text to a sane width. Needed for source output in results.</dd>
-        <dt><code>URI::Escape</code></dt>
-        <dd>Module to handle escaping special characters in URIs.</dd>
-      </dl>
-    </div>
-    <div id="config" class="stb">
-      <h2>Configuration Files</h2>
-      <p>
-        The validator uses a number of configuration files -- most of which
-        are really mapping tables of some form -- to avoid having to check in
-        a new version of the code every time a new version of HTML comes out.
-        All configuration files can be found in
-        <code>$CVSROOT/validator/htdocs/config/</code>.
-      </p>
+     <p>This document tries to give a general overview of the development framework for the Markup Validator, and
+     should help developers get a good idea of how the project is managed.</p>
+     <p>The next steps would certainly be to read about <a href="../source/">source availability</a> and then try 
+     a <a href="install.html">local installation</a> of the validator, if not done yet. We also (obviously) recommend
+     to get in touch with other developers, either through <a href="../feedback.html">regular means</a>, or on the
+     IRC channel #validator on irc.freenode.net where many developers and contributors often are.</p>
+
+     <h3><a name="devel-frame" id="devel-frame"></a>Development Framework</h3>
+
+	<h4>Bug and Issue Tracking System</h4>
       <p>
-        To really understand what each does you should read the source, but
-        here is a short description to get you started.
+        Bug and Issue Tracking for the Validator happens in the <a
+          href="http://www.w3.org/Bugs/Public/">W3C Public Bugzilla</a>
+        instance. Developers should feel free to set up an account
+        and report bugs, enhancement requests, patches, etc. directly there
+        (end users should continue to send reports and ideas to the 
+	<a href="http://lists.w3.org/Archives/Public/www-validator/">mailing list</a>).
       </p>
-      <dl>
-        <dt>validator.conf</dt>
-        <dd>
-          Main configuration file. Gives various parameters (such as the
-          address of the maintainer and the URL for the "Home Page") and
-          the locations of the other configuration files and mapping tables.
-        </dd>
-        <dt>types.conf</dt>
-        <dd>
-          <p>
-	    The main document type database for the Validator. This file
-            contains information on all the document types we know of. It
-            lets us map from a Public Identifier to a plain text version
-            string, lookup an URL for more information on a DOCTYPE, and
-            check which Content-Types and Namespaces are legal for this
-            particular DOCTYPE.
-          </p>
-          <p>And entry in this file looks like this:</p>
-<pre>
-&lt;XHTML_1_1&gt;
-  Name       = html
-  Display    = XHTML 1.1
-  Info_URL   = http://www.w3.org/TR/xhtml11/
-  PubID      = -//W3C//DTD XHTML 1.1//EN
-  SysID      = http://www.w3.org/TR/2001/REC-xhtml11-20010531/DTD/xhtml11-flat.dtd
-  Parse_Mode = XML
-  &lt;Content_Types&gt;
-    Allowed   = application/xhtml+xml
-    Forbidden = text/html
-    Preferred = application/xhtml+xml
-  &lt;/Content_Types&gt;
-  &lt;Namespaces&gt;
-    Allowed   = http://www.w3.org/1999/xhtml
-    Required  = 1
-  &lt;/Namespaces&gt;
-  &lt;Badge&gt;
-    URI    = http://www.w3.org/Icons/valid-xhtml11
-    Height = 31
-    Width  = 88
-  &lt;/Badge&gt;
-&lt;/XHTML_1_1&gt;
-</pre>
-          <p>
-            The name used for each section (e.g. "XHTML_1_1") is arbitrary.
-            The file will be turned inside out and will end up indexed by
-            the "PubID". This means that you cannot have two entries with
-            the same PubID. The rest of the parameters are:
-          </p>
-          <table class="config">
-            <tr><th>Name</th><td>The "Document Type Name" for this document type.</td></tr>
-	    <tr><th>Display</th><td>The pretty text version for the PubID.</td></tr>
-	    <tr><th>Info_URL</th><td>URL for more information on the PubID.</td></tr>
-            <tr><th>PubID</th><td>The Formal Public Identifier for this document type.</td></tr>
-	    <tr><th>SysID</th><td>A System Identifier for the DTD.</td></tr>
-	    <tr><th>Parse_Mode</th><td>Boolean describing whether to treat this as XML or SGML.</td></tr>
-	    <tr>
-	      <th>Content_Types</th>
-              <td class="subtable">
-	        <table>
-	          <tr><th>Allowed</th><td>Allowed Content-Types</td></tr>
-	          <tr><th>Forbidden</th><td>Forbidden Content-Types</td></tr>
-	          <tr><th>Preferred</th><td>Preferred Content-Types</td></tr>
-	        </table>
-	      </td>
-	    </tr>
-	    <tr>
-	      <th>Namespaces</th>
-	      <td class="subtable">
-	        <table>
-	          <tr><th>Allowed</th><td>Allowed Namespaces</td></tr>
-	          <tr><th>Required</th><td>Boolean describing whether a Namespace is required in this document type.</td></tr>
-	        </table>
-	      </td>
-	    </tr>
-	    <tr>
-	      <th>Badge</th>
-	      <td class="subtable">
-	        <table>
-	          <tr><th>URI</th><td>URI for a "Valid Foo" badge.</td></tr>
-	          <tr><th>Height</th><td>Height of this image.</td></tr>
-	          <tr><th>Width</th><td>Width of this image.</td></tr>
-	        </table>
-	      </td>
-	    </tr>
-          </table>
-        </dd>
-        <dt>eref.cfg</dt>
-        <dd>
-          Contains the mappings from element names to an URI fragment
-          (relative to a configurable URI) for their definitions. Used
-          in output when the "Show Source Input" option is enabled.
-        </dd>
-        <dt>frag.cfg</dt>
-        <dd>
-          Maps error messages to an URI fragment identifier where an
-          explanation of that error can be found.
-        </dd>
-        <dt>type.cfg</dt>
-        <dd>
-          Maps MIME/HTTP Content-Types to an internal "document type" which
-          is used for treating HTML, XML, and XHTML in different ways.
-        </dd>
-        <dt>validator.conf</dt>
-        <dd>
-          Main configuration file. Gives various parameters (such as the
-          address of the maintainer and the URL for the "Home Page") and
-          the locations of the other configuration files and mapping tables.
-        </dd>
-       </dl>
-    </div>
-    <div id="todo" class="stb">
-      <h2>TODO</h2>
+      <h4><a id="test" name="test"></a>Test suite</h4>
+
+       <p>
+         Any changes to the service will attempt to maintain
+         compatibility with a <a href="../dev/tests/">list of test cases</a>.
+       </p>
+       <p>We are in the process of turning this (crude) list into a more manageable 
+	testing framework.</p>
+
+      <h4><a id="todo" name="todo"></a>TODO</h4>
       <p>
         The TODO list for the Validator is online at
         &lt;<a href="../todo.html">http://validator.w3.org/todo.html</a>&gt;.
@@ -210,19 +80,9 @@
         think is a Good Idea&reg;. While extra features are nice, they
         shouldn't dilute the value of the validator as an objective check.
       </p>
-    </div>
-    <div id="bugzilla" class="stb">
-      <h2>Bugs and Issue Tracking</h2>
-      <p>
-        Bug and Issue Tracking for the Validator happens in the <a
-          href="http://www.w3.org/Bugs/Public/">W3C Public Bugzilla</a>
-        instance. Developers should feel free to set up an account
-        and report bugs, enhancement requests, patches, etc. directly there
-        (end users should continue to send stuff to the mailinglist).
-      </p>
-    </div>
 
+
+</div>
 <!--#include virtual="../footer.html" -->
   </body>
 </html>
-