So, I've done a text file to ReStructuredText file converter program at https://github.com/NormanDunbar/USBMParser. The main release page is at https://github.com/NormanDunbar/USBMPar ... 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 Compiling.md 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.
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"
- DESCRIPTION: text
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.
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.
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
CODE:[[
10 CLS
20 REPeat silly
30 PRINT "Hello World ";
40 END REPeat silly
]]
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!)
Cheers,
Norm.