## Installation information
for the W3C Markup Validator

### Table of Contents

### This guide, and other guides

#### Other installation guides

The installation guide we provide here is a rather generic set of instructions, which should work on most systems. To our knowledge, the following platform-specific guides are also available and can be of interest :

- Mac OS X and OS X Server at the Apple Developer Connection,
- Mac OS X and OS X Server by Stephen Yoch,
- Windows, by David Tibbe
- Linux (Slackware) by Nick Talbott

#### Related documentation

This installation guides presumes knowledge of the Source availability for the Markup Validator.

We recommend that developers wishing to contribute on the Markup Validator or modify it go through this installation procedure once, to get familiar with the system.

### Installing on packaged systems

The easiest way to install released versions of the Markup Validator is to use the packages created for some platforms by contributors: Debian GNU/Linux and Fedora/Red Hat packages are available.

### Installing from source (generic case)

These instructions are strongly inspired from Nick Talbott's guide for Slackware Linux. Thanks Nick!

#### Download

Download the Validator's Tar Ball and the DTD library from our site.

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.

(Read more about retrieving the source)

#### Prerequisites

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.

##### OpenSP, the SGML (and XML) parser

The SGML parser we're currently using is `OpenSP 1.5.2`, which can be found on the OpenJade home page. Do not try to run the Validator with an earlier than 1.5 version of OpenSP. It will not work. If one hacks it to "work" with such a version, a potential security hole will also open. Just use OpenSP 1.5 or later.

##### Perl Modules

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 CPAN (minimum versions in parenthesis after the name). The following list was complete when CVS spit out: `$Date: 2007/08/06 06:22:49 $`. `:-)`

One easy - and strongly recommended - way to take care of all these Perl module dependencies is to install Bundle-W3C-Validator from CPAN. See the documentation included with it for more details.

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 SourceForge. First make sure to have OpenSP installed, then get the latest revision of the source code for SGML::Parser::OpenSP from CVS, and follow these installation steps, as root:

- perl Makefile.PL
- make
- make test
- make install

This should give you a working SGML::Parser::OpenSP. Just then proceed to install the other required perl modules through CPAN.

##### List of required Perl module distributions

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 CPAN instructions above.

CGI.pm >= 2.81
  The all-singing, all-dancing, everything-and-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.
Config-General >= 2.19
  Configuration file handling.
Encode, Encode-HanExtra and Encode-JIS2k
  Support for multiple character encodings.
HTML-Parser >= 3.25
  Minimal HTML parser used for preparse and finding metadata.
HTML-Encoding
  Determine the encoding of HTML/XML/XHTML documents.
HTML-Template >= 2.6
  Template system which allows us to separate Validator's logic and presentation.
libwww-perl >= 5.60
  Gisle Aas' most excellent WWW library for Perl. This is where our support for downloading pages off the net comes from. Version 5.60 or newer is required, however we strongly suggest a (much) newer version. Validator's support for compressed responses is available with version 5.802 and later. If you want your Validator to support SSL/TLS, see README.SSL included in the libwww-perl distribution.
Net-IP
  IP address manipulation.
SGML-Parser-OpenSP
  Interface to the OpenSP parser. The Validator currently requires a specific version of this module, see details on getting S::P::O from CVS above.
URI
  Library to handle URIs and escaping special characters in them.
XML-LibXML
  The perl binding for libxml2, used to check the syntax of XML-based document types.

##### List of optional Perl module distributions

The perl modules listed below are optional; the validator will use them to provide some extra functionality if they're available.

HTML-Tidy
  HTML-Tidy is used for generating a cleaned up version of the submitted markup.

#### Install the various necessary components:

1. 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).

2. Proceed with the Prerequisites, as detailed above.

3. Create a directory for the validator's installation. On Unix-based systems, the default will be `/usr/local/validator`. This directory will be referred to as `[validatorpath]` throughout this guide.

4. Unpack the archives of the validator and DTD library into a temporary directory, and copy the directories `htdocs`, `httpd/cgi-bin`, and `share` from `validator-X.X.X` into `[validatorpath]`.

   The `[validatorpath]` directory should now have subdirectories named `cgi-bin`, `htdocs`, and and `share`.

#### Configure

##### Configuration files

For reference, here is an overview of all the configuration files for the Markup Validator.

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 `htdocs/config/`.

