Re: Instructions and Feedback page

On Tue, 2001-11-13 at 22:38, Lee Collings wrote:

> http://validator.w3.org/source/
> 
> I have read the page numerous times and find no mention of installation 
> instructions.  Does any one have a clue where I might actually get a copy 
> of installation instructions?  Why not include a page on how to install 
> in the TAR file itself?  I've installed hundreds of scripts and I'm sure 
> that I can review every file and every folder but it sure would be easier 
> if this info was available.

The problem is that there really aren't any installation instructions as
such. The source is available so it's /possible/ to install a local
copy, but very little work has gone into making it actually /possible/
to install. Hopefully this will be remedied at some point.

You'll find some half-baked beginnings of documentation in
<http://validator.w3.org/docs/>, but they aren't very good I'm afraid.


The source in CVS is arranged relative to the installation on
validator.w3.org on an Apache server. That is, you'll find a
sub-directory called "htdocs/" that contains all the HTML files and is
supposed to go into your server's "Document Root", and a directory
called "httpd/" that contains the configuration file for our server
(which is badly out of date BTW) and another directory called "cgi-bin/"
containing the executable CGI scripts.

To get this running you'll have to take all the HTML files and images
from "htdocs/" and place wherever you want them to live on your server,
and at least the "check" CGI program from the "httpd/cgi-bin/" directory
and place it somewhere that your server recognizes as a "CGI" directory.

You'll then have to edit all the HTML files to correct the paths in
links. Unless you have placed it as <http://www.example.com/> there will
probably be several links that do not point where they are supposed to,
and you have to correct the link to the "check" program depending on
where you've decided to place it.

And that was the /easy/ part!

The hard part is editing the "check" CGI program itself. As of right
now, that's a major hurdle unless you happen to be fluent in Perl.

First of all you have to identify all the libraries we use that you do
not have installed already. You can do this by issuing the command
"perl -cw check". It will then complain about any missing libraries.
You'll have to fetch these from CPAN <http://search.cpan.org/> and
install them. Once all libraries are installed, the above command should
say "Syntax OK" and terminate.

The next step is to tweak "check" to match your local installation.

First, you'll need to find the lines near the beginning that read:

#
# Paths and file locations
my $base_path = $0;  # get full name of program
   $base_path =~ s#^(/([^/]*/)*)[^/]*/[^/]*/[^/]*$#$1#; # move two
levels up
        # backtracking is somewhat inefficient, but nothing to worry
# DWC tweak: my $base_path="/var/www/";

Change those lines to read:

#
# Paths and file locations
my $base_path = '/path/to/where/you/put/the/htdocs/';


And then further down you'll find the lines:
#
# Executables and binaries
my $sp  = '/usr/local/bin/lq-nsgmls';
# DWC tweak: my $sp  = '/usr/bin/nsgmls';
my $osp = '/usr/local/bin/onsgmls';

Change these to point to you'r local installations of SP. If you get
OpenSP from <http://openjade.sf.net/>, you can just change both lines to
refer to the "onsgmls" from that. You do not need two separate SGML
parsers (they're an artifact of the local setup on validator.w3.org).


That should leave you with a working installation of the web frontend.
Now you'll need to get and install an SP-compatible SGML parser. I
recommend OpenSP and it comes with it's own installation instructions
(and depending on what you have experience with, it should be much
easier to install then the web frontend).


> What good is a feedback page that hides the ability to offer feedback.  
> Yes I was looking for an email address for someone to communicate with.  
> Instead I am sending a message to a list of people  most of whom may not 
> want the question or care about the answer.

Ok, we'll obviously have to update that page somewhat. Sending mail to
this list _is_ the appropriate venue. There is nobody that can commit to
answering personally addressed mail about the Validator in a timely
fashion. Gerald, the main developer, has a finite amount of time
allocated to working on the Validator and I and the other contributors
do our work in our spare time. I know I have a terrible turnaround time
for answering email these days. Sending to the list open the possibility
that you get an answer from whichever one of us happens to have some
spare time at that moment.

But this should be spelled out on the feedback page. I know most people
prefer not to send questions to a mailinglist they aren't already
subscribed to and familiar with, and don't want to subscribe to Yet
Another Mailinglist.

Thanks for the feedback on this, Lee. Hopefully it'll let us improve
both the installability of the Validator and the feedback page. And,
please, let us know if you need more help! If you absolutely don't want
to send it to the list you can feel free to email me directly, but with
the caveat that I may not be able to respond in a timely fashion. These
questions are _not_ off-topic for this list!

Received on Saturday, 17 November 2001 01:14:06 UTC