==================== UNIXhelp release 1.3 ==================== UNIXhelp is a hypertext guide for new users of the UNIX operating system. This is the README file for downloading and customising a copy of UNIXhelp 1.3. Those upgrading from release 1.2 will find some extra guidelines below. The Copyright for the UNIXhelp deliverables rests with the Computing Services of the University of Edinburgh. The deliverables may be reproduced and used freely for non-commercial purposes, provided that this and any other copyright notices are reproduced therein. Please address all queries and comments regarding UNIXhelp to the maintainer at the address "unixhelp@ed.ac.uk". Prerequisites ~~~~~~~~~~~~~ The UNIXhelp distribution is split into three parts: 1) The main body of text, in HTML format. There are almost 900 pages which take up approximately 840K of disk space. Small icons accompany the text in GIF format. 2) A script written by Panagiotis J. Christias to read manual pages on your local machine and convert them into HTML. 3) A script in the language Perl to read and interpret results from the SWISH indexing software. Also supplied is another Perl script to aid installation. This automatically updates the links in the pages to point at your local scripts. Installation Options ~~~~~~~~~~~~~~~~~~~~ Even simply making a local copy of the pages can be very useful. However, you are recommended to also install the search engine and UNIXhelp scripts if at all possible. It will cut down on your access times, provide better tailoring to your local system, and lower the load on the Edinburgh server. For the full UNIXhelp installation you will need to obtain both Perl and the SWISH indexing software. Obtaining Perl ~~~~~~~~~~~~~~ Perl is freely available for a number of platforms. There is a WWW page dedicated to Perl at: http://pubweb.nexor.co.uk/public/perl/perl.html This has lots of documentation on the language, how to obtain it for your machine, and other uses you might put it to. Obtaining SWISH ~~~~~~~~~~~~~~~ There is a WWW page dedicated to SWISH at: http://www.eit.com/software/swish/swish.html This has comprehensive documentation on installing the software and putting it to best use. You will need a C compiler to compile the source. You can obtain the source from: ftp://ftp.eit.com/pub/web.software/swish/ ============ INSTALLATION ============ Step 1: UNIXhelp pages ~~~~~~ ~~~~~~~~~~~~~~ This is straightforward to do; simply copy the contents of the directory Pages into an area of your server's filesystem where users can view it. However if you are installing a local search engine or man page script, you will have to update links on the pages first. The installation script updates links to scripts from the UNIXhelp pages. You may want to keep a copy of the original .tar file if you might move things around later. First uncompress and extract the UNIXhelp1.3 distribution. unix$ uncompress UNIXhelp1.3.tar.Z unix$ tar xvf UNIXhelp1.3.tar ... Change to the distribution directory. unix$ cd UNIXhelp1.3 unix$ ls swish.conf README installuh* Pages/ Scripts/ Next, determine the URL of your script directory. At Edinburgh this is: http://unixhelp.ed.ac.uk/CGI It is probably also a good idea to have a local maintainer for UNIXhelp who can update the resource and respond to users' queries. At Edinburgh the alias unixhelp@ed.ac.uk is used for the local maintainer. Pick an email address for your local maintainer if you want one. Now run the installation script. unix$ ./installuh The script will ask you for your script directory URL and the email address of your local maintainer. If you do not wish to add the maintainer's address at the bottom of each page, simply press Return when prompted. The script will ask you to confirm your choices. Once you are happy, it will proceed to update every UNIXhelp page and the search script to refer to your local directory for scripts. You may now copy the contents of the directory Pages/ into place on your system. If you have previously installed UNIXhelp 1.2 you should read the note below first. Be sure to use the -r option as the bulk of the pages are in subdirectories. Check the file permissions to ensure everybody can read the pages and icons. You have now installed the core pages of UNIXhelp release 1.3. The top page has the filename "index.html". Special note for those upgrading from release 1.2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In release 1.2 there were five pages which referred to particular information which will change from site to site. You may wish to preserve these and should note they have changed name with the new hierarchical structure. The filename changes are: basics_basic1.4.html becomes local/getaccount.html warnings_remove2.html becomes local/restores.html tasks_3.6.1.1.html becomes local/rcp.html tasks_lpr3.1.html becomes local/printers.html didyou_.html becomes local/sysadm.html Please particularly note that the top page has also changed filename. From being "TOP_.html" it has now become a more conventional "index.html". Local customisation ~~~~~~~~~~~~~~~~~~~ Five pages within the UNIXhelp structure make reference to local characteristics and you may wish to edit these for your user community. For your convenience they are all grouped in the subdirectory "local". They are: getaccount.html: how to obtain an account on local UNIX machines. restores.html: getting your files recovered after accidental deletion rcp.html: local security which may interfere with the "rcp" command printers.html: commands for showing printers available to users sysadm.html: how to contact your local system administrator Once you have edited these, the bulk of a customised UNIXhelp is already in place. You may wish to add extra pages for more local information. We suggest you put these pages in the local/ directory so they may be easily preserved for any future releases. Step 2: HTML manual pages ~~~~~~ ~~~~~~~~~~~~~~~~~ In the distribution directory Scripts/ is a file called man-cgi and this is the source code for UNIXhelp's dynamic conversion of manual pages into HTML. If you are setting up UNIXhelp on a Sun Solaris or SGI system, you should probably pick up a customised version of the script directly from the author's page at: http://www.softlab.ntua.gr/~christia/man-cgi.html Installing man-cgi is easy. Simply copy it to your server's script directory, under the filename "man-cgi". UNIXhelp calls the compiled binary with the desired manual page as an argument, eg: http://your.server/your-bin-directory/man-cgi?grep Check that anybody has permission to execute the binary. You have now installed the first of UNIXhelp's two scripts. ************************************************************************* * IMPORTANT * * Operating system manual pages are usually copyright material. Making * them available to remote browsers through the html-man-page script * may constitute a violation of that copyright. Please be aware of your * responsibilities in this regard. Neither Edinburgh University Computing * Services nor the script's author can accept any liability for such * breaches of copyright. * * At Edinburgh access to the html-man-page script is limited to browsers * in the local domain. This is specified in the server configuration. * * A simpler fix is to replace the html-man-page script with another CGI * script explaining why this is not available. Unfortunately this also * denies access to local users. Ultimately, of course, they can call up * pages from any UNIX prompt using the "man" command. * ************************************************************************* Step 3: Search engine ~~~~~~ ~~~~~~~~~~~~~ You may use any suitable search engine for UNIXhelp, but EIT Corporation's SWISH is the recommended one. This can be used at no charge for non-commercial purposes. Testing was done using SWISH version 1.1. The page mentioned above has comprehensive instructions for downloading and compiling the source. Put the SWISH binary somewhere appropriate in your server's filesystem. /usr/local/bin is one possibility. Take a note of where you put it and allocate a place for the index file. Included in the UNIXhelp distribution top directory is a sample configuration file for SWISH, called "swish.conf". Edit this to your satisfaction. In particular you should note the ReplaceRules section which you need to edit so SWISH can convert filenames to URLs. Then run the SWISH binary to create an index: unix$ swish -c ./swish.conf This can take some time because of the number of files which make up UNIXhelp. Once it terminates you will have a single index file which you should move into the place you allocated for it. The final step is to put in the UNIXhelp interface script. From the distribution directory you will find it in "Scripts/unixhelp_search". Edit the configuration variables which are mentioned at the top of the file. Then move the script into your server's script directory. Check the permissions on the SWISH binary and the server scripts. They should be universally executable. You have now installed UNIXhelp in its entirety. Finishing touches ~~~~~~~~~~~~~~~~~ Check your installed UNIXhelp by browsing a few pages. Try the alphabetical list of manual pages and pick one to test the html-man-page script. Try a search on a keyword like "permissions". If all is well you can advertise your server to local users. If you are also willing to let remote users access your site, please mail unixhelp@ed.ac.uk with a note of your top page URL. The maintainer will add your site to the worldwide lists. Even if you do not want remote users to access your pages, please let unixhelp@ed.ac.uk know you have made a local installation. Any comments or suggestions are warmly welcomed. Gavin Inglis UNIXhelp maintainer, January 1996