From 7006e5d1f2da8752e31f4b4ea4faf985a75e7b01 Mon Sep 17 00:00:00 2001
From: cuz <cuz@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Sun, 7 Mar 2004 22:02:45 +0000
Subject: [PATCH] Documented the new push/pop factility for #pragmas.

git-svn-id: svn://svn.cc65.org/cc65/trunk@2903 b7a2c559-68d2-44c3-8de9-860c34a00d81
---
 doc/cc65.sgml | 38 +++++++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/doc/cc65.sgml b/doc/cc65.sgml
index d574a3dd0..e939de852 100644
--- a/doc/cc65.sgml
+++ b/doc/cc65.sgml
@@ -196,7 +196,10 @@ Here is a description of all the command line options:
   switch: <tt/-Or/ will enable both, the optmizer and register variables.
 
   For more information about register variables see <ref id="regvars"
-  name="register variables">.
+  name="register variables">. 
+
+  The compiler setting can also be changed within the source file by using
+  <tt><ref id="pragma-regvars" name="#pragma regvars"></tt>.
 
 
   <tag><tt>--register-space</tt></tag>
@@ -649,8 +652,10 @@ The compiler defines several macros at startup:
 <sect>#pragmas<label id="pragmas"><p>
 
 The compiler understands some pragmas that may be used to change code
-generation and other stuff.
-
+generation and other stuff. Some of these pragmas understand a special form:
+If the first parameter is <tt/push/, the old value is saved onto a stack
+before changing it. The value may later be restored by using the <tt/pop/
+parameter with the <tt/#pragma/.
 
 <sect1><tt>#pragma bssseg (&lt;name&gt;)</tt><p>
 
@@ -706,8 +711,7 @@ generation and other stuff.
   </verb></tscreen>
 
 
-<sect1><tt>#pragma checkstack (on|off)</tt><label
-id="pragma-checkstack"><p>
+<sect1><tt>#pragma checkstack (on|off)</tt><label id="pragma-checkstack"><p>
 
   Tells the compiler to insert calls to a stack checking subroutine to detect
   stack overflows. The stack checking code will lead to somewhat larger and
@@ -718,6 +722,7 @@ id="pragma-checkstack"><p>
   If the argument is "off", stack checks are disabled (the default), otherwise
   they're enabled.
 
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
 
 <sect1><tt>#pragma codeseg (&lt;name&gt;)</tt><p>
 
@@ -767,7 +772,7 @@ id="pragma-checkstack"><p>
   </verb></tscreen>
 
 
-<sect1><tt>#pragma regvaraddr (on|off)</tt><p>
+<sect1><tt>#pragma regvaraddr ([push,]on|off)</tt><p>
 
   The compiler does not allow to take the address of register variables.
   The regvaraddr pragma changes this. Taking the address of a register
@@ -781,14 +786,26 @@ id="pragma-checkstack"><p>
   and this subroutine (or a subroutine called from there) uses itself
   register variables. So be careful with this #pragma.
 
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
+
   Example:
   <tscreen><verb>
-       	#pragma regvaraddr(1)  	/* Allow taking the address
+       	#pragma regvaraddr(on) 	/* Allow taking the address
        		      	       	 * of register variables
        		      	       	 */
   </verb></tscreen>
 
 
+<sect1><tt>#pragma regvars ([push,]on|off)</tt><label id="pragma-regvars"><p>
+
+  Enables or disables use of register variables. If register variables are
+  disabled (the default), the <tt/register/ keyword is ignored. Register
+  variables are explained in more detail in <ref id="regvars" name="a separate
+  chapter">.
+
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
+
+
 <sect1><tt>#pragma signedchars (on|off)</tt><label id="pragma-signedchars"><p>
 
   Changes the signedness of the default character type. If the argument is
@@ -797,15 +814,18 @@ id="pragma-checkstack"><p>
   lot better code. This default may be overridden by the <tt/--signed-chars/
   command line option.
 
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
 
-<sect1><tt>#pragma staticlocals (on|off)</tt><label
-id="pragma-staticlocals"<p>
+
+<sect1><tt>#pragma staticlocals (on|off)</tt><label id="pragma-staticlocals"<p>
 
   Use variables in the bss segment instead of variables on the stack. This
   pragma changes the default set by the compiler option <tt/-Cl/. If the
   argument is "on", local variables are allocated in the BSS segment,
   leading to shorter and in most cases faster, but non-reentrant code.
 
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
+
 
 <sect1><tt>#pragma zpsym (&lt;name&gt;)</tt><p>
 
-- 
2.39.5