Python Leodocumentation

8/12/2019 Python Leodocumentation

1/293

Leo

Release 4.6-b1

Edward K. Ream

July 03, 2009


2/293


3/293

CONTENTS

1 Front Matter 3

1.1 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Leos MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Preface 5

3 What People Are Saying About Leo 7

3.1 Leo is revolutionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.2 Leo is a showcase Python/Tkinter application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.3 Leo is fun, even addicting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.4 Leo is a flexible, powerful IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.5 Leo is a superb outliner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.6 Leo is an excellent PIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.7 Leo extends, completes and simplifies literate programming . . . . . . . . . . . . . . . . . . . . 9

3.8 Leo is a superb documentation tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.9 Leo simplifies the understanding of complex systems . . . . . . . . . . . . . . . . . . . . . . . . 10

3.10 Leo is stable, well designed and well supported . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.11 Longer quotes... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 Chapter 1: Installing Leo 15

4.1 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.2 Leos HOME directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.3 How to install Leo on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.4 Installing Leo on MacOS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.5 Installing Leo on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.6 Tracking the development version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.7 Running Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4.8 Running Leo in batch mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.9 How to install the Aspell spell checker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 Chapter 2: A Tutorial Introduction to Leo 21

5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.2 Unique features of Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.3 Leo for Programmers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6 Chapter 3: Using Outlines 31

6.1 Autocompletion and calltips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.2 Cloning nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.3 Creating and destroying nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.4 Creating and destroying multiple body editors . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.5 Cutting, pasting and deleting nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.6 Dragging nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326.7 Editing body text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.8 Expanding & contracting nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

i


4/293

6.9 Indenting body text automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.10 Marking nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.11 Moving & Reorganizing nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.12 Navigating through the outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.13 Opening URLs automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.14 Resizing panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.15 Undoing operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366.16 Using chapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

7 Chapter 4: Writing Programs in Leo 37

7.1 Overview: the 9 ways of accessing external files . . . . . . . . . . . . . . . . . . . . . . . . . . 37

7.2 Overview: summary of directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

7.3 Reference: all about directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

7.4 Reference: the 9 ways of accessing external files . . . . . . . . . . . . . . . . . . . . . . . . . . 47

7.5 CWEB mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

8 Chapter 5: Using Leos Commands 55

8.1 The minibuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

8.2 The File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

8.3 The Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

8.4 The Outline Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8.5 The Window Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

8.6 The Help Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

9 Chapter 6: Leo and Literate Programming 75

9.1 Why I like Literate Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

9.2 How Leo Improves Literate Programming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

9.3 How Leo Changes the Notion of Literate Programming. . . . . . . . . . . . . . . . . . . . . . . 77

10 Chapter 7: Scripting Leo with Python 79

10.1 Commonly used classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

10.2 Predefined objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8010.3 g.es writes to the log pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

10.4 app.windowList: the list of all open frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

10.5 Getting and setting headline and body text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

10.6 Getting and setting body text directly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

10.7 Ensuring that positions are valid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

10.8 About copying positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

10.9 Traversing outlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

10.10 Updating the screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

10.11 Invoking commands from scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

10.12 Getting settings from @settings trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

10.13 Getting and setting preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

10.14 Functions for finding and changing text from scripts . . . . . . . . . . . . . . . . . . . . . . . . 87

10.15 Functions defined in leoGlobals.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8710.16 Event handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.17 How to make operations undoable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

10.18 Redirecting output from scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

10.19 Writing to different log tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

10.20 Invoking dialogs using the g.app.gui class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

10.21 Inserting and deleting icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

10.22 Customizing panes with different widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

10.23 Working with directives and paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

10.24 Summary of the vnode and position classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

10.25 Creating script buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

10.26 Running Leo in batch mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

10.27 Getting interactive input from scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9810.28 Creating Leo commands - @g.command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

ii


5/293

11 Chapter 8: Customizing Leo 101

11.1 Specifying settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

11.2 Input modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

11.3 Adding extensible attributes to nodes and .leo files . . . . . . . . . . . . . . . . . . . . . . . . . 107

11.4 Specifying Tk options using .leo_xresources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

11.5 Translating Leos menus and messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

12 Chapter 9: History of Leo 109

12.1 Beginnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

12.2 Breakthrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

12.3 Apple and YellowBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

12.4 Borland C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

12.5 Discovering Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

12.6 SourceForge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

12.7 Allowing sentinel lines in derived files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

12.8 Untangling @file is easy! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

12.9 Leo 3.x: Continuous improvement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

12.10 Leo 4.0: Eliminating error recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

12.11 Leo 4.1: The debut of gnxs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11112.12 Leo 4.2: Complete at last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

12.13 Leo 4.3 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

12.14 Leo 4.4 The minibuffer and key bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

12.15 Leo 4.4.4 Improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

13 Chapter 10: Theory of Operation 115

13.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

13.2 Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

13.3 Drawing and events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

13.4 Clones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

13.5 Find and change commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

13.6 Tangle and untangle commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

13.7 Unicode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11913.8 Unlimited undo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

13.9 Key bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

14 Chapter 11: White Papers 121

14.1 Tk is the future of Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

14.2 Why I like Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

14.3 Allocating storage using lifetimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

15 Chapter 12: Plugins 125

15.1 Enabling plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

15.2 Body pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

15.3 Commands & directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

15.4 Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13315.5 Debugging & testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

15.6 External editors & Open With . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

15.7 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

15.8 Guis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

15.9 Icon and status areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

15.10 LeoN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

15.11 Menus & translations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

15.12 Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

15.13 Plugins manager & menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

15.14 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

15.15 Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

15.16 Spell checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14715.17 Text formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

15.18 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

iii


6/293

16 Chapter 13: Writing Plugins 151

16.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

16.2 Support for unit testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

16.3 Turning script buttons into plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

16.4 Important security warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

17 Chapter 14: Leo and ReStructuredText 15517.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

17.2 Power features of @rst trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

17.3 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

17.4 Headline Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

17.5 Using doc parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

17.6 Setting defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

17.7 The code-block directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

17.8 Required cascading style sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

17.9 Notes about rST markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

17.10 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

17.11 Theory of operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

17.12 Controlling the rst3 command from scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16317.13 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

18 Chapter 15: Controlling Syntax Coloring 165

18.1 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

18.2 The colorizers inner loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

