Fixes to README

[xonotic/gmqcc.git] / README

diff --git a/README b/README
index d069def2cf042f11d2df6f8047859712a1a89095..b9f3a27892ebc7e37962d0166dac82fb6040aa66 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,7 @@
-This is my work in progress C compiler.  There are very few _good_ qc
+This is my work in progress Quake C compiler. There are very few _good_ QC

 compilers out there on the internet that can be used in the opensource
 community.  There are a lot of mediocre compilers, but no one wants those.
 compilers out there on the internet that can be used in the opensource
 community.  There are a lot of mediocre compilers, but no one wants those.

-This is the solution for that, for once a proper quake c compiler that is
+This is the solution for that, for once a proper Quake C compiler that is

 capable of doing proper optimization.  The design so far of this compiler
 is basic, because it doesn't actually compile code yet.
 
 capable of doing proper optimization.  The design so far of this compiler
 is basic, because it doesn't actually compile code yet.
 


@@ -23,7 +23,21 @@ main.c
        
 parse.c
        This is the parser which goes over all tokens and generates a parse tree
        
 parse.c
        This is the parser which goes over all tokens and generates a parse tree

-       (not currently, but will) and check for syntax correctness.
+       and check for syntax correctness.
+       
+typedef.c
+       This is the typedef system, this is a seperate file because it's a lot more
+       complicated than it sounds.  This handles all typedefs, and even recrusive
+       typedefs.
+       
+util.c
+       These are utilities for the compiler, some things in here include a
+       allocator used for debugging, and some string functions.
+       
+assembler.c
+       This implements support for assembling Quake assembler (which doesn't
+       actually exist untill now: documentation of the Quake assembler is below.
+       This also implements (will) inline assembly for the C compiler.

        
 README
        This is the file you're currently reading
        
 README
        This is the file you're currently reading


@@ -39,3 +53,80 @@ Makefile
                        
                #make clean
                        Cleans the build files left behind by a previous build
                        
                #make clean
                        Cleans the build files left behind by a previous build

+
+////////////////////////////////////////////////////////////////////////
+///////////////////// Quake Assembler Documentation ////////////////////
+////////////////////////////////////////////////////////////////////////
+Quake assembler is quite simple: it's just an annotated version of the binary
+produced by any existing QuakeC compiler, but made cleaner to use, (so that
+the location of various globals or strings are not required to be known).
+
+Constants:
+       Using one of the following valid constant typenames, you can declare
+       a constant {FLOAT,VECTOR,FUNCTION,FIELD,ENTITY}, all typenames are
+       proceeded by a colon, and the name (white space doesn't matter).
+       
+       Examples:
+               FLOAT: foo 1
+               VECTOR: bar 1 2 1
+               STRING: hello "hello world"
+               
+Comments:
+       Commenting assembly requires the use of either # or ; on the line
+       that you'd like to be ignored by the assembler. You can only comment
+       blank lines, and not lines assembly already exists on.
+       
+       Examples:
+               ; this is allowed
+               # as it this
+               FLOAT: foo 1 ; this is not allowed
+               FLOAT: bar 2 # neither is this
+       
+Functions:
+       Creating functions is the same as declaring a constant, simply use
+       FUNCTION followed by a colon, and the name (white space doesn't matter)
+       and start the statements for that function on the line after it
+       
+       Examples:
+               FLOAT: foo 1
+               FLOAT: bar 2
+               FUNCTION: test1
+                       ADD foo, bar, OFS_RETURN
+                       RETURN
+                       
+               FUNCTION: test2
+                       CALL0 test1
+                       DONE
+                       
+Internal:
+       The Quake engine provides some internal functions such as print, to
+       access these you first must declare them and their names. To do this
+       you create a FUNCTION as you currently do. Adding a $ followed by the
+       number of the engine builtin (negated).
+       
+       Examples:
+               FUNCTION: print $4
+               FUNCTION: error $3
+
+Misc:
+       There are some rules as to what your identifiers can be for functions
+       and constants.  All indentifiers mustn't begin with a numeric digit,
+       identifiers cannot include spaces, or tabs; they cannot contain symbols,
+       and they cannot exceed 32768 characters. Identifiers cannot be all 
+       capitalized either, as all capatilized identifiers are reserved by the
+       assembler.
+       
+       Numeric constants cannot contain special notation such as `1-e10`, all
+       numeric constants have to be numeric, they can contain decmial points
+       and signs (+, -) however.
+       
+       Constants cannot be assigned values of other constants, their value must
+       be fully expressed inspot of the declration.
+       
+       No two identifiers can be the same name, this applies for variables allocated
+       inside a function scope (despite it being considered local).
+       
+       There exists one other keyword that is considered sugar, and that
+       is AUTHOR, this keyword will allow you to speciy the AUTHOR(S) of
+       the assembly being assembled. The string represented for each usage
+       of AUTHOR is wrote to the end of the string table.