:

Leo : Basics What is Leo

Leo is a unique, powerful computer program that you can use to organize, analyze and describe text and text files. Leo is a free program written by Edward K. Ream. For information about downloading Leo, see installation tutorial in this series. Leo runs on Windows, Mac, or Linux.

Use Leo:

  • to brainstorm a new project
  • as a Personal Information Manager
  • to add multiple outlines and commentary to any text file
  • as a tool to facilitate a new kind of literate programming.

Because Leo is unlike other tools you may have used, a series of examples may be the best way to demonstrate what can be done with Leo.

From one perspective, Leo is an outlining editor . This is a screenshot of Leo. You create an outline in the top left pane. (A later tutorial explains how to create an outline like the one in the screenshot).

Clicking on the indicated box will open the indicated node .

Here the node has been opened. Clicking on the box again will close the node.

Here the indicated node has been closed.

Clicking on a node headline (1) will show the text for that node in the body pane (2) below. The body pane is a text editor - you can enter, delete or change text here by typing it in.

You can save the outline in a leo file. Click File - Save.

Here we will save our outline in a file name "pim.leo".

The file is now saved, and the file name appears in the title bar.

You've just seen an introduction to Leo as an outlining editor. You can use Leo to make an outline, with optional text for each outline element. You can save the outline to a file. Outlines are explained more in a later tutorial in this series. The outlining capability of Leo goes far beyond what has just been demonstrated, including multipath outlines, and multiple outlines in one file .

What we've shown so far is no different from other outlining editors. What makes Leo unique is the addition of a new feature. Using simple directives, you can instruct Leo to extract text from any number of nodes, in any order, and write the text to a new file. You can also embed outline information in the second file, giving Leo the ability to read the text pieces back into the Leo outline, even if they have been changed.

In effect, Leo is a meta-text editor . It gives you the ability to create a structural document for a non structured document, or a document that is structured in some other way.

What does this mean in practice? Some examples should help clarify things...

Here is the "pim.leo" file again. We've:

  1. Selected the "2000" node.
  2. Entered a couple of directives. The second (@root) tells Leo the file name that we want to derive (extract to). (The @silent directive is explained in a later tutorial).
  3. Entered some node text.

Now we tell Leo to tangle the node. This means Leo should

  1. Start at the current node and look for a @root directive.
  2. Create the file named in the @root directive or open it if it already exists.
  3. Write all of the node text to the file named in the root directive.

Why is this operation called tangling? We'll see that a few pages from now.

Leo has derived the file (written the file to the hard disk).

Here the file is listed in Windows Explorer.

And here is the file displayed in a text editor.

That example wasn't very useful. All that we extracted was the text "This is my diary." We'll probably want to extract more than that.

In fact, when tangling, we can extract not only the node text as we just saw, but also all or part of the text of any subnode. And we can put these extracted pieces into the derived file in any order. That is why the process of extraction is called tangling.

Let's try this. Select the "Jul" node.

  1. We add << >> angle brackets to the headline. This tells Leo that the node is a section.
  2. We add the @c directive. This tells Leo where to start extracting text from this node.

Now we go back to the 2000 node. We enter the section name << Jul >> into the node text where we want the << Jul >> section text to be output. When tangling, Leo will replace this section name with the section text. This operation is recursive, so if a section text contains a section name, this also will be replaced with the named section's text.

Note: when we put a << section name >> into node text, the section name must correspond to a section located under the current node. Leo only looks in subnodes for section names.

Choose Tangle.

The file has been updated.

Here is the extracted file viewed in a text editor.

This tutorial has given you a brief introduction of Leo's:

  • Outlining capacity
  • Ability to create derived files.

These two things are the main features of Leo. However, there is much more to say about both of them:

  • Outlining - see the Outlining tutorial in this series to see how Leo can be used to create outlines with multiple paths or views, making it a powerful tool for project planning or any kind of tree-based analysis.
  • Derived files - we've seen the simple case of deriving a text file from a node. This give you the ability to collect a number of text files in one Leo outline. But Leo can do much more that that - Leo can extract not only node text, but also outline structure, and can then read back this embedded structure. For a look at this feature and why it is so useful, particularly for programmers, see the next tutorial in this series: What is Leo - Continued. In addition, in the following tutorials you will see much more complex examples of derived files.

