reorganizing the installation instructions into a set of steps. + style tweaks for docs

2 files changed, 125 insertions, 132 deletions

diff --git a/htdocs/docs/install.html b/htdocs/docs/install.html
index 2d8711b..6bd2189 100755
--- a/htdocs/docs/install.html
+++ b/htdocs/docs/install.html
@@ -1,5 +1,5 @@
-<!--#set var="revision" value="\$Id: install.html,v 1.33 2007-11-29 02:08:33 ot Exp $"
---><!--#set var="date" value="\$Date: 2007-11-29 02:08:33 $"
+<!--#set var="revision" value="\$Id: install.html,v 1.34 2008-04-30 04:35:34 ot Exp $"
+--><!--#set var="date" value="\$Date: 2008-04-30 04:35:34 $"
 --><!--#set var="title" value="Installation Documentation for The W3C Markup Validation Service"
 --><!--#set var="relroot" value="../"
 --><!--#include virtual="../header.html" -->
@@ -60,39 +60,40 @@
     
     <h3 id="install-fromsource">Installing from source (generic case)</h3>
     <p>These instructions are strongly inspired from Nick Talbott's guide for Slackware Linux. Thanks Nick!</p>
-    <h4><a id="install-download" name="install-download"></a>Download</h4>
-        <p>Download the <a href="http://validator.w3.org/validator.tar.gz">Validator's Tar Ball</a>
-        and the sgml-lib <a href="http://validator.w3.org/sgml-lib.tar.gz">DTD library</a> from our site.</p>
-        <p>Alternatively, if you want to work on the latest development version, you can download 
-        both from our CVS repository, but you should be aware that this version may not work at all.</p>
-        <p>(<a href="../source/">Read more</a> about retrieving the source)</p>
-
-    <h4><a id="install-prereq" name="install-prereq"></a>Prerequisites</h4>
 
+	<p>The installation guide assumes that you have a working Web server. We suggest
+    the popular Apache server, which is used for the W3C Markup Validation service. 
+    The validator may work with other Web servers than the popular Apache, but
+    we can not guarantee that it will. You will also need a working installation 
+    of the Perl language (standard on most Web servers).</p>
+
+    <h4 id="install-prereq">Step 0: Prerequisites</h4>
+    <p>
+       Apart from a properly configured Web server, the Validator needs a
+       SGML parser -- that does all the hard work --, Perl (version 5.8.0
+       or newer) and several Perl modules used by the "check" CGI script. 
+     </p>
+	<p>
+	   The following few steps will guide you through installing those 
+	   prerequisites, and then the validator itself</p>
+    
+    <h4 id="install-prereq-sp">Step 1: install OpenSP, the SGML (and XML) parser</h4>
      <p>
-        Apart from a properly configured Web server, the Validator needs a
-        SGML parser -- that does all the hard work --, Perl (version 5.8.0
-        or newer) and several Perl modules used by the "check" CGI script.
-      </p>
-     <h5 id="install-prereq-sp">OpenSP, the SGML (and XML) parser</h5>
-      <p>
-        The SGML parser we're currently using is <code>OpenSP 1.5.2</code>,
-        which can be found on the
-        <a href="http://sourceforge.net/projects/openjade/">OpenJade home page</a>.
-        Note that the validator will not work with any version of OpenSP earlier than 1.5.2.
-      </p>
-
-      <h5  id="install-prereq-perl">Perl Modules</h5>
-      <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/"><acronym
-            title="Comprehensive Perl Archive Network">CPAN</acronym></a>
-        (minimum versions in parenthesis after the name). The following
-        list was complete when CVS spit out:
-        <code>$Date: 2007-11-29 02:08:33 $</code>. <tt>:-)</tt>
-      </p>
+       The SGML parser we're currently using is <code>OpenSP 1.5.2</code>,
+       which can be found on the
+       <a href="http://sourceforge.net/projects/openjade/">OpenJade home page</a>.
+       Note that the validator will not work with any version of OpenSP earlier than 1.5.2.
+     </p>
+	 <p>If you install opensp from source, make sure to enable HTTP retrieval of DTDs:</p>
+	 <pre>
+[unpack opensp]
+./configure --enable-http
+make
+make install
+</pre>
+
+      <h4  id="install-prereq-perl">Step 2: install required Perl Modules</h4>
+	  <h5>Quick and Easy: install the CPAN bundle</h5>
      <p>
        One easy - and strongly recommended - way to take care of all these
        Perl module dependencies is to install
@@ -100,28 +101,19 @@
        from CPAN.  See the <a href="http://search.cpan.org/dist/Bundle-W3C-Validator/lib/Bundle/W3C/Validator.pm">documentation included with it</a>
        for more details.
      </p>
