Overview of Leo
Leo's main window
Body text define and reference sections
Outlines organize sections
Clones manage tasks
Outlines generate derived files
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.
Here is a screen shot of Leo's main window:
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:
Leo's programming language understands outline structure. The programmer may name a part of the tree and refer to that tree by name in source code.
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 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.
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,
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.
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.