Updated README

README.adoc

@@ -7,10 +7,10 @@ In Object Pascal.
 
 * A drop-in replacement for the original `CTRAN.EXE` in the Psion SIBO C SDK, replicating both the input switches and the generated files.
 * Run on modern OSes and DOS.
-* Produce identical files to the original (3.43 or 5.02 -- see below).
+* Replicate files generated by Psion CTRAN 5.02.
 * Allow multiple include sources.
 
-== Targets for v1.00
+== Targets for v1.0.0
 
 * [x] Psion Category file lexer
 * [x] Psion Category file parser/AST builder
@@ -23,7 +23,7 @@ In Object Pascal.
 * [x] Generate files designed to only work with the SDK
 * [x] Generate skeleton method files
 * [x] Generate `.asm` (TASM assembly) files
-* [ ] Generate `.ing` (TASM assembly header) files _[mostly working; `PROPERTY` and `TYPES` currently broken]_
+* [x] Generate `.ing` (TASM assembly header) files _[`PROPERTY` and `TYPES` generation is basic -- see below]_
 * [x] Generate `.lis` (class listing) files
 
 == What is (or was) `CTRAN`?
@@ -50,56 +50,120 @@ This means that you have to store every generated file inside the SDK folder.
 
 I did not like this.
 
+== Examples
+
+Generate .C and .G files from `VECTOR.CAT` on DOS and put them in the current directory.
+
+[code]
+----
+ctran vector.cat -ec:\sibosdk\include -c -g
+----
+
+Generate `.C` and `.G` files from `LCDTEST.CAT` on Linux, where the SDK is in `/home/user/sibosdk`, but put the resulting files in `/home/user/myproject/classes/`:
+
+[code]
+----
+ctran lcdtest.cat -e/home/user/sibosdk -c/home/user/myproject/classes -g/home/user/myproject/classes
+----
+
+Generate `.C`, `.G` and `.EXT` files from `WARI.CAT` on DOS that can only be used with the SDK.
+(Note that specifying the `.CAT` extension is optional)
+
+[code]
+----
+ctran wari -ec:\sibosdk\include -c -g -x -s
+----
+
+
 == State of the project
 
-=== What the new `CTRAN` can currently do
+=== What the CTRAN-ng can currently do
+
+CTRAN-ng has feature-parity with Psion CTRAN 5.02, minus the OVAL and (broken) EPOC32 featues.
+Most people only need the ability to generate `.C` and `.G` files, which it does well.
+It can be used as a drop-in replacement for the original Psion `CTRAN.EXE`.
+(In fact, it fixes some minor issues with Psion CTRAN, and generates cleaner, more readable files.)
 
-`CTRAN` in its current form is mostly feature complete (see the list above).
-Most people only need the ability to generate `.C` and `.G` files, which it does.
-It can be (and has been) used as a drop-in replacement for the original Psion `CTRAN.EXE`.
+In addition, it can act as a Psion SIBO category file validation tool, for use with category (`.CAT`), sub-category (`.CL`) and external category (`.EXT`) files.
+It extends the original `-v` (verbose) switch by adding and combining the following options:
 
-In addition, it can act as a Psion SIBO category file validation tool.
-It extends the original `-v` (verbose) switch by adding the following options:
+* `l` Show lexer debug output
+* `t` Show token table
+* `p` Show parser debug output
+* `a` Show abstract syntax tables
+* `r` Reconstruct all input files using the abstract syntax tables
 
-* `-vt` Show token list
-* `-vl` Show lexer process
-* `-vp` Show parser process
-* `-va` Show abstract syntax tables
-* `-vr` Reconstruct the file using the abstract syntax tables
+For example, the following DOS command line will take the `DEMO.CAT` file and show the token table and abstract syntax tables:
+
+[code]
+----
+ctran demo -ec:\sibosdk\include -vta
+----
 
 Finally, the `-e` switch can take multiple paths, separated by a semicolon.
+So, if you want to include external (`.EXT`) files from the SDK and a separate project location, you can use:
+
+[code]
+----
+ctran demo -ec:\sibosdk\include;p:\projects\myproject -c -g -x
+----
 
-=== What it can't do
+Or, if the include files are in the current working directory:
 
-The main missing feature is the ability to handle sub-category files.
-This is the current priority and should be ready in the next few weeks.
+[code]
+----
+ctran demo -ec:\sibosdk\include;. -c -g -x
+----
 
