Produce error when ".opt +o" or ".opt ~o" is encountered. Also, small doc additions

[rmac] / docs / rmac.rst

diff --git a/docs/rmac.rst b/docs/rmac.rst
index a562e85ff139a8fb2efaaf5b4db69380de8a313b..24110c46eb220330d3104d49a1356e26b5d2eb12 100644 (file)
--- a/docs/rmac.rst
+++ b/docs/rmac.rst
@@ -4,7 +4,7 @@ RMAC
 =====================
 Reference Manual
 ================
-version 2.0.18
+version 2.0.21
 ==============
 
 © and notes
@@ -154,8 +154,8 @@ Switch               Description
 
                       -o\ *file[.o]*       Direct object code output to the specified file.
 +/~oall              Turn all optimisations on/off
-+o\ *0-9*            Enable specific optimisation
-~o\ *0-9*            Disable specific optimisation
++o\ *0-10*/*p*       Enable specific optimisation
+~o\ *0-10*/*p*       Disable specific optimisation
 
                       `0: Absolute long adddresses to word (on by default)`
                       
@@ -177,7 +177,7 @@ Switch               Description
 
                       `9: Convert adda.w/l #x,Dy to lea x(Dy),Dy`
 
-                      'p: Enforce PC relative'
+                      `p: Force PC-Relative mode (alternative: o10)`
 -p                   Produce an executable (**.prg**) output file.
 -ps                  Produce an executable (**.prg**) output file with symbols.
 -px                  Produce an executable (**.prg**) output file with extended symbols.
@@ -404,7 +404,7 @@ necessary to make other assemblers' source code assemble.
   **ifne**, **ifeq** (etc.), and **endc**.
 * The tilde (~) character is an operator, and back-quote (`) is an illegal character.
   AS68 permitted the tilde and back-quote characters in symbols.
-* There are no equivalents to org or section directives.
+* There are no equivalents to org or section directives apart from .text, .data, .bss.
   The **.xdef** and **.xref** directives are not implemented,
   but **.globl** makes these unnecessary anyway.
 
@@ -414,6 +414,8 @@ necessary to make other assemblers' source code assemble.
 
                                 * = expression
 
+  Exceptions to this rule are when outputting a binary using the **-fr** switch,
+  6502 mode, and Jaguar GPU/DSP.
 * Back-slashes in strings are "electric" characters that are used to escape C-like
   character codes. Watch out for GEMDOS path names in ASCII constants -
   you will have to convert them to double-backslashes.
@@ -422,7 +424,7 @@ necessary to make other assemblers' source code assemble.
 * Mark your segments across files.
   Branching to a code segment that could be identified as BSS will cause a "Error: cannot initialize non-storage (BSS) section"
 * In 68020+ mode **Zan** and **Zri** (register suppression) is not supported.
-* rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using abs.
+* rs.b/rs.w/rs.l/rscount/rsreset can be simulated in rmac using **.abs**.
   For example the following source:
 
    ::
@@ -803,7 +805,7 @@ Operator                            Description
 **~**                               Tilde: bitwise not (l's complement).
 **^^defined** *symbol*              True if symbol has a value.
 **^^referenced** *symbol*           True if symbol has been referenced.
-**^^streq** *stringl*,*string2*     True if the strings are equal.
+**^^streq** *stringl*, *string2*    True if the strings are equal.
 **^^macdef** *macroName*            True if the macro is defined.
 **^^abscount**                      Returns the size of current .abs section
 **^^filesize** *string_filename*    Returns the file size of supplied filename
@@ -942,6 +944,29 @@ described in the chapter on `6502 Support`_.
    Therefore, to align GPU/DSP code, align the current section before and
    after the GPU/DSP code.
 
+**.print**
+   This directive is similar to the standard ‘C’ library printf() function
+   and is used to print user messages from the assembly process. You can
+   print any string or valid expression. Several format flags that can be used
+   to format your output are also supported.
+
+          ::
+
+           /x hexadecimal
+           /d signed decimal
+           /u unsigned decimal
+           /w word
+           /l long
+
+   For example:
+
+          ::
+
+           MASK .equ $FFF8
+           VALUE .equ -100000
+            .print “Mask: $”,/x/w MASK
+            .print “Value: “,/d/l VALUE
+
 **.phrase**
 
    Align the program counter to the next integral phrase boundary (8 bytes).
@@ -1207,6 +1232,17 @@ described in the chapter on `6502 Support`_.
                bne   .1               ; (no -- try again)
                rts                    ; return string length
 
+**.error** ["*string*"]
+
+  Aborts the build, optionally printing a user defined string. Can be useful
+  inside conditional assembly blocks in order to catch errors. For example:
+
+        ::
+
+         .if ^^defined JAGUAR
+           .error "TOS cannot be built on Jaguar, don't be silly"
+         .endif
+
 **.end**
 
    End the assembly. In an include file, end the include file and resume assembling
@@ -2088,7 +2124,7 @@ indicates that the assembler could not determine which file had the problem.
 The following sections list warnings, errors and fatal errors in alphabetical
 order, along with a short description of what may have caused the problem.
 
-.. [3] If you come across an internal error, we would appreciate it if you would contact Atari Technical Support and let us know about the problem.
+.. [3] If you come across an internal error, we would appreciate it if you would contact the rmac development team and let us know about the problem.
 
 `Warnings`_
 '''''''''''
@@ -2406,13 +2442,13 @@ order, along with a short description of what may have caused the problem.
 
 **unknown symbol following ^^**
 
-  You followed a ^^ with something other than one of the names defined, ref-
-  erenced or streq.
+  You followed a ^^ with something other than one of the names defined, referenced
+  or streq.
 
 **unsupported 68020 addressing mode**
 
-  The assembler saw a 68020-type addressing mode. RMAC does not assem-
-  ble code for the 68020 or 68010.
+  The assembler saw a 68020-type addressing mode. RMAC does not assemble
+  code for the 68020 or 68010.
 
 **unterminated string**