Page 1 of 1

NEW! Easy way to update the Online SuperBASIC Manual

Posted: Sun Sep 23, 2018 8:07 pm
by NormanDunbar
I get the odd occasional email asking me why a certain toolkit hasn't been included in the OSBM. I usually reply that no-one has provided me with the source files and refer people to the pages explaining exactly how to do that at ... en/latest/. So far, there have been no takers - which is understandable as getting your system ready to update the manual does require a lot of additional software for Windows, MAC or Linux systems.

So, I've done a text file to ReStructuredText file converter program at The main release page is at ... 0.01_alpha where the source and the Linux 64bit binary can be downloaded.

Right now, the shared and static library files included are for 64 bit Linux only. Sorry. This is because I've spent all weekend trying to get these compiled and in a reproducible way. It works fine now if you follow the commands in the file.

So, how it works, in brief:

  • You create a text file for your toolkit, or the toolkit of interest, in a sort of pseudo wiki format. This is the first draft so the text to be parsed is in a slightly weird format!
  • You include all the keywords from the toolkit in this file.
  • You then create an output folder and change into it.
  • You then run the utility. It will create one *.rst file for each keyword, in the folder that you are currently in.
  • You then send me the files, and possibly, also the source file, just in case of errors.

So, the source file:

There's a header consisting of the toolkit name and it's "location" which is what appears on the page in the manual. The toolkit name is more just documentation, and isn't used.

After the header, there's one or more 'keyword' sections consisting of:

  • KEYWORD: Name
  • SYNTAX: "String"

Those three are mandatory. There can be more than one 'SYNTAX' entry.

A "string" is just that, either single or double quoted strings of characters. You can embed single or double quotes in a string either by:

  • Using the opposite quotes to delimit the string;
  • Escaping the embedded quotes with a backslash, if the embedded quote is the same as the delimiting quotes;
  • Doubling up the embedded quotes, if the embedded quotes are the same as the delimiting quotes.

Unfortunately, I forgot about that option when I wrote the code, and it's not actually handled at present.

There follows a list of optional entries, which if present, must be in this order given, but not all need be present.

  • EXAMPLE: text or listings.
  • NOTE: text or listings.
  • NOTES : number: text or listings.
  • XREF: list of keywords.

You have one single NOTE or lots of NOTES. Each of the multiple NOTES has a numeric number (eh?) at the star but the system will number from one up by one for the notes, regardless of the numbers that you use. It's just neater that way!

Where it says text or listings, these are simply paragraphs of either plain text, or code listings. There can be as many as needed. Sadly, at the moment, text has to look like this, per paragraph:

Code: Select all

{{Text in a paragraph is wrapped in double sets of curly brackets, like this.}}


Listings are like this:

Code: Select all

10 CLS
20 REPeat silly
30    PRINT "Hello World ";
40 END REPeat silly

The file in the repository has the details in full, and there's an example_source.txt file present too, for testing or "study"!

There's no italic or bold in the grammar, in text paragraph, however, as the text is being converted to ReStructuredText anyway, just embed RST (that's easier to type than ReStructuredText) characters for these highlights - so you would use leading and trailing underscores for italic, _like this_, or double asterisks for bold, **like this**. When the page gets added to the OSBM, it will render as italic or bold text.

The application is generated from a file named usbm.g4 which is a grammar describing the input source files. From that I used ANTLR4 to generate a C++ set of files and a lexer and parser, from which I inherited into my "listener", then I feed the source file into the system and the lexer breaks it into tokens, these are passed to the parser and it builds a Abstract Syntax Tree (AST) this trr is then "walked" by a walker, and as it enters each parser rule, it calls out to a "listener" which has code written for one or both of an "enterRule" or "exitRule" function and these functions generate the RST files from the source. Simples! (Not!)

So, hopefully, it's now a lot easier to write updates for the OSBM.

I'll be working on this to try and make it easier to use, but for a first attempt it's not too bad. (If you have a 64 bit Linux system!)


Re: NEW! Easy way to update the Online SuperBASIC Manual

Posted: Mon Sep 24, 2018 9:23 am
by NormanDunbar
I've added a Windows 64bit release now.

Download the zip file and extract it. Instructions, brief, at ... lpha_Win64.


Re: NEW! Easy way to update the Online SuperBASIC Manual

Posted: Tue Sep 25, 2018 6:24 pm
by NormanDunbar
Updated today to fix a couple of problems when the output *.rst files are processed into HTML.
Version up to 0.02 now - progress!

See the new release on Github for Linux 64bit only tonight, Windows will follow tomorrow.

There's a small demo of what the example sourcefile actually becomes when processed with the parser and the *.rst files are then processed into a "manual". That's at - download, unzip, change into the html folder and open index.html in our browser.

EDIT: There's now also a 32 bit Linux release 0.02.

I should note that you only need the USBMParser file and the library. You don't need the source code, but there's a useful Example file in the source to download, at


Re: NEW! Easy way to update the Online SuperBASIC Manual

Posted: Wed Sep 26, 2018 7:47 am
by NormanDunbar