To really understand what each does you should read the source, but here is a short description to get you started.

validator.conf
  The validator's main configuration file. 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 API is enabled, etc.
charset.cfg
  Maps character sets to conversion parameters for validator's internal UTF-8 conversion.
eref.cfg
  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.
types.conf
  Maps MIME/HTTP Content-Types to an internal "document type" which is used for treating HTML, XML, and XHTML in different ways.

##### Configure the Web server

The following instructions are for the Apache Web server, and should be adapted if you plan on using another server.

1. If you are using the Apache server, you may use the validator under mod_perl2. This should happen automatically if you are using the httpd.conf snippet distributed with the validator or something similar, and your Apache server has mod_perl2 installed and enabled. Using mod_perl2 will bring important performance benefits, but has not been tested extensively. If you are successfully running the validator under mod_perl, or run into issues doing so, contact us.

   Also worth enabling within Apache is mod_expires, which will allow caching of the validator's static documents, stylesheets, and images.

2. Edit the configuration of your Web server to refer to the specific configuration file for the validator.

   This can be done by inserting the contents of the `httpd/conf/httpd.conf` file (from where you unpacked the validator's tarball above) in your `httpd.conf`, or by copying the file somewhere and including it like:

       Include /where/you/copied/it/httpd.conf

   Then, start editing the validator specific part.

3. You may want to set up a "virtual server" for the service. This can be done by adding something similar to the following :

       <VirtualHost 127.0.0.1>
       	DocumentRoot [validatorpath]/htdocs/
       	ServerName validator.example.org
       </VirtualHost>

   AND/OR you may want to have the service at a specific location on your Web server, which can be configured as follows :

       Alias /validator/ [validatorpath]/htdocs/

4. Finish editing this HTTP server configuration file, adapting all the directory references to reflect the paths used in your installation.

5. Now restart the Web server to activate the updated configuration.

   For Apache this is done by typing into a shell, as System Administrator: `apachectl graceful` (or, for older versions of Apache `apachectl configtest` then `apachectl restart`)

##### Configure the Validator itself

1. Create the directory `/etc/w3c` and copy a the files from `[validatorpath]/htdocs/config/` to it.

2. Edit `/etc/w3c/validator.conf` 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.

#### Check the installation

1. Point your browser at the new site.

2. Check the error log of the Web server to get clues on what may be wrong if you get any server errors.

Help us improve this installation guide by sending us your feedback if you install the validator on your local system!

### Troubleshooting a new installation

It is not always easy to troubleshoot an incomplete, or failed, installation of the Markup Validator. While the instructions given in this page should help most people install the validator successfully on their system, bad luck, a forgotten step or a broken component can make things go sour.

#### Double check the installation steps

The first sound thing to do if the installation failed would be to check that you did not forget any step while installing. properly copying and editing the configuration file is among the common mistakes, for example.

#### Check the logs

The error logs for your Web server should be a good first place to look for hints on what is wrong with your installation.

#### Check the dependencies

A common problem with a newly installed validator is a validator that is apparently running but marking anything as "invalid", without giving any error message as output.

This is somewhat typical of a problem with OpenSP. Cross-check that you actually have a version above 1.5, by running `onsgmls --version`.

#### The miracle debug options

If the validator is misbehaving, you can try forcing various debug options by appending to the URL the following string: `&debug=1`

This can sometimes provide you with error messages that would not have appeared anywhere in non-debug mode, and can be helpful to diagnose the problem

#### If all fails...

Don't hesitate to contact the public mailing-list www-validator@w3.org with all the details you can provide on what you did, tried, and what went wrong...

### Post-install options

if the installation succeeded, you should be able to now use the Markup Validator on your own system and network. You may want to give the validator a look and feel specific to your Web site. The easiest way to achieve this is to edit `header.html` and `footer.html` (in the `htdocs` directory), the header and footer markup snippets used to build all pages for the validator.

You may also edit the Style Sheets (in the same directory), especially `base.css` You may however want to avoid editing the other CSS files too heavily, there is a risk you could make the output of the validator unusable.

### Credits and Acknowledgments

The Validator Team wishes to thank Nick Talbott and Stephen Yoch for their help in creating these installation instructions. Thanks also to all the people who use and review the guide to make it better and better!