18.3 Format of colorizer control files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

18.4 Rule methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

18.5 Syntax coloring settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

18.6 The threading_colorizer plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

19 Chapter 16: Debugging with Leo 177

19.1 Using g.trace and g.pdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

19.2 Settings for winpdb. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17719.3 Debugging scripts with winpdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

20 Chapter 17: Using ZODB with Leo 179

20.1 Configuring Leo to use zodb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

20.2 Initing zodb. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

20.3 Writing data to zodb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

20.4 Defining zodb keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

20.5 Reading data from zodb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

20.6 About connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

20.7 Convenience routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

21 Chapter 18: Leo and Emacs 183

21.1 Controlling Leo from Emacs using Pymacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18321.2 Functions in leoPymacs.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

21.3 The minibuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

22 Chapter 19: Embedding Leo with the leoBridge module 187

22.1 The basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

22.2 Running leoBridge from within Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

23 Chapter 20: Unit testing with Leo 191

23.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

23.2 Using @test nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

23.3 Using @suite nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

23.4 How the unit test commands work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

23.5 @button timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19323.6 @button profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

iv


7/293


8/293

31.1 Major new features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

31.2 Major code reorganizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

31.3 Minor new features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

31.4 New settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

32 Whats New in Leo 4.4.7 and Leo 4.4.8 253

32.1 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25332.2 New and improved plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

32.3 New settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

33 Whats New in Leo 4.4.6 255

33.1 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

33.2 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

33.3 New settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255


34.1 Bug fixed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

34.2 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

34.3 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

34.4 New settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258


35.1 The Great Graph Aha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

35.2 Added support for @auto files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

35.3 New commands for resolving cvs conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

35.4 New kinds of settings trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

35.5 New plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

35.6 Leos core is now compatible with jython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

35.7 Improved prototype for icons in headlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

35.8 Minor improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

35.9 Summary of new commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263


36.1 Important new features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

36.2 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

36.3 New settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

36.4 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266



37.1 A major code reorg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

37.2 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

37.3 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

37.4 New and improved plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

37.5 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27137.6 ZODB scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271


38.1 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

38.2 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273


38.4 New settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

38.5 Improved settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274


39 Whats New in Leo 4.4 277

39.1 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

39.2 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27939.3 Added new convenience methods for scripts and plugins . . . . . . . . . . . . . . . . . . . . . . 280

vi


9/293


39.5 New and improved settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

40 Indices and tables 283

vii


10/293

viii


11/293

Leo, Release 4.6-b1

Contents:

CONTENTS 1


12/293

Leo, Release 4.6-b1

2 CONTENTS


13/293

CHAPTER

ONE

FRONT MATTER

1.1 Acknowledgements

Leo owes much of its visual design to MORE, possibly the most elegant computer program ever written. Leos

clone nodes are inspired by MORE.

The following people have made generous donations to the Leo project: Robert Low, Nic Cave-Lynch.

The following people reported bugs, answered questions, and made suggestions for improving Leo: Alex Abacus,

Shakeeb Alireze, Steve Allen, Bruce Arnold, Chris Barker, Dennis Benzinger, David Boddie, Jason Breti, Eric

Brown, Terry Brown, Darius Clarke, Martin Clifford, Jason Cunliffe, Josef Dalcolmo, Gil Dev, Bill Drissel, Wen-

shan Du, Allen Edwards, Chris Elliot, Dethe Elza, Mark Engleberg, Roger Erens, Stephen Ferg, Tom Fetherston,

Tomaz Ficko, Niklas Frykholm, Fred Gansevles, Jonathan M. Gilligan, Zak Greant, Thomas Guettler, Romain

Guy, Dave Hein, Tiago Castro Henriques, Gary Herron, Steve Holden, Klass Holwerda, Matthias Huening, Robert

Hustead, John Jacob, Paul Jaros, Christopher P. Jobling, Eric S. Johansson, Garold Johnson, James Kerwin, Nicola

Larosa, David LeBlanc, Chris Liechti, Steve Litt, Martin v. Loewis, Robert Low, Fredrik Lundh, Michael Manti,

Alex Martelli, Marcus A. Martin, Gidion May, David McNab, Frank Merenda, Martin Montcrieffe, Will Mun-

slow, Chad Netzer, Derick van Niekerk, Jeff Nowland, Naud Olivier, Joe Orr, Marc-Antoine Parent, Paul Paterson,

Sean Shaleh Perry, Tim Peters, David Priest, Gary Poster, Scott Powell, Bruce Rafnel, Walter H. Rauser, OlivierRavard, David Speed Ream, Rich Ries, Aharon Robbins, Guido van Rossum, David Rowe, Davide Salomoni,

Steven Schaefer,Johannes Schn, Wolfram Schwenzer, Casey Wong Kam Shun, Gil Shwartz, Jim Sizelove, Paul

Snively, Jurjen Stellingwerff, Phil Straus, David Szent-Gyrgyi, Kent Tenney, Jeffrey Thompson, Gabriel Va-

liente, Jim Vickroy, Tony Vignaux, Tom van Vleck, Kevin Walzer, Ying-Chao Wang, Cliff Wells, Dan Wharton,

John Wiegley, Wim Wijnders, Dan Winkler, Vadim Zeitlin.

The following have contributed plugins to Leo:

Rodrigo Benenson, Pierre Bidon, Felix Breuer, Terry Brown, Mike Crowe, Josef Dalcolmo, Michael Dawson, e,

Roger Erens, Andrea Galimberti, Engelbert Gruber, Timo Honkasalo, Jaakko Kourula, Maxim Krikun, Zhang Le,

LeoUser, Frdric Mommja, Bernhard Mulder, Mark Ng, Alexis Gendron Paquette, Paul Paterson, Dan Rahmel,

Davide Salomoni, Ed Taekema, Kent Tenney, Brian Theado, Ville M. Vainio, Steve Zatz.

The following deserve special mention: David Brock wrote TSyntaxMemo. The late Bob Fitzwater kept mefocused on design. Donald Knuth invented literate programming and the CWEB language. Jonathan M.

Gilligan showed how to put the Leo icon in Leos windows. Joe Orr created XSLT stylesheets for Leo;

seehttp://www.jserv.com/jk_orr/xml/leo.htm. Joe Orr also created an outstanding set of tutorials for Leo; see

http://www.evisa.com/e/sb.htm . LeoUser (B.H.) contributed numerous plugins and was the inspiration for Leos

minibuffer. LeoUser also wrote jyLeo: Leo for Jython. Bernhard Mulder proposed a new way of untangling

derived files. John K. Ousterhout created tcl/Tk. Neal Norwitz wrote PyChecker. Marc-Antoine Parent urged me

to use XML for Leos file format and helped improve it. Paul Paterson suggested the plugin architecture, sug-

gested an approach to spell checking and has contributed many excellent plugins. Franois Pinard wrote pymacs.

Norman Ramsey created noweb and gave permission to quote from the noweb web documentation. Rich Ries

has contributed a huge number of suggestions. Steven P. Schaefer pointed out major security problems lurking in

hooks. Gil Shwartz helped with unicode support. Phil Straus has been a great friend and constant support. Guido

van Rossum created Python, Tkinter and the Python License. Dave Winer created MORE. Ville M. Vainio created

ILeo. Dan Winkler helped support Leo on the Mac.

Special thanks to my family. My brother, David Speed Ream, tested Leo and made many useful suggestions.

3
http://www.jserv.com/jk_orr/xml/leo.htmhttp://www.jserv.com/jk_orr/xml/leo.htmhttp://www.evisa.com/e/sb.htmhttp://www.evisa.com/e/sb.htmhttp://www.evisa.com/e/sb.htmhttp://www.jserv.com/jk_orr/xml/leo.htm


14/293

Leo, Release 4.6-b1

Rebecca, James and Linda make it all worthwhile. It was during a conversation with Rebecca that I realized that

MOREcould be used as a prototype for Leo. That was a crucial first step.

1.2 Leos MIT License

All parts of Leo are distributed under the following copyright. This is intended to be the same as the MIT license,

namely that Leo is absolutely free, even for commercial use, including resale. There is no GNU-like copyleft

restriction. This license is compatible with the GPL.

Copyright 1997-2009 by Edward K. Ream. All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated

documentation files (the Software), to deal in the Software without restriction, including without limitation the

rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit

persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the

Software.

THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FIT-

NESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AU-

THORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LI-

ABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN

THE SOFTWARE.

4 Chapter 1. Front Matter


15/293

CHAPTER

TWO

PREFACE

Why, oh why, would anyone be interested in Leo? After all, Emacs and Vim are superb text editors, and Visual

Studio and Eclipse are great IDEs. How can Leo possibly compete with such strong competition? What does Leo

offer that these other tools dont?

Leo does have something unique to offersomething missing from Emacs,Vim, Visual Studio and Eclipse. Leos

users often speak of an Aha! moment when they understand what this something is. The Aha! arises fromconsidering programs, design and data in a new light. You might call this The Leo Way. In essence, Leo

shows that computer programs, designs and data are not, after all, mostly about text. Yes, people usuallyexpress

programs, designs and data as text. Yes, people manipulate programs, designs and data usingtext, but text is not

the whole story.

In The Leo Way, text is simply a manifestation (a shadow) of something more fundamental. That something else

might be called organization or structure or views or even architecture. However, let us use the term node

to represent the fundamental unit of structure in Leo. Well see why in a moment.

In architectural terms, nodes are bricks that make up a building. In computer programming terms, nodes make up

methods, classes, files and entire applications. So the term node doesnothave a fixed meaningit is simply a

unit of organization. Any node can be built from other nodes, and any node can be used by any other node. Leo

represent nodes directly, as nodes (headlines) in an outline. An outline node contains a headline and body text.

Theoutline paneshows all headlines; thebody paneshows the body text of the presently selected node.

Outline structure is real data

To repeat: the fundamental unit in Leo is nottext. True, headlines and body consistof text, but a node is just not

text, it is a true (Python) object. This means several specific things:

1. Because nodes are true objects, Leo commands understand what a node is, and where a node fits into the

entire outline. Ill say more about outline organization soon, but let me give an example. Every node

has exactly one parent node, (except for top-level nodes that have no parents) and every node has zero or

more children and zero or more siblings. A nodes parent, children and siblings are real properties of the

node,completely independentof the nodes headline or body text. Furthermore, any of Leos commands (or

user-written scripts or plugins, the big sisters of user scripts.) can easilyaccess the all aspects of an outline

withouthaving to parse any text whatsoever. Commands, scripts and plugins can easily do the following: getthe root of the outline, the presently selected node in the outline, the parent, siblings, children or descendants

of any node in the outline, etc., etc. Commands, scripts and plugins can easily insert, delete or move nodes,

and can alter the headline or body text in any node. All thiswithoutparsing text.

2. Having nodes be true objects means that commands scripts and plugins can treat the headline text assome-

thing truly different frombody text. The natural interpretation of headline text is as a description of the body

text. This is important! Headlines often control Leos commands. For example, headlines that start with

@thin, @file, @asis, @auto, etc. serve to guide and control Leos read and write commands. Headlines that

start with @test, @suite and @mark-for-unit-tests guide Leos unit testing commands. Moreover, it is easy

to create new conventions for headlines that control user-written scripts or plugins. For example, plugins

define specific meanings for headlines that start with @url, @rst, @bookmark, @slideshow, etc., etc. So

the separation of headline and body text,as true components of a node object, is a very big deal.

3. One application of these ideas deserves special mention. Leos scripting plugin provides support for @but-

ton nodes. The headline is @button . The body text contains a script. When Leo opens

5


16/293

Leo, Release 4.6-b1

a Leo outline, each @button node creates a command and an icon. Clicking the icon (or executing the

command) applies the script in the @button node to the presently selected outline. That is, the script is

executed in a context in which it is easy to get access to all aspects of the outline in which the script is

embedded. This is a major advance in scripting. It allows you to bring scripts to data, i.e., any part of an

outline. In particular, it is very easy to createediting scriptsthat automate what would otherwise be boring

and repetitive editing tasks.

Leo outlines arent your average outline

Earlier I said thatany node can be built from other nodes, andany node can be used by any other node. It takes a

very special kind of outline for this to be possible. In a typical outline, such as Emacs outline mode, for example,

nodes appear exactly once in the outline. This makes it impossible to reuse nodes in multiple places. Leo

removes that limitation: any outline node can be cloned, and clones can appear in as many places in an outline as

you like.

Cloned nodes are distinct: they must be distinct so they can be moved throughout the outline, butcloned nodes

share all their information. That is, changing the headline or body text in a node instantly changes the headline

and body text in all the other nodes cloned to it. Furthermore, similar remarks apply to the children and descen-

dants of any nodechanging any child (or other descendant) of a node, say node A, instantly makes corresponding

changes to all nodes cloned to node A.Earlier I said that you can think of nodes as representing organization or structure or views or even architec-

ture. Clones are the crucial feature that allows this point of view. For example, we can build up multiple views

of data in an outline using clones as follows:

Create a view node that will represent auser-specifiedview.

Clone all nodes that are to be part of the view, and move them so that each clone is a child of the view node.

Thats about all there is to it. The view node, and its children isa new view of the outline. This notion of view is

so important that Leo supports it directly. Leos chaptersare simply views created as I have just described. When

you select one chapter, you only see the nodes of that chapter in Leos outline pane.

Conclusions & encouragements

So Leo offers a new way to understand, organize and manipulate any kind of complex data, including computer

programs,designsof computer programs, web sites, personal data, whatever. The Aha that I invite you to expe-

rience is this: Outlines are more than mere eye candy. Having organization be real data creates an entirely new

dimension, literally and figuratively, in computer programming, computer design and data organization, including

web-site design, database design, etc. Leos commands use headline and body text in many creative ways. So can

you and your scripts. Its easy, its fun, and its revolutionary.

Thats about it, except for some words of caution and advice:

1. Leo has been under active development for over 10 years. The new world created by nodes is rich and

varied. You wont learn it all in a day or so. Please be patient. Start by learning Leos basic features as

explained in the tutorial. You can learn more advanced features later.

2. Those of you who are comfortable with Emacs should feel pretty much at home with Leo. Leo has shame-

lessly stolen the best features of Emacs, including the minibuffer and many Emacs-like commands.

3. For those of you who arenotcomfortable with Emacs, please understand that you donotneed to understand

all of Leos commands in order to use Leo. Start by ignoring the minibuffer. Later, the minibuffer can

become your friend, but you can get the Aha! without it.

Edward K. Ream July, 2007

6 Chapter 2. Preface


17/293

CHAPTER

THREE

WHAT PEOPLE ARE SAYING ABOUTLEO

3.1 Leo is revolutionary

I am using Leo since a few weeks and I brim over with enthusiasm for it. I think it is the most amazing software

since the invention of the spreadsheet.

We who use Leo know that it is a breakthrough tool and a whole new way of writing code. Joe Orr

I am a huge fan of Leo. I think its quite possibly the most revolutionary programming tool I have ever used and

it (along with the Python language) has utterly changed my view of programming (indeed of writing) forever.

Shakeeb Alireza

Thank you very much for Leo. I think my way of working with data will change forever... I am certain [Leo] will

be a revolution. The revolution is as important as the change from sequential linear organization of a book into a

web-like hyperlinked pages. The main concept that impress me is that the source listing isnt the main focus any

more. You focus on the non-linear, hierarchical, collapsible outline of the source code. Korakot Chaovavanich

Leo is a quantum leap for me in terms of how many projects I can manage and how much information I can find

and organize and store in a useful way. Dan Winkler

Wow, wow, and wow...I finally understand how to use clones and I realized that this is exactly how I want to

organize my information. Multiple views on my data, fully interlinkable just like my thoughts. Anon

Edward... youve come up with perhaps the most powerful new concept in code manipulation since VI and

Emacs. David McNab

Leo is...a revolutionary step in the right direction for programming. Brian Takita

3.2 Leo is a showcase Python/Tkinter application

Thanks for a wonderful program everybody should be using it! It blows the socks off that Java Mind mapping

software that won project of the month a while back on sourceforge! Derick van Niekerk.

A few years back I would have said Zope was #1 Python showcase, but I agree 100% that Leo is tops now.

Jason Cunliffe

Leo is the most interesting Python project I know of...I see lots of stuff posted on the Daily Python page, but I

usually yawn and come over to this forum to see whats cooking. Anon

Leo is the best Tkinter application ever written. It convinces me that Tkinter can really do something, and do [it]

well. - Anon

What an original synthesis of different ideas, why cant other Open Source projects change the way I think?

Anon

7


18/293


19/293

Leo, Release 4.6-b1

If you are like me, you have a kind of knowledge base with infos gathered over time. And you have projects,

where you use some of those infos. Now, with conventional outliners you begin to double these infos, because you

want to have the infos needed for the project with your project. With Leo you can do this too, but if you change

text in one place IT IS UPDATED IN THE OTHER PLACE TOO! This is a feature I did not see with any other

outliner (and I tried a few). Amazing! Leo directly supports the way I work! F. Geiger

3.6 Leo is an excellent PIM

Another day, another breakthrough using Leonow I realize Leo is the best URL bookmark manager there is. No

more bookmarks menus or favorites lists inside the browser for me. With the @url directive I can just double click

on the URL to open it in my browser. Leo lets me arrange the URLs in a hierarchy (or multiple hierarchies), attach

notes to them, save clippings of things I read on the sites. Its sooo much better than anything the browsers have

built in and it lets me easily use different browsers on different platforms and different machines (try that with the

browsers built-in bookmark managers). Dan Winkler

I am an amateur photographer. I use plain old 35mm. film for my pictures. Over the weekend, I used Leo to

organize my lists of pictures. It is quite helpfulI can have separate nodes for pictures I have enlarged, as well as

pictures I have submitted to our local camera club. Thanks! Rich ReisCloning is pure genius!... Leos cloning facility, allows me to create several views on the CFA course material.

My main view follows the prescribed study guide. Another view is organized like the textbooks. Yet another gives

me a glossary of terms. And when Im done, Ill have some nice libraries...I can re-use later in other projects.

Michael Manti

3.7 Leo extends, completes and simplifies literate programming

Ive tried Literate Programming tools off and on for more than 10 years, mainly because the promise was so great.

Ive abandoned them every time because working with the various Cweb-like tools was so awkward. Leo changes

all that. The most important benefits promised by Literate Programming are realized by using Leo, without the

awkwardness of the other tools. Dave Hein

[Leo] has enabled me to use Literate Programming in production for the first time. When I figured out I could

do it in plain text and export to DocBook for automated typesetting, I was on my way. Because I only do business

and utility software, I dont need the sophistication of LaTeX markup. Writing the documentation and the code in

the same outline at the same time improves the whole product. Being able to automatically export both with just

two key presses (tangle and export-to-DocBook) is a real luxury. Michael Dawson

I wanted to thank you for the effort youve put into Leo. It looks fantastic. Ive always though that Literate

Programming was a good idea, but the tools were completely un-workable. Bob Hustead

3.8 Leo is a superb documentation tool

Ive written documentation in WordPerfert, Ventura, Word, PageMaker, and FrameMaker and even though they

create wonderfully looking and useful documents, theyve never been able to do what Ive been looking for.

HTML, compiled help files, and later PDF came closer, but still not there...I think Ive found it in LEO, a way to

make a living document. A document built out of discrete parts that can be re-organized on the fly to meet the

needs of a varying audience...Ive already started converting the IT Procedures manual from Open Office to LEO

because I know its going to be much more useful to me and anyone else...just the possibility of keeping system

maintenance scripts in the IT manual is mind boggling. David Nichols

With the help of the rst2 plugin, [Leo is] the best outliner I have yet encountered for writing the early stages of

academic papers.

A Leo file is an ideal documentation tool, collecting the assorted readme.txt files, the comments from the source

files...as well as the config files themselves. Kent Tenney

3.6. Leo is an excellent PIM 9


20/293


21/293


22/293

Leo, Release 4.6-b1

#1 Reason would probably be clone nodes. One node can point to another. Another way of putting this is is that a

leaf can be on more than one tree. For example, suppose you have a list of recipes. You simultaneously put a single

recipe under multiple categories or even multiple hierarchies. You could put 3 bean enchilada simultaneously

under Recipes-Mexican and Food-Gas. Another example would be, if you are a biologist trying to decide under

which genus to put a new species, you could put the species under two simultaneously. In effect, you can build a

3-D tree. For a further illustration see http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htm

#2 Reason would probably be that Leo outlines can be embedded in external text files. So, a Leo outline is

more than an outline, it is a meta-structure that can be added to another text without changing that text, but

rather providing an external road map to the text. Microsoft Word has a text (xml) version with a commenting

convention, so Leo can even be used to add outlines into Word docs, although it isnt set up to do that now. For

example, see http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htmIn this case, the upper window of Leo is

the meta-structure, and the bottom window is the file to which the meta-structure is being applied, viewed one

node at a time.

I may not have made #2 very clear, but it is actually a very useful feature. It takes some getting used to before

one sees all of the possibilities tho. One way to think of it is that Leo allows you to throw external documents into

your outline, and yet the external document remains independent and can still be edited separately.

Some other cool things about Leo which Word doesnt feature: 1. Pure xml output that is easy to transform into

other formats (next version of Word will have true XML format, but not as easy to work with). One consequenceof this is that Leo files can be transformed pretty easily to web pages with their outlining capability intact. 2. Easy

to add features since is programmed in Tk and open source. Maybe your average user cant start hacking on it,

but a surprising amount can be tacked on by flipping through the Tk manual. 3. Free, opensource, multi-platform

4. Leo is scriptable with Python. It should be possible to build a Tickler into Leo using Python scripting, for

example.

3.11.3 Dan Winkler

First of all, kudos to you for the excellent progress youve been making with Leo. I upgraded today after about

three months of using and older version and I was thrilled to see all the great improvements that have happened so

fast. I especially love the ability to go to next clone. I think youre really showing what open source can do and

your current trajectory puts you on track to kick Emacs into the dustbin of computing history.

So today I copied all my data (personal information manager and project management stuff) out of my old outliner

(ThoughtManager, which syncs with and runs on the Palm) and put it into Leo. It took me hours to do it and then

to rearrange it the way I really wanted it. But having the ability to make clones and have different ways to view

my data is, as you know, fabulous. In my case, for personal information and project management things, I used

the flexibility of clones to allow me to see my data in several different views: 1) by project, the logical hierarchical

breakdown by topic, 2) by person, so whenever Im talking to someone I can easily see all the pending items

related to them which may be spread over multiple projects, 3) by priority, so I can see what needs to get done

sooner and what can wait for later and, 4) a special case of priority called Today for the things Im going to

focus on in the coming hours.

Now heres why I dont miss the ability of my old outliner to synch the entire outline with the Palm. It turns out

the main thing I really want in the Palm is the top category Today so all I have to do is have Leo flatten thatone heading into a text file (and it kindly remembers the name and directory of the file I used last time) and then

Im done because Ive told the Palm Hotsync manager that that file should be sent to Palm memo pad every time

I synch. The Palm Hotsync manager does a nice job of sending a text file to the Palm memo pad and even breaks

the file up into multiple memo records if its too big to fit in just one. So that gives me enough to be able to browse

(or full text search) the small amount of data that I really want right inside my Palm (which is also my cell phone).

Quick and dirty but it works.

For times when I want my whole outline with me, Leo wins again because thanks to its cross platform nature I can

take my whole outline with me on my Mac iBook, even though I usually edit it on a Windows PC (which is the

only kind of machine my old outliner would run on). Quite frankly, although my old outliner was able to shoehorn

the whole thing into my palm/cellphone, it was a pain to access it on the small screen and slow processor. Now

when I anticipate Ill need the whole thing, for example when Im going to a meeting, I can put it on my Mac

iBook (under X and Fink for now until Python can do it native under Aqua) and have real, full access to it all.

I think now in addition to being great for programming Leo is also a great PIM. Being able to flatten a strategically

12 Chapter 3. What People Are Saying About Leo
http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htmhttp://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htmhttp://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htmhttp://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htm


23/293


24/293

Leo, Release 4.6-b1

jump out at you from the start of the tables) and Id like a total of all the rows in the table. So I think next year,

instead of having an s-expression that computes the total of one row for me, I think Ill use s-expressions that

generate whole tables, formatted for LaTex, from the underlying data. So Im thinking next year my s-expressions

might look more like this:

@

(table "Widget Related Expenses"("widget insurance" (+

1165.26 1823.70 ; May 2002

123.38 ; June 2002

13.50 ; July 2002

13.21 ; October 2002

55.25 ; November 2002

))

("widget shipping" (+

472.15 651.94 ; May 2002

54 ; June 2002

))

("widget cleaning" (+

165.26 183.70 ; May 2002

123.38 ; June 2002

13.50 ; July 2002

13.21 ; October 2002

55.25 ; November 2002

))

)

@c

The job of that table function would be to return the LaTeX code needed to display a table with the category

names and values, sorted descending by magnitude, with the total displayed. Its sort of a poor mans way of doing

