# Derived Files Part 1

Leo
Basics
Tutorial
Using Leo to to Create files derived from outlines.
Leo derived files directives literate programming
8/4/2002
draft
C:\testtt\Leo\Basics\Tutorials\Derived Files Part 1\
<p>Using <strong>directives</strong> you can make Leo extract text from any number of nodes to&#160;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.</p><p>This tutorial will cover one way of doing this, which is to use the <strong>@root</strong> directive. A second tutorial will cover the <strong>@file</strong> directive.</p>

pic01.png

# Directives

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<ol> <li/>The file name of our Leo outline is "sample2.leo" <li/>This @root directive is saying, <strong>Put the text of this node in a separate file called "sampleHello.c".</strong> </ol>

pic02.png

# The root directive

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Next we will <strong>tangle</strong> (derive) the file. This will cause Leo to</p><ol> <li/>Create the file "sampleHello.c" <li/>Write all of the text following the <strong>@root</strong> line into the sampleHello.c file. </ol><p> However, the text of this node contains <strong>section names</strong>. Section names are indicated&#160;by the &lt;&lt; &gt;&gt; angle brackets. In place of the section names, Leo will write out to sampleHello.c the text of the named&#160;section.</p><p>This operation is called <strong>tangling</strong> 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.</p>

pic03.png

# Tangle

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>For example, there is a section name called &lt;&lt; methods &gt;&gt;.</p>

pic04.png

# The << methods >> section

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here we have selected the &lt;&lt; methods &gt;&gt; node, showing the text for that node. Since this node headline is enclosed in &lt;&lt; &gt;&gt; angle brackets, the Leo considers the node to be a section.</p><p>When tangling the <strong>@root</strong> directive shown in the previous screen, Leo will not write out &lt;&lt; methods &gt;&gt;. Instead it will write out everything following the <strong>@code</strong> directive in the &lt;&lt; methods &gt;&gt; node shown here.</p>

pic05.png

# Node text

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Let's try it. First, again select the node containing the root directive.</p>

pic06.png

# Select the first node

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now choose <strong>File - Tangle - Tangle</strong>.</p>

pic07.png

# Now choose File - Tangle - Tangle.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Leo has created and written the file.</p>

pic08.png

# Leo has created and written the file.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here is the sampleHello.c file opened with a text editor. (The text editor shown in the screenshot, <strong><a href="http://www.ultraedit.com">UltraEdit</a></strong> , does automatic syntax highlighting, so code comments are in cyan, keywords are in blue, and other code is in black).</p>

pic09.png

# Here is the sampleHello.c file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Leo has added the section names as comments.</p>

pic10.png

# Leo has added the section names as comments.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>You can see that in lines 14 - 17, the text for the &lt;&lt; methods &gt;&gt; node has been output as is.</p>

pic11.png

# The text for the methods node has been output...

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here we've added another line of code in the text editor.</p>

pic12.png

# Here we've added another line of code.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p> We then save the file.</p>

pic13.png

# We then save the file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now we look at the file in Leo again. You can see the text for the &lt;&lt; methods &gt;&gt; node has not changed. It will not change even if we open and close our Leo outline.</p><p>We can have Leo update our outline from the changes we made to the sampleHello.c file.&#160; This process is called <strong>untangling</strong> because it is the reverse of <strong>tangling</strong> .</p>

pic14.png

# Now we look at the file in Leo again.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Again choose the node with the <strong>@root</strong> directive.</p>

pic15.png

# Again choose the node with the @root directive.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Choose <strong>File - Untangle - Untangle</strong>.</p>

pic16.png

# Choose File - Untangle - Untangle.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Leo <strong>untangles</strong> the <strong>sampleHello.c</strong> file. It has identified that the &lt;&lt; methods &gt;&gt; node has changed, and has updated the text for that node.</p>

pic17.png

# Leo untangles the sampleHello.c file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>You can see that the &lt;&lt; methods &gt;&gt; node is now <strong>marked</strong> with a red line, to indicate that it has been changed externally.</p>

pic18.png

# The methods node is now marked

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>When we select the &lt;&lt; methods &gt;&gt; node, we can see that the node text has been updated with the changes we made using the text editor.</p>

pic19.png

# The node text has been updated

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>The <strong>@silent</strong> directive causes Leo not to insert structure comments in&#160;derived files.&#160; Let's take a look at it in more detail.</p><ol> <li/>Choose the node with the <strong>@root</strong> directive. <li/>Enter a <strong>@silent</strong> directive. </ol>

pic20.png

# The @silent directive

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now let's <strong>tangle</strong> the <strong>sampleHello.c</strong> file again.</p>

pic21.png

# Tangle the sampleHello.c file again.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p><strong>sampleHello.c</strong> has been updated.</p>

pic22.png

# sampleHello.c has been updated.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This time <strong>sampleHello.c</strong> 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."</p><p>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&#160;no outline information.</p>

pic23.png

# This time samplHello.c looks different

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Although we cannot <strong>untangle</strong> a file that has no outline embedded into it, it is worth noting that we can still import any text file, using <strong>File - Import&amp;Export - Import. </strong>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).</p>

[Empty]

# We cannot untangle with @silent but...

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>We've just covered the main points for deriving files using the<strong> @root</strong> directive. But there is a completely different way to work with external files using Leo: the <strong>@file</strong> directive. The <strong>@file</strong> directive is similar to the <strong>@root</strong> directive, but with some very interesting differences. Read on to the next tutorial to learn more about it.</p>

[Empty]

# The @file directive

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com