X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fca65.sgml;h=444f9e34189b3efe2c7df66f717871ada2b55d4e;hb=84be7444189a9a274d5cc3927cf7a2b08165ede2;hp=4201a5084ee99212c0701916fb8ffe4af8360bbb;hpb=5686efcb4abe7035a7a87b63d75177bd065e8544;p=cc65

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 4201a5084..444f9e341 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -109,6 +109,7 @@ Long options:
   --help      		Help (this text)
   --ignore-case		Ignore case of symbols
   --include-dir dir	Set an include directory search path
+  --list-bytes n        Maximum number of bytes per listing line
   --listing   		Create a listing if assembly was ok
   --pagelength n	Set the page length for the listing
   --smart     		Enable smart mode
@@ -125,15 +126,16 @@ Here is a description of all the command line options:
 
 <descrip>
 
+  <label id="option--cpu">
   <tag><tt>--cpu type</tt></tag>
 
   Set the default for the CPU type. The option takes a parameter, which
   may be one of
 
- 	6502, 65C02, 65816 and sunplus
+       	6502, 65SC02, 65C02, 65816, sunplus, sweet16
 
-  The latter (sunplus) is not available in the freeware version, because the
-  instruction set of the sunplus CPU is "confidential".
+  The sunplus cpu is not available in the freeware version, because the
+  instruction set is "proprietary and confidential".
 
 
   <label id="option--feature">
@@ -178,6 +180,14 @@ Here is a description of all the command line options:
   may change in future versions.
 
 
+  <tag><tt>--list-bytes n</tt></tag>
+
+  Set the maximum number of bytes printed in the listing for one line of
+  input. See the <tt><ref id=".LISTBYTES" name=".LISTBYTES"></tt> directive
+  for more information. The value zero can be used to encode an unlimited
+  number of printed bytes.
+
+
   <tag><tt>-o name</tt></tag>
 
   The default output name is the name of the input file with the extension
@@ -272,6 +282,8 @@ Here is a description of all the command line options:
 
 <sect>Input format<p>
 
