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:

• My SEcTION

• {My section}

• My, Se c t i o n 2

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?>

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
...