Installing Leo (Outlining Editor) on Windows, howto

An introduction to Leo

Looking at text editors recently, I found a recommendation for Leo ('Leonine Editor with Outlines', developed by Edward K. Ream).

The (free) programmer's text editor and outliner (see Joe Orr's slideshow, or w/s Leo tutorial) improves software project readability, excitingly -- but it's not only for programmers. Leo is a feature-rich, productivity-increasing tool.

Using outlining is a fresh approach for the world of Literate Programming. It resolves the awkwardness, but easily fulfills the essence: it provides more readability, along with program code colocation with additional explanations, which helps prevent obsolescence.

To start, all you have to do (A) is enter an idea about any section of your text and (B) incrementally develop (in Leo) an outline of your ideas, referring to sections of the text.

Programmers need only (A) enter an idea about any (freely-chosen) section of their source code (e.g., its purpose) and (B) incrementally develop (in Leo) an outline of thoughts, referring to sections of the code.

Additions you make, no matter how few, are a kind of Easy Literate Programming.

Even while using Leo, no other team members will feel impacted, even if they edit the same source files without it. In no way does it hide the project source files inside its own folders or files, and it's compatible with version control systems, such as Git.

How can Leo accomplish this? Leo in a Nutshell explains. Ream's view is worth reading also, on Slashdot.

Leo is fairly mature and ready for use, long having had a 'small but extremely loyal group of users'^[1] in addition to the developer's personal use. Its architecture is extensible by scripting; upwards of 75 interesting plugins have been written. It has borrowed much from Emacs. Some of its voluminous documentation seems obsolete (however) or merely implementation-oriented.

Presumably all Leo needs to know about the languages (even if obscure) used on your project is the syntax of how to form block- and single-line comments.

Leo opens a file by default (normally ~/.leo/workbook.leo, even on Windows) so if you want you can use it as a personal outlining planner.

Clones

Leo's outlines have cloneable nodes (and subtrees), and therefore multiple views. This might be a simple idea; I'll give you two examples.

For any given bug, a tree of relevant files can be collected (and cloned) and focused on without distraction. In the bug tree, as you edit those files, the ordinary hierarchy of files is being updated also (but not by special software). Since the nodes are cloned, you are editing the same files, not merely in essence but in actuality.

Insofar as you make notes briefly while puzzling out a problem or solving a bug, naturally they are entered right there in the place provided: in the bug's file tree (or associated with it). Afterward, you collapse the bug's tree, left behind to help explain the solved bug to future readers (developers) whenever they might need it -- Easy Literate Programming.

To explain something special to developers (readers) of the project, any files or folders (even sections of files) can be clone-arranged into a new tree structure (regardless of the layout of a project's filesystem).

In particular, if you have written about several cross-cutting (e.g., aspect-oriented) concerns (say, a, b and c), or wish to explain them to other developers, then it's good to clone-arrange the relevant files (unless that's all the files) into trees belonging to those concerns, though the files actually reside elsewhere in the project's main organizational filesystem folders (say, w, x, y and z).

It's an alternative to tagged filesystems in a way, but with explanations that grow organically -- it naturally produces a kind of manual, with an outlined table of contents.

Here's how to install Leo on Windows XP in detail (for the non Python-familiar) the way I did, using some installation instructions (or a fuller version) on the website as a basis:

Leo prerequisites

Leo requires Python 3 (or 2). Download and install minimally the latest Python-3 for Windows from Python's official website--I used 'python-3.2.1.msi'--to 'C:\progra\Python32'.

For Python, and Register Extensions, Tcl/Tk and Utility Scripts, pick 'Will be installed on local hard drive'. For Documentation and Test Suite, pick 'Entire feature will be unavailable'.

Download and install minimally the latest binary package for Windows containing QT-4, the 'cross-platform application and UI framework' and Python bindings, PyQT-4 from its developer's website; I used 'PyQt-Py3.2-x86-gpl-4.8.4-1.exe'.

Leo requires 'Qt runtime'. To ease uninstalling later, select 'Start Menu shortcuts'. Unselect everything else, including Documentation, Examples, QScintilla and the developer tools Developer, Qt, and SIP.

When PyQt asks you to specify a 'Python installation folder', give the same folder as above, 'C:\progra\Python32'; the library goes there, in a subfolder.

Installing Leo

Download and install the latest one-click installer for Windows (.exe) of Leo from its download page or possibly here. Click where it says, 'Looking for the latest version'. I used 'LeoSetup-4.9-final-a.exe'.

Leo may complain, 'Python not found,' but that's okay; we'll tell it later.

Leave selected 'Leo', '.leo File Association' and 'Leo Start Menu' and click Next. For 'Destination Folder', give 'C:\progra\Leo-4.9-final' or the equivalent. For Python Folder, give the same folder as above, 'C:\progra\Python32'. Keeping the default Start Menu folder, 'Leo', click Install and Finish.

Open a command line window with Win+ R and go to the Leo program directory with 'cd \progra\leo*'. Type launchLeo.py. It should say something like, 'is Python 3: True', and a little while later (possibly a window) will ask you for, 'an id that identifies you uniquely'. After that, Leo's graphical window should pop up.

From now on, you should be able to start Leo using the Windows Start menu.

Improving usability of Leo

With any folder menu in Windows Explorer, do Tools-Folder Options. Pick the File Types tab; move down and select the row that contains LEO in the Extensions column. Click the Advanced button; uncheck 'Confirm open after download'. Under Actions, make sure 'open' is selected and click the Edit button. Uncheck 'Use DDE' and into the box, 'Application used to perform action', paste:

C:\progra\Python32\pythonw.exe C:\progra\Leo-4.9-final\launchLeo.py "%1"

and click OK. (Double-quotes fix file and folder names that have embedded spaces, e.g. as you know, 'My Documents'.) Click OK again.

Now if you click any Leo file, an instance should be loaded to edit it.

The best documentation to read first is available by means of Menu-Help-Open quickstart.leo.

^[1]Leo (Text editors wiki)

Further introduction

o Leo

Testimonial
Why I love Leo (Dan Rahmel)
What makes Leo special
Manual introduction
Blogpost: Using Leo as a personal information manager (PIM) (J.Tauber)
Leo (text editor) (Wikipedia)
Ream's thoughts on Joe Orr's slideshow
Leo website slideshow
Introductory tutorial

o Solved by Leo

Outliners, trees and meshes (Scott Rosenberg, author of Dreaming in Code, etc.)
Outlines and meshes (Taking Note, an anonymous blog)

o Background: Outliners

Outliners then and now (Scott Rosenberg)
MORE outliner (retrospective/review, ATPM.com)
MORE, dinosaur (retrospective/review, Matt Neuburg)

o Background: Literate Programming

LP (Ward Cunningham wiki)
[LP].com
Software design for engineers and scientists (J.A. Robinson, GoogleBooks from w/s literate programming editor)
LP (PyLit website)
Lightweight LP with example (J.W.Shipman)
LP Workshop (Mac program)
LP is a terrible idea (Matt Giuca)
LP, why? (Bart Childs)
LP to enhance agile methods (Vreda Pieterse: publications)

o Related, vaguely

Tabulator: RDF semantic web browser (Tim Berners-Lee)
Bacon on instruments of the mind (Taking Note)

For more information

o On Leo

All about Leo
More Leo resources
Joe Orr's Leo resource page
Installing Leo on Windows (Matt Wilkie)
Develop in Haskell with Leo

o General

Outliner editor family (Text editors wiki)
Outliners: comparison (Mark Wieczorek)
XP/agile universe (conferences)

Copyright (c) 2011 Mark D. Blackwell.