6 The \sourcebegin and \sourceend commands

Beneath the \sourceinput command there exists another pair of commands, which can be used to highlight source code written directly into the '.pd' file. Of course they are pseudo L^ATEX commands as well and will be processed by the pdweave utility rather than by L^ATEX. Their syntax is as follows:

\sourcebegin[options]{ header}
source code
\sourceend

The \sourcebegin command has the same options like the \sourceinput command, but no filename and tagname options, since the source code begins in the line that follows the command. For compatibility reasons with older ProgDoc versions there is an optional header argument. It will be printed instead of the filename in the header of the listing if the option listing is set. The recommendation for new users however is to use the caption option instead. Notice that in contrast to the usual L^ATEX conventions, this is an optional argument. The source code will be terminated by a line which solely contains the \sourceend command.

This commands are useful if some code must be presented in the documentation which is not intended to appear in the real source code. Consider for example the following code:

 .. we don't use void pointers and ellipsis for our function {\mytt func}

 \sourcebegin[fontname=blg, fontsize=8, listing, center]{Just an example ..}
 void func(void *p, ...) {
   cout << "A function with an arbitrary number of arguments\n";
   ..
 }
 \sourceend

 since they are bad programming style and can lead to unpredictable errors ..

which will result in the following output:

``.. we don't use void pointers and ellipsis for our function func

Listing 5: Just an example ..

void func(void *p, ...) {
  cout << "A function with an arbitrary number of arguments\n";
  ..
}

since they are bad programming style and can lead to unpredictable errors ..''

The same restrictions that apply for the \sourceinput command hold good for \sourcebegin and \sourceend as well. Additionally, if present, the opening brace of the optional header argument must start in the same line like the closing bracket of the options argument.