Introduction

This part describes some of the trials and tribulations I went through to create the current (as of today, anyway!) online version of Rich Mellor’s Online SuperBASIC Manual as seen originally at http://www.rwapsoftware.co.uk/SBASIC_reference_manual_online/Foreword.html and now, online at http://superbasic-manual.readthedocs.io/en/latest/ where the latest (English language) version can be found. Anyone feel like translating?[1]

Why Bother?

Many years ago, Rich wrote a proper book, using Text 87, I believe, and this was published by Roy Wood’s company Q Branch. Although I never had a copy, I am informed that it was a very well received book, and regular updates were provided. The book itself was over 1,000 loose leaf pages - which helped in the updating.

Time goes by (that’s its job after all!).

The internet arrives.

The QL is somewhat left behind, given a pretty basic lack of TCP/IP networking abilities.

A group of old farts[2] still hang on to the QL, after all, it is one of the better computer systems around, given its age, and the fact that it did have one of the better BASIC languages around, at the time. (1984!)

Even better, it had a genuine “32” bit processor, which was sort of correct, but it had an 8 bit data bus, so each of those 32 bits needed 4 fetches! Still, advertising.

The First HTML Version

Some work was done by authors unknown, to convert the original Text 87 documents into a first draft HTML document. This involved much messing around with printer drivers and then reading through the generated (and binary) file to replace certain characters with suitable HTML alternatives.

Note

Getting text out of a Text87 file is a nightmare as the internal file format is not documented, and the author doesn’t appear to answer emails on the subject. A printer driver type thing is about all there is. Especially if you wish or need to retain some of the formatting.

The first version was a team effort - if you were involved, let me know and I’ll update this book to include your name - and a set of very rough HTML files was the result. There were bugs, but the browsers of the time coped beautifully - by simply ignoring them! The section on the ED keyword, for example, had a table of key presses which never actually showed any of the arrow keys, for example.

There were the odd occasional spelling mistake - as would be expected in a work of this size. There probably still are!

There were tables that were no longer tables - HTML ignores multiple spaces and tabs, replacing them with a single space, in most cases. Not helpful to a nice tabular layout.

And there were program listings which were not program listings, they were paragraphs of italic text. All the lines ran together and any of the special HTML characters - ‘<’, ‘>’ or ‘&’, for example, went awol as they were illegal characters in a non <pre> .. </pre> section. Sigh.

However, it was a good start.

My Own Involvement

Rich put a request out on the ql-users mailing list for help, and also on the Sinclair QL Forum. I believe the silence was deafening! And, being an author myself, pretty much as expected. So much for a community eh? [3]

I used to avoid having a lunch break in whatever location I was working at the time. This meant that I had to sit around for an hour or so, twiddling my thumbs or reading the Interwebs. Until one day I decided to have a look at tidying up the online manual - as requested by Rich in his call for help. I was bored!

I managed to manually convert all the forewords and appendices to something resembling half-decent HTML, but it was still pretty dire to be honest. Each file is many hundreds of lines long, and full of stuff generated by the various conversion programs. It wasn’t easy to work with and each chapter took ages to convert from really crappy HTML into mildly crappy HTML.

By the time I left that contract, I had only got as far as converting the first three chapters of the keywords - A, B and C. That was it. At least the program listings looks like listings now, but it was an absolute nightmare converting each line from something like[4]:

... <span style="font-style: italic;">100 do_stuff(a, b, c)...</span> ... <span style="font-style: italic;"><br>110 do_more_stuff: and_more_stuff(d,e,f) ...</span>

into:

<pre>
100 do_stuff(a, b, c)...
110 do_more_stuff: and_more_stuff(d,e,f) ...
</pre>

Which is fine for a couple of lines, but a nightmare for some of the larger examples, even with a text editor that lets me record and save the odd occasional macro to do the stripping out of the various <span>s etc.

Then, I left that contract and spent almost 3 years working in a location that was completely tied down - no personal internet usage, no ability to install even useful tools that could have helped me do my job etc. So, no work done at all on the manual I’m afraid - my wife wasn’t too keen on me wasting my spare time doing computer stuff, so doing anything at home was a non-starter too. Apparently, I needed to get a life - whatever one of those is. [5]

This Version

This version came about as a result of something else I was having to do. Producing a web site from text files created in ReStructuredText. I was rather impressed and ran a little trial before creating a project on GitHub and on ReadTheDocs to cater for the need to have the source files in a version control system - so that when I screwed up an edit, I could always revert the changes! And ReadTheDocs gave me the ability to host the manual for free, well, for the inclusion of a couple of small adverts, occasionally.

Every time I commit a change and push it to the working branch, the working version of the manual gets rebuild in HTML, PDF and EPUB formats. This is the rough and ready versions and is not really suitable for general use.

The master branch is only ever updated, other than when I make a mistake and forget to checkout the working branch of course, when I finish a complete file, such as KeywordsX.html which will become KeywordsX.clean.rst and then built. The docs on the master branch are the good copies, ready for use.

Never, ever update the docs for the master branch, unless you have already proven them in working first.

Footnotes