+<sect1>Assembler syntax<p>
+
 The assembler accepts the standard 6502/65816 assembler syntax. One line may
 contain a label (which is identified by a colon), and, in addition to the
 label, an assembler mnemonic, a macro, or a control command (see section <ref
@@ -292,11 +304,25 @@ Here are some examples for valid input lines:
    	MaSym 	= Label	       		; Another symbol
 </verb></tscreen>
 
-The assembler accepts all valid 6502 mnemonics when in 6502 mode (the
-default). The assembler accepts all valid 65SC02 mnemonics when in 65SC02 mode
-(after a <tt><ref id=".PC02" name=".PC02"></tt> command is found). The
-assembler accepts all valid 65816 mnemonics with a few exceptions after a
-.P816 command is found. These exceptions are listed below.
+The assembler accepts
+
+<itemize>
+<item>all valid 6502 mnemonics when in 6502 mode (the default or after the
+      <tt><ref id=".P02" name=".P02"></tt> command was given).
+<item>all valid 6502 mnemonics plus a set of illegal instructions when in
+      <ref id="6502X-mode" name="6502X mode">.
+<item>all valid 65SC02 mnemonics when in 65SC02 mode (after the
+      <tt><ref id=".PSC02" name=".PSC02"></tt> command was given).
+<item>all valid 65C02 mnemonics when in 65C02 mode (after the
+      <tt><ref id=".PC02" name=".PC02"></tt> command was given).
+<item>all valid 65618 mnemonics when in 65816 mode (after the
+      <tt><ref id=".P816" name=".P816"></tt> command was given).
+<item>all valid SunPlus mnemonics when in SunPlus mode (after the
+      <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given).
+</itemize>
+
+
+<sect1>65816 mode<p>
 
 In 65816 mode several aliases are accepted in addition to the official
 mnemonics:
@@ -314,23 +340,83 @@ mnemonics:
   	TSA is an alias for TSC
 </verb></tscreen>
 
-Evaluation of banked expressions in 65816 mode differs slightly from the
-official syntax:
 
-Instead of accepting a 24 bit address (something that is difficult for
-the assembler to determine and would have required one more special
-.import command), the bank and the absolute address in that bank are
-separated by a dot:
 
-<tscreen><verb>
-   	jsl	3.$1234	       	; Call subroutine at $1234 in bank 3
-</verb></tscreen>
+<sect1>6502X mode<label id="6502X-mode"><p>
 
-For literal values, the assembler accepts the widely used number formats:
-A preceeding '&dollar;' denotes a hex value, a preceeding '%' denotes a
-binary value, and a bare number is interpeted as a decimal. There are
-currently no octal values and no floats.
-<p>
+6502X mode is an extension to the normal 6502 mode. In this mode, several
+mnemomics for illegal instructions of the NMOS 6502 CPUs are accepted. Since
+these instructions are illegal, there are no official mnemonics for them. The
+unofficial ones are taken from <htmlurl
+url="http://oxyron.net/graham/opcodes02.html"
+name="http://oxyron.net/graham/opcodes02.html">. Please note that only the
+ones marked as "stable" are supported. The following table uses information
+from the mentioned web page, for more information, see there.
+
+<itemize>
+<item><tt>ALR: A:=(A and #{imm})*2;</tt>
+<item><tt>ANC: A:=A and #{imm};</tt> Generates opcode &dollar;0B.
+<item><tt>ARR: A:=(A and #{imm})/2;</tt>
+<item><tt>AXS: X:=A and X-#{imm};</tt>
+<item><tt>DCP: {adr}:={adr}-1; A-{adr};</tt>
+<item><tt>ISC: {adr}:={adr}+1; A:=A-{adr};</tt>
+<item><tt>LAS: A,X,S:={adr} and S;</tt>
+<item><tt>LAX: A,X:={adr};</tt>
+<item><tt>RLA: {adr}:={adr}rol; A:=A and {adr};</tt>
+<item><tt>RRA: {adr}:={adr}ror; A:=A adc {adr};</tt>
+<item><tt>SAX: {adr}:=A and X;</tt>
+<item><tt>SLO: {adr}:={adr}*2; A:=A or {adr};</tt>
+<item><tt>SRE: {adr}:={adr}/2; A:=A xor {adr};</tt>
+</itemize>
+
+
+
+<sect1>sweet16 mode<label id="sweet16-mode"><p>
+
+SWEET 16 is an interpreter for a pseudo 16 bit CPU written by Steve Wozniak
+for the Apple ][ machines. It is available in the Apple ][ ROM. ca65 can
+generate code for this pseudo CPU when switched into sweet16 mode. The
+following is special in sweet16 mode:
+
+<itemize>
+
+<item>The '@' character denotes indirect addressing and is no longer available
+for cheap local labels. If you need cheap local labels, you will have to
+switch to another lead character using the <tt/<ref id=".LOCALCHAR"
+name=".LOCALCHAR">/ command.
+
+<item>Registers are specified using <tt/R0/ .. <tt/R15/. In sweet16 mode,
+these identifiers are reserved words.
+
+</itemize>
+
+Please note that the assembler does neither supply the interpreter needed for
+SWEET 16 code, nor the zero page locations needed for the SWEET 16 registers,
+nor does it call the interpreter. All this must be done by your program. Apple
+][ programmers do probably know how to use sweet16 mode.
+
+For more information about SWEET 16, see
+<htmlurl url="http://www.6502.org/source/interpreters/sweet16.htm"
+name="http://www.6502.org/source/interpreters/sweet16.htm">.
+
+
+<sect1>Number format<p>
+
+For literal values, the assembler accepts the widely used number formats: A
+preceeding '&dollar;' or a trailing 'h' denotes a hex value, a preceeding '%'
+denotes a binary value, and a bare number is interpeted as a decimal. There
+are currently no octal values and no floats.
+
+
+<sect1>Conditional assembly<p>
+
+Please note that when using the conditional directives (<tt/.IF/ and friends),
+the input must consist of valid assembler tokens, even in <tt/.IF/ branches
+that are not assembled. The reason for this behaviour is that the assembler
+must still be able to detect the ending tokens (like <tt/.ENDIF/), so
+conversion of the input stream into tokens still takes place. As a consequence
+conditional assembly directives may <bf/not/ be used to prevent normal text
+(used as a comment or similar) from being assembled. <p>
 
 
 <sect>Expressions<p>
@@ -346,7 +432,7 @@ Expressions referencing imported symbols must always be evaluated by the
 linker.
 
 
-<sect1>Size of an expressions result<p>
+<sect1>Size of an expression result<p>
 
 Sometimes, the assembler must know about the size of the value that is the
 result of an expression. This is usually the case, if a decision has to be
@@ -358,7 +444,7 @@ expression:
 <item> 	If the result of an expression is constant, the actual value is
        	checked to see if it's a byte sized expression or not.
 <item> 	If the expression is explicitly casted to a byte sized expression by
-       	one of the '&gt;'/'&lt;' operators, it is a byte expression.
+       	one of the '&gt;', '&lt;' or '^' operators, it is a byte expression.
 <item> 	If this is not the case, and the expression contains a symbol,
        	explicitly declared as zero page symbol (by one of the .importzp or
        	.exportzp instructions), then the whole expression is assumed to be
@@ -386,37 +472,44 @@ already known, after evaluating the left hand side, the right hand side is
 not evaluated.
 
 
-<sect1>Available operators<p>
+<sect1>Constant expressions<p>
+
+Sometimes an expression must evaluate to a constant without looking at any
+further input. One such example is the <tt/<ref id=".IF" name=".IF">/ command
+that decides if parts of the code are assembled or not. An expression used in
+the <tt/.IF/ command cannot reference a symbol defined later, because the
+decision about the <tt/.IF/ must be made at the point when it is read. If the
+expression used in such a context contains only constant numerical values,
+there is no problem. When unresolvable symbols are involved it may get harder
+for the assembler to determine if the expression is actually constant, and it
+is even possible to create expressions that aren't recognized as constant.
+Simplifying the expressions will often help.
+
+In cases where the result of the expression is not needed immediately, the
+assembler will delay evaluation until all input is read, at which point all
+symbols are known. So using arbitrary complex constant expressions is no
+problem in most cases.
+
+
+
+<sect1>Available operators<label id="operators"><p>
 
 Available operators sorted by precedence:
 
 <tscreen><verb>
     Op 	        Description  		     	      	Precedence
   -------------------------------------------------------------------
-    .CONCAT     Builtin function                        0
-    .LEFT      	Builtin function	     	     	0
-    .MID       	Builtin function	     	     	0
-    .RIGHT     	Builtin function	     	     	0
-    .STRING    	Builtin function	     	     	0
-
-    *	       	Builtin pseudo variable (r/o)	      	1
-    .BLANK     	Builtin function	     	     	1
-    .CONST     	Builtin function	     	     	1
-    .CPU       	Builtin pseudo variable (r/o)	     	1
-    .DEFINED   	Builtin function	     	     	1
-    .MATCH     	Builtin function	     	     	1
-    .TCOUNT    	Builtin function	     	     	1
-    .TIME    	Builtin function	     	     	1
-    .XMATCH    	Builtin function	     	     	1
-    .PARAMCOUNT Builtin pseudo variable	(r/o)	      	1
-    .REFERENCED Builtin function	     	       	1
-    :: 	       	Global namespace override    	     	1
+                Builtin string functions                0
+
+                Builtin pseudo variables                1
+                Builtin pseudo functions       	       	1
     +  	       	Unary plus   		     	     	1
     -  	       	Unary minus  		     	     	1
     ~  	       	Unary bitwise not	     	     	1
     .BITNOT    	Unary bitwise not      	       	       	1
     &lt;	   Low byte operator	     	     	   1
     &gt;	   High byte operator	     	     	   1
+    ^           Bank byte operator                      1
 
     *  	       	Multiplication		     	     	2
     /  	       	Division     		     	     	2
@@ -425,7 +518,7 @@ Available operators sorted by precedence:
     .BITAND    	Bitwise and  		     	     	2
     ^  	       	Bitwise xor  		     	     	2
     .BITXOR    	Bitwise xor  		     	     	2
-    &lt;&lt;   	      Shift left operator	     	      2
+    &lt;&lt;   	      Shift left operator    	     	      2
     .SHL       	Shift left operator	     	     	2
     &gt;&gt;   	      Shift right operator
     .SHR       	Shift right operator 	     	     	2
@@ -456,15 +549,6 @@ Available operators sorted by precedence:
 
 To force a specific order of evaluation, braces may be used as usual.
 
-Some of the pseudo variables mentioned above need some more explanation:
-
-<tscreen><verb>
-  *	       	This symbol is replaced by the value of the program
-	       	counter at start of the current instruction. Note, that
-	       	'*' yields a rvalue, that means, you cannot assign to it.
-   	       	Use <tt/.ORG/ to set the program counter in sections with
-	       	absolute code.
-</verb></tscreen>
 <p>
 
 
@@ -478,14 +562,23 @@ use symbols and labels, giving a lot of flexibility.
 
 <sect1>Numeric constants<p>
 
-Numeric constants are defined using the equal sign. After doing
+Numeric constants are defined using the equal sign or the label assignment
+operator. After doing
 
 <tscreen><verb>
       two = 2
 </verb></tscreen>
 
 may use the symbol "two" in every place where a number is expected, and it is
-evaluated to the value 2 in this context. An example would be
+evaluated to the value 2 in this context. The label assignment operator causes
+the same, but causes the symbol to be marked as a label, which may cause a
+different handling in the debugger:
+
+<tscreen><verb>
+      io := $d000
+</verb></tscreen>
+
+The right side can of course be an expression:
 
 <tscreen><verb>
       four = two * two
@@ -533,8 +626,8 @@ names like "Loop". Here is an example:
 		dey
 		bne    @Loop  	     	; Ok
 		rts
-	Sub:    ... 	       	     	; New global label
-		bne    @Loop  	     	; ERROR: Unknown identifier!
+       	Sub:    ... 	       	     	; New global label
+	 	bne    @Loop  	     	; ERROR: Unknown identifier!
 </verb></tscreen>
 
 <sect1>Unnamed labels<p>
@@ -610,283 +703,1111 @@ because they don't have a name which would allow to access them.
 
 
 
-<sect>Control commands<label id="control-commands">
+<sect>Scopes<label id="scopes"><p>
 
-<p>
-Here's a list of all control commands and a description, what they do:
+ca65 implements several sorts of scopes for symbols.
 
+<sect1>Global scope<p>
 
-<sect1><tt>.A16</tt><label id=".A16"><p>
+All (non cheap local) symbols that are declared outside of any nested scopes
+are in global scope.
 
-  Valid only in 65816 mode. Switch the accumulator to 16 bit.
 
-  Note: This command will not emit any code, it will tell the assembler to
-  create 16 bit operands for immediate accumulator adressing mode.
+<sect1>A special scope: cheap locals<p>
 
-  See also: <tt><ref id=".SMART" name=".SMART"></tt>
+A special scope is the scope for cheap local symbols. It lasts from one non
+local symbol to the next one, without any provisions made by the programmer.
+All other scopes differ in usage but use the same concept internally.
 
 
-<sect1><tt>.A8</tt><label id=".A8"><p>
+<sect1>Generic nested scopes<p>
 
-  Valid only in 65816 mode. Switch the accumulator to 8 bit.
+A nested scoped for generic use is started with <tt/<ref id=".SCOPE"
+name=".SCOPE">/ and closed with <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/.
+The scope can have a name, in which case it is accessible from the outside by
+using <ref id="scopesyntax" name="explicit scopes">. If the scope does not
+have a name, all symbols created within the scope are local to the scope, and
+aren't accessible from the outside.
 
-  Note: This command will not emit any code, it will tell the assembler to
-  create 8 bit operands for immediate accu adressing mode.
+A nested scope can access symbols from the local or from enclosing scopes by
+name without using explicit scope names. In some cases there may be
+ambiguities, for example if there is a reference to a local symbol that is not
+yet defined, but a symbol with the same name exists in outer scopes:
 
-  See also: <tt><ref id=".SMART" name=".SMART"></tt>
+<tscreen><verb>
+        .scope  outer
+                foo     = 2
+                .scope  inner
+                        lda     #foo
+                        foo     = 3
+                .endscope
+        .endscope
+</verb></tscreen>
 
+In the example above, the <tt/lda/ instruction will load the value 3 into the
+accumulator, because <tt/foo/ is redefined in the scope. However:
 
-<sect1><tt>.ADDR</tt><label id=".ADDR"><p>
+<tscreen><verb>
+        .scope  outer
+                foo     = $1234
+                .scope  inner
+                        lda     foo,x
+                        foo     = $12
+                .endscope
+        .endscope
+</verb></tscreen>
 
-  Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and
-  may be used for better readability if the data words are address values. In
-  65816 mode, the address is forced to be 16 bit wide to fit into the current
-  segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command
-  must be followed by a sequence of (not necessarily constant) expressions.
+Here, <tt/lda/ will still load from <tt/$12,x/, but since it is unknown to the
+assembler that <tt/foo/ is a zeropage symbol when translating the instruction,
+absolute mode is used instead. In fact, the assembler will not use absolute
+mode by default, but it will search through the enclosing scopes for a symbol
+with the given name. If one is found, the address size of this symbol is used.
+This may lead to errors:
 
-  Example:
+<tscreen><verb>
+        .scope  outer
+                foo     = $12
+                .scope  inner
+                        lda     foo,x
+                        foo     = $1234
+                .endscope
+        .endscope
+</verb></tscreen>
 
-  <tscreen><verb>
-  	.addr  	$0D00, $AF13, _Clear
-  </verb></tscreen>
+In this case, when the assembler sees the symbol <tt/foo/ in the <tt/lda/
+instruction, it will search for an already defined symbol <tt/foo/. It will
+find <tt/foo/ in scope <tt/outer/, and a close look reveals that it is a
+zeropage symbol. So the assembler will use zeropage addressing mode. If
+<tt/foo/ is redefined later in scope <tt/inner/, the assembler tries to change
+the address in the <tt/lda/ instruction already translated, but since the new
+value needs absolute addressing mode, this fails, and an error message "Range
+error" is output.
 
-  See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD"
-       name=".WORD"></tt>
+Of course the most simple solution for the problem is to move the definition
+of <tt/foo/ in scope <tt/inner/ upwards, so it preceeds its use. There may be
+rare cases when this cannot be done. In these cases, you can use one of the
+address size override operators:
 
+<tscreen><verb>
+        .scope  outer
+                foo     = $12
+                .scope  inner
+                        lda     a:foo,x
+                        foo     = $1234
+                .endscope
+        .endscope
+</verb></tscreen>
 
-<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p>
+This will cause the <tt/lda/ instruction to be translated using absolute
+addressing mode, which means changing the symbol reference later does not
+cause any errors.
 
-  Align data to a given boundary. The command expects a constant integer
-  argument that must be a power of two, plus an optional second argument
-  in byte range. If there is a second argument, it is used as fill value,
-  otherwise the value defined in the linker configuration file is used
-  (the default for this value is zero).
 
-  Since alignment depends on the base address of the module, you must
-  give the same (or a greater) alignment for the segment when linking.
-  The linker will give you a warning, if you don't do that.
+<sect1>Nested procedures<p>
 
-  Example:
+A nested procedure is created by use of <tt/<ref id=".PROC" name=".PROC">/. It
+differs from a <tt/<ref id=".SCOPE" name=".SCOPE">/ in that it must have a
+name, and a it will introduce a symbol with this name in the enclosing scope.
+So
 
-  <tscreen><verb>
-      	.align	256
-  </verb></tscreen>
+<tscreen><verb>
+        .proc   foo
+                ...
+        .endscope
+</verb></tscreen>
 
+is actually the same as
 
-<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p>
+<tscreen><verb>
+        foo:
+        .scope  foo
+                ...
+        .endscope
+</verb></tscreen>
 
-  Define a string with a trailing zero.
+This is the reason why a procedure must have a name. If you want a scope
+without a name, use <tt/<ref id=".SCOPE" name=".SCOPE">/.
 
-  Example:
+<bf/Note:/ As you can see from the example above, scopes and symbols live in
+different namespaces. There can be a symbol named <tt/foo/ and a scope named
+<tt/foo/ without any conflicts (but see the section titled <ref
+id="scopesearch" name="&quot;Scope search order&quot;">).
 
-  <tscreen><verb>
-  	Msg: 	.asciiz	"Hello world"
-  </verb></tscreen>
 
-  This will put the string "Hello world" followed by a binary zero into
-  the current segment. There may be more strings separated by commas, but
-  the binary zero is only appended once (after the last one).
+<sect1>Structs, unions and enums<p>
 
+Structs, unions and enums are explained in a <ref id="structs" name="separate
+section">, I do only cover them here, because if they are declared with a
+name, they open a nested scope, similar to <tt/<ref id=".SCOPE"
+name=".SCOPE">/. However, when no name is specified, the behaviour is
+different: In this case, no new scope will be opened, symbols declared within
+a struct, union, or enum declaration will then be added to the enclosing scope
+instead.
 
-<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p>
 
-  Add an assertion. The command is followed by an expression, an action
-  specifier and a message that is output in case the assertion fails. The
-  action specifier may be one of <tt/warning/ or <tt/error/. The assertion
-  is passed to the linker and will be evaluated when segment placement has
-  been done.
+<sect1>Explicit scope specification<label id="scopesyntax"><p>
 
-  Example:
+Accessing symbols from other scopes is possible by using an explicit scope
+specification, provided that the scope where the symbol lives in has a name.
+The namespace token (<tt/::/) is used to access other scopes:
 
-  <tscreen><verb>
-       	.assert         * = $8000, error, "Code not at $8000"
-  </verb></tscreen>
+<tscreen><verb>
+        .scope  foo
+        bar:    .word   0
+        .endscope
 
-  The example assertion will check that the current location is at $8000,
-  when the output file is written, and abort with an error if this is not
-  the case. More complex expressions are possible. The action specifier
-  <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs
-  an error message. In the latter case, generation if the output file is
-  suppressed.
+                ...
+                lda     foo::bar        ; Access foo in scope bar
+</verb></tscreen>
 
+The only way to deny access to a scope from the outside is to declare a scope
+without a name (using the <tt/<ref id=".SCOPE" name=".SCOPE">/ command).
 
-<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p>
+A special syntax is used to specify the global scope: If a symbol or scope is
+preceeded by the namespace token, the global scope is searched:
 
-  Is followed by a plus or a minus character. When switched on (using a
-  +), undefined symbols are automatically marked as import instead of
-  giving errors. When switched off (which is the default so this does not
-  make much sense), this does not happen and an error message is
-  displayed. The state of the autoimport flag is evaluated when the
-  complete source was translated, before outputing actual code, so it is
-  <em/not/ possible to switch this feature on or off for separate sections
-  of code. The last setting is used for all symbols.
+<tscreen><verb>
+        bar     = 3
 
-  You should probably not use this switch because it delays error
-  messages about undefined symbols until the link stage. The cc65
-  compiler (which is supposed to produce correct assembler code in all
-  circumstances, something which is not true for most assembler
-  programmers) will insert this command to avoid importing each and every
-  routine from the runtime library.
+        .scope  foo
+                bar     = 2
+                lda     #::bar  ; Access the global bar (which is 3)
+        .endscope
+</verb></tscreen>
 
-  Example:
 
-  <tscreen><verb>
-  	.autoimport    	+   	; Switch on auto import
-  </verb></tscreen>
+<sect1>Scope search order<label id="scopesearch"><p>
 
+The assembler searches for a scope in a similar way as for a symbol. First, it
+looks in the current scope, and then it walks up the enclosing scopes until
+the scope is found.
 
-<sect1><tt>.BLANK</tt><label id=".BLANK"><p>
+However, one important thing to note when using explicit scope syntax is, that
+a symbol may be accessed before it is defined, but a scope may <bf/not/ be
+used without a preceeding definition. This means that in the following
+example:
 
-  Builtin function. The function evaluates its argument in braces and
-  yields "false" if the argument is non blank (there is an argument), and
-  "true" if there is no argument. As an example, the <tt/.IFBLANK/ statement
-  may be replaced by
+<tscreen><verb>
+        .scope  foo
+                bar     = 3
+        .endscope
+
+        .scope  outer
+                lda     #foo::bar  ; Will load 3, not 2!
+                .scope  foo
+                        bar     = 2
+                .endscope
+        .endscope
+</verb></tscreen>
 
-  <tscreen><verb>
-	.if	.blank(arg)
-  </verb></tscreen>
+the reference to the scope <tt/foo/ will use the global scope, and not the
+local one, because the local one is not visible at the point where it is
+referenced.
 
+Things get more complex if a complete chain of scopes is specified:
 
-<sect1><tt>.BSS</tt><label id=".BSS"><p>
+<tscreen><verb>
+        .scope  foo
+                .scope  outer
+                        .scope  inner
+                                bar = 1
+                        .endscope
+                .endscope
+                .scope  another
+                        .scope  nested
+                                lda     #outer::inner::bar      ; 1
+                        .endscope
+                .endscope
+        .endscope
+
+        .scope  outer
+                .scope  inner
+                        bar = 2
+                .endscope
+        .endscope
+</verb></tscreen>
 
-  Switch to the BSS segment. The name of the BSS segment is always "BSS",
-  so this is a shortcut for
+When <tt/outer::inner::bar/ is referenced in the <tt/lda/ instruction, the
+assembler will first search in the local scope for a scope named <tt/outer/.
+Since none is found, the enclosing scope (<tt/another/) is checked. There is
+still no scope named <tt/outer/, so scope <tt/foo/ is checked, and finally
+scope <tt/outer/ is found. Within this scope, <tt/inner/ is searched, and in
+this scope, the assembler looks for a symbol named <tt/bar/.
+
+Please note that once the anchor scope is found, all following scopes
+(<tt/inner/ in this case) are expected to be found exactly in this scope. The
+assembler will search the scope tree only for the first scope (if it is not
+anchored in the root scope). Starting from there on, there is no flexibility,
+so if the scope named <tt/outer/ found by the assembler does not contain a
+scope named <tt/inner/, this would be an error, even if such a pair does exist
+(one level up in global scope).
+
+Ambiguities that may be introduced by this search algorithm may be removed by
+anchoring the scope specification in the global scope. In the example above,
+if you want to access the "other" symbol <tt/bar/, you would have to write:
 
-  <tscreen><verb>
-  	.segment  "BSS"
-  </verb></tscreen>
+<tscreen><verb>
+        .scope  foo
+                .scope  outer
+                        .scope  inner
+                                bar = 1
+                        .endscope
+                .endscope
+                .scope  another
+                        .scope  nested
+                                lda     #::outer::inner::bar    ; 2
+                        .endscope
+                .endscope
+        .endscope
+
+        .scope  outer
+                .scope  inner
+                        bar = 2
+                .endscope
+        .endscope
+</verb></tscreen>
 
-  See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
 
+<sect>Address sizes and memory models<label id="address-sizes"><p>
 
-<sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p>
+<sect1>Address sizes<p>
 
-  Define byte sized data. Must be followed by a sequence of (byte ranged)
-  expressions or strings.
+ca65 assigns each segment and each symbol an address size. This is true, even
+if the symbol is not used as an address. You may also think of a value range
+of the symbol instead of an address size.
 
-  Example:
+Possible address sizes are:
 
-  <tscreen><verb>
-  	.byte	"Hello "
-	.byt	"world", $0D, $00
-  </verb></tscreen>
+<itemize>
+<item>Zeropage or direct (8 bits)
+<item>Absolute (16 bits)
+<item>Far (24 bits)
+<item>Long (32 bits)
+</itemize>
 
+Since the assembler uses default address sizes for the segments and symbols,
+it is usually not necessary to override the default behaviour. In cases, where
+it is necessary, the following keywords may be used to specify address sizes:
 
-<sect1><tt>.CASE</tt><label id=".CASE"><p>
+<itemize>
+<item>DIRECT, ZEROPAGE or ZP for zeropage addressing (8 bits).
+<item>ABSOLUTE, ABS or NEAR for absolute addressing (16 bits).
+<item>FAR for far addressing (24 bits).
+<item>LONG or DWORD for long addressing (32 bits).
+</itemize>
 
-  Switch on or off case sensitivity on identifiers. The default is off
-  (that is, identifiers are case sensitive), but may be changed by the
-  -i switch on the command line.
-  The command must be followed by a '+' or '-' character to switch the
-  option on or off respectively.
 
-  Example:
+<sect1>Address sizes of segments<p>
 
-  <tscreen><verb>
-       	.case	-   	    	; Identifiers are not case sensitive
-  </verb></tscreen>
+The assembler assigns an address size to each segment. Since the
+representation of a label within this segment is "segment start + offset",
+labels will inherit the address size of the segment they are declared in.
 
+The address size of a segment may be changed, by using an optional address
+size modifier. See the <tt/<ref id=".SEGMENT" name="segment directive">/ for
+an explanation on how this is done.
 
-<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p>
 
-  Apply a custom mapping for characters. The command is followed by two
-  numbers in the range 1..255. The first one is the index of the source
-  character, the second one is the mapping. The mapping applies to all
-  character and string constants when they generate output, and overrides
-  a mapping table specified with the <tt><ref id="option-t" name="-t"></tt>
-  command line switch.
+<sect1>Address sizes of symbols<p>
 
-  Example:
 
-  <tscreen><verb>
-       	.charmap        $41, $61        ; Map 'A' to 'a'
-  </verb></tscreen>
 
 
-<sect1><tt>.CODE</tt><label id=".CODE"><p>
+<sect1>Memory models<p>
 
-  Switch to the CODE segment. The name of the CODE segment is always
-  "CODE", so this is a shortcut for
+The default address size of a segment depends on the memory model used. Since
+labels inherit the address size from the segment they are declared in,
+changing the memory model is an easy way to change the address size of many
+symbols at once.
 
-  <tscreen><verb>
-       	.segment  "CODE"
-  </verb></tscreen>
 
-  See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
 
 
-<sect1><tt>.CONDES</tt><label id=".CONDES"><p>
+<sect>Pseudo variables<label id="pseudo-variables"><p>
 
-  Export a symbol and mark it in a special way. The linker is able to build
-  tables of all such symbols. This may be used to automatically create a list
-  of functions needed to initialize linked library modules.
+Pseudo variables are readable in all cases, and in some special cases also
+writable.
 
-  Note: The linker has a feature to build a table of marked routines, but it
-  is your code that must call these routines, so just declaring a symbol with
-  <tt/.CONDES/ does nothing by itself.
+<sect1><tt>*</tt><p>
 
-  All symbols are exported as an absolute (16 bit) symbol. You don't need to
-  use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this
-  is implied by <tt/.CONDES/.
+  Reading this pseudo variable will return the program counter at the start
+  of the current input line.
 
-  <tt/.CONDES/ is followed by the type, which may be <tt/constructor/,
-  <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as
-  specifiying <tt/constructor/ and 1 is equal to specifying <tt/destructor/).
-  The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
-  id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands are actually shortcuts
-  for <tt/.CONDES/ with a type of <tt/constructor/ resp. <tt/destructor/.
+  Assignment to this variable is possible when <tt/<ref id=".FEATURE"
+  name=".FEATURE pc_assignment">/ is used. Note: You should not use
+  assignments to <tt/*/, use <tt/<ref id=".ORG" name=".ORG">/ instead.
 
-  After the type, an optional priority may be specified. If no priority is
-  given, the default priority of 7 is used. Be careful when assigning
-  priorities to your own module constructors so they won't interfere with the
-  ones in the cc65 library.
+
+<sect1><tt>.CPU</tt><label id=".CPU"><p>
+
+  Reading this pseudo variable will give a constant integer value that
+  tells which CPU is currently enabled. It can also tell which instruction
+  set the CPU is able to translate. The value read from the pseudo variable
+  should be further examined by using one of the constants defined by the
+  "cpu" macro package (see <tt/<ref id=".MACPACK" name=".MACPACK">/).
+
+  It may be used to replace the .IFPxx pseudo instructions or to construct
+  even more complex expressions.
 
   Example:
 
   <tscreen><verb>
-   	.condes		ModuleInit, constructor
-	.condes		ModInit, 0, 16
+        .macpack        cpu
+       	.if	(.cpu .bitand CPU_ISET_65816)
+  	 	phx
+  	 	phy
+  	.else
+  	 	txa
+  	 	pha
+  	 	tya
+  	 	pha
+  	.endif
   </verb></tscreen>
 
-  See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
-  id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section
-  <ref id="condes" name="Module constructors/destructors"> explaining the
-  feature in more detail.
-
 
-<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p>
+<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p>
 
-  Builtin function. The function allows to concatenate a list of string
-  constants separated by commas. The result is a string constant that
-  is the concatentation of all arguments. This function is most useful
-  in macros and when used together with the <tt/.STRING/ builtin function.
-  The function may be used in any case where a string constant is
-  expected.
+  This builtin pseudo variable is only available in macros. It is replaced by
+  the actual number of parameters that were given in the macro invocation.
 
   Example:
 
   <tscreen><verb>
-	.include 	.concat ("myheader", ".", "inc")
+	.macro	foo	arg1, arg2, arg3
+	.if	.paramcount <> 3
+   	.error	"Too few parameters for macro foo"
+	.endif
+	...
+ 	.endmacro
   </verb></tscreen>
 
-  This is the same as the command
-
-  <tscreen><verb>
-	.include 	"myheader.inc"
-  </verb></tscreen>
+  See section <ref id="macros" name="Macros">.
 
 
-<sect1><tt>.CONST</tt><label id=".CONST"><p>
+<sect1><tt>.TIME</tt><label id=".TIME"><p>
 
-  Builtin function. The function evaluates its argument in braces and
-  yields "true" if the argument is a constant expression (that is, an
-  expression that yields a constant value at assembly time) and "false"
-  otherwise. As an example, the .IFCONST statement may be replaced by
+  Reading this pseudo variable will give a constant integer value that
+  represents the current time in POSIX standard (as seconds since the
+  Epoch).
+
+  It may be used to encode the time of translation somewhere in the created
+  code.
+
+  Example:
+
+  <tscreen><verb>
+        .dword  .time   ; Place time here
+  </verb></tscreen>
+
+
+<sect1><tt>.VERSION</tt><label id=".VERSION"><p>
+
+  Reading this pseudo variable will give the assembler version according to
+  the following formula:
+
+        VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH
+
+  It may be used to encode the assembler version or check the assembler for
+  special features not available with older versions.
+
+  Example:
+
+  Version 2.11.1 of the assembler will return $2B1 as numerical constant when
+  reading the pseudo variable <tt/.VERSION/.
+
+
+
+<sect>Pseudo functions<label id="pseudo-functions"><p>
+
+Pseudo functions expect their arguments in parenthesis, and they have a result,
+either a string or an expression.
+
+
+<sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p>
+
+  The function returns the bank byte (that is, bits 16-23) of its argument.
+  It works identical to the '^' operator.
+
+  See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>,
+       <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>
+
+
+<sect1><tt>.BLANK</tt><label id=".BLANK"><p>
+
+  Builtin function. The function evaluates its argument in braces and yields
+  "false" if the argument is non blank (there is an argument), and "true" if
+  there is no argument.  The token list that makes up the function argument
+  may optionally be enclosed in curly braces. This allows the inclusion of
+  tokens that would otherwise terminate the list (the closing right
+  parenthesis). The curly braces are not considered part of the list, a list
+  just consisting of curly braces is considered to be empty.
+
+  As an example, the <tt/.IFBLANK/ statement may be replaced by
+
+  <tscreen><verb>
+  	.if	.blank({arg})
+  </verb></tscreen>
+
+
+
+<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p>
+
+  Builtin string function. The function allows to concatenate a list of string
+  constants separated by commas. The result is a string constant that is the
+  concatentation of all arguments. This function is most useful in macros and
+  when used together with the <tt/.STRING/ builtin function. The function may
+  be used in any case where a string constant is expected.
+
+  Example:
+
+  <tscreen><verb>
+	.include 	.concat ("myheader", ".", "inc")
+  </verb></tscreen>
+
+  This is the same as the command
+
+  <tscreen><verb>
+	.include 	"myheader.inc"
+  </verb></tscreen>
+
+
+<sect1><tt>.CONST</tt><label id=".CONST"><p>
+
+  Builtin function. The function evaluates its argument in braces and
+  yields "true" if the argument is a constant expression (that is, an
+  expression that yields a constant value at assembly time) and "false"
+  otherwise. As an example, the .IFCONST statement may be replaced by
+
+  <tscreen><verb>
+      	.if	.const(a + 3)
+  </verb></tscreen>
+
+
+<sect1><tt>.HIBYTE</tt><label id=".HIBYTE"><p>
+
+  The function returns the high byte (that is, bits 8-15) of its argument.
+  It works identical to the '>' operator.
+
+  See: <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>,
+       <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt>
+
+
+<sect1><tt>.HIWORD</tt><label id=".HIWORD"><p>
+
+  The function returns the high word (that is, bits 16-31) of its argument.
+
+  See: <tt><ref id=".LOWORD" name=".LOWORD"></tt>
+
+
+<sect1><tt>.LEFT</tt><label id=".LEFT"><p>
+
+  Builtin function. Extracts the left part of a given token list.
+
+  Syntax:
+
+  <tscreen><verb>
+       	.LEFT (&lt;int expr&gt;, &lt;token list&gt;)
+  </verb></tscreen>
+
+  The first integer expression gives the number of tokens to extract from
+  the token list. The second argument is the token list itself. The token
+  list may optionally be enclosed into curly braces. This allows the
+  inclusion of tokens that would otherwise terminate the list (the closing
+  right paren in the given case).
+
+  Example:
+
+  To check in a macro if the given argument has a '#' as first token
+  (immidiate addressing mode), use something like this:
+
+  <tscreen><verb>
+    	.macro 	ldax	arg
+    	       	...
+    	       	.if (.match (.left (1, {arg}), #))
+
+    	       	; ldax called with immidiate operand
+    	       	...
+
+    	       	.endif
+    	       	...
+       	.endmacro
+  </verb></tscreen>
+
+  See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT"
+  name=".RIGHT"></tt> builtin functions.
+
+
+<sect1><tt>.LOBYTE</tt><label id=".LOBYTE"><p>
+
+  The function returns the low byte (that is, bits 0-7) of its argument.
+  It works identical to the '<' operator.
+
+  See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>,
+       <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt>
+
+
+<sect1><tt>.LOWORD</tt><label id=".LOWORD"><p>
+
+  The function returns the low word (that is, bits 0-15) of its argument.
+
+  See: <tt><ref id=".HIWORD" name=".HIWORD"></tt>
+
+
+<sect1><tt>.MATCH</tt><label id=".MATCH"><p>
+
+  Builtin function. Matches two token lists against each other. This is
+  most useful within macros, since macros are not stored as strings, but
+  as lists of tokens.
+
+  The syntax is
+
+  <tscreen><verb>
+       	.MATCH(&lt;token list #1&gt;, &lt;token list #2&gt;)
+  </verb></tscreen>
+
+  Both token list may contain arbitrary tokens with the exception of the
+  terminator token (comma resp. right parenthesis) and
+
+  <itemize>
+  <item>end-of-line
+  <item>end-of-file
+  </itemize>
+
+  The token lists may optionally be enclosed into curly braces. This allows
+  the inclusion of tokens that would otherwise terminate the list (the closing
+  right paren in the given case). Often a macro parameter is used for any of
+  the token lists.
+
+  Please note that the function does only compare tokens, not token
+  attributes. So any number is equal to any other number, regardless of the
+  actual value. The same is true for strings. If you need to compare tokens
+  <em/and/ token attributes, use the <tt><ref id=".XMATCH"
+  name=".XMATCH"></tt> function.
+
+  Example:
+
+  Assume the macro <tt/ASR/, that will shift right the accumulator by one,
+  while honoring the sign bit. The builtin processor instructions will allow
+  an optional "A" for accu addressing for instructions like <tt/ROL/ and
+  <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function
+  to check for this and print and error for invalid calls.
+
+  <tscreen><verb>
+  	.macro	asr 	arg
+
+       	       	.if (.not .blank(arg)) .and (.not .match ({arg}, a))
+    	    	.error "Syntax error"
+    	    	.endif
+
+    	    	cmp 	#$80		; Bit 7 into carry
+    	    	lsr 	a		; Shift carry into bit 7
+
+    	.endmacro
+  </verb></tscreen>
+
+  The macro will only accept no arguments, or one argument that must be the
+  reserved keyword "A".
+
+  See: <tt><ref id=".XMATCH" name=".XMATCH"></tt>
+
+
+<sect1><tt>.MID</tt><label id=".MID"><p>
+
+  Builtin function. Takes a starting index, a count and a token list as
+  arguments. Will return part of the token list.
+
+  Syntax:
+
+  <tscreen><verb>
+       	.MID (&lt;int expr&gt;, &lt;int expr&gt;, &lt;token list&gt;)
+  </verb></tscreen>
+
+  The first integer expression gives the starting token in the list (the first
+  token has index 0). The second integer expression gives the number of tokens
+  to extract from the token list. The third argument is the token list itself.
+  The token list may optionally be enclosed into curly braces. This allows the
+  inclusion of tokens that would otherwise terminate the list (the closing
+  right paren in the given case).
+
+  Example:
+
+  To check in a macro if the given argument has a '<tt/#/' as first token
+  (immidiate addressing mode), use something like this:
+
+    <tscreen><verb>
+  	.macro	ldax	arg
+    		...
+    		.if (.match (.mid (0, 1, {arg}), #))
+
+    		; ldax called with immidiate operand
+    		...
+
+    		.endif
+    		...
+       	.endmacro
+  </verb></tscreen>
+
+  See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT"
+  name=".RIGHT"></tt> builtin functions.
+
+
+<sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p>
+
+  Builtin function. The function expects an identifier as argument in braces.
+  The argument is evaluated, and the function yields "true" if the identifier
+  is a symbol that has already been referenced somewhere in the source file up
+  to the current position. Otherwise the function yields false. As an example,
+  the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by
+
+  <tscreen><verb>
+	.if	.referenced(a)
+  </verb></tscreen>
+
+  See: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
+
+
+<sect1><tt>.RIGHT</tt><label id=".RIGHT"><p>
+
+  Builtin function. Extracts the right part of a given token list.
+
+  Syntax:
+
+  <tscreen><verb>
+       	.RIGHT (&lt;int expr&gt;, &lt;token list&gt;)
+  </verb></tscreen>
+
+  The first integer expression gives the number of tokens to extract from the
+  token list. The second argument is the token list itself.  The token list
+  may optionally be enclosed into curly braces. This allows the inclusion of
+  tokens that would otherwise terminate the list (the closing right paren in
+  the given case).
+
+  See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID"
+  name=".MID"></tt> builtin functions.
+
+
+<sect1><tt>.SIZEOF</tt><label id=".SIZEOF"><p>
+
+  <tt/.SIZEOF/ is a pseudo function that returns the size of its argument. The
+  argument can be a struct/union, a struct member, a procedure, or a label. In
+  case of a procedure or label, its size is defined by the amount of data
+  placed in the segment where the label is relative to. If a line of code
+  switches segments (for example in a macro) data placed in other segments
+  does not count for the size.
+
+  Please note that a symbol or scope must exist, before it is used together with
+  <tt/.SIZEOF/ (this may get relaxed later, but will always be true for scopes).
+  A scope has preference over a symbol with the same name, so if the last part
+  of a name represents both, a scope and a symbol, the scope is choosen over the
+  symbol.
+
+  After the following code:
+
+  <tscreen><verb>
+        .struct Point                   ; Struct size = 4
+                xcoord  .word
+                xcoord  .word
+        .endstruct
+
+        P:      .tag    Point           ; Declare a point
+        @P:     .tag    Point           ; Declare another point
+
+        .code
+        .proc   Code
+                nop
+                .proc   Inner
+                        nop
+                .endproc
+                nop
+        .endproc
+
+        .proc   Data
+        .data                           ; Segment switch!!!
+                .res    4
+        .endproc
+  </verb></tscreen>
+
+  <descrip>
+    <tag><tt/.sizeof(Point)/</tag>
+    will have the value 4, because this is the size of struct <tt/Point/.
+
+    <tag><tt/.sizeof(Point::xcoord)/</tag>
+    will have the value 2, because this is the size of the member <tt/xcoord/
+    in struct <tt/Point/.
+
+    <tag><tt/.sizeof(P)/</tag>
+    will have the value 4, this is the size of the data declared on the same
+    source line as the label <tt/P/, which is in the same segment that <tt/P/
+    is relative to.
+
+    <tag><tt/.sizeof(@P)/</tag>
+    will have the value 4, see above. The example demonstrates that <tt/.SIZEOF/
+    does also work for cheap local symbols.
+
+    <tag><tt/.sizeof(Code)/</tag>
+    will have the value 3, since this is amount of data emitted into the code
+    segment, the segment that was active when <tt/Code/ was entered. Note that
+    this value includes the amount of data emitted in child scopes (in this
+    case <tt/Code::Inner/).
+
+    <tag><tt/.sizeof(Code::Inner)/</tag>
+    will have the value 1 as expected.
+
+    <tag><tt/.sizeof(Data)/</tag>
+    will have the value 0. Data is emitted within the scope <tt/Data/, but since
+    the segment is switched after entry, this data is emitted into another
+    segment.
+  </descrip>
+
+
+<sect1><tt>.STRAT</tt><label id=".STRAT"><p>
+
+  Builtin function. The function accepts a string and an index as
+  arguments and returns the value of the character at the given position
+  as an integer value. The index is zero based.
+
+  Example:
+
+  <tscreen><verb>
+       	.macro	M    	Arg
+		; Check if the argument string starts with '#'
+		.if (.strat (Arg, 0) = '#')
+		...
+		.endif
+       	.endmacro
+  </verb></tscreen>
+
+
+<sect1><tt>.STRING</tt><label id=".STRING"><p>
+
+  Builtin function. The function accepts an argument in braces and converts
+  this argument into a string constant. The argument may be an identifier, or
+  a constant numeric value.
+
+  Since you can use a string in the first place, the use of the function may
+  not be obvious. However, it is useful in macros, or more complex setups.
+
+  Example:
+
+  <tscreen><verb>
+       	; Emulate other assemblers:
+       	.macro	section	name
+       		.segment	.string(name)
+       	.endmacro
+  </verb></tscreen>
+
+
+<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p>
+
+  Builtin function. The function accepts a string argument in braces and
+  eveluates to the length of the string.
+
+  Example:
+
+  The following macro encodes a string as a pascal style string with
+  a leading length byte.
+
+  <tscreen><verb>
+       	.macro	PString	Arg
+		.byte	.strlen(Arg), Arg
+       	.endmacro
+  </verb></tscreen>
+
+
+<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p>
+
+  Builtin function. The function accepts a token list in braces. The function
+  result is the number of tokens given as argument. The token list may
+  optionally be enclosed into curly braces which are not considered part of
+  the list and not counted. Enclosement in curly braces allows the inclusion
+  of tokens that would otherwise terminate the list (the closing right paren
+  in the given case).
+
+  Example:
+
+  The <tt/ldax/ macro accepts the '#' token to denote immidiate addressing (as
+  with the normal 6502 instructions). To translate it into two separate 8 bit
+  load instructions, the '#' token has to get stripped from the argument:
 
   <tscreen><verb>
-      	.if	.const(a + 3)
+    	.macro	ldax	arg
+    	   	.if (.match (.mid (0, 1, {arg}), #))
+    	   	; ldax called with immidiate operand
+	   	lda	#<(.right (.tcount ({arg})-1, {arg}))
+	   	ldx	#>(.right (.tcount ({arg})-1, {arg}))
+	   	.else
+	   	...
+    	   	.endif
+       	.endmacro
+  </verb></tscreen>
+
+
+<sect1><tt>.XMATCH</tt><label id=".XMATCH"><p>
+
+  Builtin function. Matches two token lists against each other. This is
+  most useful within macros, since macros are not stored as strings, but
+  as lists of tokens.
+
+  The syntax is
+
+  <tscreen><verb>
+       	.XMATCH(&lt;token list #1&gt;, &lt;token list #2&gt;)
+  </verb></tscreen>
+
+  Both token list may contain arbitrary tokens with the exception of the
+  terminator token (comma resp. right parenthesis) and
+
+  <itemize>
+  <item>end-of-line
+  <item>end-of-file
+  </itemize>
+
+  The token lists may optionally be enclosed into curly braces. This allows
+  the inclusion of tokens that would otherwise terminate the list (the closing
+  right paren in the given case). Often a macro parameter is used for any of
+  the token lists.
+
+  The function compares tokens <em/and/ token values. If you need a function
+  that just compares the type of tokens, have a look at the <tt><ref
+  id=".MATCH" name=".MATCH"></tt> function.
+
+  See: <tt><ref id=".MATCH" name=".MATCH"></tt>
+
+
+
+<sect>Control commands<label id="control-commands"><p>
+
+Here's a list of all control commands and a description, what they do:
+
+
+<sect1><tt>.A16</tt><label id=".A16"><p>
+
+  Valid only in 65816 mode. Switch the accumulator to 16 bit.
+
+  Note: This command will not emit any code, it will tell the assembler to
+  create 16 bit operands for immediate accumulator adressing mode.
+
+  See also: <tt><ref id=".SMART" name=".SMART"></tt>
+
+
+<sect1><tt>.A8</tt><label id=".A8"><p>
+
+  Valid only in 65816 mode. Switch the accumulator to 8 bit.
+
+  Note: This command will not emit any code, it will tell the assembler to
+  create 8 bit operands for immediate accu adressing mode.
+
+  See also: <tt><ref id=".SMART" name=".SMART"></tt>
+
+
+<sect1><tt>.ADDR</tt><label id=".ADDR"><p>
+
+  Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and
+  may be used for better readability if the data words are address values. In
+  65816 mode, the address is forced to be 16 bit wide to fit into the current
+  segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command
+  must be followed by a sequence of (not necessarily constant) expressions.
+
+  Example:
+
+  <tscreen><verb>
+  	.addr  	$0D00, $AF13, _Clear
+  </verb></tscreen>
+
+  See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD"
+       name=".WORD"></tt>
+
+
+<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p>
+
+  Align data to a given boundary. The command expects a constant integer
+  argument that must be a power of two, plus an optional second argument
+  in byte range. If there is a second argument, it is used as fill value,
+  otherwise the value defined in the linker configuration file is used
+  (the default for this value is zero).
+
+  Since alignment depends on the base address of the module, you must
+  give the same (or a greater) alignment for the segment when linking.
+  The linker will give you a warning, if you don't do that.
+
+  Example:
+
+  <tscreen><verb>
+      	.align	256
+  </verb></tscreen>
+
+
+<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p>
+
+  Define a string with a trailing zero.
+
+  Example:
+
+  <tscreen><verb>
+  	Msg: 	.asciiz	"Hello world"
+  </verb></tscreen>
+
+  This will put the string "Hello world" followed by a binary zero into
+  the current segment. There may be more strings separated by commas, but
+  the binary zero is only appended once (after the last one).
+
+
+<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p>
+
+  Add an assertion. The command is followed by an expression, an action
+  specifier and a message that is output in case the assertion fails. The
+  action specifier may be one of <tt/warning/ or <tt/error/. The assertion
+  is passed to the linker and will be evaluated when segment placement has
+  been done.
+
+  Example:
+
+  <tscreen><verb>
+       	.assert         * = $8000, error, "Code not at $8000"
+  </verb></tscreen>
+
+  The example assertion will check that the current location is at $8000,
+  when the output file is written, and abort with an error if this is not
+  the case. More complex expressions are possible. The action specifier
+  <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs
+  an error message. In the latter case, generation if the output file is
+  suppressed.
+
+
+<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p>
+
+  Is followed by a plus or a minus character. When switched on (using a
+  +), undefined symbols are automatically marked as import instead of
+  giving errors. When switched off (which is the default so this does not
+  make much sense), this does not happen and an error message is
+  displayed. The state of the autoimport flag is evaluated when the
+  complete source was translated, before outputing actual code, so it is
+  <em/not/ possible to switch this feature on or off for separate sections
+  of code. The last setting is used for all symbols.
+
+  You should probably not use this switch because it delays error
+  messages about undefined symbols until the link stage. The cc65
+  compiler (which is supposed to produce correct assembler code in all
+  circumstances, something which is not true for most assembler
+  programmers) will insert this command to avoid importing each and every
+  routine from the runtime library.
+
+  Example:
+
+  <tscreen><verb>
+  	.autoimport    	+   	; Switch on auto import
+  </verb></tscreen>
+
+
+<sect1><tt>.BSS</tt><label id=".BSS"><p>
+
+  Switch to the BSS segment. The name of the BSS segment is always "BSS",
+  so this is a shortcut for
+
+  <tscreen><verb>
+  	.segment  "BSS"
+  </verb></tscreen>
+
+  See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
+
+
+<sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p>
+
+  Define byte sized data. Must be followed by a sequence of (byte ranged)
+  expressions or strings.
+
+  Example:
+
+  <tscreen><verb>
+  	.byte	"Hello "
+	.byt	"world", $0D, $00
+  </verb></tscreen>
+
+
+<sect1><tt>.CASE</tt><label id=".CASE"><p>
+
+  Switch on or off case sensitivity on identifiers. The default is off
+  (that is, identifiers are case sensitive), but may be changed by the
+  -i switch on the command line.
+  The command must be followed by a '+' or '-' character to switch the
+  option on or off respectively.
+
+  Example:
+
+  <tscreen><verb>
+       	.case	-   	    	; Identifiers are not case sensitive
+  </verb></tscreen>
+
+
+<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p>
+
+  Apply a custom mapping for characters. The command is followed by two
+  numbers in the range 1..255. The first one is the index of the source
+  character, the second one is the mapping. The mapping applies to all
+  character and string constants when they generate output, and overrides
+  a mapping table specified with the <tt><ref id="option-t" name="-t"></tt>
+  command line switch.
+
+  Example:
+
+  <tscreen><verb>
+       	.charmap        $41, $61        ; Map 'A' to 'a'
+  </verb></tscreen>
+
+
+<sect1><tt>.CODE</tt><label id=".CODE"><p>
+
+  Switch to the CODE segment. The name of the CODE segment is always
+  "CODE", so this is a shortcut for
+
+  <tscreen><verb>
+       	.segment  "CODE"
+  </verb></tscreen>
+
+  See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
+
+
+<sect1><tt>.CONDES</tt><label id=".CONDES"><p>
+
+  Export a symbol and mark it in a special way. The linker is able to build
+  tables of all such symbols. This may be used to automatically create a list
+  of functions needed to initialize linked library modules.
+
+  Note: The linker has a feature to build a table of marked routines, but it
+  is your code that must call these routines, so just declaring a symbol with
+  <tt/.CONDES/ does nothing by itself.
+
+  All symbols are exported as an absolute (16 bit) symbol. You don't need to
+  use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this
+  is implied by <tt/.CONDES/.
+
+  <tt/.CONDES/ is followed by the type, which may be <tt/constructor/,
+  <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as
+  specifiying <tt/constructor/ and 1 is equal to specifying <tt/destructor/).
+  The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
+  id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
+  name=".INTERRUPTORCONSTRUCTOR"></tt>commands are actually shortcuts
+  for <tt/.CONDES/ with a type of <tt/constructor/ resp. <tt/destructor/ or
+  <tt/interruptor/.
+
+  After the type, an optional priority may be specified. Higher numeric values
+  mean higher priority. If no priority is given, the default priority of 7 is
+  used. Be careful when assigning priorities to your own module constructors
+  so they won't interfere with the ones in the cc65 library.
+
+  Example:
+
+  <tscreen><verb>
+   	.condes	      	ModuleInit, constructor
+	.condes	      	ModInit, 0, 16
   </verb></tscreen>
 
+  See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
+  id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
+  name=".INTERRUPTOR"></tt>commands and the separate section <ref id="condes"
+  name="Module constructors/destructors"> explaining the feature in more
+  detail.
+
 
 <sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p>
 
@@ -901,9 +1822,10 @@ Here's a list of all control commands and a description, what they do:
   A constructor is always exported as an absolute (16 bit) symbol. You don't
   need to use an additional <tt/.export/ statement, this is implied by
   <tt/.constructor/. It may have an optional priority that is separated by a
-  comma. If no priority is given, the default priority of 7 is used. Be
-  careful when assigning priorities to your own module constructors so they
-  won't interfere with the ones in the cc65 library.
+  comma. Higher numeric values mean a higher priority. If no priority is
+  given, the default priority of 7 is used. Be careful when assigning
+  priorities to your own module constructors so they won't interfere with the
+  ones in the cc65 library.
 
   Example:
 
@@ -918,36 +1840,6 @@ Here's a list of all control commands and a description, what they do:
   feature in more detail.
 
 
-<sect1><tt>.CPU</tt><label id=".CPU"><p>
-
-  Reading this pseudo variable will give a constant integer value that
-  tells which instruction set is currently enabled. Possible values are:
-
-  <tscreen><verb>
-  	0 -->  	6502
-  	1 -->	65SC02
-  	2 -->	65SC816
-  	3 -->	SunPlus SPC
-  </verb></tscreen>
-
-  It may be used to replace the .IFPxx pseudo instructions or to construct
-  even more complex expressions.
-
-  Example:
-
-  <tscreen><verb>
-	.if	(.cpu = 0) .or (.cpu = 1)
-		txa
- 		pha
-		tya
-		pha
-	.else
-		phx
-		phy
-	.endif
-  </verb></tscreen>
-
-
 <sect1><tt>.DATA</tt><label id=".DATA"><p>
 
   Switch to the DATA segment. The name of the DATA segment is always
@@ -1030,9 +1922,10 @@ Here's a list of all control commands and a description, what they do:
   A destructor is always exported as an absolute (16 bit) symbol. You don't
   need to use an additional <tt/.export/ statement, this is implied by
   <tt/.destructor/. It may have an optional priority that is separated by a
-  comma. If no priority is given, the default priority of 7 is used. Be
-  careful when assigning priorities to your own module destructors so they
-  won't interfere with the ones in the cc65 library.
+  comma. Higher numerical values mean a higher priority. If no priority is
+  given, the default priority of 7 is used. Be careful when assigning
+  priorities to your own module destructors so they won't interfere with the
+  ones in the cc65 library.
 
   Example:
 
@@ -1075,6 +1968,11 @@ Here's a list of all control commands and a description, what they do:
   is read from an include file.
 
 
+<sect1><tt>.ENDENUM</tt><label id=".ENDENUM"><p>
+
+  End a <tt><ref id=".ENUM" name=".ENUM"></tt> declaration.
+
+
 <sect1><tt>.ENDIF</tt><label id=".ENDIF"><p>
 
   Conditional assembly: Close a <tt><ref id=".IF" name=".IF..."></tt> or
@@ -1096,6 +1994,78 @@ Here's a list of all control commands and a description, what they do:
   End a <tt><ref id=".REPEAT" name=".REPEAT"></tt> block.
 
 
+<sect1><tt>.ENDSCOPE</tt><label id=".ENDSCOPE"><p>
+
+  End of local lexical level (see <tt/<ref id=".SCOPE" name=".SCOPE">/).
+
+
+<sect1><tt>.ENDSTRUCT</tt><label id=".ENDSTRUCT"><p>
+
+  Ends a struct definition. See the <tt/<ref id=".STRUCT" name=".STRUCT">/
+  command and the separate section named <ref id="structs" name="&quot;Structs
+  and unions&quot;">.
+
+
+<sect1><tt>.ENUM</tt><label id=".ENUM"><p>
+
+  Start an enumeration. This directive is very similar to the C <tt/enum/
+  keyword. If a name is given, a new scope is created for the enumeration,
+  otherwise the enumeration members are placed in the enclosing scope.
+
+  In the enumeration body, symbols are declared. The first symbol has a value
+  of zero, and each following symbol will get the value of the preceeding plus
+  one. This behaviour may be overriden by an explicit assignment. Two symbols
+  may have the same value.
+
+  Example:
+
+  <tscreen><verb>
+        .enum   errorcodes
+                no_error
+                file_error
+                parse_error
+        .endenum
+  </verb></tscreen>
+
+  Above example will create a new scope named <tt/errorcodes/ with three
+  symbols in it that get the values 0, 1 and 2 respectively. Another way
+  to write this would have been:
+
+  <tscreen><verb>
+        .scope  errorcodes
+                no_error        = 0
+                file_error      = 1
+                parse_error     = 2
+        .endscope
+  </verb></tscreen>
+
+  Please note that explicit scoping must be used to access the identifiers:
+
+  <tscreen><verb>
+        .word   errorcodes::no_error
+  </verb></tscreen>
+
+  A more complex example:
+
+  <tscreen><verb>
+        .enum
+                EUNKNOWN        = -1
+                EOK
+                EFILE
+                EBUSY
+                EAGAIN
+                EWOULDBLOCK     = EAGAIN
+        .endenum
+  </verb></tscreen>
+
+  In this example, the enumeration does not have a name, which means that the
+  members will be visible in the enclosing scope and can be used in this scope
+  without explicit scoping. The first member (<tt/EUNKNOWN/) has the value -1.
+  The value for the following members is incremented by one, so <tt/EOK/ would
+  be zero and so on. <tt/EWOULDBLOCK/ is an alias for <tt/EGAIN/, so it has an
+  override for the value using an already defined symbol.
+
+
 <sect1><tt>.ERROR</tt><label id=".ERROR"><p>
 
   Force an assembly error. The assembler will output an error message
@@ -1129,12 +2099,17 @@ Here's a list of all control commands and a description, what they do:
 <sect1><tt>.EXPORT</tt><label id=".EXPORT"><p>
 
   Make symbols accessible from other modules. Must be followed by a comma
-  separated list of symbols to export.
+  separated list of symbols to export, with each one optionally followed by
+  an address specification. The default is to export the symbol with the
+  address size it actually has. The assembler will issue a warning, if the
+  symbol is exported with an address size smaller than the actual address
+  size.
 
   Example:
 
   <tscreen><verb>
-	.export	foo, bar
+	.export	foo
+        .export bar: far
   </verb></tscreen>
 
   See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt>
@@ -1187,6 +2162,18 @@ Here's a list of all control commands and a description, what they do:
 
   <descrip>
 
+  <tag><tt>at_in_identifiers</tt></tag>
+
+    Accept the at character (`@') as a valid character in identifiers. The
+    at character is not allowed to start an identifier, even with this
+    feature enabled.
+
+  <tag><tt>dollar_in_identifiers</tt></tag>
+
+    Accept the dollar sign (`&dollar;') as a valid character in identifiers. The
+    at character is not allowed to start an identifier, even with this
+    feature enabled.
+
   <tag><tt>dollar_is_pc</tt></tag>
 
     The dollar sign may be used as an alias for the star (`*'), which
@@ -1198,36 +2185,34 @@ Here's a list of all control commands and a description, what they do:
     Allow labels without a trailing colon. These labels are only accepted,
     if they start at the beginning of a line (no leading white space).
 
-  <tag><tt>loose_string_term</tt></tag>
+  <tag><tt>leading_dot_in_identifiers</tt></tag>
 
-    Accept single quotes as well as double quotes as terminators for string
-    constants.
+    Accept the dot (`.') as the first character of an identifier. This may be
+    used for example to create macro names that start with a dot emulating
+    control directives of other assemblers. Note however, that none of the
+    reserved keywords built into the assembler, that starts with a dot, may be
+    overridden. When using this feature, you may also get into trouble if
+    later versions of the assembler define new keywords starting with a dot.
 
   <tag><tt>loose_char_term</tt></tag>
 
     Accept single quotes as well as double quotes as terminators for char
     constants.
 
-  <tag><tt>at_in_identifiers</tt></tag>
-
-    Accept the at character (`@') as a valid character in identifiers. The
-    at character is not allowed to start an identifier, even with this
-    feature enabled.
-
-  <tag><tt>dollar_in_identifiers</tt></tag>
+  <tag><tt>loose_string_term</tt></tag>
 
-    Accept the dollar sign (`&dollar;') as a valid character in identifiers. The
-    at character is not allowed to start an identifier, even with this
-    feature enabled.
+    Accept single quotes as well as double quotes as terminators for string
+    constants.
 
-  <tag><tt>leading_dot_in_identifiers</tt></tag>
+  <tag><tt>missing_char_term</tt></tag>
 
-    Accept the dot (`.') as the first character of an identifier. This may be
-    used for example to create macro names that start with a dot emulating
-    control directives of other assemblers. Note however, that none of the
-    reserved keywords built into the assembler, that starts with a dot, may be
-    overridden. When using this feature, you may also get into trouble if
-    later versions of the assembler define new keywords starting with a dot.
+    Accept single quoted character constants where the terminating quote is
+    missing.
+    <tscreen><verb>
+        lda     #'a
+    </verb></tscreen>
+    <bf/Note:/ This does not work in conjunction with <tt/.FEATURE
+    loose_string_term/, since in this case the input would be ambigous.
 
   <tag><tt>pc_assignment</tt></tag>
 
@@ -1237,6 +2222,13 @@ Here's a list of all control commands and a description, what they do:
     removing the lines with the assignments may also be an option when porting
     code written for older assemblers).
 
+  <tag><tt>ubiquitous_idents</tt></tag>
+
+    Allow the use of instructions names as names for macros and symbols. This
+    makes it possible to "overload" instructions by defining a macro with the
+    same name. This does also make it possible to introduce hard to find errors
+    in your code, so be careful!
+
   </descrip>
 
   It is also possible to specify features on the command line using the
@@ -1478,6 +2470,12 @@ Here's a list of all control commands and a description, what they do:
   (see <tt><ref id=".PC02" name=".PC02"></tt> command).
 
 
+<sect1><tt>.IFPSC02</tt><label id=".IFPSC02"><p>
+
+  Conditional assembly: Check if the assembler is currently in 65SC02 mode
+  (see <tt><ref id=".PSC02" name=".PSC02"></tt> command).
+
+
 <sect1><tt>.IFREF</tt><label id=".IFREF"><p>
 
   Conditional assembly: Check if a symbol is referenced. Must be followed
@@ -1503,12 +2501,14 @@ Here's a list of all control commands and a description, what they do:
 <sect1><tt>.IMPORT</tt><label id=".IMPORT"><p>
 
   Import a symbol from another module. The command is followed by a comma
-  separated list of symbols to import.
+  separated list of symbols to import, with each one optionally followed by
+  an address specification.
 
   Example:
 
   <tscreen><verb>
-   	.import	foo, bar
+   	.import	foo
+        .import bar: zeropage
   </verb></tscreen>
 
   See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt>
@@ -1536,7 +2536,7 @@ Here's a list of all control commands and a description, what they do:
   In addition to that, a start offset and a size value may be specified,
   separated by commas. If no size is specified, all of the file from the
   start offset to end-of-file is used. If no start position is specified
-  either, zero is assume (which means that the whole file is inserted).
+  either, zero is assumed (which means that the whole file is inserted).
 
   Example:
 
@@ -1563,39 +2563,34 @@ Here's a list of all control commands and a description, what they do:
   </verb></tscreen>
 
 
-<sect1><tt>.LEFT</tt><label id=".LEFT"><p>
-
-  Builtin function. Extracts the left part of a given token list.
+<sect1><tt>.INTERRUPTOR</tt><label id=".INTERRUPTOR"><p>
 
-  Syntax:
+  Export a symbol and mark it as an interruptor. This may be used together
+  with the linker to build a table of interruptor subroutines that are called
+  in an interrupt.
 
-  <tscreen><verb>
-       	.LEFT (&lt;int expr&gt;, &lt;token list&gt;)
-  </verb></tscreen>
+  Note: The linker has a feature to build a table of marked routines, but it
+  is your code that must call these routines, so just declaring a symbol as
+  interruptor does nothing by itself.
 
-  The first integer expression gives the number of tokens to extract from
-  the token list. The second argument is the token list itself.
+  An interruptor is always exported as an absolute (16 bit) symbol. You don't
+  need to use an additional <tt/.export/ statement, this is implied by
+  <tt/.interruptor/. It may have an optional priority that is separated by a
+  comma. Higher numeric values mean a higher priority. If no priority is
+  given, the default priority of 7 is used. Be careful when assigning
+  priorities to your own module constructors so they won't interfere with the
+  ones in the cc65 library.
 
   Example:
 
-  To check in a macro if the given argument has a '#' as first token
-  (immidiate addressing mode), use something like this:
-
   <tscreen><verb>
-    	.macro 	ldax	arg
-    	       	...
-    	       	.if (.match (.left (1, arg), #))
-
-    	       	; ldax called with immidiate operand
-    	       	...
-
-    	       	.endif
-    	       	...
-       	.endmacro
+   	.interruptor    IrqHandler
+	.interruptor    Handler, 16
   </verb></tscreen>
 
-  See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT"
-  name=".RIGHT"></tt> builtin functions.
+  See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate
+  section <ref id="condes" name="Module constructors/destructors"> explaining
+  the feature in more detail.
 
 
 <sect1><tt>.LINECONT</tt><label id=".LINECONT"><p>
@@ -1707,6 +2702,8 @@ Here's a list of all control commands and a description, what they do:
   <tscreen><verb>
 	generic		Defines generic macros like add and sub.
     	longbranch     	Defines conditional long jump macros.
+        cbm             Defines the scrcode macro
+        cpu             Defines constants for the .CPU variable
   </verb></tscreen>
 
   Including a macro package twice, or including a macro package that
@@ -1734,99 +2731,6 @@ Here's a list of all control commands and a description, what they do:
   See section <ref id="macros" name="Macros">.
 
 
-<sect1><tt>.MATCH</tt><label id=".MATCH"><p>
-
-  Builtin function. Matches two token lists against each other. This is
-  most useful within macros, since macros are not stored as strings, but
-  as lists of tokens.
-
-  The syntax is
-
-  <tscreen><verb>
-       	.MATCH(&lt;token list #1&gt;, &lt;token list #2&gt;)
-  </verb></tscreen>
-
-  Both token list may contain arbitrary tokens with the exception of the
-  terminator token (comma resp. right parenthesis) and
-
-  <itemize>
-  <item>end-of-line
-  <item>end-of-file
-  </itemize>
-
-  Often a macro parameter is used for any of the token lists.
-
-  Please note that the function does only compare tokens, not token
-  attributes. So any number is equal to any other number, regardless of the
-  actual value. The same is true for strings. If you need to compare tokens
-  <em/and/ token attributes, use the <tt><ref id=".XMATCH"
-  name=".XMATCH"></tt> function.
-
-  Example:
-
-  Assume the macro <tt/ASR/, that will shift right the accumulator by one,
-  while honoring the sign bit. The builtin processor instructions will allow
-  an optional "A" for accu addressing for instructions like <tt/ROL/ and
-  <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function
-  to check for this and print and error for invalid calls.
-
-  <tscreen><verb>
-  	.macro	asr 	arg
-
-       	       	.if (.not .blank(arg)) .and (.not .match (arg, a))
-    	    	.error "Syntax error"
-    	    	.endif
-
-    	    	cmp 	#$80		; Bit 7 into carry
-    	    	lsr 	a		; Shift carry into bit 7
-
-    	.endmacro
-  </verb></tscreen>
-
-  The macro will only accept no arguments, or one argument that must be the
-  reserved keyword "A".
-
-  See: <tt><ref id=".XMATCH" name=".XMATCH"></tt>
-
-
-<sect1><tt>.MID</tt><label id=".MID"><p>
-
-  Builtin function. Takes a starting index, a count and a token list as
-  arguments. Will return part of the token list.
-
-  Syntax:
-
-  <tscreen><verb>
-       	.MID (&lt;int expr&gt;, &lt;int expr&gt;, &lt;token list&gt;)
-  </verb></tscreen>
-
-  The first integer expression gives the starting token in the list (the
-  first token has index 0). The second integer expression gives the number
-  of tokens to extract from the token list. The third argument is the
-  token list itself.
-
-  Example:
-
-  To check in a macro if the given argument has a '<tt/#/' as first token
-  (immidiate addressing mode), use something like this:
-
-    <tscreen><verb>
-  	.macro	ldax	arg
-    		...
-    		.if (.match (.mid (0, 1, arg), #))
-
-    		; ldax called with immidiate operand
-    		...
-
-    		.endif
-    		...
-       	.endmacro
-  </verb></tscreen>
-
-  See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT"
-  name=".RIGHT"></tt> builtin functions.
-
-
 <sect1><tt>.ORG</tt><label id=".ORG"><p>
 
   Start a section of absolute code. The command is followed by a constant
@@ -1865,21 +2769,21 @@ Here's a list of all control commands and a description, what they do:
 
 <sect1><tt>.P02</tt><label id=".P02"><p>
 
-  Enable the 6502 instruction set, disable 65C02 and 65816 instructions.
-  This is the default if not overridden by the <tt/--cpu/ command line
-  option.
+  Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816
+  instructions. This is the default if not overridden by the
+  <tt><ref id="option--cpu" name="--cpu"></tt> command line option.
 
-  See: <tt><ref id=".PC02" name=".PC02"></tt> and <tt><ref id=".P816"
-  name=".P816"></tt>
+  See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02"
+  name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
 
 
 <sect1><tt>.P816</tt><label id=".P816"><p>
 
-  Enable the 65816 instruction set. This is a superset of the 65C02 and
+  Enable the 65816 instruction set. This is a superset of the 65SC02 and
   6502 instruction sets.
 
-  See: <tt><ref id=".P02" name=".P02"></tt> and <tt><ref id=".PC02"
-  name=".PC02"></tt>
+  See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
+  name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt>
 
 
 <sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p>
@@ -1901,32 +2805,13 @@ Here's a list of all control commands and a description, what they do:
   </verb></tscreen>
 
 
-<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p>
-
-  This builtin pseudo variable is only available in macros. It is replaced by
-  the actual number of parameters that were given in the macro invocation.
-
-  Example:
-
-  <tscreen><verb>
-	.macro	foo	arg1, arg2, arg3
-	.if	.paramcount <> 3
-   	.error	"Too few parameters for macro foo"
-	.endif
-	...
- 	.endmacro
-  </verb></tscreen>
-
-  See section <ref id="macros" name="Macros">.
-
-
 <sect1><tt>.PC02</tt><label id=".PC02"><p>
 
   Enable the 65C02 instructions set. This instruction set includes all
-  6502 instructions.
+  6502 and 65SC02 instructions.
 
-  See: <tt><ref id=".P02" name=".P02"></tt> and <tt><ref id=".P816"
-  name=".P816"></tt>
+  See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
+  name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
 
 
 <sect1><tt>.POPSEG</tt><label id=".POPSEG"><p>
@@ -1945,17 +2830,16 @@ Here's a list of all control commands and a description, what they do:
 
 <sect1><tt>.PROC</tt><label id=".PROC"><p>
 
-  Start a nested lexical level. All new symbols from now on are in the local
-  lexical level and are not accessible from outside. Symbols defined outside
-  this local level may be accessed as long as their names are not used for new
-  symbols inside the level. Symbols names in other lexical levels do not
-  clash, so you may use the same names for identifiers. The lexical level ends
-  when the <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read.
-  Lexical levels may be nested up to a depth of 16.
-
-  The command may be followed by an identifier, in this case the
-  identifier is declared in the outer level as a label having the value of
-  the program counter at the start of the lexical level.
+  Start a nested lexical level with the given name and adds a symbol with this
+  name to the enclosing scope. All new symbols from now on are in the local
+  lexical level and are accessible from outside only via <ref id="scopesyntax"
+  name="explicit scope specification">. Symbols defined outside this local
+  level may be accessed as long as their names are not used for new symbols
+  inside the level. Symbols names in other lexical levels do not clash, so you
+  may use the same names for identifiers. The lexical level ends when the
+  <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read. Lexical levels
+  may be nested up to a depth of 16 (this is an artificial limit to protect
+  against errors in the source).
 
   Note: Macro names are always in the global level and in a separate name
   space. There is no special reason for this, it's just that I've never
@@ -1972,10 +2856,20 @@ Here's a list of all control commands and a description, what they do:
       		dey
       		bne	L1    	; Reference local symbol
       		rts
-      	.endproc	      	; Leave lexical level
+      	.endproc  	      	; Leave lexical level
   </verb></tscreen>
 
-  See: <tt><ref id=".ENDPROC" name=".ENDPROC"></tt>
+  See: <tt/<ref id=".ENDPROC" name=".ENDPROC">/ and <tt/<ref id=".SCOPE"
+  name=".SCOPE">/
+
+
+<sect1><tt>.PSC02</tt><label id=".PSC02"><p>
+
+  Enable the 65SC02 instructions set. This instruction set includes all
+  6502 instructions.
+
+  See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02"
+  name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
 
 
 <sect1><tt>.PUSHSEG</tt><label id=".PUSHSEG"><p>
@@ -1986,27 +2880,12 @@ Here's a list of all control commands and a description, what they do:
 
   <tt/.PUSHSEG/ allows together with <tt><ref id=".POPSEG" name=".POPSEG"></tt>
   to switch to another segment and to restore the old segment later, without
-  even knowing the name and type of the current segment.
-
-  The assembler will print an error message if the segment stack is already
-  full, when this command is issued.
-
-  See: <tt><ref id=".POPSEG" name=".POPSEG"></tt>
-
-
-<sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p>
-
-  Builtin function. The function expects an identifier as argument in braces.
-  The argument is evaluated, and the function yields "true" if the identifier
-  is a symbol that has already been referenced somewhere in the source file up
-  to the current position. Otherwise the function yields false. As an example,
-  the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by
+  even knowing the name and type of the current segment.
 
-  <tscreen><verb>
-	.if	.referenced(a)
-  </verb></tscreen>
+  The assembler will print an error message if the segment stack is already
+  full, when this command is issued.
 
-  See: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
+  See: <tt><ref id=".POPSEG" name=".POPSEG"></tt>
 
 
 <sect1><tt>.REPEAT</tt><label id=".REPEAT"><p>
@@ -2031,7 +2910,7 @@ Here's a list of all control commands and a description, what they do:
   <tscreen><verb>
 	.macro	Crypt  	Arg
 		.repeat	.strlen(Arg), I
-		.byte  	.strat(Arg, I) .xor $55
+		.byte  	.strat(Arg, I) ^ $55
 		.endrep
 	.endmacro
   </verb></tscreen>
@@ -2058,26 +2937,9 @@ Here's a list of all control commands and a description, what they do:
 
   <tscreen><verb>
 	; Reserve 12 bytes of memory with value $AA
-  	.res	12, $AA
-  </verb></tscreen>
-
-
-<sect1><tt>.RIGHT</tt><label id=".RIGHT"><p>
-
-  Builtin function. Extracts the right part of a given token list.
-
-  Syntax:
-
-  <tscreen><verb>
-       	.RIGHT (&lt;int expr&gt;, &lt;token list&gt;)
+     	.res	12, $AA
   </verb></tscreen>
 
-  The first integer expression gives the number of tokens to extract from
-  the token list. The second argument is the token list itself.
-
-  See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID"
-  name=".MID"></tt> builtin functions.
-
 
 <sect1><tt>.RODATA</tt><label id=".RODATA"><p>
 
@@ -2094,6 +2956,39 @@ Here's a list of all control commands and a description, what they do:
   See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
 
 
+<sect1><tt>.SCOPE</tt><label id=".SCOPE"><p>
+
+  Start a nested lexical level with the given name. All new symbols from now
+  on are in the local lexical level and are accessible from outside only via
+  <ref id="scopesyntax" name="explicit scope specification">. Symbols defined
+  outside this local level may be accessed as long as their names are not used
+  for new symbols inside the level. Symbols names in other lexical levels do
+  not clash, so you may use the same names for identifiers. The lexical level
+  ends when the <tt><ref id=".ENDSCOPE" name=".ENDSCOPE"></tt> command is
+  read. Lexical levels may be nested up to a depth of 16 (this is an
+  artificial limit to protect against errors in the source).
+
+  Note: Macro names are always in the global level and in a separate name
+  space. There is no special reason for this, it's just that I've never
+  had any need for local macro definitions.
+
+  Example:
+
+  <tscreen><verb>
+       	.scope  Error                   ; Start new scope named Error
+                None = 0                ; No error
+                File = 1                ; File error
+                Parse = 2               ; Parse error
+      	.endproc  	      	        ; Close lexical level
+
+                ...
+                lda #Error::File        ; Use symbol from scope Error
+  </verb></tscreen>
+
+  See: <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/ and <tt/<ref id=".PROC"
+  name=".PROC">/
+
+
 <sect1><tt>.SEGMENT</tt><label id=".SEGMENT"><p>
 
   Switch to another segment. Code and data is always emitted into a
@@ -2102,33 +2997,35 @@ Here's a list of all control commands and a description, what they do:
   (and up to 65534 per executable). There are shortcut commands for
   the most common segments ("CODE", "DATA" and "BSS").
 
-  The command is followed by a string containing the segment name (there
-  are some constraints for the name - as a rule of thumb use only those
-  segment names that would also be valid identifiers). There may also be
-  an optional attribute separated by a comma. Valid attributes are
-  "<tt/zeropage/" and "<tt/absolute/".
+  The command is followed by a string containing the segment name (there are
+  some constraints for the name - as a rule of thumb use only those segment
+  names that would also be valid identifiers). There may also be an optional
+  address size separated by a colon. See the section covering <tt/<ref
+  id="address-sizes" name="address sizes">/ for more information.
 
-  When specifying a segment for the first time, "absolute" is the
-  default. For all other uses, the attribute specified the first time
-  is the default.
+  The default address size for a segment depends on the memory model specified
+  on the command line. The default is "absolute", which means that you don't
+  have to use an address size modifier in most cases.
 
-  "absolute" means that this is a segment with absolute addressing. That
-  is, the segment will reside somewhere in core memory outside the zero
-  page. "zeropage" means the opposite: The segment will be placed in the
-  zero page and direct (short) addressing is possible for data in this
-  segment.
+  "absolute" means that the is a segment with 16 bit (absolute) addressing.
+  That is, the segment will reside somewhere in core memory outside the zero
+  page. "zeropage" (8 bit) means that the segment will be placed in the zero
+  page and direct (short) addressing is possible for data in this segment.
 
   Beware: Only labels in a segment with the zeropage attribute are marked
   as reachable by short addressing. The `*' (PC counter) operator will
   work as in other segments and will create absolute variable values.
 
-  Example:
+  Please note that a segment cannot have two different address sizes. A
+  segment specified as zeropage cannot be declared as being absolute later.
+
+  Examples:
 
   <tscreen><verb>
        	.segment "ROM2"			; Switch to ROM2 segment
-	.segment "ZP2", zeropage	; New direct segment
- 	.segment "ZP2"			; Ok, will use last attribute
-	.segment "ZP2", absolute	; Error, redecl mismatch
+	.segment "ZP2": zeropage	; New direct segment
+ 	.segment "ZP2" 			; Ok, will use last attribute
+	.segment "ZP2": absolute	; Error, redecl mismatch
   </verb></tscreen>
 
   See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE"
@@ -2136,6 +3033,27 @@ Here's a list of all control commands and a description, what they do:
   id=".RODATA" name=".RODATA"></tt>
 
 
+<sect1><tt>.SETCPU</tt><label id=".SETCPU"><p>
+
+  Switch the CPU instruction set. The command is followed by a string that
+  specifies the CPU. Possible values are those that can also be supplied to
+  the <tt><ref id="option--cpu" name="--cpu"></tt> command line option,
+  namely: 6502, 6502X, 65SC02, 65C02, 65816 and sunplus. Please note that
+  support for the sunplus CPU is not available in the freeware version,
+  because the instruction set of the sunplus CPU is "proprietary and
+  confidential".
+
+  See: <tt><ref id=".CPU" name=".CPU"></tt>,
+       <tt><ref id=".IFP02" name=".IFP02"></tt>,
+       <tt><ref id=".IFP816" name=".IFP816"></tt>,
+       <tt><ref id=".IFPC02" name=".IFPC02"></tt>,
+       <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>,
+       <tt><ref id=".P02" name=".P02"></tt>,
+       <tt><ref id=".P816" name=".P816"></tt>,
+       <tt><ref id=".PC02" name=".PC02"></tt>,
+       <tt><ref id=".PSC02" name=".PSC02"></tt>
+
+
 <sect1><tt>.SMART</tt><label id=".SMART"><p>
 
   Switch on or off smart mode. The command must be followed by a '+' or
@@ -2143,13 +3061,21 @@ Here's a list of all control commands and a description, what they do:
   is off (that is, the assembler doesn't try to be smart), but this
   default may be changed by the -s switch on the command line.
 
-  In smart mode the assembler will track usage of the <tt/REP/ and <tt/SEP/
-  instructions in 65816 mode and update the operand sizes accordingly. If
-  the operand of such an instruction cannot be evaluated by the assembler
-  (for example, because the operand is an imported symbol), a warning is
-  issued. Beware: Since the assembler cannot trace the execution flow this
-  may lead to false results in some cases. If in doubt, use the <tt/.Inn/ and
-  <tt/.Ann/ instructions to tell the assembler about the current settings.
+  In smart mode the assembler will do the following:
+
+  <itemize>
+  <item>Track usage of the <tt/REP/ and <tt/SEP/ instructions in 65816 mode
+        and update the operand sizes accordingly. If the operand of such an
+        instruction cannot be evaluated by the assembler (for example, because
+        the operand is an imported symbol), a warning is issued. Beware: Since
+        the assembler cannot trace the execution flow this may lead to false
+        results in some cases. If in doubt, use the <tt/.Inn/ and <tt/.Ann/
+        instructions to tell the assembler about the current settings.
+  <item>In 65816 mode, replace a <tt/RTS/ instruction by <tt/RTL/ if it is
+        used within a procedure declared as <tt/far/, or if the procedure has
+        no explicit address specification, but it is <tt/far/ because of the
+        memory model used.
+  </itemize>
 
   Example:
 
@@ -2158,98 +3084,45 @@ Here's a list of all control commands and a description, what they do:
 	.smart	-			; Stop being smart
   </verb></tscreen>
 
+  See: <tt><ref id=".A16" name=".A16"></tt>,
+       <tt><ref id=".A8" name=".A8"></tt>,
+       <tt><ref id=".I16" name=".I16"></tt>,
+       <tt><ref id=".I8" name=".I8"></tt>
 
-<sect1><tt>.STRAT</tt><label id=".STRAT"><p>
-
-  Builtin function. The function accepts a string and an index as
-  arguments and returns the value of the character at the given position
-  as an integer value. The index is zero based.
-
-  Example:
-
-  <tscreen><verb>
-       	.macro	M    	Arg
-		; Check if the argument string starts with '#'
-		.if (.strat (Arg, 0) = '#')
-		...
-		.endif
-       	.endmacro
-  </verb></tscreen>
-
-
-<sect1><tt>.STRING</tt><label id=".STRING"><p>
-
-  Builtin function. The function accepts an argument in braces and converts
-  this argument into a string constant. The argument may be an identifier, or
-  a constant numeric value.
-
-  Since you can use a string in the first place, the use of the function may
-  not be obvious. However, it is useful in macros, or more complex setups.
-
-  Example:
 
-  <tscreen><verb>
-       	; Emulate other assemblers:
-       	.macro	section	name
-       		.segment	.string(name)
-       	.endmacro
-  </verb></tscreen>
+<sect1><tt>.STRUCT</tt><label id=".STRUCT"><p>
 
+  Starts a struct definition. Structs are covered in a separate section named
+  <ref id="structs" name="&quot;Structs and unions&quot;">.
 
-<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p>
+  See: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>
 
-  Builtin function. The function accepts a string argument in braces and
-  eveluates to the length of the string.
 
-  Example:
+<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p>
 
-  The following macro encodes a string as a pascal style string with
-  a leading length byte.
+  Enable the SunPlus instructions set. This command will not work in the
+  freeware version of the assembler, because the instruction set is
+  "proprietary and confidential".
 
-  <tscreen><verb>
-       	.macro	PString	Arg
-		.byte	.strlen(Arg), Arg
-       	.endmacro
-  </verb></tscreen>
+  See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
+  name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and
+  <tt><ref id=".P816" name=".P816"></tt>
 
 
-<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p>
+<sect1><tt>.TAG</tt><label id=".TAG"><p>
 
-  Builtin function. The function accepts a token list in braces. The
-  function result is the number of tokens given as argument.
+  Allocate space for a struct or union.
 
   Example:
 
-  The <tt/ldax/ macro accepts the '#' token to denote immidiate addressing (as
-  with the normal 6502 instructions). To translate it into two separate 8 bit
-  load instructions, the '#' token has to get stripped from the argument:
-
   <tscreen><verb>
-    	.macro	ldax	arg
-    	   	.if (.match (.mid (0, 1, arg), #))
-    	   	; ldax called with immidiate operand
-	   	lda	#<(.right (.tcount (arg)-1, arg))
-	   	ldx	#>(.right (.tcount (arg)-1, arg))
-	   	.else
-	   	...
-    	   	.endif
-       	.endmacro
-  </verb></tscreen>
-
-
-<sect1><tt>.TIME</tt><label id=".TIME"><p>
-
-  Reading this pseudo variable will give a constant integer value that
-  represents the current time in POSIX standard (as seconds since the
-  Epoch).
+        .struct Point
+                xcoord  .word
+                ycoord  .word
+        .endstruct
 
-  It may be used to encode the time of translation somewhere in the created
-  code.
-
-  Example:
-
-  <tscreen><verb>
-        .dword  .time   ; Place time here
+        .bss
+                .tag    Point           ; Allocate 4 bytes
   </verb></tscreen>
 
 
@@ -2295,35 +3168,6 @@ Here's a list of all control commands and a description, what they do:
   </verb></tscreen>
 
 
-<sect1><tt>.XMATCH</tt><label id=".XMATCH"><p>
-
-  Builtin function. Matches two token lists against each other. This is
-  most useful within macros, since macros are not stored as strings, but
-  as lists of tokens.
-
-  The syntax is
-
-  <tscreen><verb>
-       	.XMATCH(&lt;token list #1&gt;, &lt;token list #2&gt;)
-  </verb></tscreen>
-
-  Both token list may contain arbitrary tokens with the exception of the
-  terminator token (comma resp. right parenthesis) and
-
-  <itemize>
-  <item>end-of-line
-  <item>end-of-file
-  </itemize>
-
-  Often a macro parameter is used for any of the token lists.
-
-  The function compares tokens <em/and/ token values. If you need a function
-  that just compares the type of tokens, have a look at the <tt><ref
-  id=".MATCH" name=".MATCH"></tt> function.
-
-  See: <tt><ref id=".MATCH" name=".MATCH"></tt>
-
-
 <sect1><tt>.ZEROPAGE</tt><label id=".ZEROPAGE"><p>
 
   Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment.
@@ -2467,6 +3311,67 @@ parameters:
   	ldaxy	1,2,3  	       	; .PARAMCOUNT = 3
 </verb></tscreen>
 
+Macro parameters may optionally be enclosed into curly braces. This allows the
+inclusion of tokens that would otherwise terminate the parameter (the comma in
+case of a macro parameter).
+
+<tscreen><verb>
+        .macro  foo     arg1, arg2
+                ...
+        .endmacro
+
+                foo     ($00,x)         ; Two parameters passed
+                foo     {($00,x)}       ; One parameter passed
+</verb></tscreen>
+
+In the first case, the macro is called with two parameters: '<tt/(&dollar;00/'
+and 'x)'. The comma is not passed to the macro, since it is part of the
+calling sequence, not the parameters.
+
+In the second case, '(&dollar;00,x)' is passed to the macro, this time
+including the comma.
+
+
+<sect1>Detecting parameter types<p>
+
+Sometimes it is nice to write a macro that acts differently depending on the
+type of the argument supplied. An example would be a macro that loads a 16 bit
+value from either an immediate operand, or from memory. The <tt/<ref
+id=".MATCH" name=".MATCH">/ and <tt/<ref id=".XMATCH" name=".XMATCH">/
+functions will allow you to do exactly this:
+
+<tscreen><verb>
+        .macro  ldax    arg
+                .if (.match (.left (1, {arg}), #))
+                    ; immediate mode
+                    lda     #<(.right (.tcount ({arg})-1, {arg}))
+                    ldx     #>(.right (.tcount ({arg})-1, {arg}))
+                .else
+                    ; assume absolute or zero page
+                    lda     arg
+                    ldx     1+(arg)
+                .endif
+        .endmacro
+</verb></tscreen>
+
+Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to
+check if its argument begins with a hash mark. If so, two immediate loads are
+emitted, Otherwise a load from an absolute zero page memory location is
+assumed. Please note how the curly braces are used to enclose parameters to
+pseudo functions handling token lists. This is necessary, because the token
+lists may include commas or parens, which would be treated by the assembler
+as end-of-list.
+
+The macro can be used as
+
+<tscreen><verb>
+        foo:    .word   $5678
+        ...
+                ldax    #$1234          ; X=$12, A=$34
+        ...
+                ldax    foo             ; X=$56, A=$78
+</verb></tscreen>
+
 
 <sect1>Recursive macros<p>
 
@@ -2733,6 +3638,166 @@ The package defines the following macros:
 
 
 
+<sect1><tt>.MACPACK cbm</tt><p>
+
+The cbm macro package will define a macro named <tt/scrcode/. It takes a
+string as argument and places this string into memory translated into screen
+codes.
+
+
+<sect1><tt>.MACPACK cpu</tt><p>
+
+This macro package does not define any macros but constants used to examine
+the value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable. For
+each supported CPU a constant similar to
+
+<tscreen><verb>
+    CPU_6502
+    CPU_65SC02
+    CPU_65C02
+    CPU_65816
+    CPU_SUNPLUS
+    CPU_SWEET16
+</verb></tscreen>
+
+is defined. These constants may be used to determine the exact type of the
+currently enabled CPU. In addition to that, for each CPU instruction set,
+another constant is defined:
+
+<tscreen><verb>
+    CPU_ISET_6502
+    CPU_ISET_65SC02
+    CPU_ISET_65C02
+    CPU_ISET_65816
+    CPU_ISET_SUNPLUS
+    CPU_ISET_SWEET16
+</verb></tscreen>
+
+The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may
+be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the
+currently enabled CPU supports a specific instruction set. For example the
+65C02 supports all instructions of the 65SC02 CPU, so it has the
+<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/
+bit. Using
+
+<tscreen><verb>
+        .if (.cpu .bitand CPU_ISET_65SC02)
+                lda     (sp)
+        .else
+                ldy     #$00
+                lda     (sp),y
+        .endif
+</verb></tscreen>
+
+it is possible to determine if the
+
+<tscreen><verb>
+                lda     (sp)
+</verb></tscreen>
+
+instruction is supported, which is the case for the 65SC02, 65C02 and 65816
+CPUs (the latter two are upwards compatible to the 65SC02).
+
+
+
+<sect>Predefined constants<label id="predefined-constants"><p>
+
+For better orthogonality, the assembler defines similar symbols as the
+compiler, depending on the target system selected:
+
+<itemize>
+<item><tt/__ACE__/ - Target system is <tt/ace/
+<item><tt/__APPLE2__",/ - Target system is <tt/apple2/
+<item><tt/__APPLE2ENH__",/ - Target system is <tt/apple2enh/
+<item><tt/__ATARI__/ - Target system is <tt/atari/
+<item><tt/__ATMOS__",/ - Target system is <tt/atmos/
+<item><tt/__BBC__",/ - Target system is <tt/bbc/
+<item><tt/__C128__/ - Target system is <tt/c128/
+<item><tt/__C16__/ - Target system is <tt/c16/
+<item><tt/__C64__/ - Target system is <tt/c64/
+<item><tt/__CBM__/ - Target is a Commodore system
+<item><tt/__CBM510__/ - Target system is <tt/cbm510/
+<item><tt/__CBM610__/ - Target system is <tt/cbm610/
+<item><tt/__GEOS__",/ - Target system is <tt/geos/
+<item><tt/__LUNIX__",/ - Target system is <tt/lunix/
+<item><tt/__NES__",/ - Target system is <tt/nes/
+<item><tt/__PET__/ - Target system is <tt/pet/
+<item><tt/__PLUS4__/ - Target system is <tt/plus4/
+<item><tt/__SUPERVISION__",/ - Target system is <tt/supervision/
+<item><tt/__VIC20__/ - Target system is <tt/vic20/
+</itemize>
+
+
+<sect>Structs and unions<label id="structs"><p>
+
+Structs and unions are special forms of <ref id="scopes" name="scopes">.  They
+are to some degree comparable to their C counterparts. Both have a list of
+members. Each member allocates storage and may optionally have a name, which,
+in case of a struct, is the offset from the beginning and, in case of a union,
+is always zero.
+
+Here is an example for a very simple struct with two members and a total size
+of 4 bytes:
+
+<tscreen><verb>
+      .struct Point
+              xcoord  .word
+              ycoord  .word
+      .endstruct
+</verb></tscreen>
+
+A union shares the total space between all its members, its size is the same
+as that of the largest member.
+
+A struct or union must not necessarily have a name. If it is anonymous, no
+local scope is opened, the identifiers used to name the members are placed
+into the current scope instead.
+
+A struct may contain unnamed members and definitions of local structs. The
+storage allocators may contain a multiplier, as in the example below:
+
+<tscreen><verb>
+      .struct Circle
+              .struct Point
+                      .word   2         ; Allocate two words
+              .endstruct
+              Radius  .word
+      .endstruct
+</verb></tscreen>
+
+Using the <ref id=".TAG" name=".TAG"> keyword, it is possible to embedd
+already defined structs or unions in structs:
+
+<tscreen><verb>
+      .struct Point
+              xcoord  .word
+              ycoord  .word
+      .endstruct
+
+      .struct Circle
+              Origin  .tag    Point
+              Radius  .byte
+      .endstruct
+</verb></tscreen>
+
+Space for a struct or union may be allocated using the <ref id=".TAG"
+name=".TAG"> directive.
+
+<tscreen><verb>
+        C:      .tag    Circle
+</verb></tscreen>
+
+Currently, members are just offsets from the start of the struct or union. To
+access a field of a struct, the member offset has to be added to the address
+of the struct itself:
+
+<tscreen><verb>
+        lda     C+Circle::Radius        ; Load circle radius into A
+</verb></tscreen>
+
+This may change in a future version of the assembler.
+
+
 <sect>Module constructors/destructors<label id="condes"><p>
 
 <em>Note:</em> This section applies mostly to C programs, so the explanation
@@ -2740,14 +3805,16 @@ below uses examples from the C libraries. However, the feature may also be
 useful for assembler programs.
 
 
-<sect1>Module overview<p>
+<sect1>Overview<p>
 
-Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
-id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> keywords it it possible to export
-functions in a special way. The linker is able to generate tables with all
-functions of a specific type. Such a table will <em>only</em> include symbols
-from object files that are linked into a specific executable. This may be used
-to add initialization and cleanup code for library modules.
+Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
+id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
+name=".INTERRUPTOR"></tt>keywords it it possible to export functions in a
+special way. The linker is able to generate tables with all functions of a
+specific type. Such a table will <em>only</em> include symbols from object
+files that are linked into a specific executable. This may be used to add
+initialization and cleanup code for library modules, or a table of interrupt
+handler functions.
 
 The C heap functions are an example where module initialization code is used.
 All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few
@@ -2786,10 +3853,22 @@ two bytes in the table (a pointer to the function).
 </enum>
 
 
+<sect1>Calling order<p>
+
+The symbols are sorted in increasing priority order by the linker when using
+one of the builtin linker configurations, so the functions with lower
+priorities come first and are followed by those with higher priorities. The C
+library runtime subroutine that walks over the function tables calls the
+functions starting from the top of the table - which means that functions with
+a high priority are called first.
+
+So when using the C runtime, functions are called with high priority functions
+first, followed by low priority functions.
+
+
 <sect1>Pitfalls<p>
 
-When creating and using module constructors and destructors, please take care
-of the following:
+When using these special symbols, please take care of the following:
 
 <itemize>
 
@@ -2797,14 +3876,14 @@ of the following:
 The linker will only generate function tables, it will not generate code to
 call these functions. If you're using the feature in some other than the
 existing C environments, you have to write code to call all functions in a
-linker generated table yourself. See the <tt>condes</tt> module in the C
-runtime for an example on how to do this.
+linker generated table yourself. See the <tt/condes/ and <tt/callirq/ modules
+in the C runtime for an example on how to do this.
 
 <item>
 The linker will only add addresses of functions that are in modules linked to
 the executable. This means that you have to be careful where to place the
-condes functions. If initialization is needed for a group of functions, be
-sure to place the initialization function into a module that is linked in
+condes functions. If initialization or an irq handler is needed for a group of
+functions, be sure to place the function into a module that is linked in
 regardless of which function is called by the user.
 
 <item>
@@ -2819,16 +3898,100 @@ does depend on other initialization or cleanup code, you have to choose the
 priority for the functions accordingly.
 
 <item>
-Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> and <tt><ref
-id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> statements, there is also a more
-generic command: <tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to
-specify an additional type. Predefined types are 0 (constructor) and 1
-(destructor). The linker generates a separate table for each type on request.
+Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
+id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
+name=".INTERRUPTOR"></tt>statements, there is also a more generic command:
+<tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to specify an
+additional type. Predefined types are 0 (constructor), 1 (destructor) and 2
+(interruptor). The linker generates a separate table for each type on request.
 
 </itemize>
 
 
+<sect>Porting sources from other assemblers<p>
 
+Sometimes it is necessary to port code written for older assemblers to ca65.
+In some cases, this can be done without any changes to the source code by
+using the emulation features of ca65 (see <tt><ref id=".FEATURE"
+name=".FEATURE"></tt>). In other cases, it is necessary to make changes to the
+source code.
+
+Probably the biggest difference is the handling of the <tt><ref id=".ORG"
+name=".ORG"></tt> directive. ca65 generates relocatable code, and placement is
+done by the linker. Most other assemblers generate absolute code, placement is
+done within the assembler and there is no external linker.
+
+In general it is not a good idea to write new code using the emulation
+features of the assembler, but there may be situations where even this rule is
+not valid.
+
+<sect1>TASS<p>
+
+You need to use some of the ca65 emulation features to simulate the behaviour
+of such simple assemblers.
+
+<enum>
+<item>Prepare your sourcecode like this:
+
+<tscreen><verb>
+        ; if you want TASS style labels without colons
+        .feature labels_without_colons
+
+        ; if you want TASS style character constants
+        ; ("a" instead of the default 'a')
+        .feature loose_char_term
+
+                .word *+2       ; the cbm load address
+
+                [yourcode here]
+</verb></tscreen>
+
+notice that the two emulation features are mostly useful for porting
+sources originally written in/for TASS, they are not needed for the
+actual "simple assembler operation" and are not recommended if you are
+writing new code from scratch.
+
+<item>Replace all program counter assignments (which are not possible in ca65
+by default, and the respective emulation feature works different from what
+you'd expect) by another way to skip to another memory location, for example
+the <tt><ref id=".RES" name=".RES"></tt>directive.
+
+<tscreen><verb>
+        ; *=$2000
+        .res $2000-*    ; reserve memory up to $2000
+</verb></tscreen>
+
+notice that other than the original TASS, ca65 can never move the
+programmcounter backwards - think of it as if you are assembling to disc with
+TASS.
+
+<item>Conditional assembly (<tt/.ifeq//<tt/.endif//<tt/.goto/ etc.) must be
+rewritten to match ca65 syntax. Most importantly notice that due to the lack
+of <tt/.goto/, everything involving loops must be replaced by
+<tt><ref id=".REPEAT" name=".REPEAT"></tt>.
+
+<item>To assemble code to a different address than it is executed at, use the
+<tt><ref id=".ORG" name=".ORG"></tt> directive instead of
+<tt/.offs/-constructs.
+
+<tscreen><verb>
+        .org $1800
+
+        [floppy code here]
+
+        .reloc  ; back to normal
+</verb></tscreen>
+
+<item>Then assemble like this:
+
+<tscreen><verb>
+        cl65 --start-addr 0x0ffe -t none myprog.s -o myprog.prg
+</verb></tscreen>
+
+notice that you need to use the actual start address minus two, since two
+bytes are used for the cbm load address.
+
+</enum>
 
 
 <sect>Bugs/Feedback<p>
@@ -2842,7 +4005,7 @@ hear from you. Feel free to contact me by email
 
 <sect>Copyright<p>
 
-ca65 (and all cc65 binutils) are (C) Copyright 1998-2001 Ullrich von
+ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von
 Bassewitz. For usage of the binaries and/or sources the following
 conditions do apply: