BBC BASIC PHP Detokeniser and Syntax Highlighter
                     ================================================
                                  Original by Ben Ryves
                                  Updates by J.G.Harston


bbc.php and bbctok.php are a pair of PHP programs that will parse a BBC BASIC program file
on a web server and detokenise it into text, and do syntax colouring. The original code was
written by Ben Ryves, and forms the majority of the functionality. The J.G.Harston updates
are some slight changes to transparently parse both Acorn and Russell format BASIC files,
and a few tweeks to catch some edge cases.

Quick & Simple Installation
---------------------------
The PHP files are supplied with .phps "source file" extensions so they don't get executed.

Create a directory:
  /bin

Upload the files:
  bbc.phps    as /bin/bbc.php
  bbctok.phps as /bin/bbctok.php

Edit the /.htaccess file (or create one if it doesn't exist). If there is no RewriteEngine
section, add to the end:
  RewriteEngine On
  RewriteBase /

Add to the end of the RewriteEngine section:
  RewriteRule ^(.*?)\.(bas|BAS)$ /bin/bbc.php?file=$1.$2

Once you have done this, any access to a file "filename.bas" or "filename.BAS" in any
directory will look for a BBC BASIC file named "filename", "filename.bbc" or "filename.src"
and generate a webpage to display it. If there is a file called "filename.bas" it will be
ignored as the rewrite engine will act before it is seen.

Detailed information
--------------------
The rewrite rule causes any access to a file ending in ".bas" or ".BAS" to be passed to the
detokeniser. I typically put links on my website in the following form:

  <a href="program">program</a> (<a href="program.bas">L</a>)

which gives the following display:

  program (L)

Selecting the 'program' link fetches the actual binary file, selecting the '(L)' link
generates a listing.

The detokeniser examines the passed file to determine what type of BBC BASIC it is. Acorn
BASIC and Russell BASIC programs have a slight difference, and Acorn uses two-byte extended
tokens whereas Russell BASIC uniformly uses one-byte tokens.

The listing is formatted as though LISTO 3 has been used. There is a single space after the
line number, and FOR/NEXT, REPEAT/UNTIL, WHILE/ENDWHILE, CASE/ENDCASE and IF/ENDIF structures
are indented.

The generated page includes a 'download' link so the user can fetch the source file from
the listing page.

If the filename passed is "filename.BAS" the tests look for "filename" before checking
any extensions. If the passed filename is "filename.bas" then "filename" is tested for
after checking any extensions.

Customisation
-------------
bbctok.php does all the heavy lifting of generating the detokenised listing. You should not
need to change any of this. bbc.php parses the filename passed to it and calls bbctok.php
with all the settings it needs. If you need to customise anything you should only need to
change bbc.php.

bbc.php starts by parsing the filename passed to it and converting it to a form to pass to
bbctok.php. It is passed a filename ending ".bas" or ".BAS" and needs to work out what the
source file is to generate a listing from. On my site I have various BBC BASIC files,
programs are almost all named "filename" or "filename.bbc", some are named "filename.src"
or "filename.s" which are machine code source programs or uncrunched BASIC files. bbc.php
starts by looking for a file with a name in one of these formats. If you wish to search for
other filenames you would add additional tests here.

The next section sets up the syntax colouring and layout. If you want to change from the
colouring used - which is the default used in the BBC BASIC for Windows editor - you would
change this section. The names of the styles should be obvious what they control.

Bugs
----
If a structure has multiple closing commands, the indentation will get messed up, for
example:
  FOR A=1 TO 5
    FOR B=1 TO 5
      IF B=2 THEN NEXT B
  NEXT B
  NEXT A

NEXT with multiple variables are not recognised, for example:

  FOR A=1 TO 5
    FOR B=1 TO 5
    NEXT B,A
    REM next line

See also
--------
* BBC BASIC program file format:
    http://beebwiki.mdfs.net/Program_format
* Ben Ryves' projects:
    https://benryves.com/projects

History
-------
v1.00 05-Jul-2014 Received Ben Ryves' version
v1.10 ??-???-???? JGH: Added Acorn Basic, inline spaces become &nbsp;
v1.11 ??-???-???? JGH: Multi-line IFs indented, expands tokens<&20
v1.12 ??-???-2020 JGH: Examines file to discover format, expands two-byte tokens and deals
                  with slight differences between one-byte tokens.
v1.13 25-Jul-2024 JGH: ".BAS" checks "filename" first, ".bas" checks "filename" last.