8.2 Displaying nested code sequences

Another possibility of hiding code at a specific level, is to nest several ``BEGIN/END'' blocks. If a ``BEGIN/END'' block appears inside another block, then he will be replaced by a single line of the form ``<see Listing xxx on page yyy>''. xxx denotes the listing number in which the code of the nested block actually appears and yyy the page number on which that listing begins. Of course this is only possible, if the mentioned nested block will be or already has been included by a \sourceinput command.

In turn, if a nested block will be included through a \sourceinput command, his heading line will additionally contain the listing and page number of his enclosing block. You can see this behavior in the following example where we show the constructors of the class Example2 by issuing the following command: `` \sourceinput[fontname= ul9, fontenc=T1, fontsize=7, listing, linenr, label=Constructors]{ ClassDefs.h} { Constructors}''.

Listing 8: ClassDefs.h [Line 18 to 21] (Referenced in Listing 7)

explicit Example2(double d) : y(d) {}
explicit Example2(int i) : y(i) {}
explicit Example2(long l) : y(l) {}
explicit Example2(char c) : y((unsigned int)c) {}

So lets finally state more precisely the difference between hiding code through '// ...' comment lines and the nesting of code blocks. While '// ...' comments always match the following '// ...' line, a nested 'BEGIN tagname' always matches its correspondent 'END tagname' and can potentially contain many '// ...' lines or even other nested chunks. Another difference is the fact that nested chunks can be presented later on in the documentation and will be linked together by references in that case , while parts masked out by '// ...' lines will simply be ignored. Nevertheless, '// ...' lines can be useful for example if a part of a source file contains many lines of comments which aren't intended to be shown in the ProgDoc documentation. If you want to use nested ``BEGIN/END'' chunks together with the \sourceinputbase command, be sure to read the comments on this topic in section 7.

One last word on the format of the comments processed by the ProgDoc system. They must be in a line on their own. The comment token, BEGIN/END and the tagname must be separated by and only by whitespace. The comment token must not necessarily begin in the first column of the line as long as it is preceded only by whitespace. The tagname should consist only of characters which are valid in a L^ATEX \label statement.