The parser internals are documented elsewhere, but here's the
quick bottom line:

1) Write your initial grammar for your language as lang.g
2) Use takeon to create the grammar tables, in parser-lang.h
3) Create the concrete syntax analyzer using update_astcode -
   this makes lang.c which contains your grammar embedded
   in C code that creates a concrete syntax tree (CST).
   (Old Edinburgh folks will understand that the concrete
    syntax tree is exactly what we used to call the "analysis
    record" or "AREC" that was usually stored in an array A(...) ))
3) Compile parser.c to build a parser using your grammar;
   running parser-lang will by default output the same file
   as its input.
4) Run generate-compiler-lang to create compile-lang.c - this
   is the procedure that is called to do the semantics of
   your language.  It works on a an abstract syntax tree (AST)
   which is a simplified version of the concrete syntax tree.
   The default behavour of the compile() procedure is to
   output what was input, but from the data stored in the AST.
   At this point you can edit compile-lang.c and make your
   compile procedure do something useful, whether that is
   an actual compilation or a source to source transformation.

Because this parser system is intended to be used for source
to source transformations, the AST includes all the terminal
strings that are also in the concrete syntax tree; however
for regular compilation the AST can be simplified to the basic
abstract elements.

It is possible to work entirely at the concrete syntax tree level,
which is in fact how all traditional Edinburgh-style parsers are
written.  However by converting to an AST, manipulation of
the tree data to do things like expression optimisation becomes
considerably easier.  The majority of textbooks dealing with
compiler optimisations use ASTs.

Because I had to create the CST first, the grammar that you
edit is embedded in the CST.  However now that I have a
generator for AST maniuplation, I copy the grammar source
from the parser tables back into the AST source code, and
it is my intention (not yet realised) that you will then
be able to update and maintain the grammar in that file
instead, rather than having to go back to the CST file to
make changes.

G
PS Updated 2022/02/15 with support for 68000 Imp - everything
in FMACS compiles now except for "string";var;"string"
which should be "string".var."string" (and if not, why not?)