In addition to Outlining and file deriving features like Tangle, Leo also has the following features:

  • Can be scripted with Python.
  • Contains a syntax highlighting programmer's editor.
  • The .leo format is XML, meaning that a leo file can be easily converted to any other text format such as HTML.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/4/2002 Additional Trademark and Copyright Information


Leo : Basics What is Leo - Continued

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 derived file functions can be put to use. We will use the creation of a computer program as an example, however, the operations are useful in other situations involving complex text documents.

A note for programmers: this tutorial, in addition to being an illustration of more file derivation operations, is an introduction to how Leo can facilitate a new kind of Literate Programming . Rather than further clarify what this means now, we'll just show an example. More information about Literate Programming is available in the documentation that comes with Leo. 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.

Here we've just opened Leo.

This website has examples from the highly recommended Java and XML book by Brett McLaughlin. We're going to download the Chapter 6 examples.

Here we've unzipped the examples, and have selected the folder containing the java files.

Now back to Leo. We are going to import the java files.

Here we have navigated to the folder containing the java files, and will select the first Java file.

Leo has imported the file.

The @file directive shown in the highlighted headline is similar to the @root directive shown in the first tutorial. The @file directive is explained in greater detail later in this tutorial.

The @language directive indicates that Java syntax highlighting will be used. The @others directive indicates that all unnamed sections will be derived. An unnamed section is a node defined without angle brackets.

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.

Here we have imported the other two Java files.

Let's suppose we're interested in working on the UpdateItemServlet.java class.

  1. Select the doPost method.
  2. The body of the method appears in the text pane.

Leo has automatically broken down the program by method. But there are still 200 lines of code in the doPost node.

Let's break the doPost method down further. First we type in a new section / node name.

Now we select all of the code (text - light grey) we want to go into our new section.

We then choose Edit - Edit Body - Extract Section.

You can see that

  1. The new node has been added.
  2. The selected code has been extracted from the current section, leaving only the section indicator.

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.

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.

But not only can you 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 Outlines tutorial of this tutorial series, or view some of the tutorials in the Examples section of this tutorial series.

A couple more notes about the @file directive: in contrast to the @root 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, and then in effecttangles or untangles from the derived file whenever the .leo file is opened or saved.

Let's examine this more closely. First, save the file.

We've saved the file as "sample.leo" in the same folder as the java files.

We've

  1. selected our new node again, and
  2. added a line of code.

We hit [CTRL-S] to save, and the changes are written to UpdateServlet.java .

Now we close Leo, and look at the folder with our java files in Windows Explorer. We'll open the UpdateItemServlet.java file with a text editor.

Looking at UpdateItemServlet.java in a text editor, we can see that Leo has updated the file to contain

  1. Outline information embedded as a java comment.
  2. Our code change.

Now let's add some code using the text editor.

We save the text file, then open the our Leo outline again.

Leo opens right back to where we were, and we can see that the code we added has been read into our outline.

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.

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

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/12/2002 Additional Trademark and Copyright Information


Leo : Basics Installation

Windows Users:

Installing Leo requires two steps:

  1. Install Python: click here, save to your desktop, then double-click on the saved file.
  2. Install Leo: click here, save to your desktop, then double-click on the saved file.

(Python is a type of software for creating and running computer programs.)

Unix and Max Users:

Please continue to next page.

Also, if you are a programmer and want to get the Leo files without using an installer, continue to the next page.

Full installation of Leo requires that you:

  1. Install Python
  2. Install the Leo files

To install Python, follow the directions on this page.

To install Leo, go to this page and download the most recent zip file under the heading "Leo2.py". Download the zip file to your desktop or other location, and then unzip it to the folder of your choice.

To run Leo, double-click on the file leo.py that you have just unzipped.

Once you have installed Leo, you can configure Leo using the leoconfig.txt file. For more information about this see the documentation distributed with Leo.

Leo is a free program distributed under the Python license. This means that not only can you use the program freely including commercially, the full installation comes with source code that you can modify as you wish, as long as you give credit to the author of the program, Edward K. Ream .

Leo is written in Python - a full featured, powerful programming language that is comparatively easy to learn and use. For an excellent introduction to Python for non-programmers, see this tutorial. Not only is Leo written in Python, it is scriptable via Python, meaning that you can embed Python commands in your outlines and execute them.

Leo is under active development and all are welcome to contribute. For more information, see the Leo SourceForge Site.

Not only is Leo free software, it is supported software. Post questions and bug reports to one of the Leo Support Forums.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/12/2002 Additional Trademark and Copyright Information


Leo : Basics Outlining

Here we have opened a new file in Leo.

Let's add a node. Choose Outline - Insert Node or key in [CTRL-I].

A new node has been created.

Click on the headline to edit the headline text.

Here we have also changed the text for the first (untitled) node.

Now let's make the second node the child of the first. Click on the node, then enter [CTRL-R]. This will move the node to the right. (You can also perform this operation with the Outline menu.

Here we have entered [CTRL-I] and created another new node.

Here we've edited the name of the third node and moved it to the right with [CTRL-R].

We've added another node...

Changed the name..

To move it left, enter [CTRL-L].

Now we'll add another child node with [CTRL-I] and [CTRL-R]

To move a node up, click on the node and enter [CTRL-U] as many times as necessary.

Here we've moved "Bob" down by entering [CTRL-D] and then right by entering [CTRL-R].

To enter text for node, click on the text pane and type.

To summarize:

  • [CTRL-I] = insert a new node
  • [CTRL-R] = move node right
  • [CTRL-L] = move node left
  • [CTRL-U] = move node up
  • [CTRL-D] = move node down

You can also delete a node with:

[CTRL-SHIFT-BACKSPACE].

You can also drag nodes from one point to another.

That is all that you really need to create an outline, but there is one more powerful feature: clones . To demonstrate this feature, first I've added more nodes...

Now I've closed up the nodes and added a new node at the level of the first. (So, another top level node).

I want to add a list of people who owe me money. So, I open a node and select a person.

Next I enter [CTRL-`] to create a clone node. You can see that a new node is created with the same name as the selected node, but now both nodes have a small red arrow.

Now I've moved one of the cloned nodes down to a new location under the "People who owe me money" node.

Cloned nodes are basically the same node. You just have another "view copy". Let's demonstrate this. Here we've entered some text for the second clone.

Now we've selected the first cloned node. You can see that the text is the same, although we did not enter any text with this node selected.

However, clones are not linked when deleting. We've just deleted the first clone, and the second remains, except that now it is just a regular node.

A cloned node can have child nodes, so you can clone entire subtrees. In effect, cloning allows you to make multiple trees for one set of "leaves".

There are more outline commands available from the Outline menu. But with just what you've learned in this tutorial you are ready to create outlines of any level of complexity.

In the next tutorial we'll see how to create separate text files derived from an outline and how these derived files can be read back into an outline.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/2/2002 Additional Trademark and Copyright Information


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.

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

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.

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.

  1. Choose the node with the @root directive.
  2. 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.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/4/2002 Additional Trademark and Copyright Information


Leo : Basics Derived Files Part 2

Leo has a second way of creating derived files. This is the @file directive. This directive at first seems similar to the @root directive, but there is an important conceptual difference. When you use the @file directive, outline information is always written to the derived file. Therefore, you cannot use the @silent directive.

The benefit of using the @file directive is that there is no longer any need to explicity tangle and untangle. Tangling and untangling happen automatically by opening a .leo file and saving it. This makes alternating between Leo and another editor or IDE completely transparent.

In addition, when you use the @file directive, you can have unnamed sections. To see how these work, read on...

Here we've added a second node with a @file directive to our tree from the previous tutorial. The @file directive, in contrast to the @root directive, appears only in a node headline, not in node text.

As before, the node text has the << includes >> section name. But this time, instead of a << methods >> section name, it has a new directive: @others. This directive means, "put the node text from all of the unnamed sections here." Unnamed sections are nodes that are not sections, i.e. nodes that do not have double angle brackets in the node headline.

We enter [CTRL-S] to save our .leo file, and the sampleHello2.c file is automatically written.

Here is the sampleHello2.c file in our text editor. Embedded outlines created with the @file directive have a different embedding format than those created with the @root directive.

All of the outline information embedded by Leo starts with the @ sign (plus, in this case, two slashes). Needless to say, we can't delete any such sentinel line without interfering with the ability of Leo to read the file back into an outline.

Let's try adding some code in the text editor.

Next we save the file with the text editor.

When we return to Leo, we do not see the changes. We must either reopen the file or reread it.

When we reopen our sample2.leo file, we can see that the changes we made to sampleHello2.c have been incorporated into our outline in the proper place.

If you are a programmer, you now have all of the information you need to start using Leo with your own programs. You may find that Leo quickly brings about a great improvement in programming speed and enjoyment, both for your own projects and for team projects.

For a look at some sample projects that have used Leo successfully, see the Examples section in this tutorial series.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/12/2002 Additional Trademark and Copyright Information


Leo : Examples The Evisa Site

This tutorial shows how using Leo greatly simplified the development of the language learning applications online at evisa.com, a multilingual information and learning site. (The .leo file containing the code for this application is not available for download, but the leo outline is illustrated via screenshots).

First, let's take a look at how the site application works, and then we'll examine the .leo file that contains all of the code for the language applications.

Here is the Language Learning Site at evisa.com. This site contains a number of vocabulary drills and activities for numerous languages.

  1. In addition to being able to study words, students can take tests, and save their scores.
  2. Saving a score however, requires registration (free).

Let's choose the French language option.

This brings us to the French Language Study page. There are two activities available from this page:

  1. Word Study: a set of language study activities.
  2. My Flashcards: a page that shows word flashcards saved by the registered user who is viewing the page.

Let's take a look at the Word Study activities.

This presents us with a list of word groups. The word groups are marked with red, green or yellow icons to show which groups have been already been reviewed by the currently logged on user.

We'll choose the colors group.

This brings us to the activity page for the colors word group.

Let's take a look at View and Listen.

This brings us to a list of colors in French and English. Also, the Merlin character (Microsoft Agent) appears. We can click on any French word to hear Merlin speak the word.

To try another activity, we can go back to the activity menu, or click on the indicated mark to go to the next activity.

This brings us to the Flashcards page. This presents the colors as a series of cards. Clicking on a card shows the word in the target language. We can also choose to save cards to the My Flashcards page, for which we saw a link earlier.

Now we'll go to the next activity.

This brings us to the Concentration card game page. This allows one or two players to play a game of Concentration with the vocabulary items.

The final activity is the Match Test . This is pairing test. You click on a word first in one column, then in the next. If the words match, you get a point. If you get a score of 100%, and you are logged in, and your pass is automatically saved, so that you can see it later in the My Achievement page, to which we saw a link earlier.

Both the Match Test and the Concentration card game allow you to configure the sound effects for right and wrong answers.

Now, let's consider what will be involved in programming an application like the one we've just seen.

  • The same words appear in many pages, so we'll want a database of words with the pages inserted into each page as required.
  • This needs to work with a number of languages, so the database will need tables for each language paired with English.

We'll need at least:

  • A program or module to do the basic word activities
  • A program or module for registration. This involves sending the user an email and the user then clicks on a link to register.
  • A program to display personal achievement.
  • A program for the My Flashcards page.

The application is going to be getting words from the database, and inserting them into each activity page. That means we need a template for each of these pages. But evisa.com doesn't just serve an English user base. It also has a complete subsite for Japanese users, with sites for other languages planned. So we'll need templates for other languages.

We'll need to plan the database, so we'll something explaining that. We need to make input pages for the database so that administrators can add words. Since we want the database to be as fast as possible for reads, we want to make some utilities to replace certain database functions that could slow down reads, such as data constraints.

Most of the activity pages have a lot of javascript, some of which could be put in a libary file, and all of which should be organized.

Hmmm... this is starting to look like a major project. Each task is simple, but keeping everything organized so that the job can be done as fast as possible even when the the project is being stopped and started over a period of time... that could be a challenge.

Here's a look at the .leo file that is actually behind the all of the code.

An explanation of some of the nodes:

  • phonics: This is a program that allows an administrator to build the phonetic library used for showing the pronunciation of English words.
  • SQL: utilities for maintaining the word database.
  • words: the application that takes care of the server side of all of the Language Learning Activities
  • recorders: small programs that record user information such as passed tests and flashcards
  • flashbox: the application for My Flashbox

In addition to the actual code for all programs, the outline contains just about every other useful piece of information for the site programmer, including how to log on to the MySQL database, and other documentation of third party programs used.

Let's take a look at the words.cgi program, because that does most of the work.

Here we see the node for the words.cgi program expanded. Already the basic structure of the program is apparent. We are going to get/initialize the cgi object, check to see what browser is being used, connect to the database and retrieve words, and then make the outgoing page.

In the text for the << make page >> section, we can see that one of the included sections is for << word groups >>. Looking down the outline, we can see that the word groups page consists of

  • getting data from the database.
  • filling in the template with the data.

If we were debugging the word groups page, we would have jumped right to this spot in the code immediately. No hunting around trying to remember how the program works and where things are.

In this screen we are viewing the text for the word groups: fill in the template node. All of the code for this node fits in one screen.

You might note that the code displayed in this node text does not stand on its own. So, to debug it, you might need to look at another node. This code and outline could have been written otherwise, but writing it in this way is not a great impediment, since finding the code that this node is dependent on is just as easy as it was to find this node itself. When you are using literate programming techniques, the whole program simply becomes much easier to navigate.

We've seen that the program is retrieving these words, and then filling in a template. Where are these templates? In Leo, of course. Underneath the words node, we find the templates node.

Since evisa.com has viewers in langages other than English, there must be a separate set of templates for each language.

Here we can see that all of the templates are embedded in the .leo file.

Let's take a look at the speak.htm template. This is the file that will display the page where the user can click to hear a word spoken. The words.cgi program simply fills words into this template. The template contains all of the code for making the page speak in the browser.

The way it does this, is to embed an ActiveX object for a Microsoft Agent, and then call that ActiveX object with Javascript. Here the code for embedding the ActiveX objects is shown. Since these same objects are embedded in the same page for each language, this is a clone node. All of the other templates that use this code simply share this node.

This has been a brief overview of the language applications at evisa.com. As you can see, all of the code, and virtually all of the supplemental information needed to work on this application is embedded in one Leo file. The programmer opens the file, works on the application in Leo, and then tangles the output code files.

This application was written in Perl, because of Perl's excellent text manipulation capability and speed of development. There is no scalability problem with this kind of Perl application, because it runs with Apache mod_perl. While programming this application in certain other languages would have given it some more inherent structure, this would sacrifice some of the advantages of development with Perl. In fact, one can think of Leo doing for the supposed "structure" problem of Perl what mod_perl has done for the scalability problem. The application as written in Leo simply could not be easier to understand.

Are there alternatives to this approach? There are more than fifty files embedded in this one Leo file. Every file is grouped and described not just with a name, but with whatever additional information is necessary. Some files are sharing components, i.e. nodes.

This application was developed on a very constrained budget and simply would not have been possible without Leo.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/3/2002 Additional Trademark and Copyright Information


Leo : Examples Screenbook Maker XSLT

The page that you are looking is an HTML page created by the Screenbook Maker program. Screenbook Maker makes it easy to create online tutorials with screenshots. It also automatically creates tables of contents, full text search pages, rdf files, and other resources.

Before Screenbook Maker created this HTML page that you are reading now, however, it saved all of the text of this tutorial in an XML file. Then, it generates the HTML for this page from an XSLT template. But Screenbook Maker doesn't just create one HTML view of the tutorial. Screenbook Maker looks in the bookshelf folder (the folder containing the screenbook tutorials) for XSLT files. For every XSLT file that it finds there, it generates a different tutorial output.

An XSLT template file is a text file that contains XSLT (a specialized language) instructions and other output text. A processor is used to take the XML file for the tutorial and create an output file based on the XSLT instructions and text in the XSLT template.

Let's take a look at what this means in practice. Here is a screenshot from the first page of one of the Windows 2000 Tutorials in the evisa.com Screenbook Library.

Each folder containing HTML pages for a screenbook tutorial has the file sbook.xml , which contains all of the text and image names for the tutorial. If we change the url, we can see the xml file.

Here we've closed up some of the XML elements to make it easier to see the structure of this screenbook's XML. You can see that it contains a number of page elements.

Here we've opened up the first page element. You can see that each page element contains the page text and other information for the page.

Now we've returned to the first page of the tutorial, and will look at the Bookshelf table of contents.

Now the bookshelf table of contents is displaying.

Here you can see that there is a menu to choose other tutorial formats. We will choose Titles with Thumbnails.

You can see that now the same tutorial is being displayed in thumbnail format.

We saw in a previous screen that there are five different tutorial formats that can be chosen from. Each of these formats consists of HTML pages output from processing the XML file we saw previously.

There is also another XML file to be aware of, that for the Bookshelf. A bookshelf is a folder that contains multiple tutorials. When Screenbook Maker creates a tutorial, it automatically updates a file called sbooktoc.xml in the Bookshelf folder where the screenbook is stored.

Here is a view of the xml file for the Bookshelf we are examining.

So, we've seen that we've got at least two XML files, and numerous output files that must be produced. All output is produced by XSLT templates. Screenbook Maker is distributed with XSLT templates for all the output formats shown, and more. Each output format corresponds to one XSLT file.

Since Screenbook Maker users have access to the XSLT files, they can easily change the way an output format looks by editing the XSLT. For example, if you want to put a banner ad at the top of every HTML page in slide view, you simply edit the XSLT template that creates the slide version of the screenbook.

The only problem is, how is the average user to be able to figure out which of the many XSLT files to edit? And, since users may not know XSLT, how can the XSLT files be distributed and explained in such a way that the anyone who knows HTML will be able to edit the XSLT templates which produce HTML output?

There are basically only two possible solutions:

  • Hire a team of programmers to create a fancy WYSYWIG editor that allows users to make some, but not all, of the changes they could make by editing the XSLT directly.
  • Use Leo to distribute, categorize and explain the XSLT in such a clear fashion that any intelligent user who knows HTML will be able to edit the XSLT to produce any kind of HTML output that they want. More advanced users will be able to add completely new output formats.

Since at this point Screenbook Maker is a free program produced by a single programmer, option #1 is not realistic.

Here is a view of the sbstylesheets.leo file that comes with Screenbook Maker. If you would like to look at this file, download and install Screenbook Maker.

You can see that there are a number of categories. The node highlighted contains all of the XSLT templates for the XML in a single screenbook folder, that is, the XSLT for the tutorial formats.

When we expand the node for the XSLT templates for a screenbook, we can see that there are numerous files, one for each format.

Let's look at the first template. This is the one that creates the slide view format (one HTML page per screenbook page).

There is a directive here that may be new to you: this is the @first directive. This allows you to specify that the following text will be written to the target file first before any Leo sentinel lines. This is necessary since the XSLT format requires that the <?xml?> declaration be the first line of the file.

Now let's look at the main template node. You can see that it contains some XSLT instructions (with the special <files> element used by Screenbook Maker to break a single XML input file into multiple output files), plus the <html></html> elements, plus a couple of subsections.

At this point there are probably two main reactions by the reader:

XSLT experts: A lightbulb should be going on over your head at this point. That's right, this is the holy grail of XSLT development - the tool that makes XSLT as easy to read as any other language. XSLT is an extremely powerful tool, but XSLT templates can be very difficult to read. That makes it harder to for multiple people to work on a single template. No WYSYWIG tool will ever beat Leo in terms of making XSLT readable, and by using real XSLT, you get all of its power. (Still not a convinced fanatic? Move ahead to the DHTML Grid example, and see if you can imagine doing that one in anything but Leo).

Average Users: If you know HTML, but don't XSLT, hang on - you'll see that Leo makes the structure of the XSLT so transparent that you can make substantial changes to the output format without even glancing at the actual XSLT instructions.

To recap what the XSLT is doing, it is reading the sbook.xml file, and on the basis of that, outputting some HTML. It does this by

  • Executing some XSLT instructions and
  • Copying verbatim the HTML tags in the XSLT template

So now let's look at the << head >> element. Well hey... this is mostly just HTML! Want to change the stylesheet the screenbook will point to? Just edit the link here.

Hmm.. the <body> tag doesn't have much in it... suppose our goal is to add a banner ad to the output. That would probably be in the node entitled "layer 1".

Now we are looking at the "layer 1" node. There are some xsl (XSLT) elements at the beginning of the code. We'll just ignore those. We can see that the next thing is a <div> tag. Then, there is a table. The div tag's position is one pixel from the top, so this must be the first thing on the page. If we want to put in a banner add, we can just move this div tag down and put another div tag or table in front of it. Or, we could add another row to that first table.

After we make our changes and save the leo file, we can have Screenbook Maker regenerate our tutorials using this new XSLT template. We may have to come back and change some more HTML since this template is using absolute positioning, but you can see that it is basically a matter of editing HTML.

And for each change you make, you can add a Leo node, documenting your change for others in your organization who will be working with these files.

A further note for XSLT developers. Since the Leo file contains a library of XSLT templates for manipulating the XML generated by Screenbook Maker, when you want to add a totally new output format, all you need to do is add a new XSLT file, and you already have examples of just about every possible useful expression you could need for extracting from the XML using XSLT.

In the screenshot here, we can see that there is a file name toc_imsmanifest.xml.xsl. Screenbook Maker will use this XSLT file to create a file named imsmanifest.xml. The format for this xml is taken from Microsoft's LRN Resource, meaning that this bookshelf will now be SCORM compliant, since it will have a properly formatted imsmanifest.xml file. In other words, adding SCORM compliance (an industry standard for online training structure) consisted of:

  1. examining Micorsoft's LRN format
  2. using the same XSLT elements as in other files in this Leo tree to extract the data from the bookshelf XML and output to the LRN format.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/3/2002 Additional Trademark and Copyright Information


Leo : Examples Perl Utilities

Perl is a great language for many things, but one thing it really shines at is in making small programs for system administration. There is a huge library of components for system administration that you can use from Perl, and it is easy to do a lot with a small script.

Scripts that are dashed off quickly to take care of small tasks tend not to be terribly readable and well documented, particularly in a language like Perl that has so many ways to pack a lot of functionality into a few statements. Such scripts also tend to proliferate, since often it can be faster to write a new script than find out whether a script already exists that can do the job.

This tutorial provides an example of how using Leo can solve both of these problems. One sample script is presented, but it is easy to see how adding more scripts to this example outline could result in a package that is very well documented. Addind a new script to this outline would not take much more effort than dashing off a script in a standard text editor.

The Leo file used in this tutorial is available from my Leo Resource Page. To download it right-click on this link and choose "Save Target".

Here is how the file looks when first opened.

The driveinfo.leo file contains a single script, with documentation and other supplementary files. The script in driveinfo.leo is driveinfo.pl , a Perl script for checking drive space on a Windows machine and then emailing this information to any number of people. (This script doesn't use the newest modules, so it may not be useful for deployment at this point, but still can serve as an illustration of Leo's capability).

If you've downloaded the file and are investigating it with Leo now, you can quickly see that the Leo outline clearly shows what the program is, how to use it, and how it is programmed. Since the benefits of such an outline will probably be immediately obvious, this tutorial will not go into much detail, but will simply point out a few features of the outline.

  1. The first node of the outline explains what is in the outline and how to use it.
  2. This node has info about installing the modules necessary to run this script. Most scripts use Perl modules, and not everyone will know how to get and install a Perl module
  3. This node has the actual script.

Users of the script will not need to look at the script node, since documentation of how to use it is contained in other nodes. Only progammers who want to change the script will be interested in opening the script node and looking at it.

The Driveinfo script is broken down into four sections plus a section for functions. The indicated node is where the script reads the drive space of the drives on the current machine.

Some people claim that Perl is hard to read, but anyone with a basic knowledge of Perl should find the code in this node to be simple to understand.

Leo not only makes it easy to deploy a program, it makes it easy to study the program to learn how to implement a particular feature. Let's suppose we aren't interested in drive space, but we do want to write a script to send email. That information is obviously going to be in the indicated node.

But apparently that functionality is implemented in the &notify function. We'll have to find and look at that.

Since it is a function, we'll expect to find it in this node.

The entire function is displayed in the body pane. This is all the code we need to send email using Perl and SMTP module.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/4/2002 Additional Trademark and Copyright Information


Leo : Examples Flextable

Flextable is a DHTML component you can use in your web pages to display data in a tabular form. This component has many features not available in HTML tables, such as click-sort, movable columns, frozen columns, resizable columns etc.

Flextable only works with Internet Explorer 5.5 or later. If you are using IE 5.5+ you can view a sample page and other information here. A Leo file containing the component is also available from the same location.

Flextable is distributed in an XSLT stylesheet. You use the stylesheet to process tabular XML, and the ouput is a DHTML page with the Flextable component.

Since the Flextable component is distributed in an XSLT stylesheet, the process of actually displaying the component to the viewer goes like this:

  1. Server (e.g. JSP page) makes XML
  2. Server applies the client.xsl stylesheet to the XML.
  3. The result is DHTML (HTML + a Javascript array of data + Javascript for the component) that is sent back to the browser.
  4. The browser executes the Javascript of which the component consists.

The actual component is a Javascript object.

Any developer wishing to extend or modify the component is going to need information about the XML format that the stylesheet explains. It is also going to be difficult for a Javascript developer to work directly from the stylesheet, since that contains a mixture of XSLT and Javascript, rather than the final Javascript output.

Packaging the XSLT template and a sample XML file in a single Leo file makes distribution of the component much more easy and understandable.

The XSLT and Javascript can be separated simply by putting each in separate nodes.

Opening up the main template of the XSLT stylesheet, we can immediately see where the output for the HTML <head> and <body> elements will be.

Looking at the headlines in the <head> and <body> elements, we can see that the actual script for the Flextable is probably in node #1, and that this script gets called in node #2.

Sure enough, a further look at the script node shows that the Javascript for the dhtmltable (flextable) object is in a subnode, and that this is further divided into the constructor and methods. Once we are in the <script> node, we are looking at pure Javascript that will be passed to the browser. We don't need to worry about XSLT.

Suppose our aim is to examine the code that allows for column resizing by the DHTML object, in order to add this feature to another component. Opening the methods node allows us to jump right to the node containing all of the code for column resizing.

Note that this node contains several methods. There are a number of small methods that enable column resizing. None of the methods really merits its own node, they belong together. This analysis is much more helpful than a simple class analyzer that would simply list all of the object methods.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/5/2002 Additional Trademark and Copyright Information


Leo : Examples A NSIS Installer for Python Applications

Nullsoft, the makers of the Winamp MP3 software, have released a powerful free installer called NSIS, available here. This application allows you to make installation packages for Windows applications.

You create NSIS packages by writing a NSIS script and then compiling it. Depending on the application, NSIS can often be a better choice than more expensive installation generators, since NSIS installations are easy to create, are small and fast, and yet can be configured with many features.

When you install Leo, you'll find that it comes with a script for generating an installer for Leo. This script is called leo.nsi, and is distributed in the Leo file nsis.leo .

If you have NSIS installed, right-clicking on a .nsi file will give you the option of compiling the script to create a package.

Since the NSIS script for the Leo installation is included in the Leo distribution in the nsis.leo file, it is easy to understand the how the script works. This .nsi file creates an installer that packages all of the Leo program files, and creates a desktop shortcut, a Program Menu item, and the file association for .leo files.

In this screenshot we're looking at the code that checks to see whether Python has been installed.

Since Leo is a Python application, modifying this installation script to create a script to build a Windows installer for your own Python application is relatively simple. You would leave this section alone, and check other sections for the program name "Leo", and change these to your program name.

For example, here is the section that creates a registry entry for associating the .leo extension with Leo. You would change the name "Leo" to the name of your application.

If you are going to use NSIS to create an installer for something other than a Python application, this .leo file still contains examples of several useful NSIS techniques, which can be easily referred to, since the script is documented in outline form in a Leo file.

Text Author: Joe Orr Copyright 2002 All Rights Reserved
Created with ScreenBook Maker Last update: 8/12/2002 Additional Trademark and Copyright Information


Client-Side Search Main Page

ScreenbookTM Bookshelf

Use this form to search for Screenbooks in the current bookshelf.

To access a book by title, see the:

Screenbook Table of Contents (Frames)

or the

Screenbook Table of Contents (No Frames)

For more Screenbooks, check out Screenbooks.net.


Screenbooks Bookshelf Search Page

Screenbook Bookshelf Search
Search for:
Using:


HTML Help Title Page

Bookshelf Name: Leo
Bookshelf Description: Tutorials for Leo, the Literate Editor With Outlines
By: Joe Orr copyright 2002 All Rights Reserved
This HTML Help File was created with: