ROADS software version 2.1 -------------------------- WHAT IS THIS ? The ROADS software is a collection of tools which can be used in building on-line catalogues. You could think of it as a free version of Yahoo, with lots of value-added features to make life easier for the service operator. Key features of the package are :- . Simple text based resource description format . World-Wide Web forms based resource description editor . WWW and WHOIS++ based search capability . Automatic generation of customised views of the catalogue, e.g. breakdowns by subject category . Automatic generation of listings of recently added resources . Dynamic browsing of resources in particular subject categories . Highly customizable HTML output . Distributed indexing and searching across multiple WHOIS++ servers using the Common Indexing Protocol (centroids) . Limited support for indexing and searching Harvest and Z39.50 servers . Tested for Year 2000 compliance according to the British Standards Institute's check list It also features a number of World-Wide Web based database administration tools, e.g. . Index maintenance . Removing/archiving old resource descriptions . Overall installation consistency checking . Resource description consistency checking . Review date checking . Checking for broken links (dangling URLs) . Checking for duplicate URLs . Checking for URL currency, e.g. records which have (or have not) been changed recently Most of these tools can be used independently of each other. You could choose, for example, not to support searching via WHOIS++ - or not to generate subject category breakdowns of your resource descriptions. However, all of the tools are written to manipulate their data in the IAFA template format, a simple way of writing simple Internet resource descriptions. BACKGROUND The aim of this work is to provide infrastructure software to support a growing number of Subject Based Information Gateways, sometimes referred to as SBIGs. Examples of existing gateway services using the ROADS software include: ADAM: - Art, Design & Media Alex: - Electronic Texts Biz/ed: - Business & Economics History: - History OMNI: - Health & Medicine SOSIG: - Social Sciences The development of this software was initially funded by the Joint Information Systems Committee (JISC) of the UK Higher Education Funding Councils as part of a project called Resource Organisation and Discovery in Subject-based Services (ROADS!). ROADS is one of a number of projects in the UK Electronic Libraries Programme (aka eLib). Further funding has been made available through the European Commission's 'DESIRE' project (under the Telematics for Research programme), and by TERENA under its Development Programme. More information about ROADS as a project and the ROADS software is available at the Institute for Learning and Research Technology (ILRT) at Bristol University :- More information about eLib and the eLib subject services is available from the UK Office of Library and Information Networking (UKOLN), based at the University of Bath :- THE AUTHORS This software was written by Jon Knight and Martin Hamilton, in the Department of Computer Studies at Loughborough University of Technology, deep in the heart of the English Midlands. We've been aided and abetted by a number of people who ran alpha and beta test versions of the code, contributed bug reports and (best of all :-) bug fixes. Our thanks to you! In particular, we'd like to thank: Mark Burrell, Debra Hiom, Andy Powell, Rebecca Bradshaw, Bob Parkinson, Dan Brickley, Jasper Tredgold, Donal Hanna, Bill Jupp, Thomas Krichel, Virginia Knight, Peter Valkenburg, Lasse Haataja, Rami Heinisuo and Annemette Hoegsbro. REQUIREMENTS This version of the ROADS software requires . a Unix-like operating system, e.g. Linux or FreeBSD . Perl 5.002 or above (5.004 recommended) . an HTTP daemon which supports the Common Gateway Interface (CGI) specification, e.g. the Apache or NCSA servers. In order to run the link checking tool, and its associated report generator, you will need libwww-perl-5, which may be obtained from or your nearest Comprehensive Perl Archive Network (CPAN) site, which you can find by pointing your WWW browser at The ROADS software was developed mostly under SunOS 4.1.4 and Linux using the Apache HTTP server. It has also been lightly tested under other variants of Unix, including IRIX 5, HP/UX 9, Digital Unix (OSF/1) and Solaris 2. Please let us know if you have any difficulty in getting it running on your platform! INSTALLATION If you're running RedHat Linux, we've made installation very simple for you - ROADS is available as an 'RPM' package which can be installed and configured with just a single command at the Unix shell prompt. Check out our software WWW site for more information! If not, you'll have to do it the hard way :-) The ROADS software distribution is packaged up as a compressed Unix tar file. To extract the installation from this file use: zcat roads-v2.1.tar.Z | tar xvf - Make sure that you use binary mode if you transfer the compressed tar file over the Internet using FTP. If not, it will be damaged in transit and will not be usable. Once the tar file has been expanded you should find that you have a directory called roads-v2.1. Before you start installing the software, we suggest that you read the installation guide, which you will find along with our other on-line documentation at: http://www.roads.lut.ac.uk/v2/Manual/ To install the software, enter the roads-v2.1 directory and type: ./Configure If this doesn't work, try perl ./Configure You may need to give the full path to Perl, e.g. /usr/local/bin/perl ./Configure This runs a configuration script which will find out about your machine, ask you some simple questions about where you wish to install the ROADS software and documentation and then proceed to install the software. The ROADS software does NOT need to run as the "root" superuser on your machine but it is important that the user the HTTP daemon runs as (e.g. nobody) is able to read the files which the ROADS software generates. Installation of the software need not take place as root, unless you do not have write access to all of the directories involved in the installation. If in doubt, you can install the ROADS software in the directory in which it was unpacked - which will NOT require root. Depending on which components of the ROADS software you choose to use, you may need to grant your HTTP daemon write access to some of the ROADS files and directories. This is discussed in detail in the appropriate sections of the documentation. DOCUMENTATION A (nearly!) comprehensive set of of technical documentation is available alongside this release. We have tried to document the following: . the installation process itself . programs used to maintain the ROADS installation . programs used to manage databases of resource descriptions . programs interacted with by end users . configuration file formats . log file formats . internal file formats Technical notes on the overall installation and configuration process will be forthcoming in a future release, as will documentation aimed at the non-technical user and end-user. We maintain a software and documentation archive at Loughborough University of Technology. This can be reached on the Web as Look out for draft documentation and information about new versions of the software here! Hint: the ROADS tools are self-documenting, using Perl's "POD" system. This means that you can get to the documentation for a program or library module by typing something like :- perldoc bin/addsl.pl i.e. "perldoc" followed by the path to the Perl code. SAMPLE DATABASE The ROADS software ships with a sample database of UK Electronic Libraries Programme (eLib) projects created by the team at UKOLN, many of which complement the work done on ROADS. If you don't already have a database of your own, you'll be asked whether you want to install this. To build an HTML breakdown of the records in the eLib projects database, use the bin/addsl.pl program, e.g. bin/addsl.pl -aiN CONTACT DETAILS If you have any problems, queries or comments about this software package, please contact the ROADS team :- roads-liaison@bristol.ac.uk Note that this alias expands to several people, and has a publicly readable archive on the WWW! You may also find it worthwhile subscribing to the open-roads mailing list. This is a public forum for users of the ROADS software. To subscribe to the mailing list send an email message with the word "subscribe" in the body to open-roads-request@net.lut.ac.uk. This mailing list is the place to be if you want to suggest features for future releases, as sometimes we have to weigh up contradictory requirements from our users and this requires some discussion. We also have a mailing list for strictly technical discussions - send mail to roads-hackers-request@net.lut.ac.uk with the word "subscribe" alone in the body to join. Cheers! Jon Knight Martin Hamilton $Id: README,v 3.18 1998/12/09 15:01:46 martin Exp $