Updated README

[xonotic/gmqcc.git] / README

diff --git a/README b/README
index 79b57cf25002f3a28ed0d666e37e068723df0714..7b5181e9afc12117d7750b05161ec1d2d48eb0ca 100644 (file)
--- a/README
+++ b/README
@@ -30,9 +30,14 @@ typedef.c
        complicated than it sounds.  This handles all typedefs, and even recrusive
        typedefs.
        
-alloc.c
-       This is just an allocator for the compiler, it's used for debugging reasons
-       only.
+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
@@ -48,3 +53,105 @@ Makefile
                        
                #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 is 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 declartion.
+       
+       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. Simaler to the
+       usage of constants and functions the AUTHOR keyword must be proceeded
+       by a colon.
+       
+       Examples:
+               AUTHOR: "Dale Weiler"
+               AUTHOR: "John Doe"
+               
+       Colons exist for the sole reason of not having to use spaces after
+       keyword usage (however spaces are allowed).  To understand the
+       following examples below are equivlent.
+       
+       Example 1:
+               FLOAT:foo 1
+       Example 2:
+               FLOAT: foo 1
+       Example 3:
+               FLOAT:  foo 2
+               
+       variable amounts of whitespace is allowed anywhere (as it should be).
+       think of `:` as a delimiter (which is what it's used for during assembly).
+       
+////////////////////////////////////////////////////////////////////////
+/////////////////////// Quake C Documentation //////////////////////////
+////////////////////////////////////////////////////////////////////////
+TODO ....