Sunday, August 8, 2010

Leo in a nutshell

I have struggled for years to explain why Leo is interesting. Here is my latest attempt. I think it looks a bit better than usual :-)

Leo combines outlines, data, files and scripting in a unique way. As a result, it takes some time to get the Leo Aha. This page introduces Leo's features and argues that Leo truly is a unique tool.

Outlines and organization: Leo's outlines are far more flexible and powerful than any other outline you have ever used, for at least three reasons:

1. Unlike other browsers, you, not the browser, are in complete control of the outline. You can organize it however you like, and Leo will remember what you have done and will show it to you just that way when come back next time. If you don't think this is important you have never used Leo :-)

2. Leo outlines may look like other outlines, but in fact Leo outlines are views of a more general underlying graph structure. Nodes in Leo's outlines may appear in many places in the same outline. We call such nodes clones. Using clones, it is easy to create as many views of the data in the outline as you like. In effect, Leo becomes a supremely flexible filing cabinet: any outline node may be filed anyplace in this cabinet.

3. Leo outlines are intimately connected to both external files and Python scripting, as explained next.

External files: Any outline node (and its descendants) can be "connected" to any file on your file system. Several kinds of connections exist. The three most common kinds are:

1. @edit: Leo reads the entire external file into the @edit node's body text.

2. @auto: Leo parses the external file and creates an outline that shows the structure of the external file, just as in typical class browsers.

3. @file: Leo makes a two way connection between the @file node (and its descendants) and the external file. You can update the external file by writing the Leo outline connected to it, or you can update the outline by changing the external file. Moreover, you can easily control how Leo writes nodes to the file: you can rearrange how Leo writes nodes. To do all this Leo uses comments in the external file called sentinels that represent the outline structure in the external file itself.

All of these connections allow you to share external files with others in a collaborative environment. With @file, you can also share outline structure with others. Thus, a single Leo outline can contain an entire project with dozens or even hundreds of external files. Using Leo, you never have to open these files by hand, Leo does so automatically when it opens the Leo outline. Leo is a unique new kind of IDE.

Scripting: Every outline node can contain Python scripts. Moreover, each node in a Leo outline is a programmable object, which is easily available to any Leo script. Furthermore, the structure of the outline is also easily available to any script. Thus, nodes can contain programs, or data, or both!

Furthermore, Leo's headlines provide a natural place to indicate the type of data contained in nodes. By convention, @test in a headline denotes a unit test, @command creates a new Leo command, and @button creates a script button, that is, a Python script that can be applied to any node in an outline!

Unifying scripting, data and outline structure creates a new world. We use the term Leonine to denote the Leo-centric (outline-centric) view of programming, data and scripting. Here are some of the implications of of this new world:

Data organization: Leo's clones allow unprecedented flexibility in organizing data. Leo outlines have been used as an entirely new kind of database. It is easily scriptable. As my brother has shown, it is possible to design Leo outlines so that parts of the outline are SQL queries!

Design: With Leo, you always see the big picture, and as many of the details as you like. But this makes outlines ideal for representing designs. In fact, Leo outlines don't just represent designs, they are the designs. For example, all of Leo's source code reside in just a few Leo outlines. There is no need for separate design tools because creating a Leo outlines simultaneously embodies both the design and the resulting code. Furthermore, Leo outlines can also represent input data to other design tools.

Programming: It's much easier to program when the design is always easily visible. Nodes provide the perfect way to organize large modules, classes and functions. Nodes also provide unlimited room to save as many details an notes as you like, without cluttering your overall view of the task, or rather tasks, at hand.

Testing: Leo is a supremely powerful unit-testing framework:

1. You can make node a unit test simply by putting @test at the start of its headline. Leo will then automatically generate all the blah-blah-blah needed to turn the node's script into a fully-functional unit test. Oh yes, the headline becomes the name of the unit test.

2. Unit tests can use data in children of @test nodes. Typical tests put input data in one child node, and the expected results of running the test in another child node. The test simply compares the actual and expected results.

3. You can easily run tests in the entire outline or just in the selected outline. Because tests reside in nodes, you can use clones to organize tests in as many ways as you like. For example, it is trivial to run only those tests that are failing.