-     
-     <p id="spo_cvs">The only current exception is SGML::Parser::OpenSP, for which at this point in time the development version
-     of the validator requires a not-yet-released version, which can be downloaded and installed 
-     from <a href="http://sourceforge.net/projects/spo">SourceForge</a>. First make sure to have 
-     <a href="#install-prereq-sp">OpenSP</a> installed, then get 
-     <a href="http://sourceforge.net/cvs/?group_id=106431">the latest revision of the source code for SGML::Parser::OpenSP</a> from CVS, 
-     and follow these installation steps, as root:</p>
-     <ul>
-       <li>perl Makefile.PL</li>
-       <li>make</li>
-       <li>make test</li>
-       <li>make install</li>
-     </ul>
-     
-     <p>This should give you a working SGML::Parser::OpenSP. Just then proceed to install the other required perl modules through CPAN.</p>
-            
-     <h5>List of required Perl module distributions</h5>
-     
+	<pre>
+sudo perl -MCPAN -e shell
+[cpan shell starts, you may need to answer configuration questions]
+install Bundle::W3C::Validator
+</pre>
+
+     <h5>For reference: List of required Perl module distributions</h5>
+     <p><strong>You may skip this if you have successfully installed the bundle above</strong>.</p>
+
 	 <p>Below are the perl modules required to run the Markup Validator. This list is informative, 
 	 you do not need to install them individually if you follow the <a href="#install-prereq-perl">CPAN instructions</a>
 	 above.</p>
-	 
+
       <dl>
         <dt><a href="http://search.cpan.org/dist/CGI.pm/">CGI.pm</a> &gt;= 2.81</dt>
         <dd>
@@ -181,7 +173,7 @@
         </dd>
       </dl>
 
-     <h5>List of optional Perl module distributions</h5>
+     <h6>For reference: List of optional Perl module distributions</h6>
 
       <p>
         The perl modules listed below are optional; the validator will use
@@ -196,21 +188,21 @@
         </dd>
       </dl>
 
-    <h4><a id="install-components" name="install-components"></a>Install the various necessary components:</h4>
-        <ol>
-            <li><p>The installation guide assumes that you have a working Web server. We suggest
-            the popular Apache server, which is used for the W3C Markup Validation service. 
-            The validator may work with other Web servers than the popular Apache, but
-            we can not guarantee that it will. You will also need a working installation 
-            of the Perl language (standard on most Web servers).</p></li>
-                
-            <li><p>Proceed with the  Prerequisites, as detailed above.</p></li>
-                
+    <h4 id="install-download">Step 3: Download the validator and DTDs</h4>
+        <p>Download the <a href="http://validator.w3.org/validator.tar.gz">Validator's Tar Ball</a>
+        and the sgml-lib <a href="http://validator.w3.org/sgml-lib.tar.gz">DTD library</a> from our site.</p>
+        <p>Alternatively, if you want to work on the latest development version, you can download 
+        both from our CVS repository, but you should be aware that this version may not work at all.</p>
+        <p>(<a href="../source/">Read more</a> about retrieving the source)</p>
+
+
+    <h4 id="install-components">Step 4: Unpack the validator</h4>
+        <ol>                
             <li><p>Create a directory for the validator's installation. On Unix-based systems, 
-            the default will be <code>/usr/local/validator</code>. This
+            we suggest to use the default folder <code>/usr/local/validator</code>. This
             directory will be referred to as <code>[validatorpath]</code>
             throughout this guide.</p></li>
-                
+     
             <li>
               <p>
                 Unpack the two archives of the validator and sgml-lib into a
@@ -225,55 +217,65 @@
                 and and <code>share</code>.
               </p>
             </li>
+			<li>
+			  <p>The validator uses a number of configuration files, originally located under
+				<code>[validatorpath]/htdocs/config</code>. On unix-based systems, we recommend
+				to move all these files to the folder <code>/etc/w3c</code>.</p>
+			</li>
         </ol>
-    <h4><a id="install-configure" name="install-configure"></a>Configure</h4>
-	<h5>Configuration files</h5>
 
