# HG changeset patch # User lost@l-w.ca # Date 1312735768 21600 # Node ID c0aedb1584af98480957218a49995d205a64f272 # Parent 38c1537857ceefc2ae4dc356a76c1df1b53cbc8f Updated manual to describe nolist pragma and pragma stacks diff -r 38c1537857ce -r c0aedb1584af docs/manual.docbook.sgml --- a/docs/manual.docbook.sgml Sun Aug 07 10:37:22 2011 -0600 +++ b/docs/manual.docbook.sgml Sun Aug 07 10:49:28 2011 -0600 @@ -1442,6 +1442,30 @@ + + +*PRAGMAPUSH pragma[,...] + + +This directive saves the current state of the specified pragma(s) for later retrieval. See discussion below for more information. + + +This directive will not throw any errors for any reason. + + + + + +*PRAGMAPOP pragma[,...] + + +This directive restores the previously saved state of the specified pragma(s). See discussion below for more information. + + +This directive will not throw any errors for any reason. + + + Each pragma supported has a positive version and a negative version. @@ -1568,8 +1592,39 @@ + +nolist + + +Lines where this pragma is in effect will not appear in the assembly +listing. Also, any symbols defined under this pragma will not show up in +the symbol list. This is most useful in include files to avoid spamming the +assembly listing with dozens, hundreds, or thousands of irrelevant +symbols. + + + + +As a convenience, each input file has a pragma state stack. This +allows, through the use of *PRAGMAPUSH and *PRAGMAPOP, a file to change a +pragma state and then restore it to the precise state it had previously. +If, at the end of an input file, all pragma states have not been popped, +they will be removed from the stack. Thus, it is critical to employ +*PRAGMAPOP correctly. Because each input file has its own pragma stack, +using *PRAGMAPUSH in one file and *PRAGMAPOP in another file will not +work. + +Pragma stacks are more useful in include files, in particular in +conjunction with the nolist pragma. One can push the state of the nolist +pragma, engage the nolist pragma, and then pop the state of the nolist +pragma at the end of the include file. This will cause the entire include +file to operate under the nolist pragma. However, if the file is included +while nolist is already engaged, it will not undo that state. + + +