- From: Olivier Thereaux via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 03 Aug 2005 04:15:27 +0000
- To: www-validator-cvs@w3.org
Update of /sources/public/validator/htdocs/docs
In directory hutz:/tmp/cvs-serv1770/docs
Modified Files:
install.html
Added Files:
install_win.html
Log Message:
adding windows installation guide courtesy of David Tibbe.
Index: install.html
===================================================================
RCS file: /sources/public/validator/htdocs/docs/install.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- install.html 22 Jul 2005 19:22:10 -0000 1.12
+++ install.html 3 Aug 2005 04:15:25 -0000 1.13
@@ -42,6 +42,7 @@
at the Apple Developer Connection,</li>
<li><a href="http://www.mediaville.net/articles/validator/">Mac OS X and OS X Server</a>
by Stephen Yoch,</li>
+ <li><a href="install_win.html">Windows</a>, by David Tibbe</li>
<li><a href="http://lists.w3.org/Archives/Public/www-validator/2003Dec/0023.html">Linux (Slackware)</a>
by Nick Talbott</li>
</ul>
--- NEW FILE: install_win.html ---
<!--#set var="revision" value="\$Id: install_win.html,v 1.1 2005/08/03 04:15:25 ot Exp $" -->
<!--#set var="date" value="\$Date: 2005/08/03 04:15:25 $" -->
<!--#set var="title" value="Installation Documentation for The W3C Markup Validation Service (Windows, Apache)" -->
<!--#set var="relroot" value="../" -->
<!--#include virtual="../header.html" -->
<div class="doc">
<h2>Installing the W3C-Validator on a Apache under Windows</h2>
<h3 id="TableOfContents">Table of Contents</h3>
<div id="toc">
<ul>
<li><a href="#about">About this guide</a></li>
<li><a href="#needed-programs">Needed programs</a></li>
<li><a href="#directory-structure">Directory Structure</a></li>
<li><a href="#install-programs">Installation of the Programs</a></li>
<li><a href="#modules">Integration of the Perl-Modules</a>
<ul>
<li><a href="#modules-local">Integration from a local repository</a></li>
<li><a href="#modules-remote">Integration from a remote repository</a></li>
</ul></li>
<li><a href="#config-apache">Configuration of the Apache</a></li>
<li><a href="#adaption-of-hosts">Adaptation of the hosts-File</a></li>
<li><a href="#config-validator">Configuration of the Validator</a></li>
<li><a href="#adaption-of-check">Adaptation of the check-Script</a></li>
<li><a href="#hints">Hints</a></li>
</ul>
</div>
<div id="install" class="stb">
<a name="skip" id="skip"></a>
<h3 id="about">About this guide</h3>
<p>This guide for the installation of the W3C Markup Validator was
contributed by David Tibbe. It is also available
<a href="http://aktuell.de.selfhtml.org/artikel/server/validator/">in german</a>.</p>
<p>See the <a href="install.html">generic installation guide</a> for instructions on how
to install the Markup Validator on other platforms and <a href="install.html#otherguides">links
to other platform-specific guides</a>.</p>
<h3 id="needed-programs">Needed programs</h3>
<p>For running the validator on your system, a web server is
required for sure. On my PC, I am running an Apache
(<a href="http://httpd.apache.org/">http://httpd.apache.org/</a>),
Version 2.0.49. Its installation and configuration will not be
discussed here.<br />
If you are running an Apache in another Version, you can use it
either. The changes in the configuration are quite similar to
the newer version.</p>
<p>The Validator-script itself is written in Perl, so you will
need it, too. I use ActivePerl 5.8
(<a href="www.activestate.com/Products/Download/Download.plex?id=ActivePerl">www.activestate.com/Products/Download/Download.plex?id=ActivePerl</a>)
which installation is not difficult either because of an installer.<br />
As mentioned in the changelog, the Validator supports <code>mod_perl</code>. But I have
not tried it yet, so it will not be described in here.</p>
<p>Of course, you need the Validator itself. Packed as a tar-archive
you can download it at
<a href="http://validator.w3.org/validator.tar.gz">http://validator.w3.org/validator.tar.gz</a>
(~900KB). Version 7 is current.</p>
<p>For parsing the files, a <acronym title="Structured Generalized Markup Language">SGML</acronym>-parser
is responsible. Therefore, the program OpenSP 1.5 is proposed. Its
sources are available at SourceForge
(<a href="http://www.sourceforge.net/projects/opensp/">http://www.sourceforge.net/projects/opensp/</a>)
but compiling them on Windows just causes problems. Some time ago,
Björn Höhrmann succeeded in compiling them and made the
binaries available (<a href="http://bjoern.hoehrmann.de/ports/OpenSP-1.5.1-win32-bin.zip">http://bjoern.hoehrmann.de/ports/OpenSP-1.5.1-win32-bin.zip</a>,
~600KB). You can use them but it is recommended to have a look at the
OpenSP-Project page for newer binaries.</p>
<p>The validator needs some Perl-modules. At <a href="http://ppm.activestate.com/">http://ppm.activestate.com/</a>,
there is a list of all available modules. In this list is also mentioned
if a module is "Core" (which means it is build in) or if it
is downloadable.<br />
For the validator, the following modules are required:</p>
<ul>
<li>Config-General</li>
<li>File-Spec</li>
<li>HTML-Template</li>
<li>Net-IP</li>
<li>Set-IntSpan</li>
<li>Text-Iconv</li>
</ul>
<p>You can get them each of them in a single package at ActiveState; I have
packed them ready-to-install in a zip-file
(<a href="http://www.myhpi.de/~dtibbe/download/ppm.zip">http://www.myhpi.de/~dtibbe/download/ppm.zip</a>).</p>
<p>Finally you will need some calm and patience. A whole installation of
the validator (including the Apache and Perl) will take about an hour
if you do not have much experience.</p>
<h3 id="directory-structure">Directory Structure</h3>
<p>It might be a good idea to think about the directories the program should be
installed to. Just clicking "Next" in all installation routines is not good at all.
On my PC, I have a directory <code>C:\www</code> in which all programs concerning my server
are located (in subfolders for sure). So the Apache is installed to <code>C:\www\Apache2</code>,
Perl to <code>C:\www\perl</code>, OpenSP to <code>C:\www\opensp</code> and finally the validator itself
to <code>C:\www\validator</code>. The modules for Perl should be unzipped in a separate
folder; <code>C:\www\pmm</code> in my case. In the following, these paths are used.</p>
<h3 id="install-programs">Installation of the Programs</h3>
<p>Now, the programs are getting installed one after the other. First, the Apache
should be installed and successfully started. As mentioned, this will not be
described in here, but you will find a lot of How-Tos all over the net, e.g.
in the Apache-Documentation:
<a href="http://httpd.apache.org/docs/2.0/platform/windows.html">http://httpd.apache.org/docs/2.0/platform/windows.html</a>.
The only fact that is important to know is that the installation
routine will create a subfolder <code>Apache2</code> by itself. When choosing
<code>C:\www</code> as installation directory, the Apache will be installed to
<code>C:\www\Apache2</code>.</p>
<p>Perl is the next program to be installed. Because of the installer, it is
no problem either. Just make sure that you install ppm3, too. This
program is needed for adding the Perl-modules.</p>
<p>OpenSP is available in a zip-file, you just need to unzip it in
the corresponding folder. It is the same for the Validator and,
if downloaded, my Perl-module collection.</p>
<h3 id="modules">Adding the Perl-Modules</h3>
<p>Now, there is a bit more difficult step: adding the Perl-Modules.
Therefore, the program ppm3 is used (ppm means "Programmer's
Package Manager"). You can start it by clicking the
<kbd>Start</kbd>-Button, selecting <kbd>Run...</kbd>, typing <kbd>ppm3</kbd> and pressing return.
The program will look like this:</p>
<p style="text-align: center"><img src="<!--#echo var="relroot" -->images/ppm_1.png" alt="PPM after the startup" /></p>
<p>When typing <kbd>rep</kbd>, you will get a list of all (in)active repositories. These are
locations for modules out of which you can download and install the needed
ones.</p>
<p>You can add the modules in two ways: In the first case, the modules can be
found local (e.g. extracted from the zip-archive) or in the second case they will
be downloaded from a server (e.g. the ActiveState-Server). In the following,
the first way will be discussed, but is is quite similar to the second one.
So it is recommended in any case to read this section.</p>
<h4 id="modules-local">Integration from a local repository</h4>
<p>When ppm3 is started, it has to be told that such a repository can be found
on the local hard disk, precise at <code>C:\www\ppm</code>. Therefore,
<kbd>rep add local C:\www\ppm</kbd> is typed. Afterwards, a repository
called local exists.<br />
Since you want ppm to search packages only in local, all the others have
to be disabled. When having a look at the output of the <kbd>rep</kbd>-command, you
will find numbers in front of each repository. Typing <kbd>rep off 1</kbd> will
disable the repository identified by the number 1. Do this for
all repositories except the local one. When having finished, you might
see a screen like this:</p>
<p style="text-align: center"><img src="<!--#echo var="relroot" -->images/ppm_2.png" alt="PPM displaying the available repositories" /></p>
<p>Now, ppm3 is ready for the installation of the modules. When typing <kbd>s *</kbd>,
local is searched and all five modules will be found. Typing <kbd>install 1</kbd> will
install the modules identified by the number 1. You have to repeat this for
all modules (by typing their numbers instead, of course). The result should be
similar to this:</p>
<p style="text-align: center"><img src="<!--#echo var="relroot" -->images/ppm_3.png" alt="PPM after having installed the modules" /></p>
<p>If you do not get a "Successfully installed..."-message as the
last output of such an installation, something has failed and you
should try again.<br />
After having done that, you can leave ppm3 by typing <kbd>quit</kbd>. The
modules are ready to use now. All programs are installed right now,
but they do not work together yet. You have to do some configuration
changes.</p>
<h4 id="modules-remote">Integration from a remote repository</h4>
<p>The installation from a remote repository is quite the same as from a local one.
First, you have to check which repositories are active, but you might not need
to change anything. After that, the procedure is the same: By typing <kbd>s *</kbd>
you will get a list of all available modules again. But it is much longer,
so restrict your search. Instead of typing <kbd>s *</kbd>, type e.g
<kbd>s Conf</kbd> for retrieving a list of all modules beginning
with Conf. Download and install all needed modules in this way
(again by typing <kbd>install 5</kbd> for the 5th
result of your search). When getting different versions of a module,
the newest might be the best choice.</p>
<h3 id="config-apache">Configuration of the Apache</h3>
<p>The first file to edit is the <code>httpd.conf</code> located at
<code>C:\www\Apache2\conf</code>, the central configuration file
of your Apache. It is recommended to make a backup before editing
it.</p>
<p>The validator pages are composed by using
<acronym title="Server Side Include">SSI</acronym>. Therefore, the
Apache has to load the required module. In
"Section 1 Global Environment", the different
modules are loaded. SSI needs <code>mod_include</code> for working.
The line</p>
<pre>
LoadModule include_module modules/mod_include.so
</pre>
<p>has to be unquoted (by deleting the # at the beginning of the line) or added
completely if the module is not loaded yet.</p>
<p>The next step is to create a virtual host. It is needed, because the validator
should be run from a different directory and logically separated from the
default host. At the end of the <code>httpd.conf</code>, in
"Section 3: Virtual Hosts", the following lines have to be added:</p>
<pre>
NameVirtualHost 127.0.0.2:80
<VirtualHost 127.0.0.2:80>
ServerName validator.example.org
DocumentRoot "C:/www/validator/htdocs"
ErrorLog logs/error_validator.log
CustomLog logs/access_validator.log common
ScriptAlias /cgi-bin "C:/www/validator/httpd/cgi-bin"
ScriptAlias /check "C:/www/validator/httpd/cgi-bin/check"
AddType text/html .html
AddOutputFilter INCLUDES .html
<Directory "C:/www/validator/htdocs">
Options ExecCGI Includes Indexes MultiViews
AllowOverride None
Order deny,allow
Allow from localhost
</Directory>
<Directory "C:/www/validator/httpd/cgi-bin">
Options ExecCGI Includes Indexes MultiViews
AllowOverride None
Order deny,allow
Allow from localhost
</Directory>
</VirtualHost>
</pre>
<p>The meaning of all these lines will not be discussed here. Who is
interested in their sense can have a look to the manual or in one
of the many How-Tos found by Google. Just some short notes about:
The first line specifies the IP-address, the validator should run
at. It is a loop back address, so the validator will be accessible
only from your machine. The following lines specify the name of
the host, the locations of the log files and some "short
cuts" for the cgi-bin directory and check-script. The next
three lines make the Apache parsing HTML-files for SSI-directives.
The last two sections set some permission for the used
directories.<br />
The files <code>error_validator.log</code> and
<code>access_validator.log</code> can be found in the
<code>C:\www\Apache2\logs</code>-directory. They log every
request and error occurring on this host and give you some
helpful advices in these cases.</p>
<p>Finally, the Apache has to be restarted so that the changes
take effect. You can do that by choosing the shortcut in the
Apache-program group (<kbd>Start</kbd>, <kbd>Programs</kbd>,
<kbd>Apache HTTP Server</kbd>, <kbd>Control Apache Server</kbd>
<kbd>Restart</kbd>). A DOS-box will appear shortly;
when it disappears, the Apache is restarted.</p>
<p>When you call http://127.0.0.2/ in your browser, you should
see the well-known site from
<a href="http://validator.w3.org/">http://validator.w3.org/</a>.
In the configuration file of the Apache, a name for the Virtual
Host was defined (validator.example.org), but it is not
resolved yet. That is changed in the next step.</p>
<h3 id="adaption-of-hosts">Adaptation of the hosts-File</h3>
<p>The <code>hosts</code>-file can be seen as a local
DNS-configuration. It is located in at
<code>C:\windows\hosts</code> on Win9x and at
<code>C:\Windows\system32\drivers\etc\hosts</code> on
WinXP. It might be possible, that the file is missing,
but a file <code>hosts.sam</code> can be found instead.
In that case you have to rename it by deleting the file
extension and its leading dot.</p>
<p>When opening it in an editor, you will find a leading
comment in there. A line</p>
<pre>
127.0.0.1 localhost
</pre>
<p>follows.</p>
<p>That line means that a request to localhost is redirected
to 127.0.0.1 (i.e. calling http://localhost/ in your browser
effects a request to http://127.0.01/).</p>
<p>Edit the file to the following:</p>
<pre>
127.0.0.1 localhost
127.0.0.1 www.example.org
127.0.0.2 validator.example.org
</pre>
<p>After these changes, the server is available at
http://localhost/ but can be accessed also at
http://www.example.org/, too. Requests for
http://validator.example.org/ are redirected to
http://127.0.0.2/.</p>
<p>The server configuration is finished right now. But if you
try to validate a page, you will get an "Internal Server Error",
because the <code>check</code>-script has not been configured yet.</p>
<h3 id="config-validator">Configuration of the Validator</h3>
<p>In the directory <code>c:\www\validator\htdocs\config</code>, a file
called <code>validator.conf</code> can be found. Open it with the editor.
Lines beginning with # are comments.</p>
<p>Because of using a Windows-system, we have to define a
base path to the validator's directory. That is done by
uncommenting the line</p>
<pre>
#Base = /usr/local/validator
</pre>
<p>and changing it to</p>
<pre>
Base = D:/www/validator
</pre>
<p>The next step to do is to define where to find OpenSP.
So we have to change</p>
<pre>
Parser = /usr/bin/onsgmls
</pre>
<p>to</p>
<pre>
Parser = D:/www/opensp/onsgmls.exe
</pre>
<p>The option <code>Home Page</code> has to be changed to the URL of
the validator, http://validator.example.org/ in our case.</p>
<p>The last option that has to be modified is Allow Private
<code>IPs = { no | yes }</code>. It must be set to
"yes". Otherwise, you cannot validate files
from the local PC and you will get just an access fault
because of security reasons.</p>
<p>After that, the configuration file will look like this:</p>
<pre>
#
# Main Configuration File for the W3C Markup Validation Service.
#
# $Id: install_win.html,v 1.1 2005/08/03 04:15:25 ot Exp $
#
# See 'perldoc Config::General' for the syntax, and be aware that the
# 'SplitPolicy' is 'equalsign', ie. keys and values are separated by '\s*=\s*',
# and that 'InterPolateVars' is in effect.
#
#
# Base Path for Markup Validator files.
#
# You MUST set these unless you use the default locations for the files.
# e.g. the config files in "/etc/w3c/" and everything else in
# "/usr/local/validator/".
#
# Make sure all file paths below do NOT end with a slash
<Paths>
#
# Base path. Defaults to the value of the W3C_VALIDATOR_HOME environment
# variable or /usr/local/validator if the variable does not exist.
Base = D:/www/validator
#
# Location of template files
Templates = $Base/share/templates
<SGML>
#
# The SGML Library Path.
Library = $Base/htdocs/sgml-lib
#
# The SGML Parser to use. Defaults to /usr/bin/onsgmls.
Parser = D:/www/opensp/onsgmls.exe
</SGML>
</Paths>
#
# This controls whether the debugging options are allowed to be enabled.
Allow Debug = yes
#
# This lets you permanently enable the debugging options. Can be overridden
# with CGI options (unlike "Allow Debug" above).
Enable Debug = no
#
# Whether private RFC1918 addresses are allowed.
Allow Private IPs = yes
#
# Whether the (highly experimental!) SOAP support should be enabled.
Enable SOAP = no
#
# Whether the validator will check its own output.
# 0 means it will refuse to check its own output, 1 means it will but it will
# refuse to check the results of it checking itself. Etc.
Max Recursion = 0
#
# Protocols the validator is allowed to use for retrieving documents.
# The default is to allow http and https.
<Protocols>
Allow = data,http,https
</Protocols>
#
# Email address of the maintainer of this service.
Maintainer = mail@validator.example.org
#
# The "Home Page" for the service. Make sure this ends with a slash.
Home Page = http://validator.example.org/
#
# Base URI for the Element Reference.
Element Ref URI = http://www.htmlhelp.com/reference/html40/
#
# Mapping tables etc...
#
#
# Maps element names to URLs (cf. "Element Ref URI" above).
<Elements>
Include eref.cfg
</Elements>
#
# Main document Type Registry; contains all information on the types
# of documents we support and how they are processed.
<Types>
Include types.conf
</Types>
#
# Mapping of charset names to their IANA names and how iconv(3) knows them.
<Charsets>
Include charset.cfg
</Charsets>
#
# Map MIME Media Type to Parse Mode mapping.
<MIME>
text/xml = XML
image/svg = XML
image/svg+xml = XML
application/smil = XML
application/xml = XML
text/html = TBD
text/vnd.wap.wml = XML
application/xhtml+xml = XML
application/mathml+xml = XML
</MIME>
#
# Source for the "Tip of The Day" blurbs.
<Tips>
Include tips.cfg
</Tips>
</pre>
<p>Now, the validator has been successfully configured. But it
is not ready for use yet, some lines in the validator script
itself have to be changed before.</p>
<h3 id="adaption-of-check">Adaptation of the check-Script</h3>
<p>The following changes are necessary because the script is
written for a Unixserver where some things are different to
a Windows-system.</p>
<p>The <code>check</code>-script located in the directory
<code>C:\www\validator\httpd\cgi-bin</code> can be opened
with the editor. I will not mention any line numbers in
the following steps, because they might differ in
later versions. Some advices are always placed in the lines above
in the script so that you can orientate yourself to those lines.</p>
<p>The very first line of the script has to be changed to</p>
<pre>
#!c:/www/perl/bin/perl.exe
</pre>
<p>This is the path to the Perl interpreter, up to now in
Unix-style. So it has to be changed to Windows-style. The
parameter <code>-T</code> is replaced by that, too.</p>
<p>In a next step, the script is told where to find the
configuration file. That is done after the comment in these lines</p>
<pre>
#
# Read Config Files.
eval {
my %config_opts = (
-ConfigFile => ($ENV{W3C_VALIDATOR_CFG} || '/etc/w3c/validator.conf'),
</pre>
<p>We do not define an environment variable but specify the full path
to the file. So the lines have to be changed to</p>
<pre>
#
# Read Config Files.
eval {
my %config_opts = (
-ConfigFile => ('D:/www/validator/htdocs/config/validator.conf'),
</pre>
<p>Later in the script, the command line parameters for OpenSP are
defined:</p>
<pre>
# Note: if you feel the urge to remove -R from here, please understand that
# doing so opens a potential security hole. Don't do that; instead just
# make sure you're running OpenSP 1.5 or later.
my @spopt = qw(
-R
-wvalid
-wnon-sgml-char-ref
-wno-duplicate
);
</pre>
<p>The option <code>-R</code> has to be deleted, so that there remains</p>
<pre>
# Note: if you feel the urge to remove -R from here, please understand that
# doing so opens a potential security hole. Don't do that; instead just
# make sure you're running OpenSP 1.5 or later.
my @spopt = qw(
-wvalid
-wnon-sgml-char-ref
-wno-duplicate
);
</pre>
<p>After saving the script, you can use it at http://validator.example.org/
as you know it from http://validator.w3.org/.</p>
<p>That is it, your own validator is working.</p>
<h3 id="hints">Hints</h3>
<p>In further versions of the validator, some other Perl modules
will be needed perhaps. They can be downloaded by ppm3. You
can discover that case very easily: When trying to run the script,
you will get an output like</p>
<pre>
Can't locate Config/General.pm in @INC (@INC contains: C:/www/perl/lib C:/www/perl/site/lib .)
at C:/www/validator/httpd/cgi-bin/check line 46.
BEGIN failed--compilation aborted at C:/www/validator/httpd/cgi-bin/check line 46.
</pre>
<p>It is easy to see that the missing module is "Config General",
that has to be installed.</p>
<p>Windows XP with Service Pack 2 installed might have problems with the
loop back address 127.0.0.2. The Problem and its solution are
described at <a href="http://support.microsoft.com/default.aspx?kbid=884020">http://support.microsoft.com/default.aspx?kbid=884020</a>.</p>
<p>If you do have any further questions, you can send a mail to the author of this
installation guide: <a href="mailto:david@tibbe-online.de">david@tibbe-online.de</a>.</p>
</div>
</div>
<!--#include virtual="../footer.html" -->
</body>
</html>
Received on Wednesday, 3 August 2005 04:15:37 UTC