Mercurial > hg-old > index.cgi
comparison 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 |
comparison
equal
deleted
inserted
replaced
395:54499b799779 | 396:62cb50c50976 |
---|---|
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"> | 1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"> |
2 <book> | 2 <book> |
3 <bookinfo> | 3 <bookinfo> |
4 <title>LW Tool Chain</title> | 4 <title>LW Tool Chain</title> |
5 <author><firstname>William</firstname><surname>Astle</surname></author> | 5 <author><firstname>William</firstname><surname>Astle</surname></author> |
6 <copyright><year>2009</year><holder>William Astle</holder></copyright> | 6 <copyright><year>2009, 2010</year><holder>William Astle</holder></copyright> |
7 </bookinfo> | 7 </bookinfo> |
8 <chapter> | 8 <chapter> |
9 | 9 |
10 <title>Introduction</title> | 10 <title>Introduction</title> |
11 | 11 |
441 </para> | 441 </para> |
442 | 442 |
443 <para> | 443 <para> |
444 By default, unless assembling to the os9 target, a "$" in the symbol will | 444 By default, unless assembling to the os9 target, a "$" in the symbol will |
445 also make it local. This can be controlled by the "dollarlocal" and | 445 also make it local. This can be controlled by the "dollarlocal" and |
446 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, For | 446 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, for |
447 the os9 target, a "$" in the symbol will not make it considered local while | 447 the os9 target, a "$" in the symbol will not make it considered local while |
448 for all other targets it will. | 448 for all other targets it will. |
449 </para> | 449 </para> |
450 | 450 |
451 </section> | 451 </section> |
758 <para>All conditionals must be fully bracketed. That is, every conditional | 758 <para>All conditionals must be fully bracketed. That is, every conditional |
759 statement must eventually be followed by an ENDC at the same level of nesting. | 759 statement must eventually be followed by an ENDC at the same level of nesting. |
760 </para> | 760 </para> |
761 <para>Conditional expressions are only evaluated on the first assembly pass. | 761 <para>Conditional expressions are only evaluated on the first assembly pass. |
762 It is not possible to game the assembly process by having a conditional | 762 It is not possible to game the assembly process by having a conditional |
763 change its value between assembly passes. Thus there is not and never will | 763 change its value between assembly passes. Due to the underlying architecture |
764 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</para> | 764 of LWASM, there is no possible utility to IFP1 and IFP2, nor can they, as of LWASM 3.0, actually |
765 be implemented meaningfully. Thus there is not and never will | |
766 be any equivalent of IFP1 or IFP2 as provided by other assemblers. Use of those opcodes | |
767 will throw a warning and be ignored.</para> | |
768 | |
769 <para>It is important to note that if a conditional does not resolve to a constant | |
770 during the first parsing pass, an error will be thrown. This is unavoidable because the assembler | |
771 must make a decision about which source to include and which source to exclude at this stage. | |
772 Thus, expressions that work normally elsewhere will not work for conditions.</para> | |
765 | 773 |
766 <variablelist> | 774 <variablelist> |
767 <varlistentry> | 775 <varlistentry> |
768 <term>IFEQ <parameter>expr</parameter></term> | 776 <term>IFEQ <parameter>expr</parameter></term> |
769 <listitem> | 777 <listitem> |
939 | 947 |
940 <para> | 948 <para> |
941 Note that the USE variation is provided only for compatibility with other | 949 Note that the USE variation is provided only for compatibility with other |
942 assemblers. It is recommended to use the INCLUDE variation.</para> | 950 assemblers. It is recommended to use the INCLUDE variation.</para> |
943 | 951 |
952 <para>If <parameter>filename</parameter> begins with a "/", it is | |
953 interpreted as an absolute path. If it does not, the search path will be used | |
954 to find the file. First, the directory containing the file that contains this | |
955 directive. (Includes within an included file are relative to the included file, | |
956 not the file that included it.) If the file is not found there, the include path | |
957 is searched. If it is still not found, an error will be thrown. Note that the | |
958 current directory as understood by your shell or operating system is not searched. | |
959 </para> | |
960 | |
944 </listitem> | 961 </listitem> |
945 </varlistentry> | 962 </varlistentry> |
946 | 963 |
947 <varlistentry> | 964 <varlistentry> |
948 <term>END <parameter>[expr]</parameter></term> | 965 <term>END <parameter>[expr]</parameter></term> |
960 <term>ERROR <parameter>string</parameter></term> | 977 <term>ERROR <parameter>string</parameter></term> |
961 <listitem> | 978 <listitem> |
962 <para> | 979 <para> |
963 Causes a custom error message to be printed at this line. This will cause | 980 Causes a custom error message to be printed at this line. This will cause |
964 assembly to fail. This directive is most useful inside conditional constructs | 981 assembly to fail. This directive is most useful inside conditional constructs |
965 to cause assembly to fail if some condition that is known bad happens. | 982 to cause assembly to fail if some condition that is known bad happens. Everything |
983 from the directive to the end of the line is considered the error message. | |
984 </para> | |
985 </listitem> | |
986 </varlistentry> | |
987 | |
988 <varlistentry> | |
989 <term>WARNING <parameter>string</parameter></term> | |
990 <listitem> | |
991 <para> | |
992 Causes a custom warning message to be printed at this line. This will not cause | |
993 assembly to fail. This directive is most useful inside conditional constructs | |
994 or include files to alert the programmer to a deprecated feature being used | |
995 or some other condition that may cause trouble later, but which may, in fact, | |
996 not cause any trouble. | |
966 </para> | 997 </para> |
967 </listitem> | 998 </listitem> |
968 </varlistentry> | 999 </varlistentry> |
969 | 1000 |
970 <varlistentry> | 1001 <varlistentry> |
974 This directive is ignored for most output targets. If the output target | 1005 This directive is ignored for most output targets. If the output target |
975 supports encoding a module name into it, <parameter>string</parameter> | 1006 supports encoding a module name into it, <parameter>string</parameter> |
976 will be used as the module name. | 1007 will be used as the module name. |
977 </para> | 1008 </para> |
978 <para> | 1009 <para> |
979 As of version 2.2, no supported output targets support this directive. | 1010 As of version 3.0, no supported output targets support this directive. |
980 </para> | 1011 </para> |
981 </listitem> | 1012 </listitem> |
982 </varlistentry> | 1013 </varlistentry> |
983 | 1014 |
984 </variablelist> | 1015 </variablelist> |
1318 </listitem> | 1349 </listitem> |
1319 | 1350 |
1320 </varlistentry> | 1351 </varlistentry> |
1321 | 1352 |
1322 <varlistentry> | 1353 <varlistentry> |
1323 <term><parameter>sym</parameter>EXTDEP</term> | 1354 <term><parameter>sym</parameter> EXTDEP</term> |
1324 <listitem> | 1355 <listitem> |
1325 | 1356 |
1326 <para>This directive forces an external dependency on | 1357 <para>This directive forces an external dependency on |
1327 <parameter>sym</parameter>, even if it is never referenced anywhere else in | 1358 <parameter>sym</parameter>, even if it is never referenced anywhere else in |
1328 this file.</para> | 1359 this file.</para> |