diff doc/manual.docbook.sgml @ 396:62cb50c50976

Cosmetic updates to documentation; added warning pseudo op
author lost@l-w.ca
date Fri, 23 Jul 2010 17:08:57 -0600
parents ed3553296580
children 0324fd09c7ac
line wrap: on
line diff
--- a/doc/manual.docbook.sgml	Fri Jul 23 16:40:51 2010 -0600
+++ b/doc/manual.docbook.sgml	Fri Jul 23 17:08:57 2010 -0600
@@ -3,7 +3,7 @@
 <bookinfo>
 <title>LW Tool Chain</title>
 <author><firstname>William</firstname><surname>Astle</surname></author>
-<copyright><year>2009</year><holder>William Astle</holder></copyright>
+<copyright><year>2009, 2010</year><holder>William Astle</holder></copyright>
 </bookinfo>
 <chapter>
 
@@ -443,7 +443,7 @@
 <para>
 By default, unless assembling to the os9 target, a "$" in the symbol will
 also make it local.  This can be controlled by the "dollarlocal" and
-"nodollarlocal" pragmas.  In the absence of a pragma to the contrary, For
+"nodollarlocal" pragmas.  In the absence of a pragma to the contrary, for
 the os9 target, a "$" in the symbol will not make it considered local while
 for all other targets it will.
 </para>
@@ -760,8 +760,16 @@
 </para>
 <para>Conditional expressions are only evaluated on the first assembly pass.
 It is not possible to game the assembly process by having a conditional
-change its value between assembly passes. Thus there is not and never will
-be any equivalent of IFP1 or IFP2 as provided by other assemblers.</para>
+change its value between assembly passes. Due to the underlying architecture
+of LWASM, there is no possible utility to IFP1 and IFP2, nor can they, as of LWASM 3.0, actually
+be implemented meaningfully. Thus there is not and never will
+be any equivalent of IFP1 or IFP2 as provided by other assemblers. Use of those opcodes
+will throw a warning and be ignored.</para>
+
+<para>It is important to note that if a conditional does not resolve to a constant
+during the first parsing pass, an error will be thrown. This is unavoidable because the assembler
+must make a decision about which source to include and which source to exclude at this stage.
+Thus, expressions that work normally elsewhere will not work for conditions.</para>
 
 <variablelist>
 <varlistentry>
@@ -941,6 +949,15 @@
 Note that the USE variation is provided only for compatibility with other
 assemblers. It is recommended to use the INCLUDE variation.</para>
 
+<para>If <parameter>filename</parameter> begins with a &quot;/&quot;, it is
+interpreted as an absolute path. If it does not, the search path will be used
+to find the file. First, the directory containing the file that contains this
+directive. (Includes within an included file are relative to the included file,
+not the file that included it.) If the file is not found there, the include path
+is searched. If it is still not found, an error will be thrown. Note that the
+current directory as understood by your shell or operating system is not searched.
+</para>
+
 </listitem>
 </varlistentry>
 
@@ -962,7 +979,21 @@
 <para>
 Causes a custom error message to be printed at this line. This will cause
 assembly to fail. This directive is most useful inside conditional constructs
-to cause assembly to fail if some condition that is known bad happens.
+to cause assembly to fail if some condition that is known bad happens. Everything
+from the directive to the end of the line is considered the error message.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>WARNING <parameter>string</parameter></term>
+<listitem>
+<para>
+Causes a custom warning message to be printed at this line. This will not cause
+assembly to fail. This directive is most useful inside conditional constructs
+or include files to alert the programmer to a deprecated feature being used
+or some other condition that may cause trouble later, but which may, in fact,
+not cause any trouble.
 </para>
 </listitem>
 </varlistentry>
@@ -976,7 +1007,7 @@
 will be used as the module name.
 </para>
 <para>
-As of version 2.2, no supported output targets support this directive.
+As of version 3.0, no supported output targets support this directive.
 </para>
 </listitem>
 </varlistentry>
@@ -1320,7 +1351,7 @@
 </varlistentry>
 
 <varlistentry>
-<term><parameter>sym</parameter>EXTDEP</term>
+<term><parameter>sym</parameter> EXTDEP</term>
 <listitem>
 
 <para>This directive forces an external dependency on