a spreadsheet inside Leo and then making it look great using LaTeX. The idea would be as I wanted to add more

data, Id add it to the s-expression and then reevaluate the whole thing by pasting it into a lisp interpreter and then

copying the result back into the same Leo node for LaTeX to process.

Dan

14 Chapter 3. What People Are Saying About Leo


25/293

CHAPTER

FOUR

CHAPTER 1: INSTALLING LEO

This chapter tells how to install and run Leo.

Important:

If you haveanyproblems installing Leo, please ask for help on Leos help forum:

4.1 System requirements

Leo will work on any platform that supports Python 2.4 or later and Tk 8.4 or later. For Qt ui, Qt 4.4 or newer

(and compatible PyQt) is required.

Download the latest version of Leo fromLeos download page.

Download Python from:http://python.org/

Most installations of Python have Tk pre-installed. If your doesnt, you may download it from:

http://tcl.activestate.com/software/tcltk/

Warning: When building Tcl on Linux, do not specify enable-threads. Only use Tcl with the default

threads not enabled case.

Leo usesPmw(Python Mega Widgets). Leos extensions folder contains a copy of Pmw for use if needed.

Leo first tries to import Pmw normally. If that fails, Leo will use the version of Pmw in the extensions

folder.

4.2 Leos HOME directory

Pythons HOME environment variable specifies Leos HOME directory. See http://docs.python.org/lib/os-

procinfo.htmlfor details.

Leo uses os.expanduser(~) to determine the HOME directory if no HOME environment variable exists.

Leo puts several files in your HOME/.leo directory: .leoID.txt, .leoRecentFiles.txt, and myLeoSettings.leo.

4.3 How to install Leo on Linux

Download the latest version of Leo (a .zip file) fromLeos download page.

Unzip the downloaded .zip file into the unpacked folder in your home directory. The unpacked folder will be

called something like leo-4-5.

You now have two choices:

1. You can run Leo from your home directory. Just add ~/leo-4-5 to your path.

15
http://sourceforge.net/project/showfiles.php?group_id=3458\&package_id=29106http://sourceforge.net/project/showfiles.php?group_id=3458\&package_id=29106http://python.org/http://tcl.activestate.com/software/tcltk/http://pmw.sourceforge.net/http://docs.python.org/lib/os-procinfo.htmlhttp://docs.python.org/lib/os-procinfo.htmlhttp://sourceforge.net/project/showfiles.php?group_id=3458\&package_id=29106http://sourceforge.net/project/showfiles.php?group_id=3458\&package_id=29106http://sourceforge.net/project/showfiles.php?group_id=3458\&package_id=29106http://docs.python.org/lib/os-procinfo.htmlhttp://docs.python.org/lib/os-procinfo.htmlhttp://pmw.sourceforge.net/http://tcl.activestate.com/software/tcltk/http://python.org/http://sourceforge.net/project/showfiles.php?group_id=3458\&package_id=29106


26/293

Leo, Release 4.6-b1

2. You can install leo into /usr/local/lib and /usr/local/bin by running Leos install script as follows:

cd ~/leo-4-4-3-final

chmod u+x install

sudo ./install

The install script will instruct you to add /usr/local/bin to your path. You can, instead, add the following link:

sudo ln -s /usr/local/lib/leo/ /usr/local/lib/python2.5/site-packages/

Now you are ready to run Leo.

4.4 Installing Leo on MacOS X

Installing Leo on MacOS 10.5 (Leopard) is straightforward.

1. MacOS 10.5 comes with Python pre-installed. See http://www.python.org/download/mac/ andhttp://wiki.python.org/moin/MacPython/Leopardfor information about using the latest version of Python.

2. Download and install bzr:

Download bzr fromhttp://bazaar-vcs.org/Download

Install bzr using the file just downloaded.

3. Get Leos sources from Leos trunk:

cd ~

mkdir leo.repo

cd leo.repo

bzr init

bzr branch lp:leo-editorcd leo-editor

4. You can run the tk version of Leo as follows:

python launchLeo.py --gui=tk

5. If you already have Qt and PyQt installed, you can run the qt version of Leo as follows:

python launchLeo.py --gui=qt

6. If you dont have Qt or PyQt installed, you will have to install Qt and PyQt from sources. There does

not seem to be any pre-built binaries.A: You may need to install XCode fromhttp://developer.apple.com/mac/ in order to get a devel-

opment environment.

B: Download and install the sip package, following the direction at

http://www.riverbankcomputing.co.uk/software/sip/download

C: Download the OpenSource Qt libraries for Mac from http://www.qtsoftware.com/downloads

D: At various points along the way you will need to build the sources:

python configure.py

make

sudo make install

16 Chapter 4. Chapter 1: Installing Leo
http://www.python.org/download/mac/http://wiki.python.org/moin/MacPython/Leopardhttp://bazaar-vcs.org/Downloadhttp://developer.apple.com/mac/http://www.riverbankcomputing.co.uk/software/sip/downloadhttp://www.qtsoftware.com/downloadshttp://www.qtsoftware.com/downloadshttp://www.riverbankcomputing.co.uk/software/sip/downloadhttp://developer.apple.com/mac/http://bazaar-vcs.org/Downloadhttp://wiki.python.org/moin/MacPython/Leopardhttp://www.python.org/download/mac/


27/293


28/293

Leo, Release 4.6-b1

1. First, you need to get Bazaar (bzr) fromhttp://bazaar-vcs.org. For windows users we recommend the stan-

dalone installer - the python installer may have problems pushing to Launchpad. Plain bzr installer only

contains the command line version, so you might want to augment that with a friendly GUI - qbzr is rec-

ommended as its the easiest one to install. It provides command like bzr qlog, bzr qannotate

etc.

2. Get Leo from launchpad by doing:

bzr branch lp:leo-editor

And thats it! You can run leo/core/leo.py directly. When you want to refresh the code with latest modifications

from Launchpad, runbzr pull.

If you make modifications to Leo (with the interest in sharing them with the Leo community),

you can check them in to your local branch by doing bzr checkin. Now, to actually request

your changes to be merged to Leo trunk, you need a Launchpad account with RSA keys in place.

There is showmedo video about how to accomplish this in Windows using puttygen and pageant at

http://showmedo.com/videos/video?name=1510070&fromSeriesID=151 .

