Mercurial > hg > index.cgi

comparison docs/manual.docbook.sgml @ 111:c0aedb1584af

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated manual to describe nolist pragma and pragma stacks
author lost@l-w.ca
date Sun, 07 Aug 2011 10:49:28 -0600
parents 99ce348b0e6b
children 8e2523061ce9
comparison
equal deleted inserted replaced
110:38c1537857ce 111:c0aedb1584af
1440 support this directive. Use this variation if the pragma is not required 1440 support this directive. Use this variation if the pragma is not required
1441 for correct functioning of the code. 1441 for correct functioning of the code.
1442 </para> 1442 </para>
1443 </listitem> 1443 </listitem>
1444 </varlistentry> 1444 </varlistentry>
1445
1446 <varlistentry>
1447 <term>*PRAGMAPUSH <parameter>pragma[,...]</parameter></term>
1448 <listitem>
1449 <para>
1450 This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information.
1451 </para>
1452
1453 <para>This directive will not throw any errors for any reason.</para>
1454
1455 </listitem>
1456 </varlistentry>
1457
1458 <varlistentry>
1459 <term>*PRAGMAPOP <parameter>pragma[,...]</parameter></term>
1460 <listitem>
1461 <para>
1462 This directive restores the previously saved state of the specified pragma(s). See discussion below for more information.
1463 </para>
1464
1465 <para>This directive will not throw any errors for any reason.</para>
1466
1467 </listitem>
1468 </varlistentry>
1445 </variablelist> 1469 </variablelist>
1446 1470
1447 <para>Each pragma supported has a positive version and a negative version. 1471 <para>Each pragma supported has a positive version and a negative version.
1448 The positive version enables the pragma while the negative version disables 1472 The positive version enables the pragma while the negative version disables
1449 it. The negatitve version is simply the positive version with "no" prefixed 1473 it. The negatitve version is simply the positive version with "no" prefixed
1566 is of dubious utility, it is disabled by default.</para> 1590 is of dubious utility, it is disabled by default.</para>
1567 1591
1568 </listitem> 1592 </listitem>
1569 </varlistentry> 1593 </varlistentry>
1570 1594
1595 <varlistentry>
1596 <term>nolist</term>
1597 <listitem>
1598
1599 <para>Lines where this pragma is in effect will not appear in the assembly
1600 listing. Also, any symbols defined under this pragma will not show up in
1601 the symbol list. This is most useful in include files to avoid spamming the
1602 assembly listing with dozens, hundreds, or thousands of irrelevant
1603 symbols.</para>
1604
1605 </listitem>
1606 </varlistentry>
1607
1571 </variablelist> 1608 </variablelist>
1609
1610 <para>As a convenience, each input file has a pragma state stack. This
1611 allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a
1612 pragma state and then restore it to the precise state it had previously.
1613 If, at the end of an input file, all pragma states have not been popped,
1614 they will be removed from the stack. Thus, it is critical to employ
1615 *PRAGMAPOP correctly. Because each input file has its own pragma stack,
1616 using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not
1617 work.</para>
1618
1619 <para>Pragma stacks are more useful in include files, in particular in
1620 conjunction with the nolist pragma. One can push the state of the nolist
1621 pragma, engage the nolist pragma, and then pop the state of the nolist
1622 pragma at the end of the include file. This will cause the entire include
1623 file to operate under the nolist pragma. However, if the file is included
1624 while nolist is already engaged, it will not undo that state.</para>
1625
1626
1572 1627
1573 </section> 1628 </section>
1574 1629
1575 </chapter> 1630 </chapter>
1576 1631