Using directives you can make Leo extract text from any number of nodes to another file of your choosing. A directive is a simple command starting with the @ sign that you add to the text of the node. The directive directs Leo how to process the node. Directives are always the first word on a line.This tutorial will cover one way of doing this, which is to use the @root directive. A second tutorial will cover the @file directive.
The file name of our Leo outline is "sample2.leo" This @root directive is saying, Put the text of this node in a separate file called "sampleHello.c".
Next we will tangle (derive) the file. This will cause Leo to Create the file "sampleHello.c" Write all of the text following the @root line into the sampleHello.c file.  However, the text of this node contains section names. Section names are indicated by the angle brackets. In place of the section names, Leo will write out to sampleHello.c the text of the named section.This operation is called tangling because the section names in the node text do not have to be in the same order as they are in the outline. So, the order of the text in the derived file can be different than the order of the text as it appears in the outline.
For example, there is a section name called methods .
Here we have selected the methods node, showing the text for that node. Since this node headline is enclosed in angle brackets, the Leo considers the node to be a section.When tangling the @root directive shown in the previous screen, Leo will not write out methods . Instead it will write out everything following the @code directive in the methods node shown here.
Let's try it. First, again select the node containing the root directive.
Now choose File - Tangle - Tangle.
Leo has created and written the file.
Here is the sampleHello.c file opened with a text editor. (The text editor shown in the screenshot, UltraEdit , does automatic syntax highlighting, so code comments are in cyan, keywords are in blue, and other code is in black).
Leo has added the section names as comments.
You can see that in lines 14 - 17, the text for the methods node has been output as is.
Here we've added another line of code in the text editor.
We then save the file.
Now we look at the file in Leo again. You can see the text for the methods node has not changed. It will not change even if we open and close our Leo outline.We can have Leo update our outline from the changes we made to the sampleHello.c file. This process is called untangling because it is the reverse of tangling .
Again choose the node with the @root directive.
Choose File - Untangle - Untangle.
Leo untangles the sampleHello.c file. It has identified that the methods node has changed, and has updated the text for that node.
You can see that the methods node is now marked with a red line, to indicate that it has been changed externally.
When we select the methods node, we can see that the node text has been updated with the changes we made using the text editor.
The @silent directive causes Leo not to insert structure comments in derived files. Let's take a look at it in more detail. Choose the node with the @root directive. Enter a @silent directive.
Now let's tangle the sampleHello.c file again.
sampleHello.c has been updated.
This time sampleHello.c looks quite different. Because of the @silent directive, Leo has written only node text; Leo hasn't put any extra comments into the derived file."This can be useful when you want to make your derived files contain only a particular kind of information. However, we will not be able to untangle this file now, because the file has no outline information.
Although we cannot untangle a file that has no outline embedded into it, it is worth noting that we can still import any text file, using File - Import Export - Import. Using this feature, you can read any text file into a node. If the text file is a C or Java file, Leo will automatically create subnodes for classes and methods. (This feature was demonstrated in the second tutorial in this series).
We've just covered the main points for deriving files using the @root directive. But there is a completely different way to work with external files using Leo: the @file directive. The @file directive is similar to the @root directive, but with some very interesting differences. Read on to the next tutorial to learn more about it.