After your Launchpad account is set up, go to https://launchpad.net/leo-editor, choose Codetab -> Register Branch, select Branch type Hosted and fill in descriptive details about the branch. After that, go

to the branch home page from Code tab again, and copy-paste the push command line to terminal. For example,

for branch:

https://code.launchpad.net/~leo-editor-team/leo-editor/mod_rclick

The push command is:

bzr push bzr+ssh://[email protected]/~leo-editor-team/leo-editor/mod_rclick

You may wish to add remember command line option to bzr push, to direct all future pushes to that location.

Then, you only need to executebzr push.

After your branch is pushed, you can email the Leo mailing list and request it to be reviewed and merged to trunk.

4.7 Running Leo

You can run Leo from a Python interpreter as follows:

import leo

leo.run() # runs Leo, opening a new outline or,

leo.run(fileName=aFileName) # runs Leo, opening the given file name.

Another way to run Leo is as follows:

cd

python launchLeo.py %1

Here are some tips that may make running Leo easier:

Linux The following shell script will allow you to open foo.leo files by typing leo foo:

#!/bin/sh

python launchLeo.py $1

where is the path to the directory containing the leo directory.

Windows If you have associated .leo files with Leo you may run Leo by double-clicking any .leo file. You can

also use a batch file. Put the following .bat file in c:\Windows:

http://bazaar-vcs.org/http://bazaar-vcs.org/


29/293

Leo, Release 4.6-b1

cd

c:\python25\python launchLeo.py %1

where is the path to the directory containingthe leo directory.

This opens the file specified by the first argument (%1).

The first time you start Leo, a dialog will ask you for a unique identifier. If you are using cvs, use your cvs login

name. Otherwise your initials will do. Leo stores this identifier in the file .leoID.txt. Leo attempts to create

leoID.txt in the .leo sub-directory of your home directory, then in Leos config directory, and finally in Leos

core directory. You can change this identifier at any time by editing .leoID.txt.

4.8 Running Leo in batch mode

On startup, Leo looks for two arguments of the form:

--script scriptFile

If found, Leo enters batch mode. In batch mode Leo does not show any windows. Leo assumes the scriptFile

contains a Python script and executes the contents of that file using Leos Execute Script command. By

default, Leo sends all output to the console window. Scripts in the scriptFile may disable or enable this output by

calling app.log.disableor app.log.enable

Scripts in the scriptFile may execute any of Leos commands except the Edit Body and Edit Headline

commands. Those commands require interaction with the user. For example, the following batch script reads a

Leo file and prints all the headlines in that file:

path = r"\leo\test\test.leo"

g.app.log.disable() # disable reading messages while opening the file

flag,newFrame = g.openWithFileName(path,None)g.app.log.enable() # re-enable the log.

for p in newFrame.c.allNodes_iter():

g.es(g.toEncodedString(p.h,"utf-8"))

4.9 How to install the Aspell spell checker

You must install the Aspell package if you want to use Leos Spell tab.

1. Download and install the Aspell package from http://aspell.sourceforge.net/Typically this will create adirectory called Aspell/bin

2. If you are using Python 2.3 or Python 2.4 you must copy a dll from Leos extensions folder to the Aspell/bin

directory. This step is not needed if you are using Python 2.5 or later. Leos extensions folder comes

with two dlls: aspell23.pyd and aspell24.pyd, for Python 2.3 and 2.4 respectively. Make a copy of the

appropriate dll,rename itto be aspell.pyd, and copy the renamed aspell.pyd file to Aspell/bin.

3. Specify the location of the Aspell and Aspell/bin directories using the aspell_dir and aspell_bin_dir settings

in LeoSettings.leo.

4.8. Running Leo in batch mode 19
http://aspell.sourceforge.net/http://aspell.sourceforge.net/


30/293

Leo, Release 4.6-b1



31/293

CHAPTER

FIVE

CHAPTER 2: A TUTORIALINTRODUCTION TO LEO

This tutorial shows you Leos basic features. These features are simple to use, yet they interact with each other

in powerful ways. All Leos features relate in some way to outlines. Indeed, outline structure is significant

everywhere.

Quick start for programmers contains the heart of this chapter. It briefly describes everything a Python programmer

needs to know in order to understand Leos source code. Good style and bad answers common question about

when to use the features described in the quickstart. The section Scripting Leo is an introduction to scripting Leo

with Python. For full details, see Chapter 7: Scripting Leo with Python.

5.1 Introduction

Important: please install Leo before reading this tutorial, If you have any problem, please do ask for help on

Leos help forum.

Now that you have Leo installed, please launch Leo. You should see Leos main window, something like this:Note: the actual contents of the icon area at the top depends on what plugins are active.

21
http://sourceforge.net/forum/forum.php?forum_id=10227http://sourceforge.net/forum/forum.php?forum_id=10227http://sourceforge.net/forum/forum.php?forum_id=10227


32/293

Leo, Release 4.6-b1

5.1.1 Leos main window

The main window represents an entire project and is stored in a single Leo file, a file with a .leo extension. As

you can see, the main window contains three panes: the outline paneat the top left, thelog paneat the top right,

and the body pane at the bottom. The window also contains an icon area at the very top, a status area and a

mini-bufferat the very bottom.

Outline pane & nodes The outline pane shows your project as an outline. The outline contains all your projects

data. An outline consists ofnodes. Nodes have two parts, a headline and body text. The outline pane

shows headlines. Selecting a headline selects the entire node; the nodes body text appears in the body

pane. Theicon box is a small icon directly to the left of the headline text. If a node contains children, a

smaller icon appears to the left of the icon box. This icon contains a + or - symbol. Clicking thisexpansionboxexpands or contracts the node.

Body pane The body pane contains the body text of the node selected in the outline pane. You can control how

Leo shows body text using Leo directives and settings. For example, directives specify whether to syntax

color the body text and whether to wrap the text.

Log pane The log pane contains informational messages from Leo. Scripts and plugins may also write message

to the log pane.

Icon area Depending on what plugins are enabled, the icon area may contain buttons and other widgets that

extend what Leo can do. The scripting plugin makes it easy to add buttons to the icon area.

Status area The status area shows the line and column containing the body texts cursor. Other information may

follow. Usually this is the UNL (Uniform Node Location) that describes the path in the outline to theselected node. Please select nodes at several levels of the outline to see how the UNL changes.

22 Chapter 5. Chapter 2: A Tutorial Introduction to Leo


33/293


34/293

Leo, Release 4.6-b1