Maintenance and support: Leo's ability to contain multiple views of data is precisely what is needed while maintaining any large project. For every new support task and every new bug, a new (plain) task node will contain all the data needed for that task, notes, test data, whatever. Furthermore, when fixing bugs, the task node can contain clones of all classes, methods or functions related to the bug. Fixing a node in the task node fixes the node in the external file! And as always, you can use all of Leo's outlining features (including clones) to organize your task nodes.

Organization everywhere: Have you noticed that Leo's organizational prowess applies to everything? Indeed, you can use outlines and clones in new ways to organize files, projects, data, design, programming, testing, and tasks. Leo doesn't need lots of features--outlines, clones and scripts suffice. The more complex your data, designs, program and tasks, the better Leo is suited to them.

Scripting everything: Let's step back a moment. A single outline can contain databases, designs, actual computer code, unit tests, test scripts and task nodes. But Leo scripts will work on any kind of node. Thus, it is easy to run scripts on anything! Examples:

- Data: The @kind convention for headlines tells scripts what a node contains without having to parse the node's contents. The possibilities are endless.

- Design: scripts can verify properties of design based on either the contents of design nodes or their outline structure.

- Coding: scripts routinely make massive changes to outlines. Scripts and unit tests can (and do!) verify arbitrarily complex properties of outlines.

- Testing: scripts can (and do!) create @test nodes themselves.

- Maintenance: scripts could gather statistics about tasks using simple @kind conventions.


  1. I don't understand what Leo is at all... A video showing a Leo user, using Leo, would be great.

  2. I use Leo for years, simply cannot live without it. I use it for most of my meeting minutes, python/xharbour developments, todo list and so on.

    Recently I make it my Sphinx documentation, adding @rst at the node with a script button, it create the sphinx html page on the fly. Very powerful.

  3. Unfortunately, Saying that just adding @rst to a node takes care of sphinx documentation, hinders more than it helps, since it implies (and I don't if that is correct) that Leo abstracts away all of the detailed configuration required by sphinx, which is a bad thing.

  4. @Flavio Leo's rst handling doesn't "abstract away" anything. You still need, etc.

    @rst just simplifies how you create the rst sources that then get fed to sphinx. For example, go to and click "show source" in the bottom of the left panel. You will see the rst sources created in LeoDocs.leo

    This is all fresh in my mind because I am in the middle of revising Leo's docs.

  5. @Mohamed Ville just created the first Leo video:

    This might help a little :-)

  6. Hi Edward,

    I've followed your stuff since your days of advertising in DDJ (wow, it's been a looong time). I'm a devout Leo user here at my company -- I use it for writing .HTML help files that are translated into .CHM and .PDF (via latex), Python scripts, C code for the parallel programming graduate course I took a while ago, *very* complicated .XSL stylesheets, etc. etc. etc.

    One feature I just love is the ability to clone nodes. It's just *the* essential feature for building multiple-target files (such as help files that are both .PDF and .CHM).

    So...thank you *so* much for your work; it's been beautiful.

  7. @Erik Thanks for these kind words. You are welcome.

  8. Are there ideas to migrate leo to XUL environment with pyxul stuff?

  9. I am new to leo, still learning it. If we have a team, how do we share the leo file among the team member? If multiple member editing the single leo file, do we able to resolve the conflict easily with VCS merge? (When I run Leo for the first time, it has for user identity, I think this should be a feature for multiple user but I not sure how Leo use it, everyone have their own leo script?)

  10. @Shin Guey The usual idea is to keep a reference copy of the .leo file that refers to the common files, represented in the .leo file as @file trees. Individuals can change their own local copy of the .leo files, and everyone can share the external files.

    Please feel free to ask more question on the leo-editor group.

  11. @Flavio Coelho

    "Saying that just adding @rst to a node takes care of sphinx documentation, hinders more than it helps."

    @rst creates sections automatically. That's about it. @rst allows Leo outlines to represent the structure of rST or sphinx documents. This is very useful.

    Of course, one still has to build sphinx docs, but so what? Leo neither helps nor hinders the build step.