BETSIE - README =============== Readme for version 1.5.* - updated 23rd April, 2002 - more minor changes, 3rd May, 2001 - minor changes, 26th April, 2001 - another update, 19th April, 2001 - updated again, 15/12/99 - updated, 13/12/99 - some minor errors corrected, 25/2/99 LICENSING AND COPYRIGHT ----------------------- The Betsie distribution consists of five files as follows: parser.pl - the Perl source code for the Betsie parser README - this file LICENCE - the terms under which Betsie is distributed ChangeLog - listing the changes made to the code TODO - a rough document outlining current wishlist items Betsie is (c) 1998 - 2001 BBC Digital Media. See the file LICENCE for full terms and conditions. Acceptance of the licence is implied by your use of Betsie in any way shape or form - the licence basically boils down to this: you can use Betsie in any way you like so long as you don't sell it and you don't redistribute it without crediting the BBC as specified. If you modify it or incorporate it into something else you can't sell that either. WHAT'S NEW 1.5.11 ----------------- Support for basic authentication added. Support for multiple rearrangable blocks added. Numerous bug-fixes. WHAT HAPPENED TO VERSIONS 1.5.7 - 1.5.10? ----------------------------------------- They didn't get released, due to pressures of other BBC-related work. :( WHAT'S NEW 1.5.6 ---------------- Sourceforge cvs and mailing list finally set up. Configuration instructions for IIS/NT added to README. Various tweaks to readme, including better move_nav section. Various bugfixes to code, detailed below. WHAT'S NEW IN 1.5 ----------------- Various minor bugs have been fixed, and extra code has now been added to allow the user to change the font, font size and colour settings for the page. This information is encoded in the URL, but old Betsie URLs will still work, so the whole thing is backwards compatible with your existing code. WHO BETSIE IS FOR ----------------- Betsie is a server-side solution to the problem faced by a large number of websites - they absolutely must be accessible to everybody, but for whatever reason they are not, and there aren't the resources to go through every page fixing them completely by hand. Betsie can provide an on the fly text-only version of every page on your site which can be (more or less) guaranteed to be accessible, and can be modified to include features of code manipulation that are wholly specific to your site. An example of this is the code used in the BBC's online version of Betsie which handles the BBC navbar. If you are a server administrator, or are involved in the design and technical accessibility issues around your website, then Betsie is likely to be at least interesting, if not useful to you. This document contains a reasonably comprehensive set of instructions as to how to install and set up Betsie on your own server. It assumes you have a working knowledge of Perl and good knowledge of HTML. If you are a home user or suffer from accessibility problems in general, then I am afraid that unless you are also something of a technical expert, Betsie is far more likely to be something you use than something you install and set up. To use Betsie you need merely visit a site on which it has already been installed. You can visit the Betsie website ( http://www.bbc.co.uk/education/betsie/ ) for a list of places where Betsie has been installed and where you can use it without having to install or set up anything. SETTING BETSIE UP ----------------- Before You Begin ---------------- You need: a) Some Perl. If you don't know any Perl, now would be a good time to start learning. http://www.perl.com/ is a good place to start that. b) Access to a web server. If you don't have anywhere to put Betsie, or if you aren't allowed to install CGI scripts, now would be a good time to start talking to your ISP or server administrator about somewhere to put it. c) A reasonably consistent set of pages to work with and a reasonable knowledge of HTML, including accessibility issues. If the URL http://www.w3c.org/WAI/ means nothing to you, this would be a good time to check it out. What You Must Do ---------------- There are a few things you have to do and a few things you can choose whether or not to do. As follows: a) You have to... Make sure that the following variables have appropriate values as described below: $pathtoparser - the url of the location of the parser file itself $parsehome - the url of the homepage for your installation of Betsie. If you wish, you may leave this set to http://www.bbc.co.uk/education/betsie/ which is the central Betsie homepage at the BBC. $parsecontact - the email address of the person you wish to have contacted with regard to any problems that may arise with this installation of Betsie. $localhost - must contain the name of the server you are going to install Betsie on. @safe - must contain the list of urls you are going to allow this installation of Betsie to point at. If you aren't going to be using this feature, it doesn't really matter what you put in here. $maxpost - contains the maximum amount of data that can be submitted via Betsie using a POST request. The default given is 65536 bytes, but you will want to double check this with your sysadmin to make sure that it corresponds to the default value used by the server. b) You might well want to... Write some code to fix specific problems to your site. Move Nav Bars ------------- For example, if you know that all your pages (or an appreciable, drillable-down-to subset of them thereof) are constructed in such a way that there is a nav bar that sits in a table which is 150 pixels wide on the left hand side of every page (sound familiar... no?) then all you need to do is come up with a way of finding it and putting it somewhere else. If you don't know why you might want to move a lefthand navbar to the bottom of the page, you should look at a number of such sites in Lynx or some other text only browser, and note what happens when you move from page to page in such a site... the lefthand navbar appears at the top of every page every time, and if there's a lot in it, you won't necessarily know whether or not you have successfully arrived at the page you want for an irritatingly long time. This (and other global changes) can be usefully inserted in the parser.pl file in the move_nav function. The move_nav function is called with preparse. In preparse, the whole of the HTML page is held in a string called $page and manipulations based on the whole of the page can therefore be done. Here's an example move_nav routine, which may be more useful to you than the rather BBC specific version in the current distribution of the code. sub move_nav() { my $page = shift; my $start_nav = "(?:)"; my $end_nav = "(?:)"; $page =~ s/(.*?)$start_nav(.*?)$end_nav(.*)<\/body>/$1$3$2<\/body>/is; return $page; } First, the whole page gets passed in. Next two variables, $start_nav and $end_nav are set, corresponding to the comments in the HTML code that are being searched for. Notice the use of the '?:' construct - this means that Perl will allow you to insert alternatives inside the brackets using '|', but will not count the contents of the brackets in the replacement part of the regular expression. The fourth line is the regexp that actually moves the nav bar. If you are unable to ensure that all your nav bars begin and end with a set of standard comments, you might want to try writing code specific to the HTML that you are looking for. However, be warned that this is much harder to maintain over time, since every time the HTML is changed, the code in Betsie must be changed. Safe List --------- You might also want to disable the safe list. You can do this in any one of several different ways, the easiest and simplest of which is to insert the line 'return 1;' at the beginning of the 'safe' subroutine. Once you have done this, Betsie will be able to point at any web site anywhere you like on the internet and will never describe sites as 'external'. On the other hand, you might want to use the safe list. In which case, simply populate the @safe array with the urls you want to allow your installation of Betsie to point at. 3 - Finally, having made all the changes you want to make, check it all still works and so forth in the normal way and move on to installing it. INSTALLING BETSIE ----------------- 1 - I can't really help you with this, save to remind you of the following: a - Did you change the #!/usr/local/bin/perl/ line to something appropriate to the location of Perl on your server? b - Did you ensure that all the permissions were set up correctly? c - Did you check that all the alterations you made to parser.pl left it syntactically intact? If the answer to all of the above is yes, and it still isn't working, then I'm afraid I have no idea what is going on either. Sorry. 2 - This isn't compulsory, but will be (hopefully) highly advantageous for anyone using Betsie on their site and will also make me very grateful, to wit and viz: email me, wayne.myers@bbc.co.uk to let me know that you have installed Betsie, so I can make sure to keep you up to date with any new versions, help you if possible with tweaks and site-specific problems you may come across, and, possibly, add your site to the list of accessible sites I am compiling for the Betsie web site (forthcoming) itself. 3 - Using NT/IIS and find it doesn't work? Microsoft's IIS server, out of the box, does not support the PATH_INFO environment variable, which Betsie relies on, since it is disabled by default. However, by following the instructions on the following page, PATH_INFO can be re-enabled. http://support.microsoft.com/support/kb/articles/Q184/3/20.ASP In addition to giving instructions on enable PATH_INFO, this page also claims that doing so is a security risk. In the case of Betsie, this will not be true, since Betsie does not use PATH_TRANSLATED, and the way in which Betsie uses PATH_INFO does not give away any information about the server which may be used to mount an attack. It is also necessary to comment out the alarm() call on NT, which does not implement it. For further details on AllowPathInfoForScriptMappings, see: http://msdn.microsoft.com/library/psdk/iisref/apro8mr7.htm 4 - Whoops. Almost forgot. Now you have to fix your HTML. All of it. Being an on-the-fly HTML repair tool, Betsie also may be used as a way of identifying pages that require repair by hand. This is why this readme recommends you install Betsie before fixing your HTML, since you can then use Betsie to help you through that process. See the Limitations section for further details of the kind of HTML that may cause problems for Betsie. (It will be causing problems anyway.) USING BETSIE ------------ Called without any PATH_INFO, Betsie now automatically parses the referring page. That means that Betsie now allows you to link to her directly, like this: Text-only The ideal situation for such a text-only link is the top left hand corner of the page. If it is anywhere else, the chances are slim that the very users who need to find it will be able to. LIMITATIONS ----------- 1 - Betsie is written in Perl. Not Magic. That is to say, Betsie cannot magically solve problems caused by dodgy HTML code. If there are pages in your site that do not validate as proper HTML, then you'd better fix that or some of them *may* make Betsie fall over. Actually, you'd better fix that anyway, even if you choose not to use Betsie in the end. 2 - Betsie has no editorial control over your site. You do. That includes the ALT attributes of your IMG tags. No matter how much you and your organisation may have been in denial about the contents of the ALT attributes of your IMG tags in the past, now is the time to face up to the fact that all that text has to make sense unless you want to have some pages that come across as really obtuse when viewed with Betsie. Or Lynx. Or with images turned off in a graphical browser. 3 - Betsie is not an excuse to continue making inaccessible pages. Betsie acts in two ways to increase the accessibility of your site. Firstly, it can eliminate standardised inaccessible features such as a long left hand navbar in one fell swoop. Secondly, it forces those maintaining large sites to examine their accessibility and to introduce accessiblity as a compulsory feature of new pages as and when they arise. If you keep adding new inaccessible pages and features, then eventually, Betsie will stop being able to deal with them. VERSION CHANGES --------------- See ChangeLog. MORE INFORMATION ---------------- Betsie Website The Betsie website is on the following URL: http://www.bbc.co.uk/education/betsie/ and contains a good deal of further information about Betsie, including up to date contact details, the latest version of the free source distribution and more. There is also now a Betsie developers site on: http://betsie.sourceforge.net/ From there you can always get the very latest development version of Betsie via CVS. There is also a Betsie development mailing list, details of which are available here: http://lists.sourceforge.net/lists/listinfo/betsie-devel The list is very low traffic, and subscribing is highly recommended in order to remain up-to-date with the latest version of Betsie. Meanwhile, I hope you find Betsie useful, and look forward to receiving your comments, criticisms and recipes for small sweet things. Cheers etc., Wayne Myers, 19th April, 2001 wayne.myers@bbc.co.uk