@all

in the body text of the @thin node. @allis a Leo directive.

When writing a derived file, Leo writes the body text of the @thin node, replacing the @all directive by the body

text of all the descendant nodes in outline order, the order that nodes appear on the screen when all nodes areexpanded. Leo for Programmers discusses other, more flexible, ways of creating derived files from @thin trees.

Note: Leo copies headlines to the derived file as comments. This means that headlines do not affect the meaning

of derived files and you can use headlines to contain whatever data you wish. Usually, headlines describe whats

in the node.

5.2.2 Clones & views

Acloned nodeis a copy of a node that changes when the original changes. Changes to the children, grandchildren,

etc. of a node are simultaneously made to the corresponding nodes contained in all cloned nodes. A small red

arrow in icon boxes marks clones.

Please take a few moments to experiment with clones. Start with a single node, say a node whose headline is A.

Clone node A using the Clone Nodecommand in Leos Outline menu. Both clones are identical; there is no

distinction between the original node and any of its clones.

Type some text into the body of either node A. The same text appears in the bodies of all other clones of A. Now

insert a node, say B, as a child of any of the A nodes. All the A nodes now have a B child. See what happens if

you clone B. See what happens if you insert, delete or move nodes that are children of A. Verify that when the

second-to-last cloned node is deleted the last cloned node becomes a regular node again.

Clones are much more than a cute feature. Clones allow multiple views of data to exist within a single outline .

The ability to create multiple views of data is crucial; you dont have to try to decide what is the correct view of

data. You can create as many views as you like, each tailored exactly to the task at hand.

To create a new view of the data, just create any ordinarynode. This node willrepresentthe new view. Let us call

it aview node. Now just put any nodes that are related to the view as descendant nodes of your view node. Let

us call the descendants of the view nodes the componentsof the view. Component nodes are typically clones of

other nodes in the outline. This is what gives the view its power: a view can contain nodes gathered from all over

the outline. However, it is also sometimes useful to add non-cloned nodes as components of views.

For example, when I begin to fix a bug I first create a view node to represent the bug. I then create a component

node (not cloned) that contains the original bug report. I may also create other non-cloned nodes to contain notes

and documentation. Next, I go looking throughout Leos code for nodes that relate in some way to the bug. When

I find such a node I clone it and move one of the clones so it becomes a component of the view node for the bug.

Note: I can organize the components of the view node as I please. In particular, I can create organizer nodes

whose only purpose is to contain groups of component nodes. In other words, the full power of Leo outlines is

available within view nodes.

Important: Once I have created the view of the bug, I can concentrate onlyon that view. In particular, I can fix

code by changingcomponentnodes. Because the code nodes are cloned, any changes I make to a component nodealso get made to the other cloned nodes throughout the outline. In effect, my view node for the bug lets me work

only on the nodes of the outline that are directly related to the bug. In other words, the view nodes lets me focus

onlyon the task at hand, and lets me ignore all other details.

Clones are the basis for Leos project management capabilities. Indeed, the ability to create multiple views of a

project is most helpful.

5.2.3 Outline structure is significant everywhere

So far we have been focusing on Leos outline pane: creating and cloning nodes. In fact, outline structure affects

all aspects of Leo. For example:

As mentioned earlier, body text can contain Leo directives that control how Leo works. By default, a Leo

directive applies to a node and all its descendants, but a Leo directive in a descendant node can overridea

24 Chapter 5. Chapter 2: A Tutorial Introduction to Leo


35/293

Leo, Release 4.6-b1

directive in an ancestor node.

Programs in body text can contain optional markup consisting of sections and section references. (See

Quick start for programmers for details.) Leo outlines limits the visibility of such sections: sections must

be defined in a node descending from the node containing the section reference.

You can organize scripts and programs using outlines, and scripts can use outline structure to access data.

Plugins and scripts often confine their effects to the presently selected outline.

5.2.4 Leo directives

Leo directives control such things as syntax coloring, line wrapping within the body pane and the width of tabs.

Leo directives may appear in headlines or body text. Leo directives start with @ in the leftmost column, followed

by the name of the directive. Some examples:

@language python

@tabwidth -4

@wrap

@nowrap

@color

@nocolor

@killcolor

The following directives are useful for non-programmers; Directives for programming lists the directives used for

computer programming.

@color,@nocolorand@killcolorcontrol syntax coloring.

@languagesets the language used for syntax coloring.

@tabwidthsets the width of tabs. Negative tab widths cause Leo to convert tabs to spaces (highly recom-

mended for Python programming.)

@wrapand@nowrapenable or disable line wrapping the Leos body pane.

Note: You can mix @nocolor and @color directives in a single node, but these directives apply to descen-

dant nodes only if they are unambiguous, that is, only if the ancestor node contains exactly one @color or

@nocolor directive.

5.3 Leo for Programmers

The previous sections have discussed the basics of Leo. Non-programmers can stop reading this tutorial now!

The following sections tell how to create derived files that contain computer programs. Yes, you could create

program files using the@alldirective, but the following section explain how you can take advantage ofpower-

user features designed specifically for computer programmers. Even if you dont read manuals, please read the

following short Quick start for programmers section.

5.3.1 Quick start for programmers

@thin trees (parts of the outline whose headlinestarts with @thin) create derived files containing your program.

Within @thin treesyou can writefunctional pseudo-code, like this:

> (in body text)

This is a referenceto asectioncalled >. When writing a derived file, Leo replaces all sectionreferences by their definition. You define sections withsection definition nodes. A section definition node is a

node whose headline starts with a section name:

5.3. Leo for Programmers 25


36/293

Leo, Release 4.6-b1

> (in a headline)

The body text of this node is its definition. For example:

import leo.core.leoGlobals as g

import sys

As you can see, section definitions can befragmentsof code; they dont have to be complete functions or methods.

Notes:

Section definition nodes must be descendants of the node containing the section reference. Leos syntax

colorer underlines undefined section references.

Section definitions may contain references to other sections.

The @othersdirective is a special kind of section reference. Leo replaces the@others directive by the

body text of all descendant nodes exceptsection definition nodes. Thats how @othersgot its name. For

example, the root node of Python derived files typically is something like this:

>

>

@others

The derived file will contain the docstring, followed by the imports, followed by the the body text of all

other nodes in the @filetree, in outline order.

A derived file may contain multiple @others directives: Each @others directive expands to the

Documents

Python Leodocumentation