From 255392eb15860bf7959e000207d3524bd5c60e68 Mon Sep 17 00:00:00 2001
From: cuz <cuz@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Tue, 15 Jun 2004 21:20:34 +0000
Subject: [PATCH] Document the codesize, optimize and warn pragmas

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

diff --git a/doc/cc65.sgml b/doc/cc65.sgml
index e5345b5b8..73f0ec321 100644
--- a/doc/cc65.sgml
+++ b/doc/cc65.sgml
@@ -133,12 +133,13 @@ Here is a description of all the command line options:
   Set the name of the code segment.
 
 
+  <label id="option-codesize">
   <tag><tt>--codesize x</tt></tag>
 
-  This options allows finer control about speed vs. size decisions in the
-  code generation phase. It gives the allowed size increase factor (in
-  percent). The default is 100 when not using <tt/-Oi/ and 200 when using
-  <tt/-Oi/ (<tt/-Oi/ is the same as <tt/--codesize 200/).
+  This options allows finer control about speed vs. size decisions in the code
+  generation and optimization phases. It gives the allowed size increase
+  factor (in percent). The default is 100 when not using <tt/-Oi/ and 200 when
+  using <tt/-Oi/ (<tt/-Oi/ is the same as <tt/--codesize 200/).
 
 
   <tag><tt>--cpu CPU</tt></tag>
@@ -315,6 +316,7 @@ Here is a description of all the command line options:
   search list.
 
 
+  <label id="option-O">
   <tag><tt>-O, -Oi, -Or, -Os</tt></tag>
 
   Enable an optimizer run over the produced code.
@@ -364,6 +366,7 @@ Here is a description of all the command line options:
   version.
 
 
+  <label id="option-W">
   <tag><tt>-W</tt></tag>
 
   This option will suppress any warnings generated by the compiler. Since
@@ -732,7 +735,7 @@ parameter with the <tt/#pragma/.
   </verb></tscreen>
 
 
-<sect1><tt>#pragma checkstack (on|off)</tt><label id="pragma-checkstack"><p>
+<sect1><tt>#pragma checkstack ([push,]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
@@ -745,7 +748,7 @@ parameter with the <tt/#pragma/.
 
   The <tt/#pragma/ understands the push and pop parameters as explained above.
 
-<sect1><tt>#pragma codeseg (&lt;name&gt;)</tt><p>
+<sect1><tt>#pragma codeseg ([push,]&lt;name&gt;)</tt><p>
 
   This pragma changes the name used for the CODE segment (the CODE segment
   is used to store executable code). The argument is a string enclosed in
@@ -763,7 +766,17 @@ parameter with the <tt/#pragma/.
   </verb></tscreen>
 
 
-<sect1><tt>#pragma dataseg (&lt;name&gt;)</tt><p>
+<sect1><tt>#pragma codesize ([push,]&lt;int&gt;)</tt><label id="pragma-codesize"><p>
+
+  This pragma allows finer control about speed vs. size decisions in the code
+  generation and optimization phase. It gives the allowed size increase factor
+  (in percent). The default is can be changed by use of the <tt/<ref
+  id="option-codesize" name="--codesize">/ compiler option.
+
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
+
+
+<sect1><tt>#pragma dataseg ([push,]&lt;name&gt;)</tt><p>
 
   This pragma changes the name used for the DATA segment (the DATA segment
   is used to store initialized data). The argument is a string enclosed in
@@ -781,7 +794,23 @@ parameter with the <tt/#pragma/.
   </verb></tscreen>
 
 
-<sect1><tt>#pragma rodataseg (&lt;name&gt;)</tt><p>
+<sect1><tt>#pragma optimize ([push,]on|off)</tt><label id="pragma-optimize"><p>
+
+  Switch optimization on or off. If the argument is "off", optimization is
+  disabled, otherwise it is enabled. Please note that this pragma only effects
+  whole functions. The setting in effect when the function is encountered will
+  determine if the generated code is optimized or not.
+
+  Optimization and code generation is also controlled by the <ref
+  id="pragma-codesize" name="codesize pragma">.
+
+  The default is "off", but may be changed with the <tt/<ref name="-O"
+  id="option-O">/ compiler option.
+
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
+
+
+<sect1><tt>#pragma rodataseg ([push,]&lt;name&gt;)</tt><p>
 
   This pragma changes the name used for the RODATA segment (the RODATA
   segment is used to store readonly data). The argument is a string
@@ -833,7 +862,7 @@ parameter with the <tt/#pragma/.
   The <tt/#pragma/ understands the push and pop parameters as explained above.
 
 
-<sect1><tt>#pragma signedchars (on|off)</tt><label id="pragma-signedchars"><p>
+<sect1><tt>#pragma signedchars ([push,]on|off)</tt><label id="pragma-signedchars"><p>
 
   Changes the signedness of the default character type. If the argument is
   "on", default characters are signed, otherwise characters are unsigned.
@@ -844,7 +873,7 @@ parameter with the <tt/#pragma/.
   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 ([push,]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
@@ -854,6 +883,15 @@ parameter with the <tt/#pragma/.
   The <tt/#pragma/ understands the push and pop parameters as explained above.
 
 
+<sect1><tt>#pragma warn ([push,]on|off)</tt><label id="pragma-warn"><p>
+
+  Switch compiler warnings on or off. If the argument is "off", warnings are
+  disabled, otherwise they're enabled. The default is "on", but may be changed
+  with the <tt/<ref name="-W" id="option-W">/ compiler option.
+
+  The <tt/#pragma/ understands the push and pop parameters as explained above.
+
+
 <sect1><tt>#pragma zpsym (&lt;name&gt;)</tt><p>
 
   Tell the compiler that the - previously as external declared - symbol with
-- 
2.39.5