Leo : Basics : Derived Files Part 1

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.



Author: Joe Orr



  1. The file name of our Leo outline is "sample2.leo"
  2. This @root directive is saying, Put the text of this node in a separate file called "sampleHello.c".


Author: Joe Orr



Next we will tangle (derive) the file. This will cause Leo to

  1. Create the file "sampleHello.c"
  2. 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.



Author: Joe Orr



For example, there is a section name called << methods >>.



Author: Joe Orr



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.



Author: Joe Orr



Let's try it. First, again select the node containing the root directive.



Author: Joe Orr



Now choose File - Tangle - Tangle.



Author: Joe Orr



Leo has created and written the file.



Author: Joe Orr



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



Author: Joe Orr



Leo has added the section names as comments.



Author: Joe Orr



You can see that in lines 14 - 17, the text for the << methods >> node has been output as is.



Author: Joe Orr



Here we've added another line of code in the text editor.



Author: Joe Orr



We then save the file.



Author: Joe Orr



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 .



Author: Joe Orr



Again choose the node with the @root directive.



Author: Joe Orr



Choose File - Untangle - Untangle.



Author: Joe Orr



Leo untangles the sampleHello.c file. It has identified that the << methods >> node has changed, and has updated the text for that node.



Author: Joe Orr



You can see that the << methods >> node is now marked with a red line, to indicate that it has been changed externally.



Author: Joe Orr



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.



Author: Joe Orr



The @silent directive causes Leo not to insert structure comments in derived files.  Let's take a look at it in more detail.

  1. Choose the node with the @root directive.
  2. Enter a @silent directive.


Author: Joe Orr



Now let's tangle the sampleHello.c file again.



Author: Joe Orr



sampleHello.c has been updated.



Author: Joe Orr



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.



Author: Joe Orr



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



Author: Joe Orr



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.



Author: Joe Orr



  Created with ScreenBook Maker   Last update: 8/4/2002   Additional Trademark and Copyright Information