Basic Processing Instructions

The processing of xmltangle is controlled by processing instructions. These instructions serve to designate what function different pieces of text have. Literate Programs are broken up into sections, which themselves can contain references to other sections to be included. Each section is identified by it's section ID. Section ID's are all lowercase, and only contain letters. However, within your document, they can look however you want - they can be mixed case and include punctuation, spaces, etc. However, all letters are converted to lower-case internally, and all spaces, punctuation, and numbers are stripped out. That means that the following section ID's are identical:

All of them convert to mysection internally. There are three reasons to use a section ID. First, if you are creating a new section of code, you have to first give it's section ID. You can do that by saying <?lp-section-id?>My Section<?lp-section-id-end?>. This makes the current section be mysection. This also creates storage space for your code internally. Now, when you want to add code to this section, you begin it with <?lp-code?>. It then records your code in that section until it hits <?lp-code-end?>. You can add as many code segments as you want. If you want to add code to a different section, just close the current code segment, and then specify which section you want to work on with <?lp-section-id?> and <?lp-section-id-end?>. You can switch back and forth between sections as often as you like. Remember, however, that since you are using processing instructions, the text you put here will be formatted as if the processing instructions didn't exist at all.

Being able to switch back and forth between code sections is a good feature, but what makes Literate Programming unique is that you can embed sections within each other. For example, if I think an algorithm would be obscured by all of the error checking code, I can simply put the error checking code in a different section, and simply refer to it. That way, the algorithm is more concise, and all of the error checking still gets done. To refer to another section in your code, you use <?lp-ref?> and <?lp-ref-end?>, and simply insert the ID of the section you want to include here between these processing instructions. I usually also but braces {} around the section ID so it is obvious that it's not part of the real code when it is typeset, like this


<?lp-ref?>{My Section}<?lp-ref-end?>
Obviously, you cannot have circular references.

Finally, in order to write out these sections to files, we have to specify which files contain which sections. Therefore, we have the single processing instruction <?lp-file?> which handles this. Each file can have exactly one section ID (of course, that section ID can include many others using <?lp-ref?>). To set the file myfile.py to point to the section ID mysection, you can simply do


<?lp-file id="mysection" file="myfile.py"?>

Finally, there is the <?lp-options?> processing instruction, which sets processing options. The only one used in this program is preserve-newlines, which, when set to no, will ignore any newline immediately following <?lp-code?>. Normally, you want it set to yes, because of stylistic issues which I won't go into here. However, on the top-level section of an interpretted program, you need it set to no to make sure that the #! line goes at the very top of the file. You usually want to set it back to yes immediately afterwards. Alternatively, you could simply start your code immediately after the <?lp-code?> processing instruction, like this:


<?lp-code?>#!/usr/bin/python
...  
However, I think that looks ugly.