This manual documents the source code of the Linux and QNX Tools Demo and Tutorials. Each chapter documents one program, with each section covering one major chunk of code, such as a function. Some of these sections are broken up into smaller chunks. In most cases, the code is interspersed with commentary.

This type of content requires two versions of the code: a chunked version and a regular version. We create these two versions from one source file, with the filename format programnamed.g. This source file is a Gamma executable identical to the actual demo program executable except that it contains processing instructions like this:

//PI (doc_newfile programname_###.g)

The source file is preprocessed with a Gamma program called splitter.g that creates a group of chunks and puts them in the doc/i/tutorial/chunks/ subdirectory, as well as creating a normal version of the program without all the processing instructions that becomes the distribution version of the demo executable. The splitter.g program uses a perl script called replacer.pl to handle the correct substitutions of tabs and newlines. The code for both of these programs is in the Scripts in doc/bin/ Appendix.

The splitter.g program is called every time the tutorial documentation is made. To ensure the demo programs run correctly, it is best to run the distribution version of the program (output from splitter.g) instead of the source program. However, you must edit only the source program so that the chunked version and the distribution version of the program remain identical. To facilitate making changes and testing the program, there is a target in the doc/o/tu-book/Makefile called progs that lets you run the splitter.g program on all the demo source files (which only takes a few seconds) without having to make the tutorial documentation.

When first creating a demo program, the easiest way is to write a regular Gamma program, make sure it runs correctly, and that it is as close to "finished" as possible. When you are ready to document the program, rename the file by putting a d at the end of the filename before the .g extension, like this: filenamed.g. Then add processing instructions to the newly-named file, to split the file into documentable chunks.

The processing instructions are written in the form of comments that all start with the sequence //PI. This allows the program to run and ignore the processing instructions. But the splitter.g program recognizes any //PI comment as a processing instruction, parses it, and executes the instructions it contains.

Make sure you don't have any regular comment lines that start with //PI, or you will get unexpected output from splitter.g.

Here are the processing instructions, and what they do:

A typical source file would look like this:

//PI (setq write_file (doc_begin demo_010.g))
//PI (setq enabled 1)

   code

//PI (doc_newfile demo_011.g)

   code

//PI (doc_newfile demo_012.g)

   code

//PI (doc_newfile demo_020.g)

   code

   .
   .
   .
   .


//PI (setq enabled 0)
//PI (setq write_file (doc_end write_file))

If you wanted to document just a small chunk of a larger piece of code, you could isolate it and insert an elipsis (...) and white space before and after it, like this:

   code

//PI (setq write_file (doc_begin demo_073.g))
//PI (doc_embed_string write_file "\n   ...\n")
//PI (setq enabled 1)

   code

//PI (setq enabled 0)
//PI (doc_embed_string write_file "\n   ...\n")
//PI (setq write_file (doc_end write_file))

   code