-      <p>
-	For reference, here is an overview of all the configuration files for
-	the Markup Validator.
-      </p>
-
-      <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>htdocs/config/</code>.
-      </p>
-      <p>
-        To really understand what each does you should read the source, but
-        here is a short description to get you started.
-      </p>
-      <dl>
-        <dt>validator.conf</dt>
-        <dd>
-          The validator's <strong>main configuration file</strong>. This will
-          generally be the only file you need to edit. It sets various parameters, such as:
-          the address of the maintainer, the URL for the "Home Page", various file paths and locations,
-          whether the <a href="api.html">API</a> is enabled, etc.
-        </dd>
-        <dt>charset.cfg</dt>
-        <dd>
-          Maps character sets to conversion parameters for validator's
-          internal UTF-8 conversion.
-        </dd>
-        <dt>eref.cfg</dt>
-        <dd>
-          Contains the mappings from element names to a URL path
-          (relative to a configurable URL) for their definitions. Used
-          in output when the "Show Parse Tree" option is enabled.
-        </dd>
-        <dt>types.conf</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>
-       </dl>
-
-
-
-	<h5>Configure the Web server</h5>
+    <h4 id="install-configure">Step 5: Configure the Validator</h4>
+	    <ol>
+	        <li>
+	          <p>
+	            Create the directory <code>/etc/w3c</code> and copy a the files
+	            from <code>[validatorpath]/htdocs/config/</code> to it. You may keep 
+				the configuration files in place, but would have to modify the Web 
+				Server's environment variables to point to the configuration directory.
+				As this may be tedious, we recommend using <code>/etc/w3c</code>.
+	          </p>
+	        </li>
+	        <li>
+	          <p>
+	            Edit <code>/etc/w3c/validator.conf</code> to reflect where files
+	            are in your installation, and configure other parameters there as
+	            you wish.  This file is well commented and modifying it should be
+	            relatively straightforward. In general you will only need to check 
+			    that the Base path is set to where you have unpacked the validator
+			    files.
+	          </p>
+	        </li>
+	    </ol>
+	     <h5>For reference: list of configuration files</h5>
+	     <p><strong>You may skip this, unless you plan to modify the validator's default behavior.</strong>.</p>
+			  <dl>
+		        <dt>validator.conf</dt>
+		        <dd>
+		          The validator's <strong>main configuration file</strong>. This will
+		          generally be the only file you need to edit. It sets various parameters, such as:
+		          the address of the maintainer, the URL for the "Home Page", various file paths and locations,
+		          whether the <a href="api.html">API</a> is enabled, etc.
+		        </dd>
+		        <dt>charset.cfg</dt>
+		        <dd>
+		          Maps character sets to conversion parameters for validator's
+		          internal UTF-8 conversion.
+		        </dd>
+		        <dt>eref.cfg</dt>
+		        <dd>
+		          Contains the mappings from element names to a URL path
+		          (relative to a configurable URL) for their definitions. Used
+		          in output when the "Show Parse Tree" option is enabled.
+		        </dd>
+		        <dt>types.conf</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>
+		       </dl>
+
+
+	<h4 id="configure-apache">Step 6: Configure the Web server</h5>
 	<p>The following instructions are for the Apache Web server, and should be adapted 
 	if you plan on using another server.</p>
         <ol>
@@ -320,24 +322,7 @@
             <code>apachectl configtest</code> then <code>apachectl restart</code>)</p></li>
        </ol>
 
-    <h5>Configure the Validator itself</h5>
-    <ol>
-        <li>
-          <p>
-            Create the directory <code>/etc/w3c</code> and copy a the files
-            from <code>[validatorpath]/htdocs/config/</code> to it.
-          </p>
-        </li>
-        <li>
-          <p>
-            Edit <code>/etc/w3c/validator.conf</code> to reflect where files
-            are in your installation, and configure other parameters there as
-            you wish.  This file is well commented and modifying it should be
-            relatively straightforward.
-          </p>
-        </li>
-    </ol>
-    <h4><a id="install-check" name="install-check"></a>Check the installation</h4>
+    <h4 id="install-check">Step 7: Check the installation</h4>
     <ol>
         <li><p>Point your browser at the new site.</p></li> 
         <li><p>Check the error log of the Web server to get clues on what may be wrong 
diff --git a/htdocs/style/base.css b/htdocs/style/base.css
index 915a5ef..b1cddce 100644
--- a/htdocs/style/base.css
+++ b/htdocs/style/base.css
@@ -92,7 +92,7 @@ h4 {
 
 h5,h6 {
     font-family:Verdana,Arial,sans-serif;
-    color: #11111a;
+    color: #690;
     background-color: white;
     font-weight: normal;
     font-size: small;
@@ -568,7 +568,7 @@ div.doc ul li {
     margin-left: 3em;
 }
 
-div.doc div#toc ol {
+div.doc div#toc ol, div.doc ol {
    list-style-type: decimal;
 }
 div.doc div#toc ol li {
@@ -631,6 +631,14 @@ div.doc code.block {
   margin-right:  3em;
 }
 
+div.doc pre {
+    margin-left: 5em;
+    padding-left: 2em;
+    line-height: 150%;
+    border-left: 1px solid #690;
+    
+}
+
 div.doc code samp {
   font-weight: normal;
   color: black;