From 9b96998e76b65eb622c2986e3056898b0d06e196 Mon Sep 17 00:00:00 2001
From: cuz <cuz@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Tue, 20 Apr 2004 12:54:21 +0000
Subject: [PATCH] Document the new ubiquitous_idents feature

git-svn-id: svn://svn.cc65.org/cc65/trunk@2982 b7a2c559-68d2-44c3-8de9-860c34a00d81
---
 doc/ca65.sgml | 150 +++++++++++++++++++++++++++++++++++---------------
 1 file changed, 105 insertions(+), 45 deletions(-)

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 72679f323..2437f9759 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -909,7 +909,58 @@ if you want to access the "other" symbol <tt/bar/, you would have to write:
 </verb></tscreen>
 
 
-<sect>Address sizes<label id="address-sizes"><p>
+<sect>Address sizes and memory models<label id="address-sizes"><p>
+
+<sect1>Address sizes<p>
+
+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.
+
+Possible address sizes are:
+
+<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:
+
+<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>
+
+
+<sect1>Address sizes of segments<p>
+
+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>Address sizes of symbols<p>
+
+
+
+
+<sect1>Memory models<p>
+
+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.
+
 
 
 
@@ -2025,27 +2076,6 @@ Here's a list of all control commands and a description, what they do:
 
   <descrip>
 
-  <tag><tt>dollar_is_pc</tt></tag>
-
-    The dollar sign may be used as an alias for the star (`*'), which
-    gives the value of the current PC in expressions.
-    Note: Assignment to the pseudo variable is not allowed.
-
-  <tag><tt>labels_without_colons</tt></tag>
-
-    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>
-
-    Accept single quotes as well as double quotes as terminators for string
-    constants.
-
-  <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
@@ -2058,6 +2088,17 @@ Here's a list of all control commands and a description, what they do:
     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
+    gives the value of the current PC in expressions.
+    Note: Assignment to the pseudo variable is not allowed.
+
+  <tag><tt>labels_without_colons</tt></tag>
+
+    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>leading_dot_in_identifiers</tt></tag>
 
     Accept the dot (`.') as the first character of an identifier. This may be
@@ -2067,13 +2108,15 @@ Here's a list of all control commands and a description, what they do:
     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>pc_assignment</tt></tag>
+  <tag><tt>loose_char_term</tt></tag>
 
-    Allow assignments to the PC symbol (`*' or `&dollar;' if <tt/dollar_is_pc/
-    is enabled). Such an assignment is handled identical to the <tt><ref
-    id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just
-    removing the lines with the assignments may also be an option when porting
-    code written for older assemblers).
+    Accept single quotes as well as double quotes as terminators for char
+    constants.
+
+  <tag><tt>loose_string_term</tt></tag>
+
+    Accept single quotes as well as double quotes as terminators for string
+    constants.
 
   <tag><tt>missing_char_term</tt></tag>
 
@@ -2085,6 +2128,21 @@ Here's a list of all control commands and a description, what they do:
     <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>
+
+    Allow assignments to the PC symbol (`*' or `&dollar;' if <tt/dollar_is_pc/
+    is enabled). Such an assignment is handled identical to the <tt><ref
+    id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just
+    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
@@ -2823,33 +2881,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"
-- 
2.39.5