<?xml version="1.0" encoding="ISO-8859-1"?>
<screenbook>
<title realName="Derived Files Part 1">Derived Files Part 1</title>
<category realName="Leo">Leo</category>
<subcategory realName="Basics">Basics</subcategory>
<format realName="Tutorial">Tutorial</format>
<description>Using Leo to to Create files derived from outlines.</description>
<keywords>Leo derived files directives literate programming</keywords><ldate>8/4/2002</ldate><version>draft</version>
<locations>
<location>
C:\testtt\Leo\Basics\Tutorials\Derived Files Part 1\</location>

</locations>

<pages>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic01.png</picture>
<title>Directives</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic02.png</picture>
<title>The root directive</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic03.png</picture>
<title>Tangle</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>For example, there is a section name called &lt;&lt; methods &gt;&gt;.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic04.png</picture>
<title>The &lt;&lt; methods &gt;&gt; section</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic05.png</picture>
<title>Node text</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Let's try it. First, again select the node containing the root directive.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic06.png</picture>
<title>Select the first node</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Now choose <strong>File - Tangle - Tangle</strong>.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic07.png</picture>
<title>Now choose File - Tangle - Tangle.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Leo has created and written the file.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic08.png</picture>
<title>Leo has created and written the file.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic09.png</picture>
<title>Here is the sampleHello.c file</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Leo has added the section names as comments.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic10.png</picture>
<title>Leo has added the section names as comments.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic11.png</picture>
<title>The text for the methods node has been output...</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Here we've added another line of code in the text editor.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic12.png</picture>
<title>Here we've added another line of code.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p> We then save the file.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic13.png</picture>
<title>We then save the file</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic14.png</picture>
<title>Now we look at the file in Leo again.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Again choose the node with the <strong>@root</strong> directive.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic15.png</picture>
<title>Again choose the node with the @root directive.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Choose <strong>File - Untangle - Untangle</strong>.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic16.png</picture>
<title>Choose File - Untangle - Untangle.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic17.png</picture>
<title>Leo untangles the sampleHello.c file</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic18.png</picture>
<title>The methods node is now marked</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic19.png</picture>
<title>The node text has been updated</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic20.png</picture>
<title>The @silent directive</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p>Now let's <strong>tangle</strong> the <strong>sampleHello.c</strong> file again.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic21.png</picture>
<title>Tangle the sampleHello.c file again.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<p><strong>sampleHello.c</strong> has been updated.</p>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic22.png</picture>
<title>sampleHello.c has been updated.</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture width="640" height="480" ldate="" id="pagepic">pic23.png</picture>
<title>This time samplHello.c looks different</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture>[Empty]</picture>
<title>We cannot untangle with @silent but...</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
<page>
<text>

<span id="pagetext"><![CDATA[<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>]]></span>

</text>
<picture>[Empty]</picture>
<title>The @file directive</title>
<author>Joe Orr</author>
<sauthor>[Empty]</sauthor>
<cp>Copyright 2002 All Rights Reserved</cp>
<authoremail>orrj@jserv.com</authoremail>

</page>
</pages>
</screenbook>