-There is also a small issue when processing classes that only have `DEFER`red methods.
-The original way of handling this is to completely skip these classes, which the new `CTRAN` doesn't do.
+This also works with *NIX paths, if you add speech marks.
+
+[code]
+----
+ctran demo -e/home/user/sibosdk/include;/home/user/myproject/inc -c -g -x
+----
+
+=== What it can't do (or is currently broken/weird)
+
+==== "Shadow" classes
+
+There is a small issue when processing classes that only have `DEFER`red methods (something I've called "shadow" classes).
+The original way of handling this is to completely skip these classes, which CTRAN-ng doesn't do.
 This shouldn't impact existing code, but it will be fixed in the future.
 
-TASM file generation, specifically `.ING` ASM include files, is currently broken.
-It is currently unable to convert the C in category file `PROPERTY` and `TYPES` sections to 8086 assembly.
-Generated files will include the original C code, commented out.
-If you want to use `.ING` files, you will need to manually convert the C to ASM.
-Fixing this will require some major work, requiring a miniature C compiler to be written and added to the code.
+==== Borland Turbo Assembler file generation
+
+TASM file generation does work and matches the original Psion CTRAN.
+However, I do not believe that it is reliable.
+
+The method used to convert the C in category file `PROPERTY` and `TYPES` sections to 8086 assembly is rudimentary at best.
+There is barely any error checking and some lines in `PROPERTY` and `TYPES` are completely ignored.
+Like I said, this does replicate Psion `CTRAN`'s behaviour, but I don't believe that means that it generates working assembly.
+
+It is highly recommended that anyone using these generated files checks them thoroughly before using them.
+
+==== The order that some lines are generated
+
+Some lines at the start of files are geneated in a different order to Psion CTRAN.
+I haven't been able to work out how the original CTRAN is generating these lines in the way that it does, although I am sure it has something to do with the way that it is storing classes.
+However, as these are just declarations of macros and the only thing different is the order, it has no affect on how TopSpeed C compiles them.
+
+==== Psion OVAL
 
-Finally, it can't generate files for use with Psion OVAL (see below).
+It can't generate files for use with Psion OVAL (see below).
 
-== Different versions of `CTRAN.EXE`
+== Different versions of Psion's `CTRAN.EXE`
 
-There are two main versions of Psion's `CTRAN`:
+There are two commonly available versions of Psion CTRAN:
 
-* 3.43: This came with the SIBO C SDK 2.20 and is (probably) the version that most people using the SDK would have.
-* 5.02: This came with Psion OVAL 1.21, an IDE based on Visual Basic 6 that could be used to create new controls for use in EPOC16 applications, as well as entire EPOC16 applications.
-This version of `CTRAN` generates cleaner code than the previous version, and fixes some (but not all) bugs in 3.43.
+* *3.43:* This came with the SIBO C SDK 2.20 and is (probably) the version that most people using the SDK would have.
+* *5.02:* This came with Psion OVAL 1.21, an IDE based on Visual Basic 6 that could be used to create new controls for use in EPOC16 applications, as well as entire EPOC16 applications.
+This version of `CTRAN.EXE` generates cleaner code than the previous version, and fixes some (but not all) bugs in 3.43.
 It adds the ability to generate files for OVAL controls.
 It also adds a (broken) option for generating code for EPOC32.
 
-The original aim was to reach feature-parity with 3.43.
-However, if 5.02 doesn't introduce any breaking changes, then the new `CTRAN` will aim to mimic the code that it generates.
-OVAL-related features won't be in v1.00, but might be added in a later release.
-As the new version of `CTRAN` is only designed to be used for making EPOC16 apps, the EPOC32 "feature" will not be added.
+The aim of CTRAN-ng 1.0.0 is to mimic the code that CTRAN 5.02 generates.
+OVAL-related features won't be in 1.0.0, but might be added in a later release.
+As CTRAN-ng is only designed to be used for making EPOC16 apps, the EPOC32 "feature" will not be added.
 
 == Why is this project written in (Object) Pascal?
 
@@ -112,9 +176,9 @@ It targets pretty much everything, including Linux, Windows, macOS, Haiku, *BSD.
 Luckily, Object Pascal is just high-level enough, taking away some of the worries of memory management and how to handle dictionaries/trees, while letting me go low-level when I want to.
 
 Unfortunately, some of Free Pascal's units (e.g. `classes`, `generics.collections`) are too big to fit into 64 KB code blocks.
-Because of this, the new `CTRAN` will target 32-bit DOS using a DPMI extender.
-As most people will be running the Psion SIBO C SDK in DOSBox, it shouldn't affect anyone using `CTRAN` directly, or if it is run from a TopSpeed project (`.pr`) file.
-However, it has been known to clash with Borland Make, as its 16-bit DPMI extender prevents `CTRAN` from running.
+Because of this, CTRAN-ng for DOS is a 32-bit executable using a `CWSDPMI.EXE`, a copy of which is bundled with CTRAN-ng for DOS.
+As most people will be running the Psion SIBO C SDK in DOSBox, it shouldn't affect anyone using CTRAN-ng directly, or if it is run from a TopSpeed project (`.pr`) file.
+However, it has been known to clash with Borland Make, as its 16-bit DPMI extender prevents CTRAN-ng from running.
 In such situations, it is recommended that you switch your project to using GNU Make from the DJGPP project.
 Alternatively, TopSpeed project files provide a good alternative without needing an external Make app.
 
@@ -123,5 +187,5 @@ Alternatively, TopSpeed project files provide a good alternative without needing
 At some point the entire SDK needs to be moved away from DOSBox.
 This will require rewriting every single tool that was included in the SDK, plus the TopSpeed C compiler.
 
-There is a lot of work to do, but rewriting `CTRAN` as a FOSS project is the first step.
+There is a lot of work to do, but recreating `CTRAN` as a FOSS project is the first step.