# What is Leo - Continued

Leo
Basics
Tutorial
This tutorial continues the introduction to Leo - the unique Literate Programming Tool.
Leo introduction programmer's outlining editor
8/12/2002
draft
C:\testtt\Leo\Basics\Tutorials\B6 What is Leo - Continued\
<p> In the first tutorial in this series, we saw the basic outlining and file derivation features of Leo. Let's take a further look at how Leo's&#160;derived file functions&#160;can be put to use.&#160;We will use the creation of a computer program as an example, however, the operations are useful in other situations involving&#160; complex text documents.</p>

[Empty]

# Continuing...

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p><strong>A note for programmers:</strong> this&#160;tutorial, in addition to being an illustration of more file derivation operations, is an introduction to how Leo can facilitate a new kind of <a href="http://www.literateprogramming.com">Literate Programming</a> .&#160;Rather than&#160;further clarify what this means now, we'll just show an example.&#160;More information about Literate Programming is available in the documentation that comes with Leo.&#160;But keep in mind that the problem to be solved by literate programming is to provide an easy-to-understand road map to a complex programming project. Using Leo, you plan your code, explain it, and write it all in the same document. You use English, not a new language like UML, and you can explain and describe all levels of structure in as many ways as you want - not just classes and methods.</p>

[Empty]

# Literate Programming

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here we've just opened Leo.</p>

pic03.png

# Open Leo

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>&#160;<a href="http://newinstance.com/writing/javaxml2/javaxml2_examples.html">This website</a>&#160;has examples from the highly recommended&#160;<a href="http://www.amazon.com/exec/obidos/asin/0596001975/qid=1028202229/sr=2-1/ref=sr_2_1/103-6904210-2103851/jsl">Java and XML</a>&#160;book by Brett McLaughlin. We're going to download the&#160;Chapter 6 examples.</p>

pic04.png

# Java and XML examples

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here we've unzipped the examples, and have selected the folder containing the java files.</p>

pic05.png

# The examples are unzipped

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now back to Leo. We are going to import the java files.</p>

pic06.png

# Back to Leo.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here we have navigated to the folder containing the java files, and will select the first Java file.</p>

pic07.png

# Select the first Java file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Leo has imported the file.</p><p>The <strong>@file</strong> directive shown in the highlighted headline is similar to the <strong>@root</strong> directive shown in the first tutorial.&#160;The <strong>@file</strong> directive is explained in greater detail later in this tutorial.&#160;</p><p> The <strong>@language</strong> directive indicates that Java syntax highlighting will be used. The <strong>@others</strong> directive indicates that all <strong>unnamed&#160;</strong> sections will be derived. An unnamed section is a node defined without angle brackets.</p>

pic08.png

# Leo has imported the file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>By expanding the nodes, you can see that Leo has automatically put each class and method in a separate node when importing the Java file.</p>

pic09.png

# Leo has automatically created an outline

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here we have imported the other two Java files.</p>

pic10.png

# Two more Java files imported

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p> Let's suppose we're interested in working on the <strong>UpdateItemServlet.java</strong> class.</p><ol> <li/>Select the <strong>doPost</strong> method. <li/>The body of the method appears in the text pane. </ol><p>Leo has automatically broken down the program by method. But there are still 200 lines of code in the <strong>doPost</strong> &#160;node.</p>

pic11.png

# The doPost node

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p> Let's break the <strong>doPost</strong> method down further. First we type in a new section / node name.</p>

pic12.png

# Breaking down the node further

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now we select all of the code (text - light grey) we want to go into our new section.</p>

pic13.png

# Select code for the section

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>We then choose&#160;<strong>Edit - Edit Body - Extract Section</strong>.&#160;</p>

pic14.png

# Extract Section.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>You can see that</p><ol> <li/><strong>The new node has been added. </strong> <li/><strong>The selected code has been extracted</strong> from the current section, leaving only the section indicator. </ol>

pic15.png

# The new node has been added.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>And when we select the new node in the outline window, we can see that the code has been pasted into our new section as expected.</p>

pic16.png

# The code has been pasted into the new section

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>In this way, you can continue to break down the program, making it much easier to focus on areas that you want to work on or study. You can add more files - in addition to adding the java files, you can add all of the xml, htm, wsd, and other files that come with this particular project. Of course, you can also add new nodes and text, as shown in the first tutorial.</p><p>But not only can you&#160;break the program down into smaller parts, you can also regroup parts of the program into different views. You can make a new branch in the outline that rearranges existing parts of the outline in a different way. To see this feature in action, read the <strong>Outlines</strong>&#160;tutorial of this tutorial series, or view some of the tutorials in the <strong>Examples</strong> section of this tutorial series.</p>

[Empty]

# You can continue to break down the program

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>A couple more notes about the <strong>@file</strong> directive: in contrast to the <strong>@root</strong> directive we saw in the first tutorial, there is no need to untangle or tangle if you use this directive. This is because in this case Leo embeds all of the outline information in the derived file,&#160;and then&#160;in effect<strong>tangles</strong> or <strong>untangles</strong> from the derived file whenever the&#160;.leo file is opened or saved.&#160;</p><p>Let's examine this more closely. First, save the file.</p>

pic18.png

# About the @file directive.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>We've saved the file as "sample.leo" in the same folder as the java files.</p>

pic19.png

# We've saved the file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>We've</p><ol> <li/>selected our new node again, and <li/>added a line of code. </ol>

pic20.png

# Add a line of code.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>We hit <strong>[CTRL-S]</strong> to save, and the changes are written to <strong>UpdateServlet.java</strong> .</p>

pic21.png

# Save, and the changes are written to UpdateServlet.java.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now we close Leo, and look at the folder with our java files in Windows Explorer. We'll open the <strong>UpdateItemServlet.java</strong> file with a text editor.</p>

pic22.png

# Windows Explorer.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Looking at&#160;&#160;<strong>UpdateItemServlet.java</strong> in a text editor, we can see that Leo has updated the file to contain</p><ol> <li/>Outline information embedded as a java comment. <li/>Our code change. </ol>

pic23.png

# Leo has updated the file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now let's add some code using the text editor.</p>

pic24.png

# Add some code with text editor

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>We save the text file, then open the our Leo outline again.</p><p> Leo opens&#160;right back to where we were, and we can see that the code we added has been read into our outline.</p><p>This means that you can transparently switch back and forth between Leo and the editor or programming tool of your choice, and each time Leo will remember your outline.</p>

pic25.png

# Save the text and open in Leo

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This concludes the basic introduction to Leo, but to actually use it you'll need to know a little more. You'll need to learn how to make an outline, and perhaps a little more about derived files.&#160;It should take about fifteen minutes to learn most of the operations you need to be proficient. But first, read on to the next tutorial, where you can learn how to install Leo.</p>

[Empty]

# Summary

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