Chapter 1: Introducing Leo

Overview of Leo
Leo's main window
Body text define and reference sections
Outlines organize sections
Clones manage tasks
Outlines generate derived files

Overview of Leo

Here are the main building blocks of Leo. The following sections will discuss each of these topics in more detail.

In short, sections simplify text, clones represent tasks, outlines organize projects and outlines generate derived files.

Leo's main window

Here is a screen shot of Leo's main window:

The main window contains two panes, an outline pane on top and a body pane below.  The outline pane contains a set of headlines.  Headlines fold (expand and contract) like Windows Explorer when you click the + or - icons. Headlines group components (subheadlines) into larger units.

The bottom pane contains the body text associated with the selected headline.  The combination of a headline and its associated body text is called a node. Body text can simply be plain text or text in the noweb or CWEB languages. A Leo program is a collection of all the body text of an outline organized by the headline.

Leo's outline are much more flexible and powerful than typical class browsers:

Body text define and reference sections

Text in Leo's body pane is simply plain text that may contain section references.  For example, here is part of Leo's source code.

def removeSentinelsCommand (self,fileName):
	valid = true
	<< Read file into s >>
	<< Set delims from the header line >>
	if valid:
		s = self.removeSentinelLines(s,line_delim,start_delim,end_delim)
		newFileName = fileName + ".tmp"
		<< Write s into newFileName >>
	else:
		es("Invalid @+leo sentinel in " + fileName)

Section references have the form <<section name>> and may appear anywhere in code.   Leo replaces a section reference by its definition  when Leo creates a source (derived) file.

Section references clarify code.  In this example, the code that is represented by the three section references does not conceal the overall shape of the removeSentinelsCommand function.  In particular, the role of the valid and s variable are clear.  Section references are often more convenient than functions.  For example, there is no need to return s from <<Read file into s>> or to pass s to  <<Write s into newFileName>>.

There are two ways to define sections.  The first way is to use a section definition line,

<<section name>>=

(notice the equal sign) on a line by itself in body text, followed by the source code that defines the section.   The second way is to create a node with <<section name>> in its headline and the source code that defines the section in its body text.  Either way, the section definition may contain other section references.

Outlines organize sections

Outlines can show relationships between sections. In the example above, a natural way of organizing the outline would be as follows:

+ removeSentinelsCommand
    + << Read file into s >>
    + << Set delims from the header line >>
    + << Write s into newFileName >>

In other words, the removeSentinelsCommand method is defined in one node which has three children, one for each section referenced in the definition of removeSentinelsCommand.  Note: to distinguished headlines from body text, this Users Guide will denote headlines with a leading plus sign.

Furthermore, Leo uses outline structure to delimit derived files and to control the scope of section definitions.  See Chapter 4 for details.

Clones manage tasks

Headlines (and the sections they contain) are the natural building block of tasks. To build tasks from headlines we need another feature of Leo's outlines, namely clones. A clone is a copy of a tree that changes whenever any part of the original tree changes.  Clones are powerful. For example, adding a node to a cloned tree adds the same node to all cloned trees as well.

We can use an ordinary headline to represent any task as follows.  We create an ordinary headline to represent the task and we label the headline with the name of the task.  Let us call such a headline a task headline. Then, throughout the entire outline, we clone all headlines (sections) that pertain to the task and move the new clones as sub-headlines of the task headline.

In effect, the task headline becomes a separate view of the project. The task headline is a natural place to place notes about the task, for example, design documents, test data and logs, etc.  Most importantly, the task view will change when any of its cloned headlines changes, and conversely, changes to clones under the task outline are propagated throughout the outline. This means that,

  1. the task headline will remain up-to-date when the project changes, and
  2. we can make changes in the task view and rather than throughout an outline.

In short, task headlines focus our attention on only those parts of a project that relate directly to a task and makes it easy to change code scattered throughout a project.

Outlines generate derived files

Leo outlines are stored in a single .leo file. Leo can create many derived files from a single outline.  You can create derived files explicitly using the Tangle command, or automatically when an outline file is saved.  Conversely, Leo can update outlines based on changes to derived files. Again, you can update an outline explicitly using the Untangle command, or automatically when an outline file is opened.  Outline files contain all information contained in derived files.  This redundancy is useful for backing up data and for error recovery.

This introduction has only sketched Leo's capabilities.  Chapter 3 shows how to create and reorganize Leo's outlines. This chapter covers clones, a powerful outline feature found in few other outliners.  Chapter 4 tells you everything you need to write programs in Leo.  Chapter 5 discusses all of Leo's commands.  Chapter 7 discusses scripting Leo with Python.