Python Leodocumentation

Leo
Release 4.6-b1
Edward K. Ream
July 03, 2009
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 exible, 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 simplies literate programming . . . . . . . . . . . . . . . . . . . . 9
3.8 Leo is a superb documentation tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.9 Leo simplies the understanding of complex systems . . . . . . . . . . . . . . . . . . . . . . . . 10
3.10 Leo is stable, well designed and well supported . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.7 Editing body text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.8 Expanding & contracting nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
i
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.16 Using chapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7 Chapter 4: Writing Programs in Leo 37
7.1 Overview: the 9 ways of accessing external les . . . . . . . . . . . . . . . . . . . . . . . . . . 37
7.2 Overview: summary of directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.3 Reference: all about directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.4 Reference: the 9 ways of accessing external les . . . . . . . . . . . . . . . . . . . . . . . . . . 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 Predened objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
10.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 nding and changing text from scripts . . . . . . . . . . . . . . . . . . . . . . . . 87
10.15 Functions dened in leoGlobals.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
10.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
10.28 Creating Leo commands - @g.command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
ii
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 les . . . . . . . . . . . . . . . . . . . . . . . . . 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 les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
12.8 Untangling @le 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
12.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
13.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
15.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
15.17 Text formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
15.18 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
iii
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 155
17.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
17.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 les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
19.3 Debugging scripts with winpdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
20 Chapter 17: Using ZODB with Leo 179
20.1 Conguring Leo to use zodb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
20.2 Initing zodb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
20.3 Writing data to zodb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
20.4 Dening 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
21.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
23.6 @button prole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
iv
24 Chapter 21: IPython and Leo 195
24.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
24.2 Installation and startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
24.3 Accessing IPython from Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
24.4 Accessing Leo nodes from IPython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
24.5 @cl denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
24.6 Special node types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
24.7 Launching ILeo from IPython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
24.8 Declaring custom push-to-ipython handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
24.9 Example code snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
24.10 Example use case: pylab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
24.11 Magic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
24.12 Acknowledgements and history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
25 Chapter 22: Using Vim Bindings with Leo 205
25.1 Vim bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
25.2 Avoiding changes to tag les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
26 Chapter 23: Eliminating sentinel lines with @shadow 213
26.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
26.2 Creating @shadow trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
26.3 What the update algorithm does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
26.4 Aha: boundary cases dont matter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
27 Appendices 217
27.1 Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
27.2 Errors while tangling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
27.3 Errors while untangling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
27.4 Errors while reading @le nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
27.5 Errors while writing @le nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
27.6 Format of .leo les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
27.7 Format of derived les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
27.8 Unicode reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
28 Glossary 225
29 FAQ 229
29.1 Getting Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
29.2 Installing Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
29.3 Learning to use Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
29.4 How should I use Leo with bzr/git/hg/svn/cvs? . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
29.5 Using derived les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
29.6 Customizing Leo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
29.7 Tips and techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
29.8 Trouble shooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
29.9 Unicode issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
30 Whats New in Leo 4.6 247
30.1 Improved unit testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
30.2 Improved le handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
30.3 Improved handling of rST les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
30.4 New code features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
30.5 New command-line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
30.6 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
30.7 New and improved directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
30.8 New settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
30.9 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
v
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
32.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 xed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
35.3 New commands for resolving cvs conicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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.5 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
37.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.1 New commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
39.2 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
39.3 Added new convenience methods for scripts and plugins . . . . . . . . . . . . . . . . . . . . . . 280
vi
39.5 New and improved settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
40 Indices and tables 283
vii
viii
Leo, Release 4.6-b1
Contents:
CONTENTS 1
Leo, Release 4.6-b1
2 CONTENTS
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, Olivier
Ravard, 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 me
focused 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;
see http://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 les. John K. Ousterhout created tcl/Tk. Neal Norwitz wrote PyChecker. Marc-Antoine Parent urged me
to use XML for Leos le 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
Leo, Release 4.6-b1
Rebecca, James and Linda make it all worthwhile. It was during a conversation with Rebecca that I realized that
MORE could be used as a prototype for Leo. That was a crucial rst 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 les (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 OR
IMPLIED, 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
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 from
considering 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 usually express
programs, designs and data as text. Yes, people manipulate programs, designs and data using text, 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, les and entire applications. So the term node does not have a xed 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.
The outline pane shows all headlines; the body pane shows the body text of the presently selected node.
Outline structure is real data
To repeat: the fundamental unit in Leo is not text. True, headlines and body consist of text, but a node is just not
text, it is a true (Python) object. This means several specic things:
1. Because nodes are true objects, Leo commands understand what a node is, and where a node ts 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 independent of the nodes headline or body text. Furthermore, any of Leos commands (or
user-written scripts or plugins, the big sisters of user scripts.) can easily access the all aspects of an outline
without having to parse any text whatsoever. Commands, scripts and plugins can easily do the following: get
the 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 this without parsing text.
2. Having nodes be true objects means that commands scripts and plugins can treat the headline text as some-
thing truly different from body 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, @le, @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
dene specic 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 <command-name>. The body text contains a script. When Leo opens
5
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 create editing scripts that automate what would otherwise be boring
and repetitive editing tasks.
Leo outlines arent your average outline
Earlier I said that any node can be built from other nodes, and any 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, but cloned 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 a user-specied view.
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 is a new view of the outline. This notion of view is
so important that Leo supports it directly. Leos chapters are 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, designs of 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 guratively, 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 are not comfortable with Emacs, please understand that you do not need 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
CHAPTER
THREE
WHAT PEOPLE ARE SAYING ABOUT
LEO
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 nd
and organize and store in a useful way. Dan Winkler
Wow, wow, and wow...I nally 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
Leo, Release 4.6-b1
3.3 Leo is fun, even addicting
When rst I opened Leo, it was out of curiosity. But having used it...Ill never go back. Theyll have to pry Leo
out of my cold, dead ngers! Seriously, it should be renamed Crack Cocaine because its that addictive. Im
ready to start a 12-Step group. Travers A. Hough
I feel addicted to programming again...in fact [Leo] has resurrected a dead project of mine :) The Outline has
proven most liberating in terms of testing ideas out. Anon
I have been absolutely seduced by Leo over the past few days. I tell you, I can not put it down. I feel like a kid
with a shiny new bike...Im already bursting with new ways Id like to use the tool in the future. Lyn Adams
Headley
Thanks for the great workI love Leo!!! Josef Dalcolmo
Leo has simplied updating and creating new scripts and .bats keeping similar information in the same place.
there is almost an addictive withdrawal effect when I can complete an operation in so much less time with Leo &
python than I had become used to. Anon
3.4 Leo is a exible, powerful IDE
[Leo] should either replace or greatly augment the development tools that I use. Zak Greant
Leo is a marriage of outlining and literate programming. Pure genius. The main reason I am impressed with this
tool is that it doesnt affect your choice of tools. You can use whatever IDE for whatever language and switch
back and forth between Leo and it. Austin King
Leo is the best IDE that I have had the pleasure to use. I have been using it now for about 23 months. It has
totally changed not only the way that I program, but also the way that I store and organize all of the information
that I need for the job that I do. Ian Mulvany
I only have one week of Leo experience but I already know it will be my default IDE/project manager...people
complain about the lack of a project manager for the free/standard Python IDEs like Idle. Leo clearly solves that
problem and in a way that commercial tools cant touch. Marshall Parsons
I have been using Leo for about 3 weeks and I hardly use my other programming editor anymore...I nd it easy
and enjoyable to use. I plan to adopt it as my presentation tool for code reviews. Jim Vickroy
Im absolutely astounded by the power of such a simple idea! It works great and I can immediately see the
benets of using Leo in place of the standard at le editor. Tom Lee
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. Dan Winkler
3.5 Leo is a superb outliner
Word outlines are very useful. But Leo makes Word look like a clunky toy. Joe Orr
Leo is an interactive editor for organizing text fragments hierarchically and sequentially into one or more les
and hierarchical folders, without arbitrary limits on the number and size of text fragments and the depth of the
hierarchy...Tangle is a tool for combining hierarchically and sequentially organized text fragments into text les,
hierarchically grouped into folders, with hierarchical or sequential organization of text within the les, and without
arbitrary limits on the size and number of les and the depth of the hierarchy of folders and text nesting within the
les. Alex Abacus
Leo reminds me a great deal of things I loved when I used Userlands Frontier (an outlining cms with a native
oodb) - but Frontier wasnt hackable enough for me, and it wasnt oriented towards coding and literate program-
ming, and you couldnt round-trip rendered pages (big Leo win). This is really a super tool - in a matter of days
Ive started to use it on all my projects and I still havent gured out how I lived without it. John Sequeira
Leo is EXACTLY the kind of outliner I was looking forfantastic job! Steve Allen
8 Chapter 3. What People Are Saying About Leo
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. lm 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 Reis
Cloning 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 simplies 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 benets 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 rst time. When I gured 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 les, 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 y to meet the
needs of a varying audience...Ive already started converting the IT Procedures manual from Open Ofce 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 le is an ideal documentation tool, collecting the assorted readme.txt les, the comments from the source
les...as well as the cong les themselves. Kent Tenney
3.6. Leo is an excellent PIM 9
Leo, Release 4.6-b1
3.9 Leo simplies the understanding of complex systems
Just as structured programming reveals and disciplines the ow control of a program, [Leo] allows the designer to
reveal and discipline structure at many layers simultaneously: data structures, object structure, entity-relationship
structure, client-server structure, design pattern structure, temporal structure, project management structure, and
any other structure relevant to the system. Steven P. Schaefer
A funny observation with Leo is that when I Leo-ise other peoples code, Leo makes the codes structure so
transparent that design faults become very quickly apparent. For example, maintenance pain caused by lack of
factorization. David McNab
Leo is a powerful tool for organizing text into tree structures, and for just generally attacking a number of
problems from a tree-based perspective. Joe Orr
I found this blog entry by someone (a talented former coworker of mine actually) complaining about some poorly
written code she had to maintain: http://snippy.ceejbot.com/wiki/show/start/2003/01/29/001 She said: Youd need
a bulldozer to start refactoring it. That was my cue to write a long message explaining that there is indeed such
a bulldozer and its called Leo. (You can see my message there as a reply to her original posting.) I gave her
my recipe for how to get someone elses messy, scary code into Leo and how to break it down into manageable
chunks. Dan Winkler
Ed, you continue to push the envelope. The amazing thing is that the footprint isnt doubling every few months
like it would be in another designers hands. Adding features by removing constraints, hot refactoring while
adding unit tests. Forget the book. I would pay to see the movie.
3.10 Leo is stable, well designed and well supported
I am extremely impressed at how stable and useful Leo appears to be. Marcus A. Martin
Leo is amazingly stable. Docs are often weak with Open Source Software. Not so Leo: Leo is unusually well
documented. F. Geiger
Leo is unimaginably useful and I always nd new things it already knows(!) how to do. Indeed I am amazed
by the never-ending resources and patience Edward is putting into it and its users community. Excellent. Gil
Shwartz
I feel strongly that Ed Ream, our ever-patient, ever-productive Leo architect deserves a nomination [ for the
ActiveState OpenSource Award] Among other reasons, for:
Delivering the rst usable visual literate programming tool.
Adding a vast abundance of new features.
Making possible a previously unimaginable amount of leverage in code editing.
Eliminating vast amounts of menial programming labour.
Tirelessly and patiently supporting users, and catering to a wide range of feature requests. David McNab
3.11 Longer quotes...
3.11.1 Speed Reams slashdot article
September 3, 2002
Hello, my full name is David Speed Ream. I am known as Speed to friends and enemies alike, but I gladly answer
to David or most any other handle. I am an unabashed and biased fan of Leo, the fact that it was written by my
brother Edward only slightly coloring my already colored glasses. I have been testing and using Leo in software
production for over 4 years. My company currently has over 50,000 lines of code in over 100 source les that are
written using Leo.
Leo, Release 4.6-b1
My comments are from two points of view, the rst being software project manager for a complicated, multi-
module software product, and the second being as a production line coder. For me, Leos greatest and only real
drawback is the learning curve. This learning curve can be shallow is if all that is required is that someone code
using Leo. However, in our company we allocate 40 to 80 hours on top of the normal coding load for someone to
come up to speed on Leo. The ROI (return on investment) is calculated by me to be on the order of 3 months. So
if I hire a consultant for less than 3 months, I dont teach him Leo, even though all source code in our company
must reside in Leo les for the reasons I wont go into now.
I consider that my coders are 15 to 30 percent more efcient in their daily operations than my competitions
people. This indefensible claim of mine is based on the changes in my productivity as Leo grew from a test
document production tool to the primary production method for all our assembly, c and cpp source code.
Personally, I hate to deal with documentation when I write code, except:
1. When I am rst sitting down to solve a new problem. Then the documentation becomes quite long-winded
and ponticatory, as if I were the only one on earth smart enough to solve the problem - or
2. When I come back to code I or someone else has written and nd the documentation insufcient to under-
stand the code without study (seems to be most of the time).
So I do not require my engineers or myself to do a great job of documentation, nor do I use Leo for that purpose.
Rather, it is Leos outlining and organizing ability, and Leos ability to create source les from within the outline
that give me what I think is a tremendous competitive advantage. Each of my companys products run on all
versions of windows from Win 3.1 to XP. In our agship software piece, there are ten main modules, and each
module is maintained by one single Leo le. In the CODEC module, one Leo le named compress.leo organizes
and creates seven .asm les, forty-four .c les, twenty .h les, two .def les, four .mak les, etc. etc. etc. This one
le can be checked out from source code control and given to an engineer for the addition of a new feature.
In it are contained all the known issues for the CODEC, each issue arranged in its own clone section. One clone
section groups together every routine, variable or type denition that must change between different versions
of Windows. These sections could be from six different c source les, two assembly les, and eight .h les.
Another clone section groups together those sections relating to memory problems, which change according to
the memory conguration and TSR conguration (or lack thereof) on the target machine. Another clone section
groups sections that fail (or dont fail) if the routine in question was accidentally run during the dreaded interrupt
time. Another clone section is a section containing clones, each of which is named after the major bug that was
xed when the engineer who xed the bug grouped a bunch of routines, denitions, etc. together to x the bug.
None of the above clone sections was designed into the document. Just the opposite happens. When the codec
was rst written, there was just a single Leo le with a bunch of sections for each c routine or assembly module. As
the product grew and was tested on various platforms, each failure of the module was organized into clones each
time a failure was xed. This is what I call SELF DOCUMENTING CODE. This has nothing to do with me
sitting and documenting anything. Its just that the STRUCTURE of a bug x (or product enhancement) lives on
long after the coding is done, as long as no one is foolish enough to delete the cloned sections that DOCUMENT
what happened.
In actual practice, this organizational history is so powerful that I cant begin to describe it. A REVERSE
LEARNING CURVE happens when an engineer gets a Leo le that already has the interrupt time sensitive
routines grouped together by the last unfortunate soul who had to work on them. There may not be any more
written documentation, but the knowledge contained in the structure can be breathtaking. It is certainly time
saving. I nd this particularly true in my own case. Often Ill look at some code that seems totally unfamiliar and
think what idiot wrote this crap. Then Ill look at the version control comments and realize that I wrote the crap.
Then for sure I know the documentation is non-existent, but the clones I used to develop it are still there, and they
always serve to refresh my memory in an indescribable way.
Enough of this commentary, I just looked at the clock. Best wishes to anyone willing to try Leo for a week. I hope
you will be glad you did.
3.11.2 Joe Orr
The Word outlines are very useful. But Leo makes Word look like a clunky toy.
3.11. Longer quotes... 11
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 les. 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.htm In this case, the upper window of Leo is
the meta-structure, and the bottom window is the le 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 consequence
of this is that Leo les 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 ipping 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 exibility 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 atten that
one heading into a text le (and it kindly remembers the name and directory of the le I used last time) and then
Im done because Ive told the Palm Hotsync manager that that le should be sent to Palm memo pad every time
I synch. The Palm Hotsync manager does a nice job of sending a text le to the Palm memo pad and even breaks
the le up into multiple memo records if its too big to t 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 atten a strategically
Leo, Release 4.6-b1
chosen portion of the outline into a known le name that the Palm synch manager has been told to send to the
Palm on every synch does the trick for me. I wonder if you would consider something like an @atten directive
so I can have that done automatically for me every time I save my outline? For now its up to me to atten the
node I want manually, although once Ive done that the transfer to the Palm is automatic.
Youre my hero! Thank you so much.
3.11.4 Dan Winkler 2
Another day, another breakthrough using Leo now 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).
When using Leo as a project manager and personal information manager as I do I can heavily annotate every task
and project with helpful and relevant URLs. And since URLs can be of the file:// form, theyre not just for
web pages or HTML documents; I can link to any le on my disk of any type to be opened by any program.
Leo is a quantum leap for me in terms of how many projects I can manage and how much information I can
nd and organize and store in a useful way. Im a data-mining army of one now and the web is my playground.
Every time I nd a web page that has interesting links to others, those links get stored in my Leo outline too, right
where I can nd them and make practical use of them. I can easily accept dozens of valuable links every day and
integrate them into what Im doing in a way that Im condant they wont get lost or forgotten. Before I always
used to get bogged down by the difculty of managing bookmarks inside the browser. But now Im no longer the
victim of information overload buried in the knowledge landslide of the Internet; instead Im the professional strip
miner with the worlds biggest bulldozer. I eagerly plunge into mountains of data and emerge with all the valuable
information nuggets neatly stored and organized. And my storehouse of knowledge is a exible thing where I can
reorganize and prioritize and massage the data to my hearts content as I learn more about it and decide to use it
in different ways for different purposes. Its the difference between the pick axe and the steam shovel for me.
3.11.5 Dan Winkler 3
This year my accountant is getting a beautiful printout generated by LaTeX and Leo. I have a complicated tax
situation this year, but I got it all laid out and organized in Leo. Then I had each of the nodes that had something
my accountant needs to see write the data out to a le in the form a LaTeX table.
Sometimes a row of a table would have a result that was calculated by adding up a list of numbers. For that I used
the modern day equivalent of an adding machine paper tape I stored a lisp s-expression in a Leo comment. I
like s-expressions for this because once I put the opening (+ on one line and the closing ) on another line, I
can ll in additional numbers just by typing them and can even annotate them with comments. So in the middle
of generating a LaTeX le I might have something like this:
@
(+
1165.26 1823.70 ; May 2002
123.38 ; June 2002
13.50 ; July 2002
13.21 ; October 2002
55.25 ; November 2002
)
@c
Thats an annotated record of how I arrived at the number the accountant will actually see. I can just paste it into
any lisp or scheme interpreter and get the total. Adding additional numbers is easy.
For next year, I think I might take this a step further. What I did this year is good for adding up numbers to get a
total for one row of a LaTeX table. But it turns out Id also like some more processing done on those tables (which
I had to do by hand this time) Id like the rows sorted in reverse order by magnitude (so that the big numbers
3.11. Longer quotes... 13
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
CHAPTER
FOUR
CHAPTER 1: INSTALLING LEO
This chapter tells how to install and run Leo.
Important:
If you have any problems 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 from Leos 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 uses Pmw (Python Mega Widgets). Leos extensions folder contains a copy of Pmw for use if needed.
Leo rst 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 species Leos HOME directory. See http://docs.python.org/lib/os-
procinfo.html for details.
Leo uses os.expanduser(~) to determine the HOME directory if no HOME environment variable exists.
Leo puts several les 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 le) from Leos download page.
Unzip the downloaded .zip le 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
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/ and
http://wiki.python.org/moin/MacPython/Leopard for information about using the latest version of Python.
2. Download and install bzr:
Download bzr from http://bazaar-vcs.org/Download
Install bzr using the le just downloaded.
3. Get Leos sources from Leos trunk:
cd ~
mkdir leo.repo
cd leo.repo
bzr init
bzr branch lp:leo-editor
cd 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 from http://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
Leo, Release 4.6-b1
4.5 Installing Leo on Windows
Leo is distributed at present only as a .zip le.
Another way is to append the path to the unpacked folder to the Windows PYTHONPATH environment variable.
Now that you have installed Leo and told Python where to nd Leo, you are ready to run Leo.
Note: If you havent already created a HOME environment variable, it would be good to dene home to be
%USERPROFILE%My Documents. You can check whether HOME exists by typing echo %HOME% (with-
out the quotes) in a console window.
4.5.1 Installing Qt on Windows
For Windows, install PyQt using the binary installer at http://www.riverbankcomputing.co.uk/software/pyqt/download
4.5.2 How to associate Leo with .leo les on Windows
Leo will open .leo les automatically provided that you associate leo.py with .leo les. Here is how to open Leo
when double-clicking a .leo le on Windows 2K or XP:
In Windows 2K or XP, go to Start->Settings->Control panel, open the Folder Options
tab.
Select the file types tab. Press the New button.
Enter Leo into the Create New File Extension eld. Press OK.
With Leo still highlighted in the Registered File Types list box, press the Advanced button.
Change the default le type eld to something like Leo Literate Outline.
Press the Icon button and browse to the LeoDoc icon in Leos Icons folder.
Click OK. This gets the icons right and registers the description of the .leo le.
You now have to tell windows what to do to open the le properly:
Press the new button to open the New Action window.
In the Action eld type Open, then type one of the following lines:
<python install dir>\pythonw.exe <path-to-unpacked-folder>\launchLeo.py "%1"
<python install dir>\python.exe -i <path-to-unpacked-folder>\launchLeo.py "%1"
Important: <path-to-unpacked-folder> refers to the full path to the directory with a name like Leo-x-y, where x
and y are version numbers. This unpacked folder must contain a folder called leo.
Important: The -i option is not valid when using pythonw.exe. Any call to pythonw -i will cause pythonw.exe to
exit immediately.
The rst line opens Leo les with no console window. The second line opens Leo les with a console window and
leaves the window open after Leo exits. You should now be able to double click on a leo le in explorer with Leo.
4.6 Tracking the development version
Many users will want to track the development version of Leo, in order to stay on top of the latest features and
bugxes. Running the development version is quite safe and easy, and its also a requirement if you want to
contribute to Leo.
4.5. Installing Leo on Windows 17
Leo, Release 4.6-b1
1. First, you need to get Bazaar (bzr) from http://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:
And thats it! You can run leo/core/leo.py directly. When you want to refresh the code with latest modications
from Launchpad, run bzr pull.
If you make modications 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 Code
tab -> Register Branch, select Branch type Hosted and ll 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://my_name@bazaar.launchpad.net/~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 execute bzr 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 <path-to-launchLeo.py>
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 les by typing leo foo:
#!/bin/sh
python <leopath>launchLeo.py $1
where <leopath> is the path to the directory containing the leo directory.
Windows If you have associated .leo les with Leo you may run Leo by double-clicking any .leo le. You can
also use a batch le. Put the following .bat le in c:\Windows:
Leo, Release 4.6-b1
cd <path-to-leo>
c:\python25\python <path-to-leo>launchLeo.py %1
where <path-to-leo> is the path to the directory containing the leo directory.
This opens the le specied by the rst argument (%1).
The rst time you start Leo, a dialog will ask you for a unique identier. If you are using cvs, use your cvs login
name. Otherwise your initials will do. Leo stores this identier in the le .leoID.txt. Leo attempts to create
leoID.txt in the .leo sub-directory of your home directory, then in Leos cong directory, and nally in Leos
core directory. You can change this identier 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 le 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.disable or 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 le and prints all the headlines in that le:
path = r"<path-to-folder-containing-the-leo-folder>\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 a
directory 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 it to be aspell.pyd, and copy the renamed aspell.pyd le 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
Leo, Release 4.6-b1
CHAPTER
FIVE
CHAPTER 2: A TUTORIAL
INTRODUCTION 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 signicant
everywhere.
Quick start for programmers contains the heart of this chapter. It briey 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
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 le, a le with a .leo extension. As
you can see, the main window contains three panes: the outline pane at the top left, the log pane at 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-buffer at 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 of nodes. 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. The icon 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 this expansion
box expands 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 the
selected 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
Leo, Release 4.6-b1
Mini-buffer It is used like the Emacs mini-buffer to invoke commands. For full details, see Chapter 5: Using
Leos Commands.
Now that we are familiar with Leos main window, lets see how to use Leo as a simple outliner.
5.1.2 Using Leo as an outliner
You can use Leo as fairly typical outliner. Play around with some of the commands from the Outline menu:
Click the expansion box of nodes to show and hide their children.
The Insert Node command (Ctrl+I) inserts a new headline into the outline.
The Cut Node command (Ctrl+Shift+X) deletes a headline and all its children, and copies the struc-
ture to clipboard - ready to paste with Paste Node command (Ctrl+Shift+V). Use Copy Node
command (Ctrl+Shift+C) to copy node to clipboard without deleting it from outline. Copy-paste com-
mand family works across different Leo documents.
The Move Up (Ctrl+U), Move Down (Ctrl+D), Move Left (Ctrl+L) and Move Right
(Ctrl+R) commands move the currently selected node, along with all its descendants.
The Promote (Ctrl+}) command makes all the children of a headline siblings of the headline. The
Demote (Ctrl+{) command makes all following siblings of a headline children of the headline.
Move around the tree and expand/collapse nodes by pressing Alt + arrow keys. This also moves the focus
to tree, so, after pressing Alt + arrow, you can move around by using arrow keys alone. Return the focus to
the body control by pressing Enter.
To edit the headline, use press Ctrl+H. This works regardless of whether body or headline has focus.
Well discuss the Clone Node command in the next section.
You enter body text for any node by selecting the nodes headline in the outline pane and then typing in the body
pane. Leo has a full range of editing commands that apply to the body pane.
5.2 Unique features of Leo
So far we have discussed features that Leo shares with other editors and outliners. The following sections explain
what makes Leo unique.
5.2.1 Derived les
You dont have to store all outline data in Leo (.leo) les. Leo allows you to store outline data in external les
called derived les. This is useful for creating programming les, documentation les such as LaTeX les, and
web pages.
Important: You can edit derived les outside of Leo. Leo will update the outline to reect those changes when
Leo next opens the outline.
It is easy to create derived les; just put @thin lename in a headline. That creates an @thin node. The @thin
tree (the @thin node and all its descendants) corresponds to the derived le lename. Leo writes a derived le
corresponding to the @thin tree to your hard drive when Leo saves your outline (.leo le). When opening a .leo
le, Leo reads all the derived les corresponding to @thin nodes in the outline.
A good rule of thumb is to use @thin nodes unless you have a specic reason to do otherwise. See Chapter 4:
Writing Programs in Leo for a full discussions of the various ways of creating derived les.
Important: You must tell Leo the order in which to write data from the @thin tree to the derived le. The
simplest way to specify the contents of a derived le is to insert:
5.2. Unique features of Leo 23
Leo, Release 4.6-b1
@all
in the body text of the @thin node. @all is a Leo directive.
When writing a derived le, 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 are
expanded. Leo for Programmers discusses other, more exible, ways of creating derived les from @thin trees.
Note: Leo copies headlines to the derived le as comments. This means that headlines do not affect the meaning
of derived les and you can use headlines to contain whatever data you wish. Usually, headlines describe whats
in the node.
5.2.2 Clones & views
A cloned node is 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 Node command 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 ordinary node. This node will represent the new view. Let us call
it a view 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 components of 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 x a bug I rst 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 nd 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 only on that view. In particular, I can x
code by changing component nodes. Because the code nodes are cloned, any changes I make to a component node
also 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
only on 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 signicant 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 override a
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 dened 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 conne 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, @nocolor and @killcolor control syntax coloring.
@language sets the language used for syntax coloring.
@tabwidth sets the width of tabs. Negative tab widths cause Leo to convert tabs to spaces (highly recom-
mended for Python programming.)
@wrap and @nowrap enable 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 les that contain computer programs. Yes, you could create
program les using the @all directive, but the following section explain how you can take advantage of power-
user features designed specically 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 headline starts with @thin) create derived les containing your program.
Within @thin trees you can write functional pseudo-code, like this:
<< imports >> (in body text)
This is a reference to a section called << imports >>. When writing a derived le, Leo replaces all section
references by their denition. You dene sections with section denition nodes. A section denition node is a
node whose headline starts with a section name:
5.3. Leo for Programmers 25
Leo, Release 4.6-b1
<< imports >> (in a headline)
The body text of this node is its denition. For example:
import leo.core.leoGlobals as g
import sys
As you can see, section denitions can be fragments of code; they dont have to be complete functions or methods.
Notes:
Section denition nodes must be descendants of the node containing the section reference. Leos syntax
colorer underlines undened section references.
Section denitions may contain references to other sections.
The @others directive is a special kind of section reference. Leo replaces the @others directive by the
body text of all descendant nodes except section denition nodes. Thats how @others got its name. For
example, the root node of Python derived les typically is something like this:
<< docstring >>
<< imports >>
@others
The derived le will contain the docstring, followed by the imports, followed by the the body text of all
other nodes in the @file tree, in outline order.
A derived le may contain multiple @others directives: Each @others directive expands to the body
text of all descendant nodes, excluding any nodes (and their descendants) that contain other @others
directives. In practice, using @others is easy.
You may precede section references (including the @others directive) with whitespace. When expanding
the section references, Leo inserts the preceding whitespace before every expanded line. For example, the
following will work properly in Python:
if path:
<< create or recreate temp file as needed >>
You now know enough to understand Leos source code. Hurray! The following sections discuss some relatively
minor details. However, I recommend reading Good style and bad; you might save yourself some extra work.
@auto trees allow you to edit derived les that do not contain sentinels. Leo imports such derived les every time
Leo reads the .leo le.
5.3.2 Beginners reference guide
This section covers all the details of programming with Leo that beginners are likely to need. Chapter 4: Writing
Programs in Leo is the full reference guide. I recommend avoiding that chapter until you have been programming
with Leo for some time.
Syntax of section names
A section name has the form:
<< any text >>
Any text is just that: any sequence of text not containing >>. For example:
Leo, Release 4.6-b1
<< initialize ivars >>
Leo ignores case and whitespace in section names, so the following are all equivalent:
<< Peanut Butter & Jelly >>
<< peanut butter&jelly >>
<<peanut butter & jelly>>
<<peanutbutter&jelly>>
<<PEANUTBUTTER&JELLY>>
When << and >> are not paired on a line, they are treated as ordinary << and >> characters. Leo has no escape
mechanism for section names. That is, paired << and >> characters on the same line always denote a section
name, even within comments and strings. This means that << and >> characters that do not delimit a section name
must be placed on separate lines. In practice, this requirement seldom causes problems.
The syntax of section names is based on Norman Ramseys noweb markup language, but without nowebs escape
conventions. Eliminating these escape conventions may seem odd, but it has turned out to be one of the best design
decisions I ever made.
Code and doc parts
Doc parts are blocks of text that Leo treats as comments. Leo syntax colors doc parts as comments, and Leo
converts doc parts into comments in derived les. Doc parts start with an @ directive and continue until an @c
directive or the end of the body text. For example:
@ This is a comment in a doc part.
Doc parts can span multiple lines.
The next line ends the doc part
@c
Doc parts are entirely optional; you could simply use comments in the language specied by the @language
directive. Using doc parts for lengthy comments is convenient, however. Not only do you not need to specify
comment delimiters, but Leo breaks doc parts into lines automatically. The @pagewidth directive species the
width of those lines.
Notes:
In body text, everything not in a doc part is in a code part. If a node does not contain a doc part, the entire
body text is a code part.
@doc is a synonym for @ and @code is a synonym for @c. However, @ and @c are preferred.
A doc part of the form:
@ %def identifiers
declares that the preceding code part contains the list of identiers. Whitespace separate the identiers; everything
else is taken to be the identiers. This construct is a convention of the noweb language, and will be of use only for
those who want to create .nw output les for use with the ofcial noweb system.
Directives for programming
The following directives are commonly used by Leo programmers. See Chapter 4: Writing Programs in Leo for
full details.
@ Starts doc parts (and ends code parts).
@all Copies all descendant nodes to the derived le.
Leo, Release 4.6-b1
@c Starts code parts (and ends doc parts).
@encoding Sets the Unicode encoding used in derived les.
@rst Forces lines to appear before the rst sentinel of a derived le.
@language Sets the language used for syntax coloring and sets the comment delimiters used in sentinel
lines and in doc parts.
@last Forces lines to appear after the last sentinel of a derived le.
@lineending Species the line ending to be used in derived les.
@others Copies all nodes except section denition nodes to the derived le.
@pagewidth Sets the page width used to break doc parts into lines.
@path Sets the path to be prepended to lenames in descendant @file nodes.
Important: Leo treats lines starting with @ as a normal code line unless the @ starts a Leo directive. In particular,
Leo will output Python decorators correctly, provided the name of the decorator is not a Leo directive.
Orphan nodes
An orphan node is a descendant of an @thin node that will not be copied to the derived le. Orphan nodes can
arise because an @thin tree has no @others or @all directives. Sections that are dened but not used also
create orphan nodes. Leo issues a warning when attempting to write an @thin tree containing orphan nodes, and
does not save the derived le. Instead Leo saves the information in the @thin tree in the .leo le. No information
is lost; Leo will load the @thin tree from the .leo le the next time Leo opens the .leo le.
Sentinel lines
When writing derived les, Leo stores information about the outline structure in special comments called sentinel
lines. Sentinel lines are comment lines with @ following the comment delimiter. For example, here are some
actual sentinel line for the derived le containing Python code:
#@+leo-ver=4-thin
#@+node:ekr.20031218072017.2794:@thin leoColor.py
#@@language python
#@@tabwidth -4
#@@pagewidth 80
#@-node:ekr.20031218072017.2794:@thin leoColor.py
#@-leo
You must not change sentinel lines when editing a derived le in another editor! Doing so will corrupt the
derived le and make it impossible for Leo to read it normally. If you do accidentally alter a sentinel line, dont
panic! Leos Import Derived File command can recover information from corrupted derived les.
The main difference between @le trees, @thin trees (and other kinds of trees that create derived les) is the kind
of sentinel lines that Leo writes:
Sentinels in les derived from @thin reduce spurious cvs conicts by marking each node with unique,
unchanging timestamp as shown above.
Sentinels in les derived from @le are as friendly as possible for human readers.
Files derived from@nosent have no sentinels at all. Important: without sentinels Leo can not automatically
update @nosent trees from changes made in external editors.
Chapter 4: Writing Programs in Leo discusses the various ways of creating derived les. This is a highly complex
subject: you should ignore these details at rst. Just use @thin to create your derived les.
Leo, Release 4.6-b1
Leo and literate programming
Leo can support a style of programming similar to Literate Programming (LP). LP has a bad reputation in some
quarters. Thats too bad; Leo xes all the problems with traditional LP. See Chapter 6: Leo and Literate Program-
ming in Leos Users Guide for more details. Please dont let the words Literate Programming get in the way of
your using Leo effectively. That would be your mistake, and a big one.
5.3.3 Good style and bad: sections vs. @others
Newcomers to Leo frequently ask when to use the @others directive and when to use sections. It is good style to
use section references only when the order of text within a derived le matters. For example, Python programmers
put docstrings and imports at the start of les. So the body text of @le nodes typically look something like this:
<< docstring >>
@language python
@tabwidth -4
<< imports >>
@others
This ensures that the docstring is rst in the le, followed by imports, followed by everything else. Note that the
order in which functions are dened in a le, or methods dened within a class, typically does not matter. Thus,
it is good style to dene classes like this:
class myClass:
<< class attributes >>
@others
It would be bad style to dene a class like this:
class myClass:
<< class attributes >>
<< method 1 >>
<< method 2 >>
...
Not only does this over-specify the order in which methods are dened, but it requires lots of extra typing. Not
only must you add a line for each method, but headlines must contain section names such as << method 1 >>,
<<method 2>>, etc. When using @others it is good style simply to put the name of each method in the headline.
A few more words about style:
It is good style to put each class, function or method in its own node. This makes it easy to see the shape
of your code.
It is good style to use organizer nodes to group related functions or methods. An organizer node has no
content except maybe for comments. Like this:
+ myClass
+ birth and death
+ __init__
etc.
+ getters
etc.
+ setters
etc.
+ misc methods
etc.
(In this notation, + denotes a headline.) This organization is far superior to using hideous comments like:
Leo, Release 4.6-b1
###########
# Getters #
###########
It is bad style to use @others in organizer nodes. There is no need to do so.
It is bad style to use @others when order does matter. The reason is that it is very easy to move nodes in a
tree by mistake, say by alphabetizing nodes. One wants to make the meaning of a derived le immune from
such movements.
One last word about style. The world wont end if you happen to use bad style by mistake: you just might cause
a bit more work for yourself than was strictly necessary. Feel free to invent your own style of using Leo. Still, it
would be wise to know the rules before you break them.
5.3.4 Scripting Leo
Leo is fully scriptable using the Python language. Leo can execute any body text as a Python script. To run the
entire body text as a script, simply choose the node and execute the Execute Script command (Ctrl+B). If
text is selected, the Execute Script command will run just the selected text as the script.
The Execute Script command preprocesses the script before executing it. Leo preprocesses scripts in ex-
actly the same way that Leo writes derived les. That is, Leo expands section references and processes @others
directives before executing the script. This allows you to use all of Leos normal capabilities to organize your
scripts. Note: test.leo contains dozens of examples of using Leo outline structure to organize stand-alone
scripts.
Your Python scripts can easily access data in an outline. For example, the following script will print all the
headlines in an outline:
for p in c.allNodes_iter():
print
*
p.level(),p.h
Your scripts can use outline structure to avoid having to parse data. With a little forethought you can arrange
outlines to make scripts easier to write. The example above is only the beginning of what scripts can do. See
Chapter 7: Scripting Leo with Python for a complete discussion of scripting.
5.3.5 Plugins & settings
Plugins are Python modules that change how Leo works, yet are not part of Leos core code. Leos user
have contributed dozens of plugins that have extended Leos capabilities in many new directions. The le
leoPlugins.leo contains all plugins that are included in Leo distributions.
Plugins and other parts of Leo can get options from @settings trees, outlines whose headline is @settings.
When opening a .leo le, Leo looks for @settings trees in the outline being opened and also in various
leoSettings.leo les. @settings trees allow plugins to get options without any further support from
Leos core code. For a full discussion of @settings trees, see Chapter 8: Customizing Leo.
5.3.6 Further study
LeoPyRef.leo (in the core subdirectory of the leo folder) contains almost all of Leos source code. It provides
hundreds of examples of everything discussed here. This le will repay close study. For full details on all aspects
of Leo see LeoDocs.leo or Leos Users Guide.
CHAPTER
SIX
CHAPTER 3: USING OUTLINES
This chapter tells how to use Leos outlines.
6.1 Autocompletion and calltips
Typing a period when @language python is in effect starts autocompletion. Typing ( during autocompletion
shows the calltip. Typing Return or Control-g (keyboard-quit) exits autocompletion or calltips.
Autocompletion
Autocompletion shows what may follow a period in code. (Actually you can specify any character using the
auto-complete shortcut setting.) For example, after typing g. Leo will show a list of all the global functions in
leoGlobals.py. Autocompletion works much like tab completion in the minibuffer. Unlike the minibuffer, the
presently selected completion appears directly in the body pane.
A leading period brings up Autocomplete Modules. (The period goes away.) You can also get any module
by typing its name. If more than 25 items would appear in the Autocompleter tab, Leo shows only the valid
starting characters. At this point, typing an exclamation mark shows the complete list. Thereafter, typing further
exclamation marks toggles between full and abbreviated modes.
If x is a list x.! shows all its elements, and if x is a Python dictionary, x.! shows x.keys(). For example,
sys.modules.! Again, further exclamation marks toggles between full and abbreviated modes.
During autocompletion, typing a question mark shows the docstring for the object. For example: g.app? shows
the docstring for g.app. This doesnt work (yet) directly for Python globals, but __builtin__.f? does. Example:
__builtin__.pow? shows the docstring for pow.
Autocompletion works in the Find tab; you can use <Tab> to cycle through the choices. The Completion tab
appears while you are doing this; the Find tab reappears once the completion is nished.
Calltips
Calltips appear after you type an open parenthesis in code. Calltips shows the expected arguments to a function or
method. Calltips work for any Python function or method, including Pythons global function. Examples:
1. g.toUnicode( gives g.toUnicode(s, encoding, reportErrors=False
2. c.widgetWantsFocusNow gives c.widgetWantsFocusNow(w
3. reduce( gives reduce(function, sequence[, initial]) -> value
The calltips appear directly in the text and the argument list is highlighted so you can just type to replace it. The
calltips appear also in the status line for reference after you have started to replace the args.
Options
Both autocompletion and calltips are initially enabled or disabled by the enable_autocompleter and en-
able_calltips settings in leoSettings.leo. You may enable or disable these features at any time with these
commands: enable-auto-completer-command, enable-calltips-command, disable-auto-completer-command and
disable-calltips-command.
31
Leo, Release 4.6-b1
6.2 Cloning nodes
A cloned node is a copy of a node that changes when the original changes. Not only are changes maintained across
all the the clones of a node, changes to its offspring (children, grandchildren, etc). are simultaneously made to
the corresponding offspring of all of those clones. A small red arrow in the icon box marks cloned nodes. There
is no real distinction between the original node and any of its clones. This makes it possible to update any of
the clones and the original node will change as well. A cloned nodes becomes a regular node again when its
penultimate clone is deleted. Clones are useful for making alternate views of a program. See Clones and views
for full details.
6.3 Creating and destroying nodes
The Insert Node command inserts a new node into the outline. The Delete Node command deletes a node
and all its children.
6.4 Creating and destroying multiple body editors
Three commands in the Cmds:Body Editors menu allow to create and destroy separate editors in the body pane.
The Add Body Editor (add-editor) command adds a new editor in the body pane. The Delete Body Editor (delete-
editor) command deletes the presently selected editor, The Change Body Editor (cycle-editor-focus) command
cycles focus between editors in the body text.
6.5 Cutting, pasting and deleting nodes
The Cut Outline, Paste Outline, Copy Outline and Delete Outline commands work on nodes
rather than text. For example, to delete a node, select the node and choose the Cut Outline or Delete
Outline command. The Cut Outline and Copy Outline commands copy a text representation of the
outline to the clipboard. This representation is the same as Leos .leo le format with some information deleted.
You may copy this text representation into a body pane (or into any other text editor) using the Edit:Paste
command.
Warning: In practice, it is almost always wiser to move clones rather than cutting or pasting them. Cutting and
pasting outlines preserves clones, but the links between clones only exist within the part of the outline that was
pasted. Therefore, if you are cutting and pasting an outline containing clones it is best to cut and paste the entire
outline. Alternatively, you can paste part of an outline, then delete all clones.
6.6 Dragging nodes
You may drag an node (including all its descendants) from one place to another in an outline. To start a drag, press
the main (left) mouse button while the cursor is over the icon for a node. The cursor will change to a hand icon. If
you release the mouse button while the hand cursor is above the icon for another node, Leo will move the dragged
node after that node. If you release the mouse button when the hand cursor is not over an icon, Leo will leave the
outline pane as it is. Leo scrolls the outline pane as the result of mouse-moved events, so to continue scrolling you
must keep moving the mouse.
6.7 Editing body text
Leo auto indents unless @nocolor is in effect. Typing a newline automatically inserts the same leading whites-
pace present on the previous line. If Python is the present language, Leo inserts an additional tab if the previous
line ends with a colon.
32 Chapter 6. Chapter 3: Using Outlines
Leo, Release 4.6-b1
The default features of Leos body text derive from the Tk.Text widget, described at:
http://www.tcl.tk/man/tcl8.3/TkCmd/text.htm Not all these features are found on all platforms. The fol-
lowing features are derived from the Tk Text widget. Some default behaviors have been changed because they
conict with other Leo features.
Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor,
sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1
strokes out a selection between the insertion cursor and the character under the mouse.
Double-clicking mouse button 1 selects the word under the mouse and positions the insertion cursor at the
end of the word.
The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this
will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed.
Clicking mouse button 1 with the Control key down will reposition the insertion cursor without affecting
the selection.
Normal printing characters are inserted at the point of the insertion cursor.
If the mouse is dragged out of the body pane while button 1 is pressed, the entry will automatically scroll to
make more text visible.
Left Arrow and Right Arrow move the cursor one character to the left or right and clear any selection
in the text.
Shift Left or Shift Right move the cursor and extend the selection.
Control-Left and Control-Right move the insertion cursor by words, and
Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and
also extend the selection.
Up Arrow and Down Arrow move the insertion cursor one line up or down and clear any selection in
the text.
Shift Up and Shift Right move the cursor and extend the selection.
Control-Up and Control-Down move the insertion cursor by paragraphs.
Control-Shift-Up and Control-Shift-Down move the insertion cursor by paragraphs and
extend the selection. Control-p and Control-n behave the same as Up and Down, respectively. Note:
by default, Leo binds Control-p and control-n to commands.
Next (Page Down) and Prior (Page Up) keys move the insertion cursor one screen and clear any text
selection.
Shift Next and Shift Prior move the cursor one screen and extend the selection.
Line movement is by text lines terminated by hard returns (newlines), not by displayed lines; if a text line
is long and wraps across more than one display line, then the Up and Down movement will skip the extra
wrapped display lines.
Home moves the insertion cursor to the beginning of its line and clears any selection in the widget.
Shift-Home moves the insertion cursor to the beginning of the line and extends the selection.
End moves the insertion cursor to the end of the line and clear any selection in the widget.
Shift-End moves the cursor to the end of the line and extends the selection.
Control-Home moves the insertion cursor to the beginning of the text and clears any selection in the
widget.
Control-Shift-Home moves the insertion cursor to the beginning of the text and extends the selection.
Control-End moves the insertion cursor to the end of the text and clears any selection.
6.7. Editing body text 33
Leo, Release 4.6-b1
Control-Shift-End moves the cursor to the end of the text and extends the selection.
Select and Control-Space set the selection anchor to the position of the insertion cursor. They dont
affect the current selection.
Shift-Select and Control-Shift-Space adjust the selection to the current position of the inser-
tion cursor, selecting from the anchor to the insertion cursor if there was no previous selection.
Control-/ selects the entire contents of the widget.
Control-\ clears any selection in the widget.
F16 (Copy on many Sun workstations) or Control-c copies the selection in the widget to the clipboard,
if there is a selection.
F20 (Cut on many Sun workstations) or Control-x copies the selection in the widget to the clipboard
and deletes the selection. These keys have no effect if no text is selected.
F18 (Paste on many Sun workstations) or Control-v inserts the contents of the clipboard at the position
of the insertion cursor.
Delete deletes the text selection, or the character to the right of the cursor if there is no text selection.
Backspace deletes the selection, or character to the left of the cursor if there is no text selection.
6.8 Expanding & contracting nodes
You can expand or contract a node by clicking in the standard Windows Tree View icon to the left of the status
icon. Expanding a node shows its immediate children; contracting a node hides all its children. The Expand
All Subheads command expands all of a nodes offspring (children, grandchildren, etc.)
6.9 Indenting body text automatically
Leo auto indents body text following colons when @language Python is in effect. When the
smart_auto_indent setting is True, Leo uses Emacs-style auto-indentation instead. This style of auto-indent
aligns newly created lines with unmatched ( [ or { brackets in the previous line.
6.10 Marking nodes
You can mark nodes in several ways:
With the Mark commands.
With the Find or Change commands.
With the Untangle command.
The Go To Next Marked command selects the next marked node, if any. The Mark command unmarks the
selected headline if it is already marked.
6.11 Moving & Reorganizing nodes
The Move Up, Move Down, Move Left and Move Right commands move the currently selected node.
The Promote command makes all the children of a node siblings of the node. The Demote command makes all
following siblings of a node children of the node.
Leo, Release 4.6-b1
You can cut and paste any part of a tree. If a node contains selected text, the cut, copy, clear or paste operation
affects only the selected text. Otherwise, the cut, copy, clear or paste operations acts on the node and all nodes
contained by it. For example, you can move a node by cutting it, selecting another location in the outline and
pasting the node in the new location.
Warning: In practice, it is almost always wiser to move clones rather than cutting or pasting them. Cutting and
pasting outlines preserves clones, but the links between clones only exist within the part of the outline that was
pasted. Therefore, if you are cutting and pasting an outline containing clones it is best to cut and paste the _entire_
outline. Alternatively, you can paste part of an outline, then delete all clones.
6.12 Navigating through the outline
Leo has many commands that select nodes in the outline. These commands can be found in the Outline:Go To
menu.
When focus is in the outline Pane, you can move to from node to node by typing the rst letter of a headline.
For example, typing a will go to the next visible headline that starts with either a or A, wrapping around to
the start of the outline if needed. Typing an uppercase A will go to the next headline that starts with a or A,
making the node visible (expanding its ancestors) if the node was not visible.
When keystrokes (in the outline pane) are typed close together in time Leo rst looks for prex + ch, where ch
is the character just typed and prex is the previous match. The term close together is dened by the setting:
@oat outline_nav_extend_delay = 2.0
The outline nav search reverts to a single-character search if the extended search fails, so in fact the delay is not
too signicant. In practice everything works well without thinking about what is happening.
6.13 Opening URLs automatically
Double-clicking the icon box of a node whose headline has the form:
@url <any url>
executes the url in your default web browser.
Leo checks that the url is valid before doing so. A valid url is:
3 or more lowercase alphas
followed by one :
followed by one or more of:
$%&()
*
+,-./0-9:=?@A-Z_a-z{}~
followed by one of: $%&()
*
+/0-9:=?@A-Z_a-z}~
Urls should contain no spaces: use %20 to indicate spaces. You may use any type of url that your browser
supports: http, mailto, ftp, le, etc.
6.14 Resizing panes
You can change the relative sizes of the outline and body panes by dragging the splitter bar. The Equal Sized
Panes command resizes the panes so that each lls half of the main window.
6.12. Navigating through the outline 35
Leo, Release 4.6-b1
6.15 Undoing operations
Leo supports unlimited undo for all typing and all commands. The undo_granularity setting controls the granu-
larity of undo. There are four possible values:
node Starts a new undo unit when typing moves to a new node.
line (default) Starts a new undo unit when typing moves to new line.
word Starts a new undo unit when typing starts a new word.
char (not recommended) Starts a new undo unit for each character typed. This wastes lots of computer mem-
ory.
setUndoTypingParams calls recognizeStartOfTypingWord to recognize the start of words. Plugins
can modify recognizeStartOfTypingWord. It should return True if the typing indicated by the params
starts a new word for the purposes of undo with word granularity. setUndoTypingParams calls this
method only when the typing could possibly continue a previous word. In other words, undo will work safely
regardless of the value returned. See the actual code for recognizeStartOfTypingWord for more details.
6.16 Using chapters
Chapters are regions of a Leo outline whose root is an @chapter node. @chapter nodes may appear anywhere in
an outline, but the create-chapter command (see below) creates @chapter nodes as children of the rst @chapters
node in the outline.
Selecting a chapter shows only then nodes in the selected chapter; in this respect, chapters are like hoists. The
main chapter represents the entire outline and can not be deleted by name. When chapters are in effect, Leo creates
a hidden @chapters node containing one @chapter node for every chapter except the main chapter.
Associated settings:
The @bool use_chapters setting determines whether chapters are enabled.
The @bool use_chapter_tabs setting determines whether the chapters pop-up menu appears in the icon area.
Choosing a chapter name from this list selects a chapter.
When chapters are enabled, the Cmds:Chapters menu shows all available chapter commands:
The create-chapter command creates an @chapter node and with a single node.
The delete-chapter command deletes the presently selected chapter.
The select-chapter command makes only the nodes of the selected chapter visible.
The move-node-to-chapter, clone-node-to-chapter and copy-node-to-chapter commands add a node (and its
descendants) to another chapter.
CHAPTER
SEVEN
CHAPTER 4: WRITING PROGRAMS IN
LEO
This chapter is a reference guide to computer programming with Leo. This chapter does not teach you how to
use Leo: for that you should read Leos tutorial. This chapter assumes you are thoroughly familiar with the
terminology introduced in the tutorial. Note: Are you sure you want to read this chapter? It contains many details
that are no interest to the average user of Leo. I recommend using Leo for two weeks, or longer, before attempting
this chapter.
7.1 Overview: the 9 ways of accessing external les
You can create external les using @<file> directives. Most of these directives may only appear in headlines.
Here are all the ways of creating external les:
@asis This directive copies body text verbatim, without even ensuring that newlines terminate each node. Use
this directive only when you must have complete control over every character of the external le.
@auto Imports the external le when Leo reads an outline. See the @auto reference for full details.
@edit Reads the external le into a single node.
@le @file is like @thin, but @file sentinels are more readable than @thin sentinels. However,@le
is not as friendly to cvs or bzr as @thin. Avoid @file in cooperative environments.
@thin Creates external les containing sentinels that minimize conicts in source code control systems such as
bzr. Use @thin unless you have a good reason not to.
@noref This directive produces external les with minimal sentinels. Section references are not allowed. This is
the least often used way of producing external les. Dont use this unless you are sure you must.
@nosent Creates external les without sentinels. Use @nosent only as a last resort: @auto or @shadow are
usually a better choice. Leo can not update @nosent trees from changes made to the external les.
The @bool force_newlines_in_at_nosent_bodies setting controls whether Leo writes a trailing newline if
non-empty body text does not end in a newline. The default is True. In effect, the default value of this
setting was False in previous versions of Leo.
@root This directive is the most exible, and the most difcult to use. Note: @root is a true directive: you put
@root in body text. Historically, this was the rst directive that created external les. It comes closest in
spirit to traditional literate programming tools. However, it is seldom necessary to suffer the drawbacks of
using @root. My advice is to avoid using @root unless you have a compelling reason.
@shadow This directive writes two external les, a public le without sentinels, and a private le (by default in
the .leo_shadow subfolder) containing sentinels. This allows Leo to get the benets of @thin or @file
trees, without having sentinels in the public les that people care about.
37
Leo, Release 4.6-b1
To complicate matters further, you can use CWEB markup instead of noweb markup. See the section called
CWEB mode for the details. The choice between CWEB and noweb is independent of the directive is used to
create external les.
7.2 Overview: summary of directives
Here is a brief summary of each directive:
@ Starts a doc part. @doc is a deprecated synonym.
@all Copies all descendant nodes to the external le. Not valid in @root trees.
@asis Creates an external le without sentinels, containing exactly the data in the @asis tree, without
expanding section references or @others directives.
@auto Imports the external le every time Leo reads the outline. The read-at-auto-nodes and write-at-auto-
nodes commands can be used to read and write and @auto nodes.
@c Starts a code part. @code is a deprecated synonym.
@color, @nocolor, @nocolor-node and @killcolor Control syntax coloring.
@comment Sets comment delimiters in @root and @unit trees.
@delims Sets comment delimiters in @file trees.
@edit Reads an external le into a single node.
@encoding Sets the Unicode encoding used in external les.
@le Creates an external le containing sentinels. Thin external les contains simpler sentinels than
@thin. The @le tree in the outline contains a copy of all information in the external le.
@rst Forces lines to appear before the rst sentinel of an external le.
@ignore Causes Leo to ignore all or part of an external le. Works differently in @file and @root trees.
@language Sets the language used for syntax coloring and sets the comment delimiters used in sentinel
lines and in doc parts.
@last Forces lines to appear after the last sentinel of an external le.
@lineending Sets the line ending to be used in external les.
@others Copies all nodes except section denition nodes to the external le.
@nosent Same as @file, but the external le contains no sentinels.
@pagewidth Sets the page width used to break doc parts into lines.
@path Set the path to be appended to lenames.
@raw and @end_raw Delimit a section of raw text. Not valid in @root or @unit trees.
@root, @root-code and @root-code Start an @root tree. The last two forms set the starting mode for
body text.
@shadow Creates two external les, a public le without sentinels, and a private le containing sentinels.
Imports the le just as @auto does if the private le does not exist.
@tabwidth Sets the width of tabs. Negative tab widths cause Leo to convert tabs to spaces.
@thin Creates an external le containing sentinels. Thin external les miminize cvs and bzr conicts. All
essential information is stored in the thin external le.
@verbose, @terse, @quiet and @silent Set the verbosity of sentinels in external les from @root.
@wrap and @nowrap Enable or disable line wrapping the Leos body pane.
38 Chapter 7. Chapter 4: Writing Programs in Leo
Leo, Release 4.6-b1
7.3 Reference: all about directives
The following sections give full details about each directive. The directives listed here may appear in headlines or
body text.
7.3.1 @ and @doc
The @ directive starts a doc part. Doc parts continue until an @c directive or the end of the body text. For example:
@c
@doc is a synonym for @, but @ is preferred.
7.3.2 @all
The @all directive is valid only in @thin trees. The @all directive is similar to @others, but it is less
restrictive: it dumps all nodes to the external le, including @ignore nodes and nodes that in an @others tree
would be considered to be orphan nodes.
The @all directive is required for les such as @thin leoProjects.txt in LeoPy.leo.
leoProjects.txt contains so-called project nodes. It doesnt have any meaning as a program le: it is
simply a collection of unrelated data. @others would not work at all: it would complain about lots of orphan
nodes.
7.3.3 @asis and @noref
The only difference between @asis and @noref trees is that external les created from @noref contain sen-
tinels while external les created from@asis do not.
Leo creates les from @noref and @asis trees by writing the body text of all nodes of the tree in outline order.
Leo writes the body text as is, without recognizing section denitions, without expanding section references,
and without treating directives specially in any way. In particular, Leo copies all directives, including @ or @c
directives, to the external le as text.
Leo does recognize the @ignore directive in the ancestors of @noref or @asis nodes, so you may use the
@ignore directive as usual to prevent Leo from writing @noref or @asis trees.
Notes:
When writing @noref trees, Leo writes only the @+leo, @-leo, @+node, @-node, @+body and
@-body sentinels.
Within @asis trees only, if a headline starts with @@, Leo writes everything in the headline following the
@@ just before the corresponding body text.
Files created from @asis trees contain nothing not contained in body text (or @@ headlines). In particular,
if body text does not end in a newline, the rst line from the next node will concatenated to the last line of
the preceding node.
7.3.4 @auto
@auto trees allow people to use Leo in collaborative environments without using sentinels in the les Leo gener-
ates. In contrast to @nosent, @auto trees can change when the corresponding le changes outside of Leo.
7.3. Reference: all about directives 39
Leo, Release 4.6-b1
Leo will automatically recreate (import) all @auto trees when reading a .leo le, and will write all dirty @auto
trees when saving a .leo le. There are two exceptions to this statement:
1. Leo will never read (import) or write an @auto tree if the root @auto tree is under the inuence of an @ignore
directive.
1. Saving a .leo le does not save @auto nodes if:
1. they havent been changed or,
2. they do not contain a signicant amount of information. An @auto tree contains a signicant amount of
information if it has children or if the root node contains more than 10 characters.
Leo creates @auto trees by parsing the corresponding external le. Parsers create descendant nodes of the @auto
tree: one node for each class, method and function in the external le.
Parsers presently exist for C, elisp, Java, Javascript, Pascal, PHP, Python and xml. Leo determines the language
using the les extension. Notes:
If no parser exists for a language, the entire body of the external le is copied to the body of the @auto
node.
Javascript regexps that look like section references cause problems, but that can not be helped.
Use the @data import_xml_tags setting in leoSettings.leo to specify the xml tags that create outline nodes.
By default, the organizer tags are html, body, head, and div.
7.3.5 @c and @code
The @c directive ends a doc part and begins a code part. @code is a synonym for @c, but @c is preferred.
In @root and @unit trees, the headline must contain a valid section name.
7.3.6 @color, @nocolor, @nocolor-node and @killcolor
Syntax coloring is on by default in all body text. Leo formats comments and documentation parts in red, directives
and C keywords in blue, strings and character constants in gray and all other text in code parts in black. The
@nocolor directive disables syntax coloring for the body text in which it appears. No syntax coloring is done
until an @color directive re-enables syntax coloring.
If a node contains neither the @color nor the @nocolor directive it may inherit the syntax coloring attribute
from an ancestor. The nearest ancestor that contains exactly one of the @color or @nocolor directives will
control the syntax coloring. Ambiguous nodes, nodes containing both the @color and @nocolor directives,
never affect the coloring of their offspring.
The @nocolor-node directive completely disables coloring for that node only. Descedant nodes are not af-
fected.
The @killcolor directive completely disables the colorizer for that node. The result is much faster syntax
coloring of large body text. As usual @killcolor may itself be overridden in descendant nodes. The differences
between @killcolor and @nocolor:
@nocolor suppresses coloring only until the next @color directive.
@killcolor overrides @nocolor and @color directives. Any node containing @killcolor is unam-
biguously a @killcolor node regardless of whether that node also contains @color or @nocolor
directives.
Note: These directives do not affect the Tangle commands in any way. In particular, the Tangle commands
will recognize section denitions as usual even after an @nocolor directive is seen.
Leo, Release 4.6-b1
7.3.7 @comment
Note: the @comment directive is deprecated: you should use the @language directive whenever possible.
However, sometimes using both @language and @comment is useful. For this to be effective the @comment
directive should appear after the @language directive (in outline order).
The Untangle command will not process an @root or @unit node if an @comment directive is in effect be-
cause Untangle cant be sure of properly parsing an external le if the language of the external le isnt known.
It might be possible to assume some defaults in this case, but that is not done at present and is not a high priority.
By default, the Tangle commands produces C-language comments. Single-line comments generated during tan-
gling start with ///, while documentation parts are surrounded by /
*
and
*
/. The @comment directive allows
you to use Tangle to produce shell and make les, as well as source code for other programming languages.
The @comment directive may be followed by zero to three delimiters, separated by whitespace. This directive
sets the single-line comment delimiter and the opening and closing block comment delimiters as follows:
@comment no args: restores the defaults to ///, /* and */
@comment /// 1 arg: sets the single-line comment and clears the other delims.
@comment /* */ 2 args: sets the block comment delims; clears the single-line delim.
@comment /// /* */ 3 args: sets all three delimiters.
If only one delimiter is given, Leo does not write any documentation parts while tangling. If two delimiters
are given, block-style comments are used instead of single-line comments. For example, the @comment { }
directive could be used to tangle Pascal les.
The @comment directive is only recognized in @root, @unit or @file nodes, and the @comment directive
must precede the rst section name or @code directive. An @comment directive in the body text of an @unit
directive species the current global defaults. An @comment directive in the body text of an @root directive
affects comments generated for one root only. Comments in all other roots are governed by the global defaults.
Leo will convert underscores in the @comment directives to signicant spaces. For example:
@comment REM_
causes the comment delimiter to be REM (Note the trailing space).
7.3.8 @delims
The @delims directive changes the comment strings used to mark sentinel lines. This directive is often used to
place Javascript text inside XML or HTML les. The delims directive is not valid in @root or @unit trees.
The @delims directive contains one or two delimiters, separated by whitespace. If only one delim is present it
delimits single-line comments. If two delims are present they delimit block comments. The @delims directive
can not be used to change the comment strings at the start of the external le, that is, the comment strings for the
@+leo sentinel and the initial @+body and @+node sentinels.
The @delims directive inserts @@delims sentinels into the external le. The new delimiter strings continue in
effect until the next @@delims sentinel in the external le or the end of the external le.
Note: Leo can not revert to previous delimiters automatically; you must change back to previous delimiters using
another @delims directive. For example:
@delims /
* *
/
Javascript stuff
@delims <-- -->
HTML stuff
Adding, deleting or changing @@delims sentinels will destroy Leos ability to read the external le. Mistakes
using the @delims directive have no effect on Leo, though such mistakes will thoroughly mess up a external le
as far as compilers, HTML renderers, etc. are concerned.
Leo, Release 4.6-b1
7.3.9 @edit
Reads a le into a single node. @edit is similar to @auto; saving a .leo le does not save dirty @edit nodes if they
do not contain a signicant amount of information. An @edit tree contains a signicant amount of information if
it has children or if the root node contains more than 10 characters.
7.3.10 @encoding
You may use the @encoding directive to specify the encoding used in an external le. You cant mix encodings
in a single external le. For example:
@encoding iso-8859-1
If the encoding used in an external le is not utf-8 it is represented in the @+leo sentinel line, like this:
#@+leo-encoding=iso-8859-1.
The utf-8 encoding is used by default. The utf-8 encoding is a lossless encoding (it can represent all uni-
code code points), so encoding and decoding to and from utf-8 plain strings will never cause a problem. When
reading or writing a character not in a lossy encoding (such as iso-8859-1), Leo converts such characters to
? and issues a warning.
7.3.11 @le
The @file directive is deprecated - use @thin instead. @file trees can be converted to @thin trees by
replacing @file by @thin in outline.
The @file directive creates an external le containing sentinels. External les contain sentinels different from
@thin. The @file tree in the outline contains a copy of all information in the external le.
7.3.12 @rst
The @first directive allows you to place lines at the very start of external les created by @thin and @file
nodes. For example, the body text of @file spam.py might be:
@first #! /usr/bin/env python
The body text of @file foo.perl might be:
@first #/usr/bin/perl
@first directives are recognized only at the start of the body text of @file and @thin nodes. No text may
precede @first directives. More than one @first directive may exist, like this:
@first # more comments.
The @first directive is not valid in @root or @unit trees.
7.3.13 @ignore
Generally speaking, @ignore directive prevents nodes from being processed.
1. In the root node of any @auto, @edit, @file, @noref, @nosent, @root, @thin or @shadow tree,
@ignore prevents Leo from writing the external le.
Leo, Release 4.6-b1
2. @auto trees are an exception. Everything, including @ignore directives, are written. However, you can
disable the writing of an @auto tree by putting an @ignore directive in an ancestor of the @auto tree.
3. At present, @ignore can be used to prevent the inclusion of a node that descends from @others. This
may be dubious behavior, but thats how Leo works.
4. @ignore can be used by scripts and plugins as they like, but should preserve the behavior in item 1 above.
7.3.14 @language
The @language directive species the comment delimiters and string types used by the Tangle and
Untangle commands. This directive over-rides the default specied in the settings dialog.
When the threading_colorizer plugin is enabled, the valid @language directives are:
@language x
where the leo/modes folder contains the le x.py. When the threading_colorizier plugin is not enabled, the old
colorizer is used and the valid @language directives are:
@language actionscript
@language c
@language c++
@language cweb
@language elisp
@language html
@language java
@language latex
@language objective-c
@language pascal
@language perl
@language perlpod
@language plain
@language python
@language rebol
@language shell
@language tcltk
Shell les have comments that start with #. Case is ignored in the language speciers, but not in the @language
itself. Thus, the following are equivalent:
@language html
@language HTML
@language hTmL
but the following is invalid:
@LANGUAGE html
7.3.15 @last
The @last directive allows you to place lines at the very end of external les created from @file and @thin
nodes. The @last directive is recognized only at the end of body text of @file and @thin nodes. No text may
follow @last directives. More than one @last directive may exist. For example, here is how a PHP le might
be set up:
@first <?php
...
@last ?>
Leo, Release 4.6-b1
7.3.16 @lineending
The @lineending directive sets the line endings for individual external les. This directive will override the
output_newline setting. The @lineending never affects the line endings in .leo les themselves: .leo les
must have consistent line endings!
The valid forms of the @lineending directive are:
@lineending nl The default, Linux.
@lineending cr Mac
@lineending crlf Windows
@lineending lf Same as nl, not recommended
@lineending platform Same as platform value for output_newline setting.
7.3.17 @others
The @others directive refers to the body text of all nodes except section denition nodes. The @others
directive places the body text of section denition nodes in the external le in outline order.
An @file tree may contain more than one @others directive. @others directives that descend from other
@others directives refer only to unnamed nodes that descend from them. The @others directive that occurs
highest in the @file tree refers to all other unnamed nodes.
Notes:
No node may contain more than one @others directive.
No section denition node may intervene between an non-section denition node containing body text and
an @others node. In practice this is never a problem.
The @others directive is not valid in @root or @unit trees.
7.3.18 @nosent
Leo writes @nosent trees just as for @thin trees, but Leo writes no sentinels at all.
The @bool force_newlines_in_at_nosent_bodies setting controls whether Leo writes a trailing newline if non-
empty body text does not end in a newline. The default is True. In effect, the default value of this setting was
False in previous versions of Leo.
7.3.19 @path
The @path directives override the deprecated default_tangle_directory setting.
The form of the @path directive is @path lename, where lename is taken to be everything following @path to
the end of the line.
If lename is an absolute lename the location of the external le is specied only by the lename. Otherwise, if
lename is a relative lename, the location of the external le is relative to:
1. the directory specied the applicable @path directive, or
2. the Default Tangle Directory in the Settings dialog if no @path directive is in effect, or
3. the directory in which the .leo le resides if the .leo le has ever been saved.
An error occurs if no absolute path can be computed according to these rules, or if lename does not exist.
Leo, Release 4.6-b1
7.3.20 @pagewidth
The @pagewidth directive overrides the page_width setting. The form of the @pagewidth directive is
@pagewidth n, where n is a positive integer that indicates the width of tangled pages in columns. For example:
@pagewidth 100
This setting only affects how Leo reformats doc parts, and how the Tangle command outputs block comments.
7.3.21 @raw and @end_raw
The @raw and @end_raw directives are valid only within @file trees. The @raw directive starts a section of
raw text. The @end_raw directive ends such a section, as does the end of body text. No section references are
recognized within raw text, and no additional leading whitespace is generated within raw text when writing the
external le.
7.3.22 @root
@root creates external les that are more exible than @file, @thin, @shadow, etc.
Sections may be dened anywhere within @root trees. Moreover, the @unit directive expands the scope
of section denitions in @root trees so that a section may be referenced in several @root trees.
The meaning of section denitions in @root trees are independent of their position within the tree.
However, this exibility comes at a cost:
@file trees use less markup than @root trees. In particular, the @others directive is valid only within
@file trees.
You must explicitly tangle and untangle @root trees using the Tangle and Untangle commands.
See @root reference for more details.
7.3.23 @root-code and @root-doc
Leo allows you to choose whether body text in @root trees will start in code mode or doc mode by default.
@root-doc lename and @root-code lename directives specify that body text is assumed to start in doc
mode or code mode respectively. The options (-doc and -code) must follow @root immediately with no
intervening whitespace. In effect, @root-code and @root-doc are two new directives.
These @root options override the at_root_bodies_start_in_doc_mode setting. This setting affects
only @root trees without options. Such plain @root trees are now deprecated, which only means that it is
better style to use either @root-code or @root-doc. The reason is simple: the meaning of plain @root
trees will depend on the at_root_bodies_start_in_doc_mode setting. Its better to be explicit. By
default, at_root_bodies_start_in_doc_mode = 1 for compatibility for old @root trees. I actually
dont think this option is good for much; I created it before I created @root-doc and @root-code settings,
and I decided it wouldnt hurt to leave it in. Anyway, you now have complete exibility about how @root works,
and in particular you can make @root work just like @file.
7.3.24 @shadow
When writing an @shadow tree, Leo writes two les, a public le without sentinels, and a private le (by default
in the .leo_shadow subfolder) containing sentinels. The primary sources for @shadow trees are the private les,
updated by changes to the public le.
Leo, Release 4.6-b1
When reading an @shadow tree, Leo will import the tree from the public le if the private le does not exist.
Important: just as for @auto, the following exceptions apply:
1. Leo will never read (import) or write an @shadow tree if the @shadow tree is under the inuence of an
@ignore directive.
2. Saving a .leo le does not save @shadow nodes if:
Leo imports shadow trees by parsing the corresponding public le, exactly as is done for @auto node. See the
discussion of @auto above for details.
7.3.25 @tabwidth
The @tabwidth directive overrides the tab_width setting. The form of the @tabwidth directive is
@tabwidth n, where n is a positive integer that indicates the width of tabs in spaces. For example:
@tabwidth -4
Negative values cause Leo to convert tabs to blanks.
7.3.26 @thin
Creates an external le containing sentinels.
Thin exteral les contain all information needed to recreate the @thin tree in the outline.
The @all directive is valid only in @thin trees, not @file trees.
In a collaborative environment, where a version control system is utilized and everyone can use Leo for editing,
@thin is the recommended way to hold most of the content.
7.3.27 @unit
The @unit directive expands the scope of section denitions in @root trees so that a section may be referenced
in several @root trees. The @unit directive is ignored outside of @root trees.
7.3.28 @verbose, @terse, @quiet and @silent
The @verbose, @terse, @quiet and @silent directives determine how the Tangle command outputs
comments in @root trees. Comments written by the user in code sections are always output. These directives
control only: a) the comments containing doc sections and b) sentinel comments that delimit the beginning and
end of code sections.
When @verbose is in effect Tangle outputs all comments. When @terse is in effect, Tangle outputs
only those comments necessary for Untangle to work. When @silent is in effect Tangle adds no additional
comments. The @quiet directive is like @silent except that it does output leading sentinels as comments. Like
@silent, @quiet inhibits untangling. @verbose is the default. If more than one of these directives appear in
the same body text the most verbose of these options will be in effect.
Leo, Release 4.6-b1
7.3.29 @wrap and @nowrap
By default, the body_pane_wraps setting controls whether body text wraps. You may override this setting
for a particular tree using the @wrap and @nowrap directives. Only the rst @wrap or @nowrap directive in a
node has any effect.
7.4 Reference: the 9 ways of accessing external les
In the following table all terms in each row are equivalent. The spelling in the rst column is preferred:
@asis @le-asis @silent
@nosent @le-nosent @nosentinelsle
@noref @le-noref @rawle
You can get any combination of sentinels/no sentinels and references/no references using @auto, @file,
@thin, @nosent, @noref and @asis trees:
Type Sentinels? Sections and @others expanded?
@asis no no
@auto no no
@edit no yes
@le yes yes
@noref yes no
@nosent no yes
@root yes yes
@shadow yes and no yes
@thin yes yes
Leo can not update the outline from changes made from external les unless those les contain sentinels. The
primary source for @nosent and @asis trees are the outlines from which those les were created.
@shadow trees create two les, a public le without sentinels, and a private le (by default in the .leo_shadow
subfolder) containing sentinels. The primary sources for @shadow trees are the private les, updated by changes
to the public le.
7.4.1 @auto
@auto trees allow people to use Leo in collaborative environments without using sentinels in the les Leo gener-
directive.
1. Saving a .leo le does not save @auto nodes if:
Leo creates @auto trees by parsing the corresponding external le. Parsers create descendant nodes of the @auto
tree: one node for each class, method and function in the external le.
Parsers presently exist for C, elisp, Java, Javascript, Pascal, PHP, Python and xml. Leo determines the language
using the les extension. Notes:
If no parser exists for a language, the entire body of the external le is copied to the body of the @auto
node.
7.4. Reference: the 9 ways of accessing external les 47
Leo, Release 4.6-b1
Javascript regexps that look like section references cause problems, but that can not be helped.
Use the @data import_xml_tags setting in leoSettings.leo to specify the xml tags that create outline nodes.
By default, the organizer tags are html, body, head, and div.
Perfect import checks
Leo performs several checks to ensure that the result of importing an external le will be equivalent to the le that
writing the @auto tree would produce.
These checks can produces errors or warnings. Errors indicate a potentially serious problem. Leo inserts an
@ignore directive in the @auto tree if any error is found. This @ignore directive prevents the @auto tree from
modifying the external le. If you @ignore directive, a later write of the @auto tree will attempt to x the problems
that gave rise to the errors. There are no guarantees however.
Before importing a le, Leo regularizes the leading whitespace of all lines of the original source le. That is, Leo
converts blanks to tabs or tabs to blanks depending on the value of the @tabwidth directive in effect for the @auto
node. Leo also checks that the indentation of any non-blank line is not a multiple of the indentation specied by
the @tabwidth directive in effect for the @auto node.
Leo cannot guarantee to reproduce the original source le exactly if problems are discovered while regularizing
leading whitespace. Strict languages are languages such as Python for which leading whitespace must be pre-
served exactly as it appears in the original source le. Problems during regularizing generate errors for strict
languages and warnings for non-strict languages.
After importing a le, Leo veries that writing the @auto node would create exactly the same le as the original
le. Such le comparison mismatches generate errors unless the problem involves only leading whitespace for
non-strict languages. Whenever a mismatch occurs the rst non-matching line is printed.
File comparison mismatches can arise for several reasons:
1. Bugs in the import parsers. Please report any suspected bugs immediately.
2. Underindented lines in classes, methods or function. An underindented line is a line that is indented less
then the starting line of the class, method or function in which it appears. Leo outlines can not represent
such lines exactly: every line of node implicitly has at least the indentation of any unindented line of the
node.
Leo will issue a warning (not an error) for underindented Python comment lines. Such lines can not change the
meaning of Python programs.
Commands related to @auto
Three commands in the File:Read/Write menu allow you to manually read and write @auto nodes from the
presently selected outline. As always, an @ignore directive in the @auto node or its ancestors will suppress
any of these commands:
The Read @auto Nodes (read-at-auto-nodes) command reads all @auto nodes in the presently selected
outline. An @ignore directive will suppress this import.
The Write @auto Nodes (write-at-auto-nodes) command writes all @auto nodes. An @ignore directive will
suppress this import. Caution: the write will occur even if Leo has not previously read the @auto node.
The Write Dirty @auto Nodes (write-dirty-at-auto-nodes) is the same as the write-at-auto-nodes command,
except that only changed @auto trees are written.
Most users will rarely use these explicit commands, because reading and writing .leo les handles @auto nodes
well enough. However, you can use the read-at-auto-nodes command to update @auto nodes without having to
reload the .leo le.
Leo, Release 4.6-b1
7.4.2 @edit
Initially, Leos File:Open command creates such nodes when opening any non-.leo le.
When writing @edit nodes, Leo uses Leos @auto write logic. That is, no sentinels are written.
When reading @edit nodes, Leo just puts then entire text of the le into the node, along with @language or
@nocolor directives as appropriate. These added directives will not change the le when it gets written because
no sentinels are written.
7.4.3 @le
The @file directive is deprecated - use @thin instead. @file trees can be converted to @thin trees by
replacing @file by @thin in outline.
The @file directive creates an external le containing sentinels. External les contain sentinels different from
@thin. The @file tree in the outline contains a copy of all information in the external le.
7.4.4 @nosent
Leo writes @nosent trees just as for @thin trees, but Leo writes no sentinels at all.
The @bool force_newlines_in_at_nosent_bodies setting controls whether Leo writes a trailing newline if non-
empty body text does not end in a newline. The default is True. In effect, the default value of this setting was
False in previous versions of Leo.
7.4.5 @asis and @noref
The only difference between @asis and @noref trees is that external les created from @noref contain sen-
tinels while external les created from@asis do not.
Leo creates les from @noref and @asis trees by writing the body text of all nodes of the tree in outline order.
Leo writes the body text as is, without recognizing section denitions, without expanding section references,
and without treating directives specially in any way. In particular, Leo copies all directives, including @ or @c
directives, to the external le as text.
Leo does recognize the @ignore directive in the ancestors of @noref or @asis nodes, so you may use the
@ignore directive as usual to prevent Leo from writing @noref or @asis trees.
Notes:
When writing @noref trees, Leo writes only the @+leo, @-leo, @+node, @-node, @+body and
@-body sentinels.
Within @asis trees only, if a headline starts with @@, Leo writes everything in the headline following the
@@ just before the corresponding body text.
Files created from @asis trees contain nothing not contained in body text (or @@ headlines). In particular,
if body text does not end in a newline, the rst line from the next node will concatenated to the last line of
the preceding node.
7.4.6 @root reference
This section discusses all aspects of @root trees. You should carefully consider whether the extra exibility
afforded by @root trees is worth the extra bother. Indeed, @file trees are much easier to use than @root trees:
@file trees use less markup than @root trees. In particular, the @others directive is valid only within
@file trees.
Leo, Release 4.6-b1
However, @root trees are more exible than @file trees:
Sections and section denitions
Just as with @file trees, @root trees may contain code parts and doc parts. Code parts start with section
denition lines (see below) or the @c directive. Doc parts start with @ directive. Doc parts continue until the end
of body text or until the next @c or @ directive.
Body text in @root trees contain zero or more code and doc parts in any order. The @c directive starts a named
code section if the nodes headline starts with <<section name>>. Otherwise, the @c directive is invalid.
Section denition lines are lines of the form:
<< section name>>=
(note the equal sign). Such lines also start named code parts. Named code parts in @root trees may be dened
in several places. The denition of a named code part is the concatenation of all code parts with the same name.
Body text that denes no code part is ignored. At least one non-blank line must follow the section denition line;
empty sections are not allowed.
As in @file trees, paired << and >> characters on the same line always denote a section name, even within
comments and strings. Thus, << and >> characters that do not delimit a section name must be placed on separate
lines. If << and >> are not paired on a line, they are treated as ordinary << and >> characters.
Here is a typical example of body text within an @root tree:
@ This method puts an open node sentinel for node v.
<<atFile methods>>=
def putOpenNodeSentinel(self,v):
if v.isAtFileNode() and v != self.root:
<< issue an error message >>
else:
s = self.nodeSentinelText(v)
self.putSentinel("@+node:" + s)
Provided that the nodes headline starts with <<atFile methods>>, the example above is equivalent to:
@ This method puts an open node sentinel for node v.
@c
else:
We may not eliminate @c directives in @root trees. If we convert the doc part to a comment we are left with:
@c
# This method puts an open node sentinel for node v.
else:
Leo, Release 4.6-b1
The following escape convention applies only in @root trees. Within a code part @@ in the rst column (and only
in the rst column) stands for a single @ sign.
Tangling @root trees with the Tangle commands
Each @root tree represents a single external le. Tangling is the process of creating external les from@file or
@root trees. Leo tangles @file trees automatically whenever an outline is saved. The user must tangle @root
trees explicitly using one of the Tangle commands.
Leo creates external les by expanding all section references in an @root node. Leo expands a section reference
by substituting the code section itself for the section reference. This is a recursive process: the substituted code
section may contain other code references which are themselves expanded, and so on.
The outline provides a natural way of organizing an sections as follows:
Place the definition of a section S in a child of
the node containing the reference to S.
If a section is referenced in more than one node, I usually place its denition in a node containing all the nodes
that refer to it. Using this rule of thumb creates an outline whose structure mirrors the intrinsic organization of a
program.
The Tangle command creates external les from @root node. The @root directive indicates which sections
constitute an output le. The text following a @root directive forms the entire content of the le, that is, after
section references are expanded. An outline can contain arbitrarily many @root directives: Leos Tangle
commands will create one output le for each. The process of creating external les is called tangling because
the code from the outline is rearranged to create the external les.
For example, the following @root section shows a typical way of specifying a header le xx.h:
@root xx.h
#ifndef xx_defined
#define xx_defined
<< declarations of public constants of the xx class >>
<< declarations of public types of the xx class >>
<< declarations of public variables of the xx class >>
<< public prototypes of the xx class >>
#endif
The Tangle commands will create the le xx.h from this body text by expanding all the section references.
Incidentally, the introductory documentation will be included in the header le: any text preceding the @root
directive is treated just like the doc part of a section denition.
As another example, the following shows a typical way of specifying the corresponding xx.c le:
@root xx.c
<< public variables of the xx class >>
<< private types of the xx class >>
<< private variables of the xx class >>
<< private function prototypes of the xx class >>
<< methods of the xx class >>
There are three menu commands that tangle an outline: Tangle, Tangle All and Tangle Marked. These
commands are identical except for how much of the outline is tangled. The Tangle command tangles only the
selected portion of the outline, the Tangle All command tangles the entire outline, and the Tangle Marked
command tangles only marked headlines.
The @root directive has three forms. All three forms mean exactly the same thing:
@root filename
@root "filename"
@root <filename>
Leo, Release 4.6-b1
If lename is an absolute lename the location of the external le is specied only by the lename. Otherwise, if
the @root node contains a relative lename, the location of the external le is relative to:
1. the directory specied by an @path directive, or
2. the default_tangle_directory setting if no @path directive is in effect, or
3. the directory in which the .leo resides if the .leo le has ever been saved.
An error occurs if no absolute path can be computed according to these rules, or if the lename or directory does
not exist.
The scope of a denition is the tree in which the denition is known. By default, Tangle commands look for
section denitions only in the suboutline of the @root node being tangled. That is, all sections are assumed to
be dened either in the body text of the headline, say h, containing the @root directive, or in the body texts of
the descendants of h. The @unit directive explicitly indicates the scope of section denitions. When a Tangle
command encounters the @unit directive it treats the suboutline containing the @unit command as the scope
for all enclosed roots. This ensures that the group of roots in the subtree use the same section denitions.
For example, suppose we have a tree organized as follows:
+ @unit
+ @root A
sections in A
+ @root B
sections in B
The @unit directive insures that only sections dened in the unit can affect les A and B and that all sections
denitions in A and B are compatible with each other.
The Tangle commands ignore any tree containing an @ignore directive. This ensures that trees that contain
cloned nodes or other subsidiary information do not cause the tangle commands to issue spurious error messages.
It also ensures that a tree can never contribute a section denition to another part of the outline by mistake.
Untangling @root trees with the Untangle commands
The Untangle, Untangle All and Untangle Marked commands are the reverse of the corresponding
Tangle commands. They update one or more @root nodes based on changes made to the corresponding
external les.
For example, suppose you create a new part of the outline and tangle it for the rst time. When you compile
external les for the rst you are likely to get many syntax errors. You could x those errors in the outline and
tangle the outline again, but there is a much easier way: you x the errors in the external les using the compilers
editor, then run the untangle command on the part of the outline that created the external le. The Untangle
command updates the selected outline to match the changes in the external les. Its as simple as that. By the way,
the Untangle command marks all the nodes in the outline that it updates, and you can examine all such nodes
with the Go To Next Marked command in the Outline menu.
You cannot use Untangle to update doc parts, or leading comments in code parts or trivial whitespace in code
parts. This is a limitation of the Untangle command that cannot be xed; Untangle has no way of knowing
whether leading comments came from doc parts or are just leading comments.
Untangle never changes the structure of an outline; it never inserts, deletes or moves nodes. Dont attempt to
change the structure of an outline by modifying external les; it wont work. Also, never delete, move or alter
the sentinel lines in external les written by the Tangle command. Such lines start with the comment delimiter
followed by a section name.
If you change the section name in a sentinel line Untangle will not update the code in the outline (with the old
name) that generated the renamed section. Untangle warns about sections that appear in an external le but
not in the outline. Untangle has no trouble with changed section references in external les; it is only changed
sentinel lines that cause problems.
Leo, Release 4.6-b1
Cloned nodes that generate code in several les may cause problems for Untangle. If Untangle is run
separately on these external les, Untangle will update all cloned nodes each time it is run, so only the code in
the last Untangle run will take effect. Therefore, the safe way to update text in cloned nodes is to make the change
in the .leo le rather than the external les.
7.4.7 @thin
Creates an external le containing sentinels.
Thin exteral les contain all information needed to recreate the @thin tree in the outline.
The @all directive is valid only in @thin trees, not @file trees.
In a collaborative environment, where a version control system is utilized and everyone can use Leo for editing,
@thin is the recommended way to hold most of the content.
7.4.8 @shadow
When writing an @shadow tree, Leo writes two les, a public le without sentinels, and a private le (by default
in the .leo_shadow subfolder) containing sentinels. The primary sources for @shadow trees are the private les,
updated by changes to the public le.
When reading an @shadow tree, Leo will import the tree from the public le if the private le does not exist.
Important: just as for @auto, the following exceptions apply:
1. Leo will never read (import) or write an @shadow tree if the @shadow tree is under the inuence of an
@ignore directive.
2. Saving a .leo le does not save @shadow nodes if:
Leo imports shadow trees by parsing the corresponding public le, exactly as is done for @auto node. See the
discussion of @auto above for details.
7.4.9 Converting @root trees to @le trees
To convert an @root tree to an @file tree, choose the root of the tree to be converted, then do the following in
the Python window:
import c2py
c2py.leo1to2()
This script makes numerous changes throughout the tree. It does not, however, change @root to @file, or insert
the needed @others directives. You must do that by hand.
To convert @root trees to @file trees by hand:
1. Change the @root node to an @file node. That is, delete the @root <filename> from the body
text and insert @file <filename> in the headline. Typically, the root node contains a reference like
<<methods of class x>> as the last body text. Replace this reference with the @others directive.
The expansion of @others is all text that is not part of a section denition.
2. Add @ to the start of all doc parts. Leo starts syntax coloring in code mode rather than doc mode, so if a doc
part starts body text it should start with @
Leo, Release 4.6-b1
3. Replace all section denition lines (like <<name>>=) by @c. This results in the node being added to the
expansion of @others.
4. Remove all unused code from the @file tree. Leo does not write external les whose @file trees contain
orphan or @ignore nodes.
5. Make sure that all nodes dening a section have a headline that starts with <<section>>. This will
typically be true when converting @root trees that use the @code directive.
6. If a section is referenced in more than one node (a rare occurrence in my code), clone the dening node and
move one clone under each referencing node.
7. If a node contains the denitions of several sections, place each different denition in a different node.
7.5 CWEB mode
See CWEB for a discussion of the CWEB language. CWEB mode refers to how Leo tangles an outline when
@language cweb is in effect or the cweb setting is in effect. Leo treats all cweb code in cweb mode as
unevaluated text. That is, Leo treats cweb control codes, including @<...@>, @<..@>=, @c, @, @
*
and @
**
as
raw text within cweb mode. Leo does not expand cweb section references when writing external les in cweb
mode. However, Leo does expand noweb section references, so you may use noweb sections to organize cweb
les! You can create noweb code and doc sections using the @code and @doc directives in place of @c and @
directives.
By default, cweb colors @, @
*
and @
**
sections using the same syntax coloring as for LaTeX. In addition, cweb
colors C // and /
*
..
*
/ comments using LaTeX coloring by default. You may change these defaults using the
color_cweb_doc_parts_with_latex and color_cweb_comments_with_latex settings.
CHAPTER
EIGHT
CHAPTER 5: USING LEOS
COMMANDS
This chapter discusses all of Leos menu commands. It starts with a discussion of the Emacs-like minibuffer, then
continues with a discussion of commands in each of Leos menus.
8.1 The minibuffer
The mini-buffer is a text area at the bottom of the body pane. You use it like the Emacs mini-buffer to invoke
commands by their so-called long name. The following commands affect the minibuffer:
full-command: (default shortcut: Alt-x) Puts the focus in the minibuffer. Type a full command name, then
hit <Return> to execute the command. Tab completion works, but not yet for le names.
universal-argument: (default shortcut: Alt-u) Like Emacs Ctrl-u. Adds a repeat count for later command.
Ctrl-u 999 a adds 999 as.
keyboard-quit: (default shortcut: Ctrl-g) Exits any minibuffer mode and puts the focus in the body pane.
For example, to print a list of all commands type Alt-X print-commands <Return>.
The following sections list the various commands that you can invoke from the minibuffer. Important: you may
bind keystrokes to any of these commands. See Chapter 8: Customizing Leo for full details.
8.1.1 Basic editing commands
The following basic editing commands are typically bound to key strokes:
back-char
back-char-extend-selection
back-paragraph
back-paragraph-extend-selection
back-sentence
back-sentence-extend-selection
back-to-indentation
back-word
back-word-extend-selection
backward-delete-char
backward-kill-paragraph
backward-kill-sentence
backward-kill-word
beginning-of-buffer
beginning-of-buffer-extend-selection
beginning-of-line
55
Leo, Release 4.6-b1
beginning-of-line-extend-selection
cut-text
delete-char
end-of-buffer
end-of-buffer-extend-selection
end-of-line
end-of-line-extend-selection
exchange-point-mark
extend-to-word
forward-char
forward-char-extend-selection
forward-paragraph
forward-paragraph-extend-selection
forward-sentence
forward-sentence-extend-selection
forward-word
forward-word-extend-selection
insert-newline
move-lines-down
move-lines-up
move-past-close
move-past-close-extend-selection
newline-and-indent
next-line
next-line-extend-selection
paste-text
previous-line
previous-line-extend-selection
redo
select-all
set-mark-command
undo
8.1.2 Debugging commands
These commands are for debugging Leo itself:
collect-garbage
debug
disable-gc-trace
dump-all-objects
dump-new-objects
dump-outline
enable-gc-trace
free-tree-widgets
print-focus
print-gc-summary
print-stats
verbose-dump-objects
8.1.3 Emacs commands
The following commands work just like their Emacs counterparts. Use the help-for-command command for further
details:
abbrev-mode
add-global-abbrev
add-space-to-lines
56 Chapter 8. Chapter 5: Using Leos Commands
Leo, Release 4.6-b1
add-tab-to-lines
advertised-undo
append-to-buffer
append-to-register
call-last-keyboard-macro
capitalize-word
center-line
center-region
clean-lines
clear-extend-mode
clear-kill-ring
clear-rectangle
clear-selected-text
close-rectangle
copy-rectangle-to-register
copy-text
copy-to-register
count-region
dabbrev-completion
dabbrev-expands
delete-comments
delete-file
delete-indentation
delete-rectangle
delete-spaces
diff
digit-argument
downcase-region
downcase-word
end-kbd-macro
escape
eval-expression
expand-region-abbrevs
fill-paragraph
fill-region
fill-region-as-paragraph
flush-lines
full-command
goto-char
how-many
increment-register
indent-region
indent-relative
indent-rigidly
indent-to-comment-column
insert-body-time
insert-file
insert-keyboard-macro
insert-parentheses
insert-register
inverse-add-global-abbrev
jump-to-register
keep-lines
keyboard-quit
kill-all-abbrevs
kill-buffer
kill-line
kill-paragraph
kill-rectangle
kill-region
kill-region-save
kill-sentence
8.1. The minibuffer 57
Leo, Release 4.6-b1
kill-word
line-number
list-abbrevs
list-buffers-alphabetically
load-file
make-directory
match-bracket
name-last-kbd-macro
negative-argument
number-command
number-command-0
number-command-1
number-command-2
number-command-3
number-command-4
number-command-5
number-command-6
number-command-7
number-command-8
number-command-9
open-rectangle
point-to-register
prepend-to-buffer
prepend-to-register
read-abbrev-file
remove-blank-lines
remove-directory
remove-sentinels
remove-space-from-lines
remove-tab-from-lines
rename-buffer
repeat-complex-command
reverse-region
run-unit-tests
select-paragraph
set-comment-column
set-fill-column
set-fill-prefix
shell-command
shell-command-on-region
sort-columns
sort-fields
sort-lines
split-line
start-kbd-macro
string-rectangle
suspend
switch-to-buffer
tabify
transpose-chars
transpose-lines
transpose-words
unindent-region
universal-argument
unmark-all
untabify
upcase-region
upcase-word
view-lossage
view-register
what-line
yank
Leo, Release 4.6-b1
yank-pop
yank-rectangle
zap-to-character
8.1.4 Find commands
Here is a list of all of Leos nd commands. The apropos-nd-commands command will print a detailed help
message discussing these commands:
clone-find-all
find-character
find-tab-change
find-tab-change-all
find-tab-change-then-find
find-tab-find
find-tab-find-all
find-tab-find-prev
find-word
isearch-backward
isearch-backward-regexp
isearch-forward
isearch-forward-regexp
isearch-with-present-options
query-replace
query-replace-regex
re-search-backward
re-search-forward
replace-string
search-again
search-backward
search-forward
search-with-present-options
set-find-everywhere
set-find-node-only
set-find-suboutline-only
toggle-find-ignore-case-option
toggle-find-in-body-option
toggle-find-in-headline-option
toggle-find-mark-changes-option
toggle-find-mark-finds-option
toggle-find-regex-option
toggle-find-reverse-option
toggle-find-word-option
toggle-find-wrap-around-option
word-search-backward
word-search-forward
8.1.5 Gui commands
The following commands simulate mouse clicks, double-clicks or drags:
abort-edit-headline
activate-cmds-menu
activate-edit-menu
activate-file-menu
activate-help-menu
activate-outline-menu
activate-plugins-menu
Leo, Release 4.6-b1
activate-window-menu
add-editor
cascade-windows
click-click-box
click-headline
click-icon-box
close-window
contract-body-pane
contract-log-pane
contract-outline-pane
contract-pane
cycle-editor-focus
cycle-focus
delete-editor
double-click-headline
double-click-icon-box
edit-headline
end-edit-headline
equal-sized-panes
expand-body-pane
expand-log-pane
expand-outline-pane
expand-pane
focus-to-body
focus-to-log
focus-to-minibuffer
focus-to-tree
fully-expand-body-pane
fully-expand-log-pane
fully-expand-outline-pane
fully-expand-pane
hide-body-pane
hide-find-tab
hide-invisibles
hide-log-pane
hide-mini-buffer
hide-outline-pane
hide-pane
hide-spell-tab
iconify-frame
minimize-all
open-compare-window
open-find-dialog
open-find-tab
open-spell-tab
press-rst3-button
press-save-button
press-spell-button
resize-to-screen
scroll-down
scroll-down-extend-selection
scroll-outline-down-line
scroll-outline-down-page
scroll-outline-up-line
scroll-outline-up-page
scroll-up
scroll-up-extend-selection
show-mini-buffer
simulate-begin-drag
simulate-end-drag
toggle-active-pane
toggle-invisibles
Leo, Release 4.6-b1
toggle-mini-buffer
toggle-split-direction
8.1.6 Help commands
The following commands print various helpful messages. Apropos commands print longer discussions of specic
topics. The help-for-command command prompts for a command name (you can use typing completion to specify
the command) and then prints a brief description of that command:
apropos-autocompletion
apropos-bindings
apropos-find-commands
help
help-for-command
mode-help
print-bindings
print-commands
python-help
8.1.7 Mode commands
These commands put Leo into various kinds of modes.
The enter-
*
-mode commands enter modes dened by @mode nodes in leoSettings.leo (or in other .leo
les).
The set-command-state, set-insert-state, set-overwrite-state commands determine how treats unbound plain
keys. Leo ignores such keys in command state, inserts them into the body pane in insert state, and overwrites
the character at the cursor position in overwrite state.
Other commands determine whether autocompletion or calltips are in effect.
When extend mode is effect, basic editing commands that move the cursor also extend the se-
lected text. For example, in extend mode the back-char command works the same as the
back-char-extend-selection command.
Here is the full list of mode-related commands:
auto-complete
auto-complete-force
disable-autocompleter
disable-calltips
enable-autocompleter
enable-calltips
enter-apropos-mode
enter-commands-mode
enter-edit-mode
enter-emacs-mode
enter-extract-mode
enter-file-mode
enter-gui-mode
enter-help-mode
enter-kill-mode
enter-modes-mode
enter-move-outline-mode
enter-outline-mode
enter-quick-command-mode
enter-toggle-find-mode
Leo, Release 4.6-b1
exit-named-mode
set-command-state
set-extend-mode
set-insert-state
set-overwrite-state
set-silent-mode
show-calltips
show-calltips-force
toggle-autocompleter
toggle-calltips
toggle-extend-mode
toggle-input-state
8.1.8 Outline commands
The following commands invoke Leos outline commands:
clone-node
contract-all
contract-node
contract-or-go-left
contract-parent
copy-node
cut-node
de-hoist
delete-node
demote
expand-to-level-1
expand-to-level-2
expand-to-level-3
expand-to-level-4
expand-to-level-5
expand-to-level-6
expand-to-level-7
expand-to-level-8
expand-to-level-9
expand-all
expand-and-go-right
expand-next-level
expand-node
expand-or-go-right
expand-prev-level
go-back
go-forward
goto-first-node
goto-first-sibling
goto-last-node
goto-last-sibling
goto-last-visible
goto-line
goto-line-number
goto-next-changed
goto-next-clone
goto-next-marked
goto-next-node
goto-next-sibling
goto-next-visible
goto-parent
goto-prev-node
goto-prev-sibling
Leo, Release 4.6-b1
goto-prev-visible
hoist
insert-node
mark
mark-changed-items
mark-changed-roots
mark-clones
mark-subheads
move-outline-down
move-outline-left
move-outline-right
move-outline-up
outline-to-CWEB
outline-to-noweb
paste-node
paste-retaining-clones
promote
sort-children
sort-siblings
8.1.9 Miscellaneous commands
Here are various miscellaneous minibuffer commands:
about-leo
add-comments
check-all-python-code
check-outline
check-python-code
clear-recent-files
convert-all-blanks
convert-all-tabs
convert-blanks
convert-tabs
execute-script
export-headlines
exit-leo
extract
extract-names
extract-section
flatten-outline
goto-global-line
import-at-file
import-at-root
import-cweb-files
import-derived-file
import-flattened-outline
import-noweb-files
insert-headline-time
new
open-leoDocs-leo
open-leoPlugins-leo
open-leoSettings-leo
open-offline-tutorial
open-online-home
open-online-tutorial
open-outline
open-outline-by-name
open-python-window
open-with
Leo, Release 4.6-b1
open-with-idle
open-with-word
open-with-wordpad
pretty-print-all-python-code
pretty-print-python-code
read-at-file-nodes
read-outline-only
reformat-paragraph
revert
save-buffers-kill-leo
save-file
save-file-as
save-file-to
settings
set-colors
set-font
show-colors
show-find-options
show-fonts
show-invisibles
spell-change
spell-change-then-find
spell-find
spell-ignore
tangle
tangle-all
tangle-marked
toggle-angle-brackets
untangle
untangle-all
untangle-marked
weave
write-abbrev-file
write-at-file-nodes
write-dirty-at-file-nodes
write-missing-at-file-nodes
write-outline-only
8.2 The File Menu
8.2.1 Loading, Saving and Reverting Files
The New command creates a new Leo main window.
The Open command opens an existing Leo le and shows it in a main window.
The Close command closes the topmost Leo window, giving you an opportunity to save your work if you
havent yet done so.
The Save, Save As and Save To commands save the Leo window to a le. The Save As command
changes the name of the outline being edited; the Save To command does not.
The Save File As Zipped command is the same as the Save As command except that the resulting
.leo le is compressed with Pythons ziple module. Similarly, the Save File As Unzipped com-
mand is the same as the Save As command except that the resulting .leo le is not compressed. The
Save, Save As and Save To commands compress the le if it was originally compressed. Note: Leo
writes les with .leo extension, regardless of whether the le is zipped or not. Zipped .leo les contain a
single archive, whose name is the same as the .leo le itself. Outside of Leo you can change the extension
to .leo.zip and use stuft or other program to expand the .leo le contained within.
Leo, Release 4.6-b1
The Revert command reloads a le, discarding any changes made to the le since it was last saved.
The Recent Files command brings up a submenu containing a list of recently opened les. Choosing
an item in this submenu opens the selected le or brings it to the front.
The Clear Recent Files command deletes all entries in the Recent Files submenu except the most
recent le. The les themselves are not affected, just the menu entries.
The following commands are located in the Read/Write menu, part of the File menu.
The Read Outline Only command reads an outline using only the .leo le, not any les derived from
@file nodes. This command is useful for reverting a project to a previously saved state.
The Read @file Nodes command updates all @file nodes in an outline. This ensures that the state
of an outline matches all les derived from @file nodes.
The Write Outline Only command saves an outline without writing any @file trees. Useful for
inserting an @le node into an outline without modifying a derived le with the same name.
The Write @file Nodes command forces an update of all @le trees.
The Write Dirty @file Nodes command writes all @file trees that have been changed.
8.2.2 Communicating with external editors
The Open With command allows you to communicate with external editor. When you select this command Leo
creates a temporary le and invokes an external program. Leo periodically checks whether this temporary le has
changed; Leo changes the corresponding node in the outline if so. You must create the entries in the Open With
submenu. This would typically be done in a hook routine, using the createOpenWithMenuFromTable routine
described in the child of this node. The @file mod_open_with.py node in LeoPlugins.leo gives a
complete example of handling the Open With menu.
8.2.3 Tangling an outline: Producing Derived Files
The Tangle, Tangle All and Tangle Marked commands create derived les from portions of an outline.
These commands indent and format the derived les so that they are easy to read and so that it is clear what
sections produced the code. The .c le in the Examples folder shows the code produced by the Tangle commands.
The Tangle command tangles only the selected portion of the outline, the Tangle All command tangles the
entire outline, and the Tangle Marked command tangles only marked headlines.
The Tangle commands create a derived le, call it F, from each @root node. This process is like macro
expansion. The contents of F are simply the body text of the @root node, with each section reference replaced
by its denition. Substitution continues until all references to sections are replaced with their denitions. By
default, Tangle commands look for section denitions only in the suboutline containing the @root directive
being tangled. That is, all sections are assumed to be dened either in the body text of the headline, say h,
containing the @root directive, or in the body texts of the descendants of h. The @unit directive changes the
default scope of the tangle command, while the @ignore directive causes the tangle commands to ignore a
subtree. For more details, see: Tangling @root trees with the Tangle commands
8.2.4 Untangling: updating an outline
The Untangle, Untangle All and Untangle Marked commands are the reverse of the corresponding
Tangle commands. They update an outline based on changes made to one or more derived les. These are
exceptionally useful commands. For example, suppose you create a new part of the outline and Tangle it for the
rst time. When you compile the resulting derived les for the rst time, you are likely to get many syntax errors.
You could x those errors in the outline and Tangle the outline again, but there is a much easier way: you x the
errors in the derived les using the compilers editor, then run the untangle command on the part of the outline
that created the derived le. The Untangle command updates the selected outline to match the changes in the
8.2. The File Menu 65
Leo, Release 4.6-b1
derived les. Its as simple as that. The Untangle command marks all the nodes in the outline that it updates;
you can examine all such nodes with the Go To Next Marked command in the Outline menu. You cannot use
Untangle to update doc parts, or leading comments in code parts or trivial whitespace in code parts. This is a
limitation of the Untangle command that cannot be xed; Untangle has no way of knowing whether leading
comments came from doc parts or are just leading comments.
Untangle never changes the structure of an outline; it never inserts, deletes or moves nodes. Dont attempt to
change the structure of an outline by modifying derived les; it wont work. Also, never delete, move or alter the
sentinel lines in derived les written by the Tangle command. Such lines start with /// followed by a section
name. If you change the section name in a sentinel line Untangle will not update the code in the outline (with
the old name) that generated the renamed section. Untangle now warns about sections that appear in a derived le
but not in the outline. Untangle has no trouble with changed section references in derived les; it is only changed
sentinel lines that cause problems. Cloned nodes that generate code in several les may cause problems for
Untangle if not all the code is changed the same way in derived les. If Untangle is run separately on these
derived les, Untangle will update all cloned nodes each time it is run, so only the code in the last Untangle run
will take effect. Therefore, the only reliable way to update text in cloned nodes is to make the change in the .leo
le rather than the derived les.
8.2.5 Importing Files into Leo Outlines
The Import commands do not attempt to do perfect translations; they merely automate the bulk of the drudgery:
The Import to @file command creates an @file node from a le.
The Import to @root command creates an @root node from a le.
The Import CWEB Files command creates an @le node from a CWEB le.
The Import noweb Files command creates an @le node from a noweb le.
The Import Derived File command imports all the nodes in a derived le into the outline. Unlike the read
commands, the command preserves no outline structure.
The Import Flattened Outline command converts plain text written in MORE format to an outline.
The Import Flattened Outline command brings up a dialog which will accept at most one le. If that
le contains MORE-format text it creates an outline corresponding to that text. MORE is a now-defunct outliner
program. MORE represents outlines as follows. Headlines are denoted by a leading + or - character, preceding by
zero or more tabs that denote the level of the headline. Body text follows its headline, with no indentation. The
original MORE format did not escape lines in the body text that started with + or -. Leo escapes such characters
by preceding +, - or backslash with a backslash.
8.2.6 Exporting Files from Leo Outlines
The Outline To CWEB command creates a CWEB le from the selected outline.
The Outline TO noweb command creates a noweb le from the selected outline.
The Flatten Outline command creates a text le in MORE format from the selected outline. See the
previous section for a discussion of MORE format.
The Remove Sentinels command removes all sentinel lines from a le derived from an @file node.
The Weave Command formats the selected text and writes it to a le.
8.2.7 Quitting Leo
The Quit command causes Leo to exit. You may also exit Leo by closing the main window. You will be prompted
to save any le that has been altered but not saved.
Leo, Release 4.6-b1
8.3 The Edit Menu
8.3.1 Undoing changes
Leo supports unlimited undo and redo. Think of actions that may be undone or redone as a string of beads. A
bead pointer points to the present bead. Performing an operation creates a new bead after the present bead
and removes all following beads. Undoing an operation moves the bead pointer backwards; redoing an operation
moves the bead pointer forwards. The Undo command is disabled when the bead pointer moves in front of the
rst bead; the Redo command is disabled when the bead pointer points to the last bead.
8.3.2 Cutting, pasting and selecting text
Leo supports the standard editing commands: Cut, Copy, Paste, Clear and Select All. These commands
work with either headline or body text.
8.3.3 Shifting body text
The Shift Left and Shift Right commands shift selected lines in the body text left or right one tab
position. These commands shift the entire line if any characters in that line are selected.
8.3.4 Adding and deleting comments in body text
The Add Comments command puts comments around a block of code. This command uses single-line
comments if possible.
The Delete Comments command deletes the comments specied by the Add Comments command.
8.3.5 Creating nodes from body text
The Extract, Extract Section and Extract Section Names commands create child nodes whose headline is the rst
line of the selected body text.
The Extract command creates a new node whose headline is the rst line of selected body text and
whose body is all other lines of selected text. Previously selected text is deleted from the original body text.
The Extract Section command creates a new node whose headline is the rst line of selected text
and whose body is @code followed by all the other lines of selected text. All selected text lines except the
rst line are deleted from the original body text. This command is enabled only if the rst line contains
nothing but section name.
The Extract Section Names command creates one or more child nodes, one for each section name
in the selected body text. The headline of each created node is the section name; the body text is @code
followed by a newline.
8.3.6 Converting leading blanks and tabs in body text
The Convert Tabs command converts leading tabs to blanks in a single node.
The Convert Blanks command converts blanks to tabs in a single node.
The Convert All Tabs converts leading tabs to blanks throughout the selected tree.
The Convert All Blanks command converts leading blanks to tabs throughout the selected tree.
All these commands convert between tabs and blanks using the tab width presently in effect.
8.3. The Edit Menu 67
Leo, Release 4.6-b1
8.3.7 Executing Python scripts in body text
The Execute Script command executes body text as a Python script. Leo execute the selected text, or the
entire body text if no text is selected. The Execute Script command pre-denes the values c, g and p as
follows:
c is the commander of the outline containing the script.
g is the leoGlobals modules.
p is c.p, that is, c.currentPosition().
Important: Body text may contain Leo directives and section references. You can now use all of Leos features
to organize scripts that you execute interactively. Section denitions must appear in the node containing the script
or in descendant nodes.
Leo preprocesses all scripts by simulating the writing of a derived le to a string. The Execute Script
command sets app.scriptDict["script1"] to the value of the script before preprocessing, and sets
app.scriptDict["script2"] to the value of the script after preprocessing. Scripts may examine and
change app.scriptDict as they please.
8.3.8 Finding and changing text
The following check boxes options appear in the search dialog and control the operations of the nd and change
commands.
Clone Find All When checked, the the Find All command creates a new root node called Found: <your search
pattern>. This node contains clones of the nodes found by the Find All command. It is your responsibility
to navigate to this new node and to clean it up when its no longer needed.
Ignore Case When checked, the Find and Change commands ignore the case of alphabetic characters when
determining matches.
Mark Changes When checked, the Change command marks all headlines whose headline or body text are
changed by the command.
Mark Matches When checked, the Find and Change commands mark all headlines in which a match is
found with the pattern.
Pattern Match When checked, the Find and Change commands treat several characters specially in the nd
pattern.
* matches any sequence of zero or more characters.
. matches any single character.
^ matches a newline at the start of a pattern.
$ matches a newline at the end of a pattern.
Examples:
"^abc$" matches lines that only contain "abc".
"^a" matches any line starting with "A".
"a$" matches any line ending with "a".
"^
*
$" matches any line at all.
Reverse When checked, the Find and Change commands search backward through the le.
Search Body Text When checked, the Find and Change commands search body text.
Search Headline Text When checked, the Find and Change commands search headline text.
Leo, Release 4.6-b1
Show Context When checked, the Find All command shows additional context information when printing
matches.
Suboutline Only When checked, the Find and Change commands search only the currently selected head-
line and its offspring.
Whole Word When checked, the nd pattern must match an entire word. Words consist of an alphabetic character
or underscore, followed by zero or more alphabetic characters, numbers or underscores.
Wrap Around When checked, the Find and Change commands continues at the top of the le when the
command reaches the bottom of the le. For reverse searches, the nd or change command continues at the
bottom of the le when the command reaches the top of the le.
8.3.9 Script search
Important: Script buttons are easier to use than the script-oriented nd/change commands described next. I
recommend using script buttons whenever possible. See Creating script buttons. You are not likely to need all the
repower that script-orient nd/change commands, but it could save you lots of time for complex jobs.
Leos nd panel contains the Script Search radio button and the Script Change checkbox. When the
Script Search radio button is selected Leo treats the contents of the Search Text as a script to execute
whenever any kind of Find command is executed. Similarly, when the Script Change checkbox is selected
Leo treats the context of the Change Text as a script to execute whenever any kind of Change command is
executed.
Script-based nd-change turns Leos Find/Change panel into a platform for running scripts interactively. The
script writer need not write code to control interactive searches.
Heres how it works. Leo dedicates g.app.searchDict for communication between Leo and the search and
change scripts. The search and change scripts may also use g.app.searchDict for communication between
themselves. Leo sets g.app.searchDict["type"] to nd, change, ndAll or changeAll to indicate
the kind of command being executed. Scripts may use all other entries in g.app.searchDict as they please.
Here is what Leo does when the user presses buttons with Script Search enable:
Find and Change, then Find buttons Leo executes the nd script once. Typically, the nd script would
traverse the tree and highlight the found text or otherwise indicate to the user that the nd operation has
succeeded. However, the script can do anything it pleases.
Find All button Leo executes the nd script repeatedly until g.app.searchDict["continue"] eval-
uates to False. Initially there is no entry for g.app.searchDict["continue"], so the nd script
must set g.app.searchDict["continue"] = True if it wants Leo call it again.
Change button Leo executes the change script once. Typically, the change script would change the
selected text. Usually the change script will compute the new value of body text and call
c.setBodyString(p,newText) to make that change permanent. To handle undo, the change script
can call c.frame.onBodyChanged(v,"Change",oldText=oldText).
Change All button Leo executes the change script repeatedly until g.app.searchDict[continue] evaluates to
false.
Most nd and change scripts will ignore settings in the Find Panel like whole word, pattern match, and
reverse. However, these settings are available to the scripts via ivars such as c.whole_word_flag, etc. if
desired.
The initScriptFind script in LeoPy.leo makes it easy to set up script based searches:
1. Put the following code in the root of a tree that will contain your script search:
# Initialize Leos find panel using the named children of this node.
import leo.core.leoGlobals as g.
g.initScriptFind("Find script","Change script") # Second argument is optional.
8.3. The Edit Menu 69
Leo, Release 4.6-b1
# Start searching at the top.
c.selectPosition(c.rootPosition())
2. Put the search script in a child node called Find script (no quotes).
3. (Optional) Put the change script in a child node called Change script
4. Execute the code above. Leo does the following:
Puts the body of the Find script into the nd text of Leos Find/Change dialog.
Puts the body of the Change script into the change text of Leos Find/Change dialog.
Selects the Script Find radio button.
Selects the Script Change checkbox if the change script exists.
Selects the root of the entire outline.
Presto! Leo is ready for a script search. Note: you could also consider creating a script button to set up complex
nd/change scripts.
Here are some ideas for using script nd/change.
Find and change scripts may use Pythons re module. For example, the nd script could set
g.app.searchDict["m"] to the match object returned by res match method. The change script would
then compute the result, change the text and set the undo info as usual.
Find and change scripts may operate on data outside any Leo outline. For example, script-nd scripts could
traverse your le system. Scripts could even pull data from the le system into the outline so that you can
see the effects of changes as the scripts operate.
8.3.10 Go To Line Number
The Go To Line Number command selects the locations in your outlines corresponding to a line in a derived
le.
8.3.11 Inserting the date and time
The Insert Body Time/Date and Insert Headline Time/Date commands insert formatted time
and date into body or headline text. You must be editing a headline to be able to insert the time/date into the head-
line. The body_time_format_string and headline_time_format_string settings specify the format
of the inserted text. These settings are the format string passed to time.strftime. For a complete list of the format
options see http://www.python.org/doc/current/lib/module-time.html If the format specied by either of these two
settings is erroneous the "%m/%d/%Y %H:%M:%S" format is used by default, resulting in a time/date format
like:
1/30/2003 8:31:55
8.3.12 Reformatting paragraphs in body text
The Reformat Paragraph command rearranges the words in a text paragraph to ll each line as full as possible, up
to the @pagewidth setting. A paragraph is delimited by blank lines, Leo directives, and (of course) start and end
of text in a node. The width of the line used by the reformatting operation is governed by @pagewidth and the
indentation that would be applied to the node when tangled (as part of a @root) or written (as part of a @file).
Leo, Release 4.6-b1
The command operates on the paragraph containing the insert cursor. If the insert cursor is on a blank line or
directive, nothing happens. If the cursor is on a line containing text, then the paragraph containing that text line is
reformatted and the insert cursor is moved to the next paragraph.
Note: Hanging indentation is preserved. This is most useful for bulleted or numbered lists, such as:
1. This is the first paragraph,
and it has a hanging indentation.
2. This is the second paragraph,
and it too has a hanging indentation.
8.3.13 Matching brackets and parenthesis
The Match Brackets command is enabled if the cursor is next to one of the following characters in the body
pane:
( ) [ ] { } < >
This command looks for the matching character, searching backwards through the body text if the cursor is next
to ) ] } or > and searching forward through the text otherwise. If the cursor is between two brackets the search is
made for the bracket matching the leftmost bracket. If a match is found, the entire range of characters delimited
by the brackets is highlighted and the cursor is placed just to the left of the matching characters. Thus, executing
this command twice highlights the range of matched characters without changing the cursor.
8.4 The Outline Menu
8.4.1 Checking outlines
The Check Outline command checks the outline for consistency.
The Check All Python Code and Check Python Code commands report any syntax errors or
tabnanny errors. These commands mark erroneous nodes and ignore any nodes for which:
@ignore is in effect or
@language python is in not effect.
The Check Python Code and Pretty Print Python Code pretty print body text. You can cus-
tomize this code by overriding the following methods of class prettyPrinter in leoCommands.py:
putOperator: puts whitespace around operators.
putNormalToken: puts whitespace around everything else.
8.4.2 Creating & cloning nodes
The Insert Headline command inserts a new headline after the presently selected headline, either as
the next sibling or the rst child of the presently selected headline if the presently selected headline has
children and is expanded.
The Clone Node creates a clone of the selected node. See Clones and views for full details about clones.
8.4. The Outline Menu 71
Leo, Release 4.6-b1
8.4.3 Cutting, pasting and deleting nodes
The Cut Outline and Copy Outline commands copy a text representation of the outline to the clip-
board. This representation is the same as the le format with some information deleted.
The Paste command (in the Edit menu) copies this representation into the body pane.
The Paste Node As Clone command pastes the node from the clipboard, retaining the identity of
nodes. Thus, if the pasted node already exists in the outline the newly pasted node will become of a clone
of the already-existing node.
The Paste Outline command creates nodes with new identities (new gnxs).
8.4.4 Expanding and contracting nodes
The Expand command expands the currently selected node so that all its children are visible.
The Expand All Subheads command expands the currently selected node so that all its offspring are
visible.
The Expand All command expands all the nodes of the entire tree.
The Contract Parent contracts the selected nodes parent and selects the parent node.
8.4.5 Marking nodes
The Mark Headline command marks a headline with a red marker near the leader characters.
The Unmark Headline command removes such a mark.
The Mark Subheads command marks all offspring of the currently selected node.
The Unmark All command removes the marks from the entire tree.
The Mark Changed Items command marks all headlines whose headline or body text has been
changed since the le was last saved.
The Mark Changed Roots command marks all changed headlines whose body text contains the @root
directive. This command is especially useful with the Tangle Marked command.
8.4.6 Moving, sorting and reorganizing nodes
The Move Up, Move Down, Move Left and Move Right commands move the currently selected
node.
The Promote command makes all the children of a node siblings of the node.
The Demote command makes all the siblings that follow a node children of the node.
The Sort Children command sorts all children of the present node in alphabetical order of their head-
lines.
The Sort Siblings command sorts all siblings of the present node in alphabetical order.
8.4.7 Hoisting & De-hoisting nodes
The Hoist command redraws the screen so presently selected tree becomes the only visible part of the
outline. Hoist commands may be nested.
The De-hoist command restores the outline.
Leo, Release 4.6-b1
8.5 The Window Menu
The Equal Sized Panes command adjusts the sizes of the outline and body panes so that they are the
same height.
The Cascade command cleans up the screen by cascading all Leo windows.
The Minimize All command minimizes all Leo windows.
The Toggle Active Pane command toggles keyboard focus between the outline and body panes.
The Toggle Split Direction command switches between vertical and horizontal orientations of the
Leo window. In the vertical orientation, the body pane appears below the pane containing the outline and
log panes. In the horizontal orientation, the body pane appears to the left the pane containing the outline
and log panes. By default, the ratio of pane outline pane to the body pane is 0.5 in the vertical orientation
and 0.3 in the horizontal orientation. These two ratios may be changed using settings.
The Open Compare Window command opens a dialog that allows you to compare two les, one con-
taining sentinels and one not.
8.6 The Help Menu
The About Leo command puts up a dialog box showing the version of Leo.
The Online Home Page command opens Leos home page at
http://webpages.charter.net/edreamleo/front.html.
The Open Online Tutorial command opens Joe Orrs excellent ScreenBook tutorial at
http://www.evisa.com/e/sbooks/leo/sbframetoc_ie.htm.
The Open Ofine Tutorial command opens the le sbooks.chm if it exists. Otherwise, you will
be asked whether you want to download it from Leos SourceForge web site. If you say yes, the
page http://sourceforge.net/project/showles.php?group_id=3458 will open. You may then download
sbooks.sbm to the folder containing leo.py.
The Open LeoDocs.leo command opens LeoDocs.leo.
The Open LeoPlugins.leo command opens LeoPlugins.leo.
The Open LeoSettings.leo command opens LeoSettings.leo.
8.5. The Window Menu 73
Leo, Release 4.6-b1
CHAPTER
NINE
CHAPTER 6: LEO AND LITERATE
PROGRAMMING
This chapter discusses Leos relationship with traditional literate programming.
9.1 Why I like Literate Programming
The following paragraphs discuss the main benets of traditional literate programming. Note: none of these
benets depends on printed output.
Design and coding happen at the highest possible level. The names of sections are constrained only by ones
design skill, not by any rules of language. You say what you mean, and that becomes both the design and the code.
You never have to simulate a concept because concepts become section names.
The visual weight of code is separate from its actual length. The visual weight of a section is simply the length
and complexity of the section name, regardless of how complex the actual denition of the section is. The results
of this separation are spectacular. No longer is one reluctant to do extensive error handling (or any other kind of
minutia) for fear that it would obscure the essence of the program. Donald Knuth stresses this aspect of literate
programming and I fully agree.
Sections show relations between snippets of code. Sections can show and enforce relationships between ap-
parently unrelated pieces of code. Comments, macros or functions are other ways to indicate such relationships,
but often sections are ideal. Indeed, a natural progression is to create sections as a matter of course. I typically
convert a section to a function only when it becomes apparent that a functions greater generality outweighs the
inconvenience of having to declare and dene the function.
Complex section names invite improvements. A section name is complex when it implies unwholesome depen-
dencies between the caller (user) of the section and the section itself. Such section names tend to be conspicuous,
so that the programmer is lead to revise both the section name and its purpose. Many times my attention has been
drawn to a poorly conceived section because I didnt like what its name implied. I have always been able to revise
the code to improve the design, either by splitting a section into parts or be simplifying its relation to colleagues.
Sections create a place for extensive comments. One of the most surprising thing about literate programming is
how severely traditional programming tends to limit comments. In a conventional program the formatting of code
must indicate structure, and comments obscure that formatting. Sections in literate programming provide a place
for lengthy comments that do not clutter the code at the place the section is referenced.
Section names eliminate mundane comments. The section name often says it all. The reference to the section
says everything that the user needs to know, and the section name at the point of denition also eliminates the
need for many comments.
Sections create comments automatically. A typical @root node starts out with something like:
<< includes for class x >>
<< private data for class x >>
<< private prototypes for class x >>
<< functions of class x >>
75
Leo, Release 4.6-b1
In the derived le there is a comment that looks like this:
/// << includes for class x >>
It would be silly to write this comment by hand, though often programmers do just that in order to have a place
holder for a mark in the source le. With literate programming the situation is different: the comment indicates
that the code came from a particular section; that is, the comment servers a real purpose.
Literate programming claries the shape of code. These last several paragraphs have discussed comments in
detail because the net effect of putting comments where they belong is that comments dont clutter the code.
Section references hide irrelevant detail, so larger-scale patterns within functions (or declarations) become more
apparent. Often just recasting code into web format has created Ahas about my own code, with no special
attention to recoding or redesign! Recasting a function as a web raises the real and apparent level of abstraction.
I spend less time formatting code. Formatting no longer has to indicate overall design; sections do that. I
am less obsessive about formatting code; it simply doesnt matter much whether different sections are formatted
consistently because the format of one section has no effect on the look of other sections. Also, I dont worry
about most line breaks within documentation parts, or about adding comment delimiters.
Literate programming creates a new design dimension. Sections add a new dimension to the design and
coding process. Choices about what sections do, what they are named, what order they appear in, are choices in a
design space different from normal programming. This an abstract concept, to be sure. However, the previous
paragraphs are really a manifestation of working in this new design space.
9.2 How Leo Improves Literate Programming
Outlines add something brand new to traditional literate programming, namely an explicit mechanism for express-
ing structure at any level of detail, from largest overall view to smallest detail. The following paragraphs elaborate
on this theme.
Outlines add context. There are too many sections in conventional literate programming. It becomes difcult to
understand the relationships between sections. Using an outline to express a literate programming instantly solves
this problem. The programmer is always aware of how sections are related.
Outlines provide scope for commands. Outlines provide a convenient way of expressing the intended scope of
commands. For example, the Tangle command operates only on the presently selected tree. The Extract
Section command creates a new section as the last child of the present node.
Clones create different views and focus attention. Clones can create different views of the outline. An outline
can contain many such views. Clones & views discusses the implications of clones in detail.
Outlines increase exibility. Organizer nodes do not affect derived les in any way, but organizer nodes often
convey the most information about the structure and design of a large system. Decoupling structure from content
in this way is precisely what is needed for exibility: one can reorganize at will without worrying about changing
the meaning of the code.
Outlines express hierarchy directly. Hierarchy is often implicit in programming: for example, the grouping of
functions into les, or the organization of a single le as a set of functions, etc. An outline directly expresses
hierarchy. Many of Leos commands operate on the presently selected node. It is natural to apply operations on
selected node of the outline.
reStructuredText is much easier to use than CWEB markup. Leos rst3 plugin makes it easy to use reStruc-
turedText (rST) instead of CWEB markup. For most purposes, rST sufces, and rST is much easier to use and
less intrusive than CWEB.
Outlines create new design dimensions. There are many ways to express a program as a Leo outline. Such
choices are important. They add clarity to the entire program. These are different kind of choices. They simply
can not be expressed at all in other editors. In other words, such choices exist in a new design space.
Leo improves tangling and adds untangling. Tangling and untangling are fundamental operations of literate
programming. Leo tangles and untangles les derived from @le trees automatically. This is an important conve-
nience.
76 Chapter 9. Chapter 6: Leo and Literate Programming
Leo, Release 4.6-b1
9.3 How Leo Changes the Notion of Literate Programming
Leo changes the theory and practice of literate programming as follows:
Leo reduces the need for comments. In particular, bridge or transition phrases are almost always unnecessary in
a Leo outline. One never needs to say something like, having just nished with topic x, we turn now to topic y.
Leos outlines tend to be far less chatty than at literate programs.
Leo reduces the need for printed listings. Experience with the Weave command shows that an outline can
easily become unintelligible when printed, no matter how beautiful the typeset printout is. No printed listing
can be as clear as Leos outline view.
Leo reduces the need for indices and tables of contents. You could say the entire outline is a table of contents.
Moreover, sections must always be dened in a descendant of the node containing the section reference, so there
is very little need for an index.
Leo shows that outline structure is more powerful than narrative. Indeed, narrative style creates severe main-
tenance problems. The narrative is soon forgotten, and when that happens it becomes difcult to nd anything.
The few times I have tried narrative organization I soon regretted it: things just werent where I expected them to
be.
Leo shows that traditional literate programming encourages a too creative approach to programming. A
dictionary is a better model for programs than a novel. Leos outlines provide a more regular organization, while
providing space for the most lengthy discussions when those discussions are required.
9.3. How Leo Changes the Notion of Literate Programming 77
Leo, Release 4.6-b1
78 Chapter 9. Chapter 6: Leo and Literate Programming
CHAPTER
TEN
CHAPTER 7: SCRIPTING LEO WITH
PYTHON
This chapter is a tutorial describing how to write Python scripts that get and modify data contained in Leo outlines.
Scripts use Leos, vnode, tnode and position classes to access data in Leo outlines. The combination of a vnode v
and its tnode v.t represents a nodes data. Leo needs both vnodes and tnodes to represent clones efciently. Indeed,
a tnode represents all data shared by cloned nodes. When Leo clones a vnode v, Leo creates a new, independent
vnode v2 and sets v2.t == v.t. Thus, cloning a node does not duplicate any information in descendant trees, but
descendants of a cloned node appear more than once on the screen (when all nodes are expanded). Positions
represent a node at a particular place on the screen. Equivalently, a position indicates a particular place in a tree
traversal. Iterators of the position class dene various kinds of tree traversals.
Leos execute-script command predenes several symbols. This makes it easy to access the data in Leo outlines
and the Leos own source code. g is predened to the leoGlobals module. Scripts commonly use utility functions
such as g.es, g.trace, etc. The g.app object represents Leo itself. The instance vars (ivars) of g.app are Leos
global variables and constants. The execute-script command predenes c to be the commander (see below) of the
Leo outline in which the script is contained. Whenever possible, scripts should use the high-level methods of the
commander to insert, delete or clone nodes. Finally, the execute-script commands predenes p to be the presently
selected position.
This chapter describes only some of Leos functions, classes and methods. However, your scripts have complete
access to all of Leos source code, that is, all the code in LeoPy.leo. You are not limited by what you see in
this chapter.
10.1 Commonly used classes
@language python
Leos source code is a collection of classes, along with utility functions in leoGlobals.py. Here are the classes
and objects that scripts will commonly use:
g.app The application object representing the entire Leo application. The ivars (instance variables) of g.app
represent Leos global variables.
g.app.gui This is a wrapper class that shields Leos core code from gui-dependent details. As described below,
scripts can invoke dialogs using g.app.gui convenience methods.
commander An instance of the Commands class in leoCommands.py. Commanders represent commands for
a particular window. Each open Leo window has its own commander. By convention, any variable named
c is a commander.
frame An instance of the base leoFrame class in leoFrame.py. Frames contains all the internal data needed
to manage a Leo window. Given a commander c, c.frame is commanders frame. Given a frame f, f.c
is the frames commander.
position An instance of the position class in leoNodes.py. A position object represents the location of
a particular node in a tree traversal. By convention, variables named p, p1 or p2 are positions. For any
79
Leo, Release 4.6-b1
position p, p.v is the vnode at that position and p.v.t is the tnode at that position. Positions are
the primary way to access data. c.currentPosition (aka c.p) and c.rootPosition return
positions. From those starting point, it is possible to access the data in any node.
Important: Positions can become invalid when the structure of the outline changes. As discussed below,
plugins and scripts that store positions for use at a later time should make sure the position p is still valid by
calling c.positionExists(p)
Important: For compatibility with old (pre-4.2) scripts, c.currentVnode and c.rootVnode methods
return positions not vnodes. Old scripts appear to be using vnodes; in fact they are using positions. I call
such scripts confused scripts. Confused scripts work because the position class is designed to make
them work. Well see how this works in detail in About copying positions. This section is supremely
important.
baseTextWidget and its subclasses
Leos body pane (c.frame.body.bodyCtrl, aka w), is an instance of (a subclass of) baseTextWidget. Gui plugins
implement Leos body pane by subclassing baseTextWidget.
vnode An instance of the vnode class in leoNodes.py. vnodes represent one or more outline nodes on the
screen. Normally, scripts access vnodes via the position class described below. By convention, variables
named v, v1 or v2 refer to vnodes. Important: scripts normally should use positions, not vnodes.
tnode An instance of the tnode class in leoNodes.py. tnodes represent the actual data in a vnode, including
headline and body text. For any vnode v, v.t is vs tnode. Cloned vnodes v1 and v2 share the same tnode.
That is v1.t == v2. Important: If p is a position, p.v.t is the tnode associated with that position.
Many positions may share the same tnode.
Important: With the exception of the p.v and v.t ivars, scripts should be careful to use only the methods of the
position, vnode and tnode classes rather than the internal ivars of these classes. Doing so will ensure that the script
is as simple as possible and that the script will continue to work regardless of future changes to the internals of
these classes.
10.2 Predened objects
Leos Execute Script command predenes c to be the commander of the outline containing the script. g
and p are predened as follows:
p = c.p
These denitions provide an easy way to access or change any information in a Leo outline. For example, as
discussed below, the following script will print every headline in the Leo outline in which the script occurs.
for p in c.allNodes_iter(): print p.h
10.3 g.es writes to the log pane
The g.es method prints its arguments to the Log tab of the log pane:
g.es("Hello world")
g.es converts non-string arguments using repr:
g.es(c)
g.es prints multiple arguments separated by commas:
80 Chapter 10. Chapter 7: Scripting Leo with Python
Leo, Release 4.6-b1
g.es("Hello","world")
To create a tab named Test or make it visible if it already exists:
c.frame.log.selectTab(Test)
When rst created, a tab contains a Tk.Text widget. To write to this widget, add the tabName argument to g.es:
g.es(Test,color=blue,tabName=Test)
10.4 app.windowList: the list of all open frames
The windowlist attribute of the application instance contains the list of the frames of all open windows. The
commands ivar of the frame gives the commander for that frame:
windows = g.app.windowList # get the list of all open frames.
g.es("windows...")
for f in windows:
c = f.c # c is fs commander
g.es(f)
g.es(f.shortFileName())
g.es(c)
g.es(c.rootPosition())
There is also g.app.commandrs() method, that gives the list of all active commanders directly.
10.5 Getting and setting headline and body text
Here is how to access the data of a Leo window:
g.es(p) # p is already defined.
p = c.p # get the current position.
g.es(p)
g.es("head:",p.h)
g.es("body:",p.b)
Here is how to access data at position p. Note: these methods work whether or not p is the current position:
body = p.b # get the body text.
head = p.h # get the headline text.
p.b = body # set body text of p to body.
p.h = head # set headline text of p to head.
Note: Sometimes you want to use text that looks like a section reference, but isnt. In such cases, you can use
g.angleBrackets. For example:
g.es(g.angleBrackets(abc))
10.6 Getting and setting body text directly
As stated above, Leos body text, c.frame.body.bodyCtrl, is a subclass of baseTextWidget class. Scripts can get
and set information directly from the body pane, using the following methods:
10.4. app.windowList: the list of all open frames 81
Leo, Release 4.6-b1
w.appendText(s) # Append s to end of body text.
w.delete(i,j=None) # Delete characters from i to j.
w.deleteTextSelection() # Delete the selected text, if any.
s = w.get(i,j=None) # Return the text from i to j.
s = w.getAllText # Return the entire body text.
i = w.getInsertPoint() # Return the location of the cursor.
s = w.getSelectedText() # Return the selected text, if any.
i,j = w.getSelectionRange (sort=True) # Return the range of selected text.
w.replace(i,j,s) # Replace the text from i to j by s.
w.setAllText(s) # Set the entire body text to s.
w.setBackgroundColor(color) # Set the background color.
w.setSelectionRange(i,j,insert=None) # Select the text.
w.setForegroundColor(color) # Set the foreground color.
Notes:
These are only the most commonly-used methods. For more information, consult Leos source code.
i and j are zero-based indices into the the text. When j is not specied, it defaults to i. When the sort
parameter is in effect, getSelectionRange ensures i <= j.
color is a tk color name, even when using the qt gui plugin.
10.7 Ensuring that positions are valid
Positions become invalid when the user deletes or moves the node to which the position refers. Plugins and scripts
that store positions for use at a later time should make sure the position p is still valid by calling c.positionExists(p).
The following code will nd a position p2 describing the same node as p:
if not c.positionExists(p):
for p2 in c.allNodes_iter():
if p2.v == p.v:
# found
c.selectPosition(p2)
else:
print position no longer exists
10.8 About copying positions
Understanding this section is essential. By default, all iterators discussed below use a single position to move
through the outline. This is a vital optimization; otherwise Leo would generate one or more position object for
each node of a tree traversal. However, it means that it is useless to try to capture a position with:
p2 = p # Wrong. p2 will change after this assignment.
Instead, scripts and plugins should use p.copy() to capture the value of a position:
p2 = p.copy() # Correct: p2 will not change when p changes later.
Another way to solve this problem is to set copy=True when using an iterator:
d = {}
for p in c.allNodes_iter(copy=True):
d[p.v.t] = p
Leo, Release 4.6-b1
This creates a dictionary of (unchanging!) positions, indexed via tnode. Warning The positions in this dictionary
will become invalid when the outlines structure changes. It would be wrong to save a dictionary like this for use
between commands.
Setting the copy=True argument to iterators is an acceptable strategy for infrequently used scripts; it is not
acceptable for heavily used code in Leos core: it would create huge numbers of positions that would immediately
be candidates for garbage collection.
Important: Confused scripts work because the position methods that simulate the old vnode methods
automatically create copies of positions when moving through an outline. Thus, confused scripts generate many
more positions than would the equivalent script that uses position iterators. Such is the price of compatibility.
10.9 Traversing outlines
The proper way to traverse an outline is with an iterator. Iterators are dened only by the position class; vnodes
can not have iterators because vnodes may appear in multiple places in an outline.
10.9.1 c.allNodes_iter
The c.allNodes_iter iterator returns a list of all positions in the outline. This script makes a list of all the
nodes in an outline:
nodes = [p for p in c.allNodes_iter()]
g.es("This outline contains %d nodes" % len(nodes))
Here is one way to count the nodes of an outline:
count = 0
count += 1
g.es("This outline contains %d nodes" % count)
Here is a way to count the distinct vnodes of an outline:
positions = 0 ; tnodes = {}
positions += 1
if not tnodes.get(p.v.t):
tnodes[p.v.t] = p.v.t
g.es("%8s positions" % positions)
g.es("%8s vnodes" % len(tnodes.keys()))
10.9.2 p.children_iter
The p.children_iter iterator returns a list of all children of position p:
parent = p.parent()
g.es("children of %s" % parent.h,color="purple")
for p in parent.children_iter():
g.es(p.h)
10.9.3 p.parents_iter & p.self_and_parents_iter
The p.parents_iter iterator returns a list of all parents of position p, excluding p:
10.9. Traversing outlines 83
Leo, Release 4.6-b1
current = p.copy()
g.es("exclusive of %s" % current.h,color="purple")
for p in current.parents_iter():
g.es(p.h)
The p.self_and_parents_iter iterator returns a list of all parents of position p, including p:
current = p.copy()
g.es("inclusive parents of %s" % current.h,color="purple")
for p in current.self_and_parents_iter():
g.es(p.h)
10.9.4 p.siblings_iter & p.following_siblings_iter
The p.siblings_iter iterator returns a list of all siblings of position p:
current = c.p
g.es("all siblings of %s" % current.h,color="purple")
for p in current.self_and_siblings_iter():
g.es(p.h)
The p.following_siblings_iter iterator returns a list of all siblings that follow position p:
current = c.p
g.es("following siblings of %s" % current.h,color="purple")
for p in current.following_siblings_iter():
g.es(p.h)
10.9.5 p.subtree_iter & p.self_and_subtree_iter
The p.subtree_iter iterator returns a list of all positions in ps subtree, excluding p:
parent = p.parent()
g.es("exclusive subtree of %s" % parent.h,color="purple")
for p in parent.subtree_iter():
g.es(p.h)
The p.self_and_subtree_iter iterator returns a list of all positions in ps subtree, including p:
parent = p.parent()
g.es("inclusive subtree of %s" % parent.h,color="purple")
for p in parent.self_and_subtree_iter():
g.es(p.h)
10.9.6 Testing whether a position is valid
The tests:
if p: # Right
if not p: # Right
are the only correct ways to test whether a position p is valid. In particular, the following will not work:
Leo, Release 4.6-b1
if p is None: # Wrong
if p is not None: # Wrong
10.9.7 Visiting each node once
Joined nodes represent the same data. Joined nodes are vnodes v1 and v2 such that v1.t == v2.t. Joined vnodes
are distinct (v1 != v2) if the vnodes are clones of each other. Joined nodes are in fact the same node (v1 == v2)
if they are descendants of clone nodes. In particular, we can say that p1.v is joined to p2.v if p1.v.t == p2.v.t
regardless of whether p1.v == p2.v. Thus a script can process nodes exactly once if it ignores nodes joined to
previously visited nodes. A later section will provide an example of this common scripting pattern.
The following script illustrates a common idiom. It prints each headline of an outline, eliminating duplications
that would happen as the result of cloned trees:
d = {}
if p.v.t not in d:
print p.h
d[p.v.t] = p.v.t
As mentioned in the introduction, joined nodes share the same tnode. Thus, when we visit a position p we print p.h
only if p.v.t is not already in the dictionary. We then enter p.v.t in the dictionary to prevent printing the headlines
of any future node joined to p.v.
10.10 Updating the screen
You can use c.redraw_now to redraw the entire screen immediately:
c.redraw_now()
However, it is usually better to request a redraw to be done later as follows:
c.redraw()
Leo actually redraws the screen in c.outerUpdate, provided that a redraw has been requested. Leo will call
c.outerUpdate at the end of each script, event handler and Leo command.
The old (deprecated) way to redraw the screen was with the following pattern:
c.beginUpdate()
try:
<< whatever >>
finally:
c.endUpdate()
This pattern is no longer useful: as of Leo 4.5 b2, c.beginUpdate() does nothing, c.endUpdate() is equivalent to
c.redraw(), and c.endUpdate(False) does nothing.
10.11 Invoking commands from scripts
Leo dispatches commands using c.doCommand, which calls the command1 and command2 hook routines for
the given label. c.doCommand catches all exceptions thrown by the command:
c.doCommand(c.markHeadline,label="markheadline")
10.10. Updating the screen 85
Leo, Release 4.6-b1
You can also call command handlers directly so that hooks will not be called:
c.markHeadline()
You can invoke minibuffer commands by name. For example:
c.executeMinibufferCommand(open-outline)
c.keyHandler.funcReturn contains the value returned from the command. In many cases, as above, this value is
simply break.
10.12 Getting settings from @settings trees
Any .leo le may contain an @settings tree, so settings may be different for each commander. Plugins and
other scripts can get the value of settings as follows:
format_headlines = c.config.getBool(rst3_format_headlines)
g.es(format_headlines,format_headlines)
The c.config class has the following getters. See the configSettings in leoCommands.py for details:
c.config.getBool(settingName,default=None)
c.config.getColor(settingName)
c.config.getDirectory(settingName)
c.config.getFloat(settingName)
c.config.getInt(settingName)
c.config.getLanguage(settingName)
c.config.getRatio(settingName)
c.config.getShortcut(settingName)
c.config.getString(settingName)
These methods return None if no setting exists. The getBool default argument to getBool gives the value to be
returned if the setting does not exist.
You can set any existing item in an @settings tree with c.config.set(p,setting,val). For example:
for val in (False,True):
c.config.set(p,rst3_format_headlines,val)
format_headlines = c.config.getBool(rst3_format_headlines)
g.es(format_headlines,format_headlines)
c.config.set does not change the @settings tree; it simply changes the values returned by the getters.
10.13 Getting and setting preferences
Each commander maintains its own preferences. Your scripts can get the following ivars:
ivars = (
output_doc_flag,
page_width,
page_width,
tab_width,
tangle_batch_flag,
tangle_directory,
target_language,
untangle_batch_flag,
use_header_flag,
Leo, Release 4.6-b1
)
g.es("Prefs ivars...\n",color="purple")
for ivar in ivars:
g.es(getattr(c,ivar))
If your script sets c.tab_width your script may call f.setTabWidth to redraw the screen:
c.tab_width = -4 # Change this and see what happens.
c.frame.setTabWidth(c.tab_width)
10.14 Functions for nding and changing text from scripts
The le leoFindScript.py contains functions for nding and changing text from within scripts. See
leoFindScript.py in LeoPy.leo for full details.
The ndall function returns a list of tuples (v,pos) describing matches in cs entire tree:
import leo.scripts.leoFindScript as leoFindScript
pattern="import leo.core.leoGlobals as g"
result = leoFindScript.findAll(c,pattern,bodyFlag=1)
g.es("%-3d instances of: %s...\n" % (len(result),pattern),color="purple")
for v,pos in result:
body = v.b
g.es(\n%-4d %s % (pos,v.h))
g.es(g.get_line_after(body,pos))
The reFindall function returns a list of tuples (v,mo,pos), where mo is a MatchObject. The reFlags
argument are ags to re.search:
import leo.scripts.leoFindScript as leoFindScript
pattern="from .
*
import"
result = leoFindScript.reFindAll(c,pattern,bodyFlag=1,reFlags=None)
g.es("%-3d instances of: %s...\n" % (len(result),pattern),color="purple")
for v,mo,pos in result:
body = v.b
g.es(\n%-4d %s % (pos,v.h))
g.es(g.get_line_after(body,pos))
10.15 Functions dened in leoGlobals.py
leoGlobals.py contains many utility functions and constants. The following script prints all the names dened
in leoGlobals.py:
g.es("Names defined in leoGlobals.py",color="purple")
names = g.__dict__.keys()
names.sort()
for name in names:
g.es(name)
10.14. Functions for nding and changing text from scripts 87
Leo, Release 4.6-b1
10.16 Event handlers
Plugins and other scripts can register event handlers (also known as hooks) with code such as:
leoPlugins.registerHandler("after-create-leo-frame",onCreate)
leoPlugins.registerHandler("idle", on_idle)
leoPlugins.registerHandler(("start2","open2","command2"), create_open_with_menu)
As shown above, a plugin may register one or more event handlers with a single call to
leoPlugins.registerHandler. Once a hook is registered, Leo will call the registered function at
the named hook time. For example:
leoPlugins.registerHandler("idle", on_idle)
causes Leo to call on_idle at idle time.
Event handlers must have the following signature:
def myHook (tag, keywords):
whatever
tag is the name of the hook (a string).
keywords is a Python dictionary containing additional information. The following section describes the
contents of the keywords dictionary in detail.
Important: hooks should get the proper commander this way:
c = keywords.get(c)
The following table tells about each event handler: its name, when it is called, and the additional arguments passed
to the hook in the keywords dictionary. For some kind of hooks, Leo will skip its own normal processing if the
hook returns anything other than None. The table indicates such hooks with yes in the Stop? column.
Important: Ever since Leo 4.2, the v, old_v and new_v keys in the keyword dictionary contain positions, not
vnodes. These keys are deprecated. The new_c key is also deprecated. Plugins should use the c key instead.
Leo, Release 4.6-b1
Event name (tag argument) Stop? When called Keys in keywords dict
after-auto after each @auto le loaded c,p (note 14)
after-create-leo-frame after creating any frame c
after-redraw-outline end of tree.redraw c (note 6)
before-create-leo-frame before frame.nishCreate c
bodyclick1 yes before normal click in body c,p,v,event
bodyclick2 after normal click in body c,p,v,event
bodydclick1 yes before double click in body c,p,v,event
bodydclick2 after double click in body c,p,v,event
bodykey1 yes before body keystrokes c,p,v,ch,oldSel,undoType
bodykey2 after body keystrokes c,p,v,ch,oldSel,undoType
bodyrclick1 yes before right click in body c,p,v,event
bodyrclick2 after right click in body c,p,v,event
boxclick1 yes before click in +- box c,p,v,event
boxclick2 after click in +- box c,p,v,event
clear-all-marks after clear-all-marks command c,p,v
clear-mark when mark is set c,p,v
close-frame in app.closeLeoWindow c
color-optional-markup yes * (note 7) colorer,p,v,s,i,j,colortag (note 7)
command1 yes before each command c,p,v,label (note 2)
command2 after each command c,p,v,label (note 2)
create-optional-menus (note 8) c (note 8)
create-popup-menu-items in tree.OnPopup c,p,v,event (new)
destroy-all-global-windows (note 12) None
draw-outline-box yes when drawing +- box tree,p,v,x,y
draw-outline-icon yes when drawing icon tree,p,v,x,y
draw-outline-node yes when drawing node tree,p,v,x,y
draw-outline-text-box yes when drawing headline tree,p,v,x,y
drag1 yes before start of drag c,p,v,event
drag2 after start of drag c,p,v,event
dragging1 yes before continuing to drag c,p,v,event
dragging2 after continuing to drag c,p,v,event
enable-popup-menu-items in tree.OnPopup c,p,v,event
end1 start of app.quit() None
enddrag1 yes before end of drag c,p,v,event
enddrag2 after end of drag c,p,v,event
headclick1 yes before normal click in headline c,p,v,event
headclick2 after normal click in headline c,p,v,event
headrclick1 yes before right click in headline c,p,v,event
headrclick2 after right click in headline c,p,v,event
headkey1 yes before headline keystrokes c,p,v,ch (note 13)
headkey2 after headline keystrokes c,p,v,ch (note 13)
hoist-changed whenever the hoist stack changes c
hypercclick1 yes before control click in hyperlink c,p,v,event
hypercclick2 after control click in hyperlink c,p,v,event
hyperenter1 yes before entering hyperlink c,p,v,event
hyperenter2 after entering hyperlink c,p,v,event
hyperleave1 yes before leaving hyperlink c,p,v,event
hyperleave2 after leaving hyperlink c,p,v,event
iconclick1 yes before single click in icon box c,p,v,event
iconclick2 after single click in icon box c,p,v,event
iconrclick1 yes before right click in icon box c,p,v,event
iconrclick2 after right click in icon box c,p,v,event
icondclick1 yes before double click in icon box c,p,v,event
icondclick2 after double click in icon box c,p,v,event
idle periodically (at idle time) c
init-color-markup (note 7) colorer,p,v (note 7)
menu1 yes before creating menus c,p,v (note 3)
menu2 yes during creating menus c,p,v (note 3)
menu-update yes before updating menus c,p,v
new start of New command c,old_c,new_c (note 9)
open1 yes before opening any le c,old_c,new_c,leName (note 4)
open2 after opening any le c,old_c,new_c,leName (note 4)
openwith1 yes before Open With command c,p,v,openType,arg,ext
openwith2 after Open With command c,p,v,openType,arg,ext
recentles1 yes before Recent Files command c,p,v,leName,closeFlag
recentles2 after Recent Files command c,p,v,leName,closeFlag
redraw-entire-outline yes start of tree.redraw c (note 6)
save1 yes before any Save command c,p,v,leName
save2 after any Save command c,p,v,leName
scan-directives in scanDirectives c,p,v,s,old_dict,dict,pluginsList (note 10)
select1 yes before selecting a position c,new_p,old_p,new_v,new_v
select2 after selecting a position c,new_p,old_p,new_v,old_v
select3 after selecting a position c,new_p,old_p,new_v,old_v
set-mark when a mark is set c,p,v
show-popup-menu in tree.OnPopup c,p,v,event
start1 after app.nishCreate() None
start2 after opening rst Leo window c,p,v,leName
unselect1 yes before unselecting a vnode c,new_p,old_p,new_v,old_v
unselect2 after unselecting a vnode c,new_p,old_p,old_v,old_v
@url1 yes before double-click @url node c,p,v,url (note 5)
@url2 after double-click @url node c,p,v(note 5)
10.16. Event handlers 89
Leo, Release 4.6-b1
Notes:
1. activate and deactivate hooks have been removed because they do not work as expected.
2. commands hooks: The label entry in the keywords dict contains the canonicalized form of the command,
that is, the lowercase name of the command with all non-alphabetic characters removed. Commands hooks
now set the label for undo and redo commands undo and redo rather than cantundo and cantredo.
3. menu1 hook: Setting g.app.realMenuNameDict in this hook is an easy way of translating menu
names to other languages. Note: the new names created this way affect only the actual spelling of the
menu items, they do not affect how you specify shortcuts settings, nor do they affect the ofcial command
names passed in g.app.commandName. For example:
app().realMenuNameDict[Open...] = Ouvre.
4. open1 and open2 hooks: These are called with a keywords dict containing the following entries:
c: The commander of the newly opened window.
old_c: The commander of the previously open window.
new_c: (deprecated: use c instead) The commander of the newly opened window.
leName: The name of the le being opened.
You can use old_c.p and c.p to get the current position in the old and new windows. Leo calls the
open1 and open2 hooks only if the le is not already open. Leo will also call the open1 and open2
hooks if: a) a le is opened using the Recent Files menu and b) the le is not already open.
5. @url1 and @url2 hooks are only executed if the icondclick1 hook returns None.
6. These hooks are useful for testing.
7. These hooks allow plugins to parse and handle markup within doc parts, comments and Python strings.
Note that these hooks are not called in Python strings. See the color_markup plugin for a complete
example of how to use these hooks.
8. Leo calls the create-optional-menus hook when creating menus. This hook need only create new menus in
the correct order, without worrying about the placement of the menus in the menu bar. See the plugins_menu
and scripts_menu plugins for examples of how to use this hook.
9. The New command calls new. The new_c key is deprecated. Use the c key instead.
10. g.scanDirectives calls scan-directives hook. g.scanDirectives returns a dictionary, say d.
d.get(pluginsList) is an a list of tuples (d,v,s,k) where:
d is the spelling of the @directive, without the leading @.
v is the vnode containing the directive, _not_ the original vnode.
s[k:] is a string containing whatever follows the @directive. k has already been moved past any
whitespace that follows the @directive.
See the add_directives plugins directive for a complete example of how to use the scan-directives hook.
11. g.app.closeLeoWindow calls the close-frame hook just before removing the window from
g.app.windowList. The hook code may remove the window from app.windowList to prevent
g.app.closeLeoWindow from destroying the window.
12. g.app.destroyAllGlobalWindows calls the destroy-all-global-windows hook. This hook gives
plugins the chance to clean up after themselves when Leo shuts down.
13. Leo calls the headkey1 and headkey2 when the headline might have changed.
14. p is the new node (position) containing @auto lename.ext
Leo, Release 4.6-b1
10.16.1 Enabling idle time event handlers
Two methods in leoGlobals.py allow scripts and plugins to enable and disable idle events.
g.enableIdleTimeHook(idleTimeDelay=100) enables the idle hook. Afterwards, Leo will call the idle hook
approximately every idleTimeDelay milliseconds. Leo will continue to call the idle hook periodically until
disableIdleTimeHook is called. g.disableIdleTimeHook() disables the idle hook.
10.17 How to make operations undoable
Plugins and scripts should call u.beforeX and u.afterX methods ato describe the operation that is being
performed. Note: u is shorthand for c.undoer. Most u.beforeX methods return undoData that the client
code merely passes to the corresponding u.afterX method. This data contains the before snapshot. The
u.afterX methods then create a bead containing both the before and after snapshots.
u.beforeChangeGroup and u.afterChangeGroup allow multiple calls to u.beforeX and u.afterX
methods to be treated as a single undoable entry. See the code for the Change All, Sort, Promote and
Demote commands for examples. The u.beforeChangeGroup and u.afterChangeGroup methods sub-
stantially reduce the number of u.beforeX and afterX methods needed.
Plugins and scripts may dene their own u.beforeX and afterX methods. Indeed, u.afterX merely needs
to set the bunch.undoHelper and bunch.redoHelper ivars to the methods used to undo and redo the
operation. See the code for the various u.beforeX and afterX methods for guidance.
p.setDirty and p.setAllAncestorAtFileNodesDirty now return a dirtyVnodeList that all vn-
odes that became dirty as the result of an operation. More than one list may be generated: client code is responsible
for merging lists using the pattern dirtyVnodeList.extend(dirtyVnodeList2)
See the section << How Leo implements unlimited undo >> in leoUndo.py for more details. In
general, the best way to see how to implement undo is to see how Leos core calls the u.beforeX and afterX
methods.
10.18 Redirecting output from scripts
leoGlobals.py denes 6 convenience methods for redirecting stdout and stderr:
g.redirectStderr() # Redirect stderr to the current log pane.
g.redirectStdout() # Redirect stdout to the current log pane.
g.restoreStderr() # Restores stderr so it prints to the console window.
g.restoreStdout() # Restores stdout so it prints to the console window.
g.stdErrIsRedirected() # Returns True if the stderr stream is redirected to the log pane.
g.stdOutIsRedirected() # Returns True if the stdout stream is redirected to the log pane.
Calls need not be paired. Redundant calls are ignored and the last call made controls where output for each stream
goes. Note: you must execute Leo in a console window to see non-redirected output from the print statement:
print "stdout isRedirected:", g.stdOutIsRedirected()
print "stderr isRedirected:", g.stdErrIsRedirected()
g.redirectStderr()
g.redirectStdout()
g.restoreStderr()
10.17. How to make operations undoable 91
Leo, Release 4.6-b1
g.restoreStdout()
10.19 Writing to different log tabs
Plugins and scripts can create new tabs in the log panel. The following creates a tab named test or make it visible
if it already exists:
c.frame.log.selectTab(Test)
g.es, g.enl, g.ecnl, g.ecnls write to the log tab specied by the optional tabName argument. The default for
tabName is Log. The put and putnl methods of the tkinterLog class also take an optional tabName argument
which defaults to Log.
Plugins and scripts may call the c.frame.canvas.createCanvas method to create a log tab containing a Tk.Canvas
widget. Here is an example script:
log = c.frame.log ; tag = my-canvas
w = log.canvasDict.get(tag)
if not w:
w = log.createCanvas(tag)
w.configure(bg=yellow)
log.selectTab(tag)
10.20 Invoking dialogs using the g.app.gui class
Scripts can invoke various dialogs using the following methods of the g.app.gui object. Here is a partial list. You
can use typing completion(default bindings: Alt-1 and Alt-2) to get the full list!
g.app.gui.runAskOkCancelNumberDialog(c,title,message)
g.app.gui.runAskOkCancelStringDialog(c,title,message)
g.app.gui.runAskOkDialog(c,title,message=None,text=Ok)
g.app.gui.runAskYesNoCancelDialog(c,title,message=None,
yesMessage=Yes,noMessage=No,defaultButton=Yes)
g.app.gui.runAskYesNoDialog(c,title,message=None)
The values returned are in (ok,yes,no,cancel), as indicated by the method names. Some dialogs also return
strings or numbers, again as indicated by their names.
Scripts can run File Open and Save dialogs with these methods:
g.app.gui.runOpenFileDialog(title,filetypes,defaultextension,multiple=False)
g.app.gui.runSaveFileDialog(initialfile,title,filetypes,defaultextension)
For details about how to use these le dialogs, look for examples in Leos own source code. The runOpenFileDi-
alog returns a list of le names.
10.21 Inserting and deleting icons
You can add an icon to the presently selected node with c.editCommands.insertIconFromFile(path). path is an
absolute path or a path relative to the leo/Icons folder. A relative path is recommended if you plan to use the icons
Leo, Release 4.6-b1
on machines with different directory structures.
For example:
path = rt_arrow_disabled.gif
c.editCommands.insertIconFromFile(path)
Scripts can delete icons from the presently selected node using the following methods:
c.editCommands.deleteFirstIcon()
c.editCommands.deleteLastIcon()
c.editCommands.deleteNodeIcons()
10.22 Customizing panes with different widgets
Tk/Tkinter make it easy to customize the contents of any of Leos panes. The following sections will discuss the
ofcial ivars that make it possible for scripts to access and alter the contents of panes. The next three sections
will give examples of modifying each pane.
10.22.1 Ofcial ivars
The c.frame.log class contains the following ofcial ivars:
g.es(tabName,c.frame.log.tabName) # The name of the active tab.
g.es(tabFrame,c.frame.log.tabFrame) # The Tk.Frame containing all the other widgets of the tab.
g.es(logCtrl,c.frame.log.logCtrl) # Tk.Text widget containing the log text.
The following ivars provide access to the body pane:
g.es(bodyFrame,c.frame.body.frame) # The Tk.Frame widget containing the c.frame.body.bodyCtrl
The following ivars provide access to the outline pane:
g.es(canvas,c.frame.tree.canvas) # The Tk.Canvas on which Leos outline is drawn.
Tkinter provides a way of determining the enclosing widget of any widget. The body text is enclosed in a
Pmw.PanedWidget to support multiple editors.
w = c.frame.body.bodyCtrl parent = w.pack_info().get(in) g.es(bodyCtrl.parent,parent) # The
Tk.Frame containing the body text.
10.22.2 Common operations on Tk.Text widgets
The following is no substitute for a full discussion of programming the Tk.Text widget: it can do lots.
To clear the log:
w = c.frame.log.logCtrl
w.delete(1.0,end)
To write a line to the end of the log:
w.insert(end,This is a test\n)
To get the entire contents of the log:
10.22. Customizing panes with different widgets 93
Leo, Release 4.6-b1
g.es(w.get(1.0,end)+\n)
10.22.3 Customizing the log pane
The following line removes the initial text widget:
c.frame.log.logCtrl.pack_forget()
To make the text widget visible again:
c.frame.log.logCtrl.pack(side=top,expand=1,fill=both)
Plugins and scripts can pack any other widgets into c.frame.log.tabFrame. For example, the following replaces
the default text widget with a red box:
import Tkinter as Tk
# Remove the old contents.
parent = w.pack_info().get(in)
w.pack_forget()
# Replace with a red frame.
f = c.frame.newLog = Tk.Frame(parent,background=red)
f.pack(side=left,expand=1,fill=both)
And the following will restore the original pane:
c.frame.newLog.pack_forget()
w.pack(side=left,expand=1,fill=both)
10.22.4 Customizing the body pane
Warning: you will nd it hard to execute scripts after removing the body pane, so you had best make the following
two scripts into script buttons before executing them :-)
Plugins and scripts can pack any other widgets into c.frame.log.tabFrame. For example, the following replaces
the default text widget with a red box:
w = c.frame.body.bodyCtrl
w.pack_forget()
f = c.frame.newBody = Tk.Frame(parent,background=red)
To restore:
c.frame.newBody.pack_forget()
w = c.frame.body.bodyCtrl
w.pack(side=left,expand=1,fill=both)
Leo, Release 4.6-b1
10.22.5 Customizing the outine pane
The following replaces the outline pane with a red frame:
w = c.frame.tree.canvas
w.pack_forget()
f = c.frame.newTree = Tk.Frame(parent,background=red)
And this script restores the outline:
c.frame.newTree.pack_forget()
c.frame.tree.canvas.pack(side=left,expand=1,fill=both)
10.23 Working with directives and paths
Scripts can easily determine what directives are in effect at a particular position in an outline.
c.scanAllDirectives(p) returns a Python dictionary whose keys are directive names and whose values are the value
in effect at position p. For example:
d = c.scanAllDirectives(p)
g.es(g.dictToString(d))
In particular, d.get(path) returns the full, absolute path created by all @path directives that are in ancestors of
node p. If p is any kind of @le node (including @thin, @auto, @nosent, @shadow, etc.), the following script
will print the full path to the created le:
path = d.get(path)
name = p.anyAtFileNodeName()
if name:
name = g.os_path_finalize_join(path,name)
g.es(name)
10.24 Summary of the vnode and position classes
Most scripts will use methods of the position class to access information in an outline. The following sections
summarizes the most useful methods that your scripts can use. For a complete list, see the leoNodes.py in of
LeoPy.leo.
10.24.1 Iterators
Iterators exist only in the position class:
c.allNodes_iter # returns all positions in cs outline.
p.children_iter # returns all children of p.
p.parents_iter # returns all parents of p.
p.self_and_parents_iter # returns p and all parents of p.
p.siblings_iter # returns all siblings of p, including p.
p.following_siblings_iter # returns all siblings following p.
10.23. Working with directives and paths 95
Leo, Release 4.6-b1
p.subtree_iter # returns all positions in ps subtree, excluding p.
p.self_and_subtree_iter # returns all positions in ps subtree, including p.
10.24.2 Getters
Here are the most useful getters of the vnode and position classes.
Returning strings:
p.b # the body string of p.
p.h # the headline string of p. A property.
Returning ints:
p.childIndex()
p.numberOfChildren()
p.level()
Returning bools representing property bits:
p.hasChildren()
p.isAncestorOf(v2) # True if v2 is a child, grandchild, etc. of p.
p.isCloned()
p.isDirty()
p.isExpanded()
p.isMarked()
p.isVisible()
p.isVisited()
10.24.3 Setters
Here are the most useful setters of the Commands and position classes. The following setters of the
position class regardless of whether p is the presently selected position:
c.setBodyString(p,s) # Sets the body text of p.
c.setHeadString(p,s) # Sets the headline text of p.
Moving nodes:
p.moveAfter(v2) # move p after v2
p.moveToNthChildOf(v2,n) # move p to the nth child of v2
p.moveToRoot(oldRoot) # make p the root position.
# oldRoot must be the old root position if it exists.
The visited bit may be used by commands or scripts for any purpose. Many commands use this bits for tree
traversal, so these bits do not persist:
c.clearAllVisited() # Clears all visited bits in cs tree.
p.clearVisited()
p.setVisited()
Leo, Release 4.6-b1
10.25 Creating script buttons
Creating a script button should be your rst thought whenever you want to automate any task. The scripting
plugin, mod_scripting.py, puts two buttons in the icon menu, a pink Run Script button and a yellow
Script Button button. The Run Script button does the same thing as the Execute Script command.
The Script Button button is the interesting one. It creates a button, confusingly called a script button in the
icon area. A script button executes a script when you push it.
Suppose node N is selected. When you press the Script Button button a new (pink) script button is created.
The name of the new button is Ns headline text. The script associated with the new button is Ns body text.
Now whenever you press the new button, Ns script is executed on the presently selected node. Script buttons
are extraordinarily useful. In effect, each script button denes an instant command! For example, sometimes my
ngers get tired of saving a le. I simply put Save in a nodes headline and c.save() in the body text. I hit the
Script Button button and I get a new button called Save that will save the outline when I press it.
Heres a more interesting example. The following script searches the present node and its ancestors looking for
an @rst node. When such a node is found the script calls the rst3 plugin to format it. I dont have to select the
actual @rst node; I can select any of its children:
import leo.core.leoPlugins as leoPlugins
rst3 = leoPlugins.getPluginModule(rst3)
if rst3: # already loaded.
controller = rst3.controllers.get(c)
if controller:
for p in p.self_and_parents_iter():
if p.h.startswith(@rst ):
controller.processTree(p)
break
else: # Just load the plugin.
rst3 = leoPlugins.loadOnePlugin(rst3,verbose=True)
if rst3:
g.es(rst3 loaded)
rst3.onCreate(tag,{c:c})
else:
# Ask to be removed.
g.app.scriptDict[removeMe] = True
Notes:
The scripting plugin pre-denes the c, g and p symbols just as the Execute Script command does.
By default a script button executes the present body text of the node that original created the script button.
This is very handy: you can modify a script buttons script at any time without having to recreate the script
button.
You can delete any script button by right-clicking on it.
On startup, the scripting plugin scans the entire .leo le and creates a script button for every node
whose headline starts with @button scriptName. Warning: this is indeed a security risk of the
kind discussed later. This feature can be disabled by setting atButtonNodes = True at the start of
mod_scripting.py.
10.26 Running Leo in batch mode
On startup, Leo looks for two arguments of the form:
--script scriptFile
10.25. Creating script buttons 97
Leo, Release 4.6-b1
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 le 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.disable or 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 le and prints all the headlines in that le:
path = r"c:\prog\leoCVS\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"))
10.27 Getting interactive input from scripts
The following code can be run from a script to get input from the user using the minibuffer:
def getInput (event=None):
stateName = get-input
k = c.k
state = k.getState(stateName)
if state == 0:
k.setLabelBlue(Input: ,protect=True)
k.getArg(event,stateName,1,getInput)
else:
k.clearState()
g.es_print(input:,k.arg)
getInput()
Lets look at this in detail. The lines:
stateName = get-input
k = c.k
state = k.getState(stateName)
dene a state name, get-input, unique to this code. k.getState returns the present state (an int) associated with
this state.
When getInput() is rst called, the state returned by k.getState will be 0, so the following lines are executed:
if state == 0:
k.setLabelBlue(Input: ,protect=True)
k.getArg(event,stateName,1,getInput)
These lines put a protected label in the minibuffer: the user cant delete the label by backspacing. getArg, and the
rest of Leos key handling code, take care of the extremely complex details of handling key strokes in states. The
call to getArg never returns. Instead, when the user has nished entering the input by typing <Return> getArg calls
getInput so that k.getState will return state 1, the value passed as the third argument to k.getArg. The following
lines handle state 1:
Leo, Release 4.6-b1
else:
k.clearState()
g.es_print(input:,k.arg)
k.arg is the value returned by k.getArg. This example code just prints the value of k.arg and clears the input state.
10.28 Creating Leo commands - @g.command
You can use the @g.command decorator to create new commands. This is an easy-to-use wrapper for
c.k.registerCommand(), with the following advantages over it:
The new command is automatically created for all Leo controllers (open Leo documents).
The new command is also automatically available on all new Leo controllers (documents that will be opened
in the future).
Prettier syntax.
Therefore, @g.command can be naturally prototyped with execute-script (Ctrl+b) in Leo node.
As an example, you can execute this script to make command hello available:
@g.command(hello)
def hello_f(event):
# use even[c] to access controller
c = event[c]
pos = c.currentPosition()
g.es(hello from, pos.h)
If you want to create a plugin that only exposes new commands, this is basically all you need in the plugins .py
le. There is no need to hook up for after-create-leo-frame just to make your commands available.
If you want to create a command in object oriented style (so that the commands deal with your own objects),
create them using closures like this (note how self is available inside command functions):
class MyCommands:
def create(self):
@g.command(foo1)
def foo1_f(event):
self.foo = 1
@g.command(foo2)
def foo2_f(event):
self.foo = 2
@g.command(foo-print)
def foo_print_f(event):
g.es(foo is, self.foo)
o = MyCommands()
o.create()
Note that running create() in this example in after-create-leo-frame is pointless - the newly created commands
will override the commands in all previous controllers. You should consider this in your plugin design, and create
your commands only once per Leo session.
10.28. Creating Leo commands - @g.command 99
Leo, Release 4.6-b1
CHAPTER
ELEVEN
CHAPTER 8: CUSTOMIZING LEO
This chapter discusses how to customize Leo using the plugins and other means. See Specifying settings for a
description of how to change Leos settings.
11.1 Specifying settings
Leo stores options in @settings trees, outlines whose headline is @settings. When opening a .leo le, Leo looks
for @settings trees not only in the outline being opened but also in various leoSettings.leo les. This scheme
allows for the following kinds of settings:
Per-installation or per-machine settings.
Per-user settings.
Per-folder settings.
Per-le settings.
There are four kinds of settings les:
1. Default settings les, named leoSettings.leo. Although they can be used in other ways, they typically
contain default settings.
2. Personal settings les, named myLeoSettings.leo. They provide a way of ensuring that your customized
settings are not altered when updating Leo frombzr or while installing a newversion of Leo. The myLeoSet-
tings.leo acts much like Pythons site-customize.py le. myLeoSettings.leo will never be part of any Leo
distribution, and it will never exist in Leos cvs repository. This solution is much better than trying to update
leoSettings.leo with scripts.
3. Machine settings les, named LeoSettings.leo (note the capital L), and appearing in a unique directory.
4. Command-line settings les, specied using Leos -c command-line option. Any .leo le may be used,
provided it has an @settings tree. These les typically provide a common set of settings for les scattered
in various places on the le system.
The following sections describe the kinds of nodes in @settings trees.
11.1.1 Conguration directories
Settings les can be found in the following directories:
homeDir, the HOME/.leo directory. HOME is given by Pythons HOME environment variable, or by
os.expanduser(~) if no HOME environment variable exists.
congDir, Leos conguration directory: leo/cong.
101
Leo, Release 4.6-b1
machineDir, the HOME/.leo/MACHINE directory. MACHINE is given by Pythons HOSTNAME envi-
ronment variable, or by Pythons COMPUTERNAME environment variable if there is no HOSTNAME
variable, or by the value returned by socket.gethostname() if neither environment variable exists.
localDir, the directory containing the .leo le being loaded.
In addition, Leos -c command-line option can specify any .leo le anywhere.
11.1.2 Search order for settings les
When reading a .leo le, Leo looks for settings in default settings les rst, then settings in personal settings les,
and nally settings in local settings les. The exact search order is:
1. Default settings les:
(a) congDir/leoSettings.leo
(b) homeDir/leoSettings.leo
(c) localDir/leoSettings.leo
2. Personal settings les:
(a) congDir/myLeoSettings.leo
(b) homeDir/myLeoSettings.leo
(c) homeDir/<machine-name>LeoSettings.leo (note capitalization)
(d) localDir/myLeoSettings.leo
3. Local settings les:
(a) The le specied by the -c command-line option.
(b) The le being loaded.
Settings that appear later in this list override settings that appear earlier in this list. This happens on a setting-by-
setting basis, not on a le-by-le basis. In other words, each individual setting overrides only the corresponding
setting in previously-read les. Reading a setting le does not reset all previous settings. Note that the same le
might appear several times in the search list. Leo detects such duplicate le names and only loads each settings
le once. Leo remembers all the settings in settings les and does not reread those settings when reading another
.leo le.
Caution: This search order offers almost too much exibilty. This can be confusing, even for power users. Its
important to choose the simplest conguration scheme that could possibly work. Something like:
Use a single leoSettings.leo le for installation-wide defaults.
Use a single myLeoSettings.leo les for personal defaults.
Use local settings sparingly.
Important: it is good style to limit settings placed in myLeoSettings.leo to those settings that differ from default
settings.
11.1.3 Safe rules for local settings
You should use special care when placing default or personal settings les in local directories, that is, directories
other than homeDir, congDir or machineDir. In particular, the value of localDir can change when Leo reads
additional les. This can result in Leo nding new default and personal settings les. The values of these newly-
read settings les will, as always, override any previously-read settings.
Let us say that a setting is volatile if it is different from a default setting. Let us say that settings le A.leo covers
settings le if B.leo if all volatile settings in B.leo occur in A.leo. With these denitions, the safe rule for placing
settings les in local directories is:
102 Chapter 11. Chapter 8: Customizing Leo
Leo, Release 4.6-b1
Settings files in local directories should
cover all other settings files.
Following this rule will ensure that the per-directory defaults specied in the local settings le will take precedence
over all previously-read default and personal settings les. Ignore this principle at your peril.
11.1.4 Organizer nodes
Organizer nodes have headlines that do no start with @. Organizer nodes may be inserted freely without changing
the meaning of an @setting tree.
11.1.5 @ignore and @if nodes
Leo ignores any subtree of an @settings tree whose headline starts with @ignore.
You can use several other kinds of nodes to cause Leo to ignore parts of an @settings tree:
@if expression
A node whose headline starts with @if expression acts like an organizer node if the expression evaluates
to True, otherwise acts like an @ignore node. If the expression is empty the body text should contain a
script that will be evaluated (in an empty context).
@ifplatform platform-name
Same as @if sys.platform == "platform-name": except that it isnt necessary to import sys.
@ifhostname hostA,!hostB
Evaluates to True iff: h=g.computeMachineName(); h==hostAand h!=hostB. The ! version allows match-
ing to every machineName except the given one to allow differing settings on only a few machines.
11.1.6 Simple settings nodes
Simple settings nodes have headlines of the form:
@<type> name = val
set the value of name to val, with the indicated type.
<type> may be one of the following:
<type> Valid values
@bool True, False, 0, 1
@color A Tk color name or value, such as red or xf2fddff (without the quotes)
@directory A path to a directory
@oat A oating point number of the form nn.ff.
@int An integer
@ints[list] An integer (must be one of the ints in the list). Example: @ints meaningOfLife[0,42,666]=42
@keys[name] Gives a name to a set of bindings for the Check Bindings script in leoSettings.leo.
@path A path to a directory or le
@ratio A oating point number between 0.0 and 1.0, inclusive.
@string A string
@strings[list] A string (must be one of the strings in the list). Example: @strings
tk_relief[at,groove,raised]=groove
Note: For a list of Tk color speciers see:
http://www.tcl.tk/man/tcl8.4/TkCmd/colors.htm
11.1. Specifying settings 103
Leo, Release 4.6-b1
http://www.tcl.tk/man/tcl8.4/TkLib/GetColor.htm
Important: you can use the show-colors minibuffer command to guide you in making these settings.
11.1.7 Complex settings nodes
Complex settings nodes have headlines of the form:
@<type> description
The type may be one of the following:
<type> Valid values
@buttons Child @button nodes create global buttons
@commands Child @command nodes create global buttons
@data Body text contains a list of strings, one per line.
@enabled-plugins Body text contains a list of enabled plugins
@font Body text contains a font description
@menus Child @menu and @item nodes create menus and menu items.
@menuat Child @menu and @item nodes modify menu tree create by @menus.
@mode [name] Body text contains a list of shortcut speciers.
@recentles Body text contains a list of le paths.
@shortcuts Body text contains a list of shortcut species.
Complex nodes specify settings in their body text. See the following sections for details.
@button
An @buttons tree in a settings le denes global buttons that are created in the icon area of all .leo les. All
@button nodes in the @commands tree create global buttons. All @button nodes outside the commands tree
create buttons local to the settings le.
@commands
An @commands tree in a settings le denes global commands. All @command nodes in the @commands tree
create global commands. All @command nodes outside the commands tree create commands local to the settings
le.
@data
The body text contains a list of strings, one per line. Lines starting with # are ignored.
@enabled-plugins
The body text of the @enabled plugins node contains a list of enabled plugins, one per line. Comment lines starting
with # are ignored. Leo loads plugins in the order they appear. Important: Leo handles @enabled-plugins nodes
a differently from other kinds of settings. To avoid confusion, please read the following carefully.
As always, Leo looks for @enabled-plugins nodes in settings les in the order specied by Search order for
settings les. Leo will enable all plugins found in the @enabled-plugins node it nds last in the search order.
Leo does not enable plugins found in any other @enabled-plugins node. In particular, you can not specify a list
of default plugins by placing that list in a settings le that appears early in the search list. Instead, the last
@enabled-plugins node found in the search list species all and only the plugins that will be enabled.
Let us distinguish two different situations. First, what Leo does when loading a le, say x.leo. Second, what Leo
does when loading a second le, say y.leo, from x.leo. When loading the rst .leo le, Leo enables plugins from the
@enabled-plugins node it nds last in the search order. But after plugins have already been loaded and enabled,
Leo, Release 4.6-b1
there is no way to disable previously loaded-and-enabled plugins. But local settings les can enable additional
plugins.
To avoid confusion, I highly recommend following another kind of safe rule. We say that an @enabled-plugin
node in le A.leo covers an @enabled-plugin node in le B.leo if all plugins specied in Bs @enabled-plugin
node appear As @enabled-plugin node. The safe rule for plugins is:
@enabled-plugin nodes in settings files in local directories
should cover @enabled-plugins nodes in all other settings files.
@font
The body text contains a list of settings for a font. For example:
body_text_font_family = Courier New
body_text_font_size = None
body_text_font_slant = None
body_text_font_weight = None
Important: you can use the show-fonts minibuffer command to guide you in making these settings.
@menuat
The form of this node is:
@menuat
*
<path>
* *
<action>
* *
[clipboard]
*
The @menuat setting has 2-3 parameters in its head text, its children are @menu and @item nodes as for the
@menu setting. @menuat modies the menu tree created by @menus. It is intended to be used in myLeoSet-
tings.leo to modify the menu tree created in leoSettings.leo. This allows you to change the menus without hav-
ing to re-create the entire menu tree from leoSettings.leo, and ensures you dont miss out when new things are
added in the @menus in leoSettings.leo, as you would if you replaced the @menus in leoSettings.leo with one in
myLeoSettings.leo. @menuat should occur in a @settings tree, but not as a descendant of a @menus tree. There
is an example of the use of the @menuat setting in the le .../leo/core/test/menuAtTest.leo.
The path argument species a target location in the menu tree as dened by @menus and modied by earlier
@menuat settings. The path takes the form /entry1/entry2/entry3 where each entry is the name of a menu or item
with all text except a-z and 0-9 removed. Upper case letters are converted to lower case. So for example to use the
Outline->Move->Move Down menu item as a target, you would specify a path as /outline/move/movedown.
The action argument species what the menu item does. There are 5 available actions:
before: The supplied items and sub menus will be inserted immediately before the target menu or item.
after: The supplied items and sub menus will be inserted immediately after the target menu or item.
append: The supplied items and sub menus will be appended at the end of the menu containing the target
menu or item.
cut: The target menu or item will be removed from the menu tree and saved to an internal clipboard. This
can be used for deleting menus or items. Descendants of the @menuat setting are ignored.
copy: The target menu or item will be copied and saved to an internal clipboard. Descendants of the
@menuat setting are ignored.
The optional clipboard argument modies the action of the before, after, and append actions. By default these
actions insert the menus and items supplied as descendants of the @menuat setting. If you specify clipboard
(without the quotes) as the source, the contents of the clipboard from a previous cut or copy action will be used
instead. This parameter is optional and can be left blank.
11.1. Specifying settings 105
Leo, Release 4.6-b1
@menus
Leo creates its menus from the @menu, @item and @popup nodes in the @menus tree. Within @menus trees,
@menu nodes create menus and @item nodes create menu items.
The menu name always follows @menu. If the menu name is Plugins, Leo will create the Plugins menu and
populate the menu by calling the create-optional-menus hook. This creates the Plugins menu as usual. Nested
@menu nodes dene submenus.
The command name follows @item. If the body text of an @item node exists, this body text is the menu name.
Otherwise, the menu name is the command name. However, if the command name starts with a
*
, hyphens are
removed from the menu name. Menu names and command names may contain a single ampersand (&). If present,
the following character is underlined in the name. If the command name in an @item node is just a hyphen (-),
the item represents a menu separator.
@popup <widget-name> creates a popup menu for use by the rClick plugin. The children of this node should be
@menu and @item nodes, used as with @menus.
@mode
The form of this node is:
@mode
*
<mode name>
*
The body text contains a list of shortcut speciers. @mode nodes work just like @shortcuts nodes, but in
addition they have the side effect of creating the enter-<mode name>-mode command.
@recentles
The body text contains a list of paths of recently opened les, one path per line. Leo writes the list of recent les
to .leoRecentFiles.txt in Leos config directory, again one le per line.
@shortcuts
The body text contains a list of shortcut speciers.
11.2 Input modes
Leo now allows you to specify input modes. You enter mode x with the enter-x-mode command. The purpose
of a mode is to create different bindings for keys within a mode. Often plain keys are useful in input modes.
You can specify modes with @mode nodes in leoSettings.leo. @mode nodes work just like @shortcuts nodes,
but in addition they have the side effect of creating the enter-<mode name>-mode command.
Notes:
You can exit any mode using the keyboard-quit (Control-g) command. This is the only binding that is
automatically created in each mode. All other bindings must be specied in the @mode node. In particular,
the bindings specied in @shortcuts nodes are not in effect in mode (again, except for the keyboard-quit
binding).
Leo supports something akin to tab completion within modes: if you type a key that isnt bound in a mode
a Mode tab will appear in the log pane. This tab shows all the keys that you can type and the commands
to which they are bound. The mode-help command does the same thing.
@shortcuts nodes specify the bindings for what might be called the top-level mode. These are the
bindings in effect when no internal state is present, for example, just after executing the keyboard-quit
command.
Leo, Release 4.6-b1
The top_level_unbound_key_action setting determines what happens to unbound keys in the top-
level mode. Leo ignores unbound keys in all other modes. The possibilities are insert, replace and
ignore.
The set-insert-mode, set-overwrite-mode and set-ignore-mode commands alter what
happens to unbound keys in the top-level mode.
With all these options it should be possible to emulate the keyboard behavior of any other editor.
11.3 Adding extensible attributes to nodes and .leo les
Leos .leo le format is extensible. The basis for extending .leo les are the t.unknownAttributes and
v.unknownAttributes ivars of tnodes and vnodes, or uAs for short. Leo translates between uAs and xml
attributes in the corresponding <v> and <t> elements in .leo les. Plugins may also use v.tempAttributes
or t.tempAttributes ivars to hold temporary information that will not be written to the .leo le.
Collectively, these four kinds of ivars are called attribute ivars. Attribute ivars must be Python dictionaries,
whose keys are names of plugins and whose values are other dictionaries, called inner dictionaries, for exclusive
use of each plugin. For example, a plugin named xyzzy would set t.unknownAttributes as follows:
# Create the uA if necessary.
if not hasattr(p.v.t,unknownAttributes):
p.v.t.unknownAttributes = {}
# Get the inner dictionary for the xyzzy plugin, creating it if necessary.
d = p.v.t.unknownAttributes.get(xyzzy,{})
# Set some values. These values must be picklable.
d [duration] = 5
d [notes] = "This is a note."
# Update the uA.
p.v.t.unknownAttributes [xyzzy] = d
if hasattr(p.v.t,"unknownAttributes"):
d = p.v.t.unknownAttributes.get("xyzzy",{})
g.es(d[duration])
g.es(d[notes])
Plugins would use similar code to create v.unknownAttributes, t.tempAttributes, and
v.tempAttributes ivars.
Important: All members of inner dictionaries should be picklable: Leo uses Pythons Pickle module to encode
all values in these dictionaries. Leo will discard any attributes that can not be pickled. This should not be a major
problem to plugins. For example, instead of putting a tnode into these dictionaries, a plugin could put the tnodes
gnx (a string) in the dictionary.
Note: Leo does not pickle members of inner dictionaries whose name (key) starts with str_. The values of
such members should be a Python string. This convention allows strings to appear in .leo les in a more readable
format.
Important: Plugins must not use v.unknownAttributes inside @thin trees. Indeed Leo uses hidden
machinery to write t.unknownAttributes. Leo does not write t.unknownAttributes to thin derived
les. Instead Leo writes a representation of all t.unknownAttributes contained in the @thin tree to a
special xml attribute called descendentTnodeUnknownAttributes in the <v> element corresponding to
the @thin node. Yes, this is complicated, but it works. Leo can not write v.unknownAttributes in @thin
trees because only tnodes have gnxs in thin derived les. In effect, vnodes are anonymous.
Plugins that must associate attributes with vnodes should support only @file trees. A completely different
alternative would be for the plugin to extend how Leo reads and writes <v> elements in .leo les, but that would
be much more complicated than using t.unknownAttributes
11.3. Adding extensible attributes to nodes and .leo les 107
Leo, Release 4.6-b1
Here are the details about how Leo associates uAs with <v> and <t> elements in .leo les:
Native xml attributes are the attributes of <v> and <t> elements that are known (treated spe-
cially) by Leos read/write code. The only native attribute of <t> elements is tx. The
native attributes of <v> elements are a, t, vtag, tnodeList, marks, expanded and
descendentTnodeUnknownAttributes. All other attributes of <v> and <t> elements are foreign
xml attributes.
When reading a .leo le, Leo will create t.unknownAttributes or v.unknownAttributes ivars
for any tnode or vnode whose corresponding <v> or <t> element contains a foreign xml attribute.
When writing a le, Leo will write foreign xml attributes in <v> or <t> elements if the corresponding
vnode or tnode contains an unknownAttributes ivar.
Leo performs the usual xml escapes on these strings when reading or writing the unknownAttributes
ivars.
11.4 Specifying Tk options using .leo_xresources
Leo looks for a le called .leo_xresources in the users home directory. If found, Leo will pass that le to
Tks option_readfile method for the top widget. This allows users to set Tk options.
11.5 Translating Leos menus and messages
It is easy to translate Leos menu strings: simply create an @menus tree in leoSettings.leo or myLeoSettings.leo
that contains the translated menu names.
New in Leo 4.4.8: Leo now contains support for translating messages sent to Leos log:
Rather than using an _ function to denote strings to be translated, Leos g.es and g.es_print functions
translate odd (rst, third, fth) arguments, leaving even arguments untranslated. Keyword arguments,
color, newline, etc. are never translated.
All calls to g.es and g.es_print in Leos core follow this convention.
g.translateString does the actual translation using Pythons gettext module.
You can use the script in the node @button print g.es stats in scripts.leo to create catalogs of all scripts
that need to be translated. Such catalogs are used by Pythons gettext module. (This script was also used to
check that the proper arguments to g.es and g.es_print were translated.)
CHAPTER
TWELVE
CHAPTER 9: HISTORY OF LEO
This chapter discusses the history of Leo and tells the essential features of each version. Here are the most
important dates in Leos history:
12.1 Beginnings
Leo grew out of my efforts to use Donald Knuths CWEB system of Structured documentation. I had known
of literate programming since the mid 1980s, but I never understood how to make it work for me. In November
1995 I started thinking about literate programming in earnest. Over the holidays I mused about making literate
programs more understandable. In January 1996 the fog of confusion suddenly cleared. I summarized my thinking
with the phrase, web are outlines in disguise. I suspected that outline views were the key to literate programming,
but many details remained obscure.
12.2 Breakthrough
March 5, 1996, is the most important date in Leos history. While returning from a day of skiing, I discussed my
thoughts with Rebecca. During that conversation I realized that I could use the MORE outliner as a prototype for a
literate outliner. I immediately started work on my rst literate outline. It quickly became apparent that outlines
work: all my old problems with literate programming vanished. The @others directive dates from this day. I
realized that MOREs outlines could form the basis for Leos screen design. Rather than opening body text within
the outline, as MORE does, I decided to use a separate body pane.
I hacked a translator called M2C which allowed me to use MORE to write real code. I would write code in MORE,
copy the text to the clipboard in MORE format, then run M2C, which would tangle the outline into C code. This
process was useful, if clumsy. I called the language used in the outline SWEB, for simplied CWEB. Much later
Leo started supporting the noweb language.
12.3 Apple and YellowBox
Throughout 1996 I created a version of Leo on the Macintosh in plain C and the native Mac Toolbox. This was
a poor choice; I wasted a huge amount of time programming with these primitive tools. However, this effort
convinced me that Leo was a great way to program.
Late in 1997 I wrote a Print command to typeset an outline. Printing (Weaving) is supposedly a key feature
of literate programming. Imagine my surprise when I realized that such a beautiful program listing was almost
unintelligible; all the structure inherent in the outline was lost! I saw clearly that typesetting, no matter how well
done, is no substitute for explicit structure.
In 1998 I created a version of Leo using Apples YellowBox environment. Alas, Apple broke its promises to Apple
developers. I had to start again.
109
Leo, Release 4.6-b1
12.4 Borland C++
I rewrote Leo for Borland C++ starting in May 1999. Borland C++ was much better than CodeWarrior C, but it
was still C++. This version of Leo was the rst version to use xml as the format of .leo les. The last version of
Borland Leo, 3.12 Final went out the door July 17, 2003.
12.5 Discovering Python
I attended the Python conference in early 2001. In May of 2000 I began work on an wxWindows version of Leo.
This did not work out, but something good did come from this effort. I spent a lot of time adding Python scripting
to the wxWindows code and I became familiar with Python and its internals.
I really started to get Python in September 2001. I wrote the white papers at about this time. Python solved all
my programming problems. I rewrote Leo in Python in about two months! For the rst time in my career I was no
longer anxious while programming; it simply isnt possible to create bad bugs in Python. The Python version of
Leo was the rst ofcially OpenSoftware version of Leo. The rst functional version of Leo in Python was 0.05
alpha, December 17, 2001.
12.6 SourceForge
I registered the Leo project on SourceForge on March 10, 2003. It is certainly no accident that Leo started a new
life shortly thereafter. Prior to SourceForge my interest in Leo had been waning.
12.7 Allowing sentinel lines in derived les
In the summer of 2001 I began to consider using sentinel lines in derived les. Previously I had thought that
outline structure must be protected by remaining inside .leo les. Accepting the possibility that sentinels might
be corrupted opened vast new design possibilities. In retrospect, problems with sentinel almost never happen, but
that wasnt obvious at the time! The result of this design was known at rst as Leo2. That terminology is extinct.
I think of this version as the rst version to support @file and automatic tangling and untangling.
12.8 Untangling @le is easy!
The biggest surprise in Leos history was the realization it is much easier to untangle les derived from @file.
Indeed, @root creates all sorts of problems that just disappear when using @file. The new Python version of
Leo became fully operational in early 2002. It was probably about this time that I chose noweb as Leos preferred
markup language. My decision not to support nowebs escape sequences made Leos read code much more robust.
12.9 Leo 3.x: Continuous improvement
I spent 2002 taking advantages of Pythons tremendous power and safety. Many improvements were at last easy
enough to do:
Nested @others directives appeared in 3.2.
Unicode support started in 3.3.
@rst and @last appeared in 3.7
@asis and @nosent appeared in 3.8.
110 Chapter 12. Chapter 9: History of Leo
Leo, Release 4.6-b1
Incremental syntax coloring and incremental undo appeared in 3.9.
Paul Paterson created Leos plugin architecture sometime during this period. Plugins have been a driving
force in Leos development because people can change how Leo works without altering Leos core.
3.12 xed a huge memory leak.
3.12 Final, the last 3.x version, appeared July 17, 2003.
12.10 Leo 4.0: Eliminating error recovery
In late 2002 and throughout 2003 I worked on an entirely new le format. 4.0 nal went out the door October 17,
2003 after almost a year intense design work trying to improve error recovery scheme used while reading derived
les. In the summer of 2003 I realized that orphan and @ignored nodes must be prohibited in @file trees.
With this restriction, Leo could nally recreate @file trees in outlines using only the information in derived les.
This made the read code much more robust, and eliminated all the previous unworkable error recovery schemes.
At last Leo was on a completely rm foundation.
12.11 Leo 4.1: The debut of gnxs
Leo rst used gnxs (global node indices) as a foolproof way of associating nodes in .leo les with nodes in derived
les. At the time, there was still intense discussions about protecting the logical consistency of outlines. @thin
was later to solve all those problems, but nobody knew that then.
12.12 Leo 4.2: Complete at last
Leo 4.2 Final went out the door September 20, 2004. This surely is one of the most signicant dates in Leos
history:
This marked the end worries about consistency of outlines and derived les: Leo recreates all essential
information from thin derived les, so there is nothing left in the .leo le to get out of synch.
Thin derived les use gnxs extensively. This simplies the le format and makes thin derived les more
cvs friendly.
A sensational scripting plugin showed how to create script buttons. This has lead to improvements in the
Execute Script command and other signicant improvements in Unit testing.
As if this were not enough, 4.2 marked the great divide in Leos internal data structures. Before 4.2,
Leo every node in the outline had its own vnode. This was a big performance problem: clone operations
had to traverse the entire outline! 4.2 represents clones by sharing subtrees. Changing Leos fundamental
data structures while retaining compatibility with old scripts was engineering work of which the entire
Leo community can be proud. Chapter 7: Scripting Leo with Python tells how the position class makes
this happen. This was a cooperative effort. Kent Tenney and Bernhard Mulder made absolutely crucial
contributions. Kent pointed out that it is a tnode, not a vnode that must form the root of the shared data.
Bernhard showed that iterators are the way to avoid creating huge numbers of positions.
Leo 4.2 marked so many signicant changes. I often nd it hard to remember what life with Leo was like before
it.
12.13 Leo 4.3 Settings
Leo 4.3 corrected many problems with leoConfig.txt. Instead, Leo gets settings from one or more
leoSettings.leo files. This version also introduced a way to changed settings using a settings dia-
12.10. Leo 4.0: Eliminating error recovery 111
Leo, Release 4.6-b1
log. However, the settings dialog proved not to be useful (worse, it inhibited design) and the settings dialog was
retired in Leo 4.4.
12.14 Leo 4.4 The minibuffer and key bindings
Leo 4.4 was a year-long effort to incorporate an Emacs-style minibuffer and related commands into Leo. Thinking
in terms of minibuffer commands frees my thinking. Leo 4.4 also featured many improvements in how keys are
bound to commands, including per-pane bindings and user-dened key-binding modes.
Development on long-delayed projects accelerated after 4.4 nal went out the door. Recent projects include:
Controlling syntax coloring with jEdits xml language-description les. See Chapter 15.
Support for debugging scripts using external debuggers. See Chapter 16.
Modifying Leos vnodes and tnodes so that Leos data can be used with ZODB. See Chapter 17.
Using pymacs to write Leo scripts within Emacs. See Chapter 18.
Using the leoBridge module to embed Leo support in other programs. See Chapter 19.
Using Leo to run unit tests. See Chapter 20.
12.15 Leo 4.4.4 Improvements
Leo 4.4.1 through 4.4.8 contained many incremental improvements, as documented in Chapters 15 through 21 of
this Users Guide.
12.15.1 Leo 4.4.1
Supported multiple editors in body pane.
Added the jEdit_colorizer plugin. See Chapter 15: Controlling Syntax Coloring.
Added the slideshow plugin.
12.15.2 Leo 4.4.2
Added support for myLeoSettings.leo
The Big Reorg made Leos vnodes and tnode classes independent of the rest of Leo.
Added support for ZODB. See Chapter 17: Using ZODB with Leo.
Added leoPymacs module. See Chapter 18: Leo and Emacs.
Added the leoOPML, leo_to_rtf and leo_to_html plugins.
Added outline navigation: typing a letter selects the next outline node that starts with that letter.
Added autocontract during nds.
Added new commands and options to make Leo usable without a mouse.
Added an option sax parser for reading .leo les.
Leo, Release 4.6-b1
12.15.3 Leo 4.4.3
Added support for chapters in Leos core.
Added support for zipped .leo les.
Added the leoBridge module. See Chapter 19: Embedding Leo with the leoBridge Module.
Removed all gui-dependent code from Leos core.
Added better support for the winpdb debugger.
Added support for @enabled-plugins and @open-with nodes in settings les.
12.15.4 Leo 4.4.4
The Great Graph Aha: Outlines dont have to be graphs to represent graphs. This Aha meant that there is
no need for a separate graph world.
Added support for @menus and @buttons trees in settings les.
Added perfect import of foreign les with @auto nodes.
Added new commands for resolving cvs conicts.
Replaced the jEdit_colorizer plugin with the threading_colorizer plugin.
Made Leo compatible with jython.
Added better support for icons in headlines.
12.15.5 Leo 4.4.5
Leo now recognizes directives in headlines.
Added support for @rst-preformat nodes to the rst3 plugin.
12.15.6 Leo 4.4.7 and Leo 4.4.8
Added the ILeo, the IPython bridge. See Chapter 21: ILeo - the IPython bridge.
Added support for translating messages to Leos log.
12.15. Leo 4.4.4 Improvements 113
Leo, Release 4.6-b1
CHAPTER
THIRTEEN
CHAPTER 10: THEORY OF
OPERATION
This chapter discusses how Leos code works, paying particular attention to topics that have caused difculties in
design or implementation. This chapter will be of use primarily to those wanting to change Leos code.
13.1 Overview
All versions of Leo are organized as a collection of classes. The general organization of Leo has remained re-
markably stable throughout all versions of Leo, although the names of classes are different in different versions.
Smalltalks Model/View/Controller terminology is a good way think about Leos classes. Model classes represent
the fundamental data. The vnode and tnode classes are Leos primary model classes.
View classes draw the screen. The main view classes are leoFrame.py and leoTree.py. The colorizer class in
leoColor.py handles syntax coloring in the body pane. Leos view classes know about data stored in the vnode
class. Most events (keystrokes and mouse actions) in the outline and body pane are handled in the leoTree class.
The leoFrame class also creates the Leo window, including menus, and dispatches the appropriate members of the
controller classes in response to menu commands.
Controller classes (aka commanders) control the application. In Leo, controllers mostly handle menu commands.
Commanders create subcommanders to handle complex commands. The atFile class reads and writes les derived
from @file trees. The LeoFind class handles the Find and Change commands. The leoImportCommands class
handles the Import and Export commands, the tangleCommands class handles the Tangle and Untangle commands
and the undoer class handles the Undo command. Other classes could be considered controller classes.
Each Leo window has its own commander and subcommanders. Subcommanders are not subclasses of their
commander. Instead, subcommanders know the commander that created them, and call that commander as needed.
Commanders and subcommanders call the model and view classes as needed. For example, the Commands class
handles outline commands. To move a headline, the commander for the window calls a vnode move routine to
alter the data, then calls the view class to redraw the screen based on the new data.
A singleton instance of the LeoApp class represents the application itself. All code uses the app() global function
to gain access to this singleton member. The ivars of the LeoApp object are the equivalent of Leos global
variables. leo.py uses no global Python variables, except the gApp variable returned by app(). leoGlobals.py
denes all application constants. Naturally, most constants are local to the class that uses them.
Several classes combine aspects of model, view and controller. For example, the LeoPrefs class represents user
preferences (model), the Preference Panel (view) and the Preferences menu command (controller). Similarly, the
LeoFind class represents nd settings, the Find/Change dialog, and the Find/Change commands.
We use the following convention throughout this documentation. Any variable named c is a commander, i.e.,
an instance of the Commands class in leoCommands.py. Variables named v and t are vnodes and tnodes
respectively. These classes are dened in leoNodes.py.
115
Leo, Release 4.6-b1
13.2 Nodes
The vnode and tnode classes represent most of the data contained in the outline. These classes are Leos funda-
mental Model classes. A vnode (visual node) represents a headline at a particular location on the screen. When a
headline is cloned, vnodes must be copied. vnodes persist even if they are not drawn on the screen. Commanders
call vnode routines to insert, delete and move headlines.
The vnode contains data associated with a headline, except the body text data which is contained in tnodes. A
vnode contains headline text, a link to its tnode and other information. Vnodes contain structure links: parent,
rstChild, next and back ivars. To insert, delete, move or clone a vnode the vnode class just alters those links. The
Commands class calls the leoTree class to redraw the outline pane whenever it changes. The leoTree class knows
about these structure links; in effect, the leoTree and vnode classes work together.
A tnode, (text node) represents body text. All vnodes that are clones of each other share the same tnode. In other
words, tnodes are the unit of sharing of body text. The tnode class is more private than the vnode class. Most
commanders deal only with vnodes, though there are exceptions.
Because Leo has unlimited Undo commands, Leo deletes vnodes and tnodes only when a window closes. Leo
deletes nodes indirectly using destroy methods. Several classes, including the vnode, tnode, leoFrame and
leoTree classes, have destroy methods. destroy methods merely clear links so that Pythons and Tkinters
reference counting mechanisms will eventually delete vnodes, tnodes and other data when a window closes.
Leos XML le format uses tnode indices to indicate which tnodes (t elements) belong to which vnodes (v
elements). Such indices are required. Even if we duplicated the body text of shared tnodes within the le, the le
format would still need an unambiguous way to denote that tnodes are shared. Present versions of Leo use gnxs
(global node indices) as node indices. These indices do not change once a node has created. This reduces cvs
conicts.
13.3 Drawing and events
Leo must redraw the outline pane when commands are executed and as the result of mouse and keyboard events.
The main challenges are eliminating icker and handling events properly. These topics are interrelated.
Eliminating icker. Leo must update the outline pane with minimum icker. Various versions of Leo have
approached this problem in different ways. The drawing code in leo.py is robust, exible, relatively simple
and should work in almost any conceivable environment. Leo assumes that all code that changes the outline
pane will be enclosed in matching calls to the c.beginUpdate and c.endUpdate methods of the Commands class.
c.beginUpdate() inhibits drawing until the matching c.endUpdate(). These calls may be nested; only the outermost
call to c.endUpdate() calls c.redraw() to force a redraw of the outline pane.
Code may call c.endUpdate(flag) instead of c.endUpdate(). Leo redraws the screen only if ag is
true. This allows code to suppress redrawing entirely when needed. For example, here is how the idle_body_key
event handler in leoTree.py conditionally redraws the outline pane:
redraw_flag = false
c.beginUpdate()
val = v.computeIcon()
if val != v.iconVal:
v.iconVal = val
redraw_flag = true
c.endUpdate(redraw_flag) # redraw only if necessary
The leoTree class redraws all icons automatically when c.redraw() is called. This is a major simplication
compared to previous versions of Leo. The entire machinery of drawing icons in the vnode class has been elimi-
nated. The v.computeIcon method tells what the icon should be. The v.iconVal ivar tells what the present
icon is. The event handler simply compares these two values and sets redraw_flag if they dont match.
Handling events. Besides redrawing the screen, Leo must handle events or commands that change the text in the
outline or body panes. It is surprisingly difcult to ensure that headline and body text corresponds to the vnode
and tnode corresponding to presently selected outline, and vice versa. For example, when the user selects a new
116 Chapter 13. Chapter 10: Theory of Operation
Leo, Release 4.6-b1
headline in the outline pane, we must ensure that 1) the vnode and tnode of the previously selected node have
up-to-date information and 2) the body pane is loaded from the correct data in the corresponding tnode. Early
versions of Leo attempted to satisfy these conditions when the user switched outline nodes. Such attempts never
worked well; there were too many special cases. Later versions of Leo, including leo.py, use a much more direct
approach. The event handlers make sure that the vnode and tnode corresponding to the presently selected node
are always kept up-to-date. In particular, every keystroke in the body pane causes the presently selected tnode to
be updated immediately. There is no longer any need for the c.synchVnode method, though that method still
exists for compatibility with old scripts.
The leoTree class contains all the event handlers for the body and outline panes. The actual work is done in the
idle_head_key and idle_body_key methods. These routines are surprisingly complex; they must handle
all the tasks mentioned above, as well as others. The idle_head_key and idle_body_key methods should
not be called outside the leoTree class. However, it often happens that code that handles user commands must
simulate an event. That is, the code needs to indicate that headline or body text has changed so that the screen
may be redrawn properly. The leoTree class denes the following simplied event handlers: onBodyChanged,
onBodyWillChange, onBodyKey, onHeadChanged and onHeadlineKey. Commanders and subcom-
manders call these event handlers to indicate that a command has changed, or will change, the headline or body
text. Calling event handlers rather than c.beginUpdate and c.endUpdate ensures that the outline pane is
redrawn only when needed.
13.4 Clones
Since version 4.2, Leo represents clones by sharing tnodes. Cloned vnodes share the same tnode. This shared
tnode represents the entire shared subtree of both clones. Thus, the _firstChild link must reside in tnodes,
not vnodes.
Because vnodes may be visited many times during a complete traversal of a tree, a vnode does not repre-
sent unique location on the screen. As a result, the position class had to be invented. c.rootVnode and
c.currentVnode now return positions instead of vnodes. The position class was designed to allow compati-
bility with old scripts. Old code can use positions just like they used to use vnodes.
Earlier versions of Leo duplicated all the descendants of vnode v when cloning v. This created many complications
that no longer exist. In particular, in the new scheme a vnode v is cloned if and only if len(v.t.vnodeList)
> 1.
13.5 Find and change commands
The nd and change commands are tricky; there are many details that must be handled properly. The following
principles govern the LeoFind class:
1. Find and Change commands initialize themselves using only the state of the present Leo window. In par-
ticular, the Find class must not save internal state information from one invocation to the next. This means
that when the user changes the nodes, or selects new text in headline or body text, those changes will affect
the next invocation of any Find or Change command. Failure to follow this principle caused all kinds of
problems in the Borland and Macintosh codes. There is one exception to this rule: we must remember
where interactive wrapped searches start. This principle simplies the code because most ivars do not per-
sist. However, each command must ensure that the Leo window is left in a state suitable for restarting the
incremental (interactive) Find and Change commands. Details of initialization are discussed below.
2. The Find and Change commands must not change the state of the outline or body pane during execu-
tion. That would cause severe ashing and slow down the commands a great deal. In particular, the
c.selectPosition and c.editPosition methods must not be called while looking for matches.
3. When incremental Find or Change commands succeed they must leave the Leo window in the proper state
to execute another incremental command. We restore the Leo window as it was on entry whenever an
incremental search fails and after any Find All and Change All command. Initialization involves setting the
self.c, self.v, self.in_headline, self.wrapping and self.s_text ivars.
13.4. Clones 117
Leo, Release 4.6-b1
Setting self.in_headline is tricky; we must be sure to retain the state of the outline pane until initialization
is complete. Initializing the Find All and Change All commands is much easier because such initialization does
not depend on the state of the Leo window. Using Tk.Text widgets for both headlines and body text results in a
huge simplication of the code.
Indeed, the searching code does not know whether it is searching headline or body text. The search code knows
only that self.s_text is a Tk.Text widget that contains the text to be searched or changed and the insert
and sel Tk attributes of self.search_text indicate the range of text to be searched. Searching headline and body
text simultaneously is complicated. The selectNextVnode() method handles the many details involved by setting
self.s_text and its insert and sel attributes.
13.6 Tangle and untangle commands
This section describes Leos explicit Tangle and Untangle commands. Such commands operate only on
@root and @unit trees. The previous chapter discusses the implicit Tangle on Write/Untangle on Read pro-
cesses used to read and write @file trees.
The Tangle command translates the selected @root tree into one or more well-formatted C source les. The
outline should contain directives, sections references and section denitions, as described in Chapter 4. The
Untangle command is essentially the reverse of the Tangle command. The Tangle command creates a derived
le from an @root tree; the Untangle command incorporates changes made to derived les back into the @root
tree.
The Tangle command operates in two passes. The rst pass discovers the complete denitions of all sections and
places these denitions in a symbol table. The rst pass also makes a list of root sections. Denitions can appear
in any order, so we must scan the entire input le to know whether any particular denition has been completed.
This second pass creates one le for each @root node. Tangle rescans each section in the list of roots, copying
the root text to the output and replacing each section reference by the sections denition. This is a recursive
process because any denition may contain other references. We can not allow a section to be dened in terms
of itself, either directly or indirectly. We check for such illegally recursive denitions in pass 2 using the section
stack class. Tangle indicates where sections begin and end using comment lines called sentinel lines. The this
part of the appendix discusses the format of the sentinels output by the Tangle command.
The key design principle of the Tangle command is this:
Tangle must output newlines in a context-free manner.
That is, Tangle must never output conditional newlines, either directly or indirectly. Without this rule
Untangle could not determine whether to skip or copy newlines.
The Tangle command increases the indentation level of a section expansion the minimum necessary to align the
section expansion with the surrounding code. In essence, this scheme aligns all section expansions with the line
of code in which the reference to the section occurs. In some cases, several nested sections expansions will have
the same indentation level. This can occur, for example, when a section reference in an outline occurs at the left
margin of the outline.
This scheme is probably better than more obvious schemes that indent more consistently. Such schemes would
produce too much indentation for deeply nested outlines. The present scheme is clear enough and avoids inden-
tation wherever possible, yet indents sections adequately. End sentinel lines make this scheme work by making
clear where the expansion of one section ends and the expansion of a containing section resumes.
Tangle increases indentation if the section reference does not start a line. Untangle is aware of this hack and
adjusts accordingly. This extra indentation handles several common code idioms, which otherwise would cre-
ate under-indented code. In short, Tangle produces highly readable output, given the necessity of preserving
newlines for Untangle.
Untangle is inherently complex. It must do a perfect job of updating the outline, especially whitespace, from
expansions of section denitions created by the Tangle command. Such expansions need not be identical because
they may have been generated at different levels of indentation. The Untangle command can not assume that
all expansions of a section will be identical in the derived le; within the derived le, the programmer may have
Leo, Release 4.6-b1
made incompatible changes to two different expansions of the same section. Untangle must check to see that all
expansions of a section are equivalent. As an added complication, derived les do not contain all the information
found in @root trees. @root trees may contain headlines that generate no code at all. Also, an outline may dene
a section in several ways: with an @c or @code directive or with a section denition line. To be useful, Untangle
must handle all these complications awlessly. The this part of the appendix discusses the various conventions
used in the sentinels output by the Tangle command. These conventions allow the Untangle command to
recreate whitespace correctly.
Untangle operates in two passes. The rst pass nds denitions in the derived le and enters them into the
Untangle Symbol Table, or UST. Denitions often include references to other sections, so denitions often
include nested denitions of referenced sections. The rst pass uses a denition stack to keep track of nested
denitions. The top of the stack represents the denition following the latest reference, except for the very rst
entry pushed on the stack, which represents the code in the outline that contains the @root directive. The stack
never becomes empty because of the entry for the @root section. All denitions of a section should match
otherwise there is an inconsistent denition. This pass uses a forgiving compare routine that ignores differences
that do not affect the meaning of a program.
The second pass of Untangle enters denitions from the outline into the Tangle Symbol Table, or TST. The
second pass simultaneously updates all sections in the outline whose denition in the TST does not match the
denition in the UST. The central coding insight of the Untangle command is this: the second pass of Untangle
is almost identical to the rst pass of Tangle. That is, Tangle and Untangle share key parts of code, namely
the skip_body method and its allies. Just when skip_body enters a denition into the symbol table, all the
information is present that Untangle needs to update that denition.
13.7 Unicode
Leo uses unicode objects in vnodes and tnodes to denote headline and body text. Note that unicode strings have no
encoding; only plain strings have encodings. This means that once an (encoded) plain string has been converted
to a unicode string it doesnt matter how the unicode string was created. This is the key that makes Leos new
code robust: internally Leo never has to worry about encodings. Encoding matter only when encoded strings are
converted to and from Unicode. This happens when Leo reads or writes les.
Python expressions that mix unicode strings u and plain strings s, like one of these:
u + s
u == s
u[5] == s[2:]
are promoted to unicode objects using the system encoding. This encoding should never be changed, but we
cant assume that we know what it is, so for safety we should assume the most restrictive encoding, namely ascii.
With this assumption, Leos code cant throw an exception during these promotions provided that:
All strings are converted to unicode when Leo reads les or gets text from Tk.Text widgets.
All string literals in Leos code have only ascii characters.
13.8 Unlimited undo
Unlimited undo is straightforward; it merely requires that all commands that affect the outline or body text must
be undoable. In other words, everything that affects the outline or body text must be remembered. We may think
of all the actions that may be Undone or Redone as a string of beads (undo nodes).
Undoing an operation moves backwards to the next bead; redoing an operation moves forwards to the next bead.
A bead pointer points to the present bead. The bead pointer points in front of the rst bead when Undo is disabled.
The bead pointer points at the last bead when Redo is disabled. An undo node is a Python dictionary containing all
information needed to undo or redo the operation. The Undo command uses the present bead to undo the action,
then moves the bead pointer backwards.
13.7. Unicode 119
Leo, Release 4.6-b1
The Redo command uses the bead after the present bead to redo the action, then moves the bead pointer forwards.
All undoable operations call setUndoParams() to create a new bead. The list of beads does not branch; all undoable
operations (except the Undo and Redo commands themselves) delete any beads following the newly created bead.
I did not invent this model of unlimited undo. I rst came across it in the documentation for Apples Yellow Box
classes.
13.9 Key bindings
leoKeys.py handles key bindings. There are two kinds of bindings, gui bindings and pane bindings.
Gui bindings are the actual binding as seen by Tkinter (or whatever gui is in effect). Leo binds every key that
has a binding to k.masterKeyHander. For Tkinter, a separate binding must be made, rather than a single <Key>
binding, because, alas, Tkinter key events provide insufcient enough information to tell what key actually caused
the key event(!) This is a signicant hole in Tkinters event mechanism.
At present Leo makes gui bindings in several places, all equivalent. Bindings are made to callbacks, all of which
have this form:
def callback(event=None,k=k,stroke=stroke):
return k.masterKeyHandler(event,stroke)
As a result, changing gui bindings actually has no effect whatever. It would be clearer to have a single place to
make these bindings...
In any case, the purpose of these callbacks is to capture the value of stroke so that it can be passed to
k.masterKeyHandler. This relieves k.masterKeyHandler of the impossible task of computing the stroke from
the event. Important: No function argument is ever passed to k.masterKeyHandler from these callbacks, because
k.masterKeyHandler binds keys to command handlers as described next.
Pane bindings are bindings represented by various Python dictionaries in the keyHandlerClass (see below).
k.masterKeyHandler and its helpers use these dictionaries to call the proper command or mode handler. This
logic is hairy, but it is completely separate from the gui binding logic.
Here are the dictionaries that k.masterKeyHandler uses:
c.commandsDict: Keys are minibuffer command names; values are functions f.
k.inverseCommandsDict: Keys are f.__name__l values are emacs command names.
k.bindingsDict: Keys are shortcuts; values are lists of g.bunch(func,name,warningGiven).
k.masterBindingsDict: Keys are pane names: all,text,etc. or mode names. Values are dicts: keys are
strokes; values are g.Bunch(commandName,func,pane,stroke).
k.modeWidgetsDict: Keys are mode names; values are lists of widgets to which bindings have been made.
k.settingsNameDict: Keys are lowercase settings; values are real Tk key speciers. Important: this table
has no inverse.
inverseBindingDict: This is not an ivar; it is computed by k.computeInverseBindingDict(). Keys are emacs
command names; values are lists of shortcuts.
CHAPTER
FOURTEEN
CHAPTER 11: WHITE PAPERS
I wrote the rst two white papers soon after discovering Python. The conclusions in these papers have remained
largely unchanged. I wrote the third in November 2004, and rewrote it in February 2006.
14.1 Tk is the future of Leo
The more I look at Tk, the more convinced I am that Python + Tk (aka Tkinter) is, by far, the best way to go
with Leo. I now have Open Source code for tree widgets and splitter windows, and have intensely studied how to
modify that code for use in Leo. It is clear, even at this early date, that this code will provide a very pleasant base
on which to build Leo.
The tree code is based on code in IDLE, the Python IDE. This code is simple, good and plenty fast enough. The
tree code draws directly to a Tk canvas object. The look and feel matches Windows exactly. It would be trivial to
use Mac triangle icons instead of the Windows plus and minus icons. It would also be trivial to modify the look
and feel for Linux.
The tree widget code solves several intractable problems with wxTreeCtrl. Moving nodes becomes trivial.
Bugs in wxTreeCtrl involving editing and redrawing disappear. Using Python/Tk code simplies the vnode
class, and having access to the vnode class simplies and speeds up the tree widget code. It will now be possible
to bind keystrokes properly; this simply can not be done in wxWindows. The tree widget code shows just how
trivial the Windows native tree control is. The Tk canvas is a splendid example of higher-level code being superior,
in every way, to lower level code.
Another big win comes from using the Tk text widget. This widget is extraordinarily powerful. The only text
control that rivals it is the MacOS/Yellow Box text control. Indeed, the Tk text widget does everything that
Leo could possibly want. One can even embed images in text.
In short, using Tk for Leo will be fast enough and will greatly increase what is possible in Leo while at the same
time greatly simplifying Leos code. I am about to convert Leo from wxPython to Python + Tk. Edward K. Ream,
November 4, 2001
14.2 Why I like Python
Ive known for a while that Python was interesting; I attended a Python conference last year and added Python
support to Leo. But last week I got that Python is something truly remarkable. I wanted to convert Leo from
wxWindows to wxPython, so I began work on c2py, a Python script that would help convert from C++ syntax
to Python. While doing so, I had an Aha experience. Python is more than an incremental improvement over
Smalltalk or C++ or objective-C; it is something completely different. The rest of this post tries to explain this
difference.
121
Leo, Release 4.6-b1
14.2.1 Clarity
What struck me rst as I converted C++ code to Python is how much less blah, blah, blah there is in Python.
No braces, no stupid semicolons and most importantly, no declarations. No more pointless distinctions between
const, char
*
, char const
*
, char
*
and wxString. No more wondering whether a variable should
be signed, unsigned, short or long.
Declarations add clutter, declarations are never obviously right and declarations dont prevent memory allocation
tragedies. Declarations also hinder prototyping. In C++, if I change the type of something I must change all
related declarations; this can be a huge and dangerous task. With Python, I can change the type of an object
without changing the code at all! Its no accident that Leos new log pane was created rst in Python.
Functions returning tuples are a minor feature with a huge impact on code clarity. No more passing pointers to
data, no more dening (and allocating and deallocating) temporary structs to hold multiple values.
Python cant check declarations because there arent any. However, there is a really nifty tool called Pychecker
that does many of the checks typically done by compilers. See pychecker for details.
14.2.2 Power
Python is much more powerful than C++, not because Python has more features, but because Python needs less
features. Some examples:
Python does everything that the C++ Standard Template Library (STL) does, without any of the blah, blah,
blah needed by STL. No fuss, no muss, no code bloat.
Pythons slicing mechanism is very powerful and applies to any sequence (string, list or tuple). Pythons
string library does more with far less functions because slices replace many functions typically found in
other string libraries.
Writing dict = {} creates a dictionary (hash table). Hash tables can contain anything, including lists and
other hash tables.
Pythons special functions, __init__, __del__, __repr__, __cmp__, etc. are an elegant way to
handle any special need that might arise.
14.2.3 Safety
Before using Python I never fully realized how difcult and dangerous memory allocation is in C++. Try doing:
aList[i:j] = list(aString)
in C. You will write about 20 lines of C code. Any error in this code will create a memory allocation crash or leak.
Python is fundamentally safe. C++ is fundamentally unsafe. When I am using Python I am free from worry and
anxiety. When I am using C++ I must be constantly on guard. A momentary lapse can create a hard-to-nd
pointer bug. With Python, almost nothing serious can ever go wrong, so I can work late at night, or after a beer.
The Python debugger is always available. If an exception occurs, the debugger/interpreter tells me just what went
wrong. I dont have to plan a debugging strategy! Finally, Python recovers from exceptions, so Leo can keep right
on going even after a crash!
14.2.4 Speed
Python has almost all the speed of C. Other interpretive environments such as icon and Smalltalk have clarity,
power and safety similar to Python. What makes Python unique is its seamless way of making C code look like
Python code. Python executes at essentially the speed of C code because most Python modules are written in C.
The overhead in calling such modules is negligible. Moreover, if code is too slow, one can always create a C
module to do the job.
122 Chapter 14. Chapter 11: White Papers
Leo, Release 4.6-b1
In fact, Python encourages optimization by moving to higher levels of expression. For example, Leos Open
command reads an XML le. If this command is too slow I can use Pythons XML parser module. This will speed
up Leo while at the same time raising the level of the code.
14.2.5 Conclusions
Little of Python is completely new. What stands out is the superb engineering judgment evident in Pythons
design. Python is extremely powerful, yet small, simple and elegant. Python allows me to express my intentions
clearly and at the highest possible level.
The only hope of making Leo all it can be is to use the best possible tools. I believe Python (possibly with Tkinter)
will allow me to add, at long last, the new features that Leo should have.
Edward K. Ream, October 25, 2001. P.S., September, 2005:
Four years of experience have only added to my admiration for Python. Leo could not possibly be what it is today
without Python.
14.3 Allocating storage using lifetimes
This white paper describes the storage allocation used in a commercial optimizing C compiler written for Tuple,
Inc. ca. 1993. The last section discusses tantalizing possibilities for the pypy project. These possibilities are why
I wrote this paper.
Storage allocation is crucial to any compiler because of the number, size and complexity of data which must be
allocated. You might event say that a compiler consists of storage allocation and everything else. I paid a lot of
attention to storage allocation in CC2, and that work paid off. The resulting compiler was a few percent faster
than the CodeWarrior C compiler, perhaps the fastest C compiler in existence at that time. The original notes
were written around 1993, so I would do some things differently today. However, the design discussed below still
seems relevant today. Indeed, attention to low-level details can make a huge difference.
14.3.1 Lifetime allocation
CC2 allocated objects one-at-a-time (simple allocation), in blocks of xed-sized objects (block allocation) or in
blocks of variable-sized objects (lifetime-based allocation). Simple-allocation was used for short-lived objects
and will not be discussed further. Block allocation was used in several ways, the most interesting of which was
to allocate cons cells used to represent lists. These cons cells could be reused by placing them on a global avail
list. Thus, the blocks holding cons cells could (and did) have permanent lifetime: they were never deallocated.
The most interesting aspect of CC2s storage allocation scheme was what I eventually came to call lifetime-based
storage allocation. This was, for me, an new discovery, though clearly I was not the rst to discover it. The
Aha is that a lifetime is dened by the time (or equivalently by the place in program code) at which objects are
deallocated. A lifetime may hold many different kinds of objects that were allocated at many different times. The
essence of lifetime-based allocation is that the proper time to specify when an object will be deallocated is
when the object is created.
Lifetime-based allocation is a superb invention:
It becomes an effective design tool. Thinking of objects in terms of their lifetimes often shows the essence
of a design problem.
It can be used for any kind of object, regardless of its size or type.
It reduces the number of calls to calloc and free by one or two orders of magnitude over naive schemes.
Furthermore, it typically requests standard-sized blocks (say 8K or more) from calloc, further easing the
burden on calloc and free.
CC2 could allocate objects with a particular lifetime using small, extremely fast, macros. The macros
expanded to C code something like this:
14.3. Allocating storage using lifetimes 123
Leo, Release 4.6-b1
if lifetime -> avail >= sizeof(theObjectKind) {
// Allocate the storage.
theObject = lifetime -> ptr
lifetime -> ptr += sizeof(theObjectKind)
}
else {
<< allocate theObject in another block >>
}
Importantly, the speed of the else clause makes absolutely no difference because it is so seldom executed. Thus,
it uses a function call. Clearly then, this code is optimal: it could not be improved even if coded in assembly
language.
14.3.2 Typical lifetimes
What makes lifetime-based allocation so powerful is that so few lifetimes are typically required. Indeed, CC2 had
only the following lifetimes:
Permanent: These objects were never deallocated. Examples were list pointers held in cons cells and other
kinds of application-wide objects.
Tokenizer: Tokenizing in C is complex due to Cs various preprocessing directives and macro expansion.
Objects with tokenizer lifetime are deallocated before the parser starts.
Function: Objects with function lifetime are deallocated after the compiler generates code for the function.
File: Objects with le lifetime are deallocated after the compiler completes a source le.
Thats all. Similarly, if Leo were recast as a C program only the following lifetimes would be needed:
Permanent: application-wide objects.
Window/outline: All data associated with a single Leo outline. This is a semi-permanent lifetime. Leo
has unlimited undo, so it is essentially impossible to delete any data object (an object that could be written
to an output le) until the entire outline closes.
Dialog: data associated with a temporary dialog.
Function/method: data not used outside a single function or method.
The remarkable thing about dynamic languages like Python is how often objects can, in fact, be assigned static
lifetimes.
14.3.3 Implications for pypy
Lifetime allocation isnt used in Java, Python, etc. because these languages have no way of knowing (in general)
what the lifetime of any object will be. Furthermore, translating Python to C would be straightforward were it not
for storage allocation issues. For example, most of Leos code could easily be translated into C, provided that the
lifetime of all objects were known. Again, just for example, the prospect of translating the Python version of Leo
to a fully optimized C version is tantalizing.
This is where pypy comes in: its extensive ow analysis may be sufcient to discover lifetimes for a signicant
percentage of objects. Perhaps user hints may be effective. For example, pypy offers the chance to make something
like region inference truly useful. Note that the pypy project might benet from deducing lifetimes even if not all
objects could be assigned a static lifetime. Another reason why lifetimes are not a standard technique is that they
are a potentially dangerous optimization. Errors in specifying lifetimes will result in dangling pointer references.
But this danger might disappear if pypy could deduce lifetimes automatically.
124 Chapter 14. Chapter 11: White Papers
CHAPTER
FIFTEEN
CHAPTER 12: PLUGINS
This chapter discusses the plugins contained in leoPlugins.leo. These plugins are part of Leos ofcial distribution.
Chapter 13: Writing Plugins tells how to write plugins.
The scripting plugin (mod_scripting.py) deserves special mention. This plugin lets you create script but-
tons in a matter of seconds. See Creating script buttons. Script buttons are extraordinarily useful. Try them, youll
be instantly hooked.
15.1 Enabling plugins
You enable or disable plugins using @enabled-plugins nodes in leoSettings les (leoSettings.leo, myLeoSet-
tings.leo or the .leo le being loaded). See Specifying settings for full details of settings les.
The body text of the @enabled-plugins node contains a list of enabled plugins. Notes:
Leo attempts to load all plugins every time an @enabled-plugins node is seen. If the plugin has al-
ready been loaded, Leo silently ignores the request to re-enable the plugin. Leo never attempts to dis-
able a plugin while processing enabled plugin strings. Thus, plugins enabled in an @enabled-plugins
node in leoSettings.leo will be enabled regardless of the contents of any other @enabled-plugins node.
g.app.gui.getEnabledPlugins contains the last value last processed @enabled-plugins node.
15.2 Body pane
15.2.1 arrows.py
Rebinds up/down arrow keys.
15.2.2 image.py
Handles images in body text. Based on work by Gil Shwartz. Brent Burley provided many important insights.
See: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52264
15.2.3 rClick.py
This plugin provides a simple but powerful and exible system of managing scriptable context menus.
Named menus dened in scripts or @popup <name> settings can be associated with any widget.
Menu items may have icons and the foreground/background colors can be set in @popup settings.
Full details can be found in the plugins docstring.
Many executable howtos, demos and examples can be found in:
125
Leo, Release 4.6-b1
test/testAtPopup.leo
15.2.4 autocompleter.py
Autocompletion and calltips plugin.
. summons the autocompletion.
( summons the calltips
Escape closes either box.
Ctrl selects an item.
alt-up_arrow, alt-down_arrow move up or down in the list. The mouse will work for this as well.
This plugin scans the complete outline at startup. You many enable or disable features in autocompleter.ini. This
le contains two options under the [ autocompleter ] section:
useauto
usecalltips
Setting either to 1 will turn on the feature. 0 means off. If there is a section called [ newlanguages ] it will read
each option as a new language for autocompleter to recognize, and compile its value as a regex pattern for the
autocompleter system to recognize as a calltip. This has relevance for the .ato system described below. Languages
that currently have patterns:
python, java, c++, c, perl
Autocompleter looks in the plugin directory for a directory called autocompleter. If it doesnt nd one it will
attempt to create this directory. This directory should contain what are called .ato les ( pronounced auto ).
Autocompleter will scan each .ato le that has a rst part that matches a languages name. For example: python.ato
autocompleter recognizes python, and will scan this le. The contents are read with the same mechanism that
reads the information in the nodes, so calltip and autocompleter information is added to autocompleters runtime
database. If a new language has been added in the autocompleter.ini le then an .ato le that starts with the
new languages name will be recognized and read in. Note, this language needs to be recognizable to Leo. Used
correctly an .ato le is a mechanism by which a user can carry autocompletion and calltip information between
.leo les/sessions.
15.2.5 color_markup.py
Handle coloring for markup in doc parts and Python triple-double-quoted strings.
Important:
This plugin requires that the add_directives plugin is enabled.
To color a text with wiki markup the text must be in the range of an @markup wiki directive.
The currently supported markups are:
text # write text in italics
__text__ # write text in bold
~~<color>:text~~ # write text in the color specified by <color> (e.g. blue, grey, etc)
{picture file=<filename>} # load the picture indicated by <filename>
http://url # URL support: double clicking on the url will open it in the default browser.
https://url # URL support: double clicking on the url will open it in the default browser.
126 Chapter 15. Chapter 12: Plugins
Leo, Release 4.6-b1
Note 1: italics and bold markups can be nested, e.g.,:
__text__ # write text in italics and bold
Just remember to terminate the tags in the order they were opened.
Note 2: URLs must be terminated by a space.
By default, once the text has been markup up, the actual tags (e.g. __ for bold) are not displayed anymore. You
can choose to display them selecting Show Invisibles from the Edit menu.
15.2.6 script_io_to_body.py
Send output from the Execute Script command to the end of the body pane.
15.3 Commands & directives
15.3.1 add_directives.py
Supports new Leo directives.
15.3.2 bibtex.py
This plugin manages BibTeX les with Leo. Create a bibliographic database by putting @bibtex filename
in a headline. Entries are added as nodes, with @entrytype key as the headline, and the contents of the
entry in body text. The plugin will automatically insert a template for the entry in the body pane when a new
entry is created (hooked to pressing enter when typing the headline text). The templates are dened in dictionary
templates in the <<globals>> section, by default containing all required elds for every entry.
The le is written by double-clicking the node. Thus the following outline:
-@bibtex biblio.bib
+@book key
author = {A. Uthor},
year = 1999
will be written in the le biblio.bib as:
@book{key,
year= 1999}
Strings are dened in @string nodes and they can contain multiple entries. All @string nodes are written at
the start of the le. Thus the following outline:
-@bibtext biblio.bib
+@string
j1 = {Journal}
+@article AUj1
journal = j1
+@string
j2 = {Journal2}
j3 = {Journal3}
Will be written as:
15.3. Commands & directives 127
Leo, Release 4.6-b1
@string{j1 = {Journal1}}
@article{AUj1,
journal = j1}
No error checking is made on the syntax. The entries can be organized under nodesif the headline doesnt start
with @, the headline and body text are ignored, but the child nodes are parsed as usual. BibTeX les can be
imported by creating an empty node with @bibtex filename in the headline. Double-clicking it will read the
le filename and parse it into a @bibtex tree. No syntax checking is made, filename is expected to be a
valid BibTeX le.
15.3.3 ConceptualSort.py
This plugin is enhances the EditAttributes.py plugin. It puts a command in Outline called ConceptualSort. This
will prompt you for a concept to sort by. This gives the user some more exibility in how they want to arrange
their nodes. Nodes without the attribute in question go to the bottom of the sort. The user can:
Select which attribute he wants to sort on by clicking on the Attribute box.
Select the type of sort he wants by clicking on the radio buttons:
Normal.
Reversed. Like normal but the results are reversed.
Used dened. For advanced users. The text box is where a user can type in their own python code to
sort the nodes-attributes. There is no need for a def. That gets appended to the beginning of the code.
It prototype looks like:
def( a, b, att ):
where a and b are nodes and att is dictionary of the nodes and the respective value of the selected attribute. There
is no need to indent on the rst level since indentation is added at compile time.
15.3.4 datenodes.py
This plugin adds date nodes (nodes with dates as their headlines) to the current outline. Date nodes may be added
one at a time, a months-worth at a time, or a years-worth at a time. The format of the headlines is congurable
in the ini le.
15.3.5 FileActions.py
Leo plugin that permits the denition of actions for double-clicking on le nodes. Double-clicking in a @file
node writes out the le if changes have been made since the last save, and then runs a script on it, which is retrieved
from the outline. Scripts are located in a node whose headline is FileActions. This node can be anywhere in the
outline. If there is more than one such node, the rst one in outline order is used. The children of that node are
expected to contain a le pattern in the headline and the script to be executed in the body. The le name is matched
against the patterns (which are Unix-style shell patterns), and the rst matching node is selected. If the lename
is a path, only the last item is matched. Execution of the scripts is similar to the Execute Script command
in Leo. The main difference is that the namespace in which the scripts are run contains two elements:
filename, which contains the lename from the @file directive.
shellScriptInWindow, a utility function that runs a shell script in an external windows, thus permit-
ting programs to be called that require user interaction
Leo, Release 4.6-b1
File actions are implemented for @file nodes and all its variants (@file-nosent, @thin, etc.). There is also
a new node type @file-ref for referring to les purely for the purpose of le actions, Leo does not do anything
with or to such les.
15.3.6 groupOperations.py
A Leo Plugin that adds Group commands functionality. Restrictions currently apply to using Leo with a Tk front
end. There are several commands in this plugin:
Mark Node: marks a node for further operations such as copying, cloning and moving.
Mark Spot: marks a node as the place where group operations are to target.
Operate On Marked: moves lassoed nodes to the spot where the roundup node is placed. Clones are main-
tained.
Clear Marked: unmarks all marked nodes and removes the roundup node.
Transfer Lassoed Nodes: this is a menu for inter-windowcommunication. The windows must all be spawned
from the same Leo instance. It allows the user to move all node marked for copying and moving from
another window to this one.
15.3.7 import_cisco_cong.py
This plugin adds a menu item under the File->Import menu to import Cisco conguration les. The plugin will:
1. Create a new node, under the current node, where the conguration will be written. This node will typically
have references to several sections (see below).
2. Create sections (child nodes) for the indented blocks present in the original cong le. These child nodes
will have sub-nodes grouping similar blocks (e.g. there will be an interface child node, with as many
sub-nodes as there are real interfaces in the conguration le).
3. Create sections for the custom keywords specied in the customBlocks[] list in importCiscoCong(). You
can modify this list to specify different keywords. DO NOT put keywords that are followed by indented
blocks (these are taken care of by point 2 above). The negated form of the keywords (for example, if the
keyword is service, the negated form is no service) is also included in the sections.
4. Not display consecutive empty comment lines (lines with only a !).
All created sections are alphabetically ordered.
15.3.8 Library.py
A plugin to store Leo trees in anydbm les. Note: there isnt such a thing as an anydbm le: its whatever the
anydbm module uses. Under Outline, there is an option called Library. This will open a dialog with a list of
the trees that you have saved. You can insert trees stored in the library, remove them and add trees to the library.
Be aware of unicode, any characters outside of the ascii set gets turned into a ?. I found this problem in storing
some trees from Edwards Leo outline. Id like it to be able to store unicode, but that may require a more specic
db background, than anydbm. Also note, that your library les may not be OS independent. If your python
distribution does not have the backing db on another machine, it will not be able to open your library. This should
help people develop templates that they want to reuse between Leo projects. For example, Id like a template of
many Java interfaces to be easily accessible.
15.3.9 macros.py
Creates new nodes containing parameterized section references.
Leo, Release 4.6-b1
15.3.10 mod_autosave.py
Autosave the Leo document every so often. The time between saves is given in seconds in autosave.ini.
15.3.11 mod_read_dir_outline.py
This plugin allows Leo to read a complete directorys outline into a Leos Outline. Directories are converted into
headlines and les names are listed into the bodies.
15.3.12 mod_timestamp.py
Timestamp all save operations to show when they occur.
15.3.13 nodeActions.py
A Leo plugin that permits the easy assignment of scripts to be performed on double-clicked nodes based on
pattern matching.
When a node is double-clicked, the nodeActions plugin checks for a match of the double-clicked nodes headline
text with a list of patterns and, if a match occurs, the script associated with the pattern is executed.
The nodeActions plugin will only pass the double-click event to other plugins if no pattern match occurred unless
overridden by the > pattern directive.
Patterns: The patterns are dened in the headlines of sub-nodes of a single nodeActions node.
The nodeActions node can be located anywhere within the same Leo le as the node that will be double-
clicked. For example, a pattern that matches a URL and a pattern that matches any python les stored as an
@thin derived le could be stored under an @settings node as follows:
@settings
|
+- nodeActions
|
+- http:\\
*
|
+- @thin
*
.py
Pattern matching is performed using pythons support for Unix shell-style patterns unless overwritten by the
X pattern directive. The following pattern elements are supported:
*
- matches everything
? - matches any single character
[<seq>] - matches any character in <seq>
[!<seq>] - matches any character
**
not
**
in <seq>
Unix shell-style pattern matching is case insensitive and always starts from the beginning of the headline.
For example:
Pattern Matches Does not match
*.py Abc_Test.py
.py .py - Test Abc_Test.py
test* Test_Abc.py Abc_Test.py
To enable a script to run on any type of @le node (@thin, @shadow, ...), the pattern can use @les at
the beginning of the pattern to match on any derived le type. For example, the pattern @les *.py will
match a node with the headline @thin Abcd.py.
The headline of the double-clicked node is matched against the patterns starting from the rst sub-node
under the nodeActions node to the last sub-node. Only the script associated with the rst matching
pattern is invoked unless overwritten by the V pattern directive.
Leo, Release 4.6-b1
This can be used to dene a broad pattern such as @les *.py, and then, by placing a more restrictive
pattern above it, such as @les *_test.py, a different script can be executed for those special cases:
+- nodeActions
|
+- @files
*
_test.py
|
+- @files
*
.py
Note To prevent Leo from trying to save patterns that begin with a derived le directive (@thin,
@auto, ...) to disk, such as @thin *.py, place the @ignore directive in the body of the
nodeActions node.
Scripts: The script for a pattern is located in the body of the patterns node. The following global variables are
available to the script:
c
g
pClicked - node position of the double-clicked node
pScript - node position of the invoked script
Directives: The following pattern specic directives can be appended to the end of a pattern (do not include the
:):
[X] Use pythons regular expression type patterns instead of the Unix shell-style pattern syntax.
For example, the following patterns will match the same headline string:
Unix shell-style pattern:
@files
*
.py
Regular Expression patern:
^@files .
*
\.py$ [X]
[V] Matching the pattern will not block the double-click event from being passed to the remain-
ing patterns. The V represents a down arrow that symbolizes the passing of the event to
the next pattern below it.
For example, adding the [V] directive to the @les *_test.py in the Patterns section
above, changes its script from being an alternate to to being a pre-processor for the
@les *.py script:
+- nodeActions
|
+- @files
*
_test.py [V]
|
+- @files
*
.py
[>] Matching the pattern will not block the double-click event from being passed to other plu-
gins. The > represents a right arrow that symbolizes the passing of the event to the next
plugin.
If the headline matched more than one headline, the double-click event will be passed to the
next plugin if the directive is associated with any of the matched patterns.
The directive(s) for a pattern must be contained within a single set of brackets, separated from the pattern
by a space, with or without a comma separator. For example, the following species all three directives:
^@files .
*
\.py$ [X,V>]
Congurations: The nodeActions plugin supports the following global congurations using Leos support for
setting global variables within an @settings nodes sub-nodes in the leoSettings.leo, myLeoSettings.leo,
and the project Leo le:
@bool nodeActions_save_atFile_nodes = False
Leo, Release 4.6-b1
True The nodeActions plugin will save a double-clicked derived le node to disk, if a
pattern match occurred, before executing its script.
False A pattern match to a double-clicked derived le node will not cause the derived
le to be saved to disk. (default)
@int nodeActions_message_level = 1
Species the type of messages to be sent to the log pane. Specifying a higher message level will
display that level and all lower levels. The following integer values are supported:
0 no messages
1 Plugin triggered and the patterns that were matched (default)
2 Double-click event passed or not to next plugin
3 Patterns that did not match
4 Code debugging messages
Script examples: Displaying URLs (tested with WinXP):
Double-clicking on a node with a http:\\www.google.com headline will invoke the script asso-
ciated with the http:\\* pattern. The following script in the body of the patterns node displays
the URL in a browser:
import webbrowser
hClicked = pClicked.h #Clicked nodes Headline text
webbrowser.open(hClicked) #Invoke browser
Executing commands (tested with WinXP):
The following script can be placed in the body of a patterns node to execute a command in the
rst line of the body of a double-clicked node:
g.os.system("Start /b + pClicked.bodyString() + ")
15.3.14 outline_export.py
Modify the way exported outlines are displayed.
15.3.15 paste_as_headlines.py
This plug-in takes any text is stored in the clipboard and creates new headlines for each line of text. The paste
routine checks to make sure the line of text is not greater than 50 characters in length. If it is, the routine truncates
the headline to 50 characters and pastes the entire line into the body text of that node.
If the plug-in is functioning properly, a Paste as Headlines option should appear in the Edit menu directly under
the existing Paste option.
15.3.16 pretty_print.py
A plugin that helps customize pretty printing. It creates a do-nothing subclass of the default pretty printer. To
customize, simply override in this le the methods of the base prettyPrinter class in leoCommands.py. You would
typically want to override putNormalToken or its allies. Templates for these methods have been provided. You
may, however, override any methods you like. You could even dene your own class entirely, provided you
implement the prettyPrintNode method.
15.3.17 scheduler.py
A plugin to schedule commands for later execution. Its provides the ability to issue commands at a future time
and to write messages that will be displayed at a later time. To record commands You goto Schedule and choose
Leo, Release 4.6-b1
begin recording. Then you jump to the nodes and select the commands you want issued on them. This process is
ended with the end recording option. A dialog pops up. You can then click on the individual commands and set
the time for execution. To set the execution time for all, enter a value and hit set_all. All times must be in the form
hh:mm. For example I want to issue a save command for 5:00 PM. I would do so by using the value 17:00. The
Schedule Message is simple. There is a Text box to enter the message and a Entry to place the time. View Queue
will summon a view of The Queue. This dialog will show the commands that have been enqueued. There is also
the option to Cancel out any scheduled commands/messages.
15.3.18 table.py
This plugin puts the View Table command in the Outline menu. This command checks the current node using the
csv (comma separated values) mods Sniffer. It tries to determine the format that is in the nodes data. If you had
excel data in it, it should be able to determine its excel data. It then creates a dialog with the data presented as in
a table for the user to see it. Requires Pmw and the tktable widget at http://sourceforge.net/projects/tktable.
15.3.19 templates.py
This plugin lets you add customizable templates to an outline. Templates are like any other node except that the
plugin replaces %s in the body text by values that you specify when using template. Templates may have section
references; this plugin uses Leos @nosent write machinery to create one string out of possibly many nodes.
This plugin requires the simplied atFile write code that is new in 4.2.1.
This plugin creates two buttons in Leos icon area:
The %s button marks or unmarks a node as a template. A %s symbol will appear to the left of the node
when it is marked as a template.
The -> %s button brings up a dialog that shows you the template text and asks you to specify the value
for all %s instances. Dismissing this dialog inserts the template as the rst child of the node, and creates a
section reference in the node that references the template.
If a template does not have a %s in it, then the templates plugin just adds the text as a node. Templates once
marked are stored across sessions. Do not put a template in a thin le, as your template mark will be erased
between sessions.
15.3.20 word_cound.py
This plugin displays a message box with information about the body text of the current node such as number of:
characters, words, lines, and paragraphs. It adds a Word Count... option to the bottom of the Edit menu that will
activate the message box.
The Word Count... menu has a shortcut key of W.
15.4 Dialogs
15.4.1 gtkDialogs
gtkDialogs replaces Tks le dialogs with Gtk le chooser dialogs.
The plugin is aimed mainly at Linux users with pyGtk installed on their systems, but it should work on on any
system that support Gtk2 and pyGtk.
15.4. Dialogs 133
Leo, Release 4.6-b1
15.5 Debugging & testing
15.5.1 failed_import.py
A plugin to test import problems.
15.5.2 dump_globals.py
Dump Python globals at startup.
15.5.3 enable_gc.py
Enable debugging and tracing for Pythons garbage collector.
15.5.4 trace_gc.py
Trace changes to Leos objects at idle time.
15.5.5 trace_keys.py
Trace keystrokes in the outline and body panes.
15.5.6 trace_tags.py
Trace the most common hooks, but not key, drag or idle hooks.
15.6 External editors & Open With
15.6.1 mod_tempfname.py
Replaces Commands.openWithTempFilePath so Leo opens temporary les with a lename that begins
with the headline text, and located in a username_Leo subdirectory of the temporary directory. The LeoTemp
prex is omitted. This makes it easier to see which temporary le is related to which outline node.
15.6.2 open_shell.py
Creates an extensions menu with commands to open either an xterm on Linux or a cmd windows/explorer
window on win32 in the directory of the current @file node. This allows quick navigation to facilitate testing
and navigating large systems with complex directories.
15.6.3 open_with.py
This plugin creates menu items in the File:Open With menu.
@openwith nodes in @settings trees create menu items. The openWith plugin must be active for these settings to
have any effect.
The headline of an @openwith node has the form:
@openwith name = shortcut
Leo, Release 4.6-b1
name is name of the menu item. shortcut species the shortcut used to invoke the menu item. shortcut may be
None.
The body text @openwith nodes should contain a single line contain a tuple of the form:
command,arg,ext
For example:
subprocess.Popen,[pythonw,C:/Python24/Lib/idlelib/idle.pyw],.py
When the user selects this menu item Leo executes command(arg+path) where path is the full path to the temp
le. The ext argument species the extension of the temp le.
Notes:
command is a string. Valid values are:
subprocess.Popen
os.system
os.startfile
os.spawnl
os.spawnv
exec
arg is either a single string or a list of strings.
ext is a string or None. If None, Leo computes a le extension base on what @language directive is in
effect.
If the .leo le being loaded contains @openwith nodes, the File:Open With menu contains only the items cre-
ated by those nodes. Similarly, @openwith nodes in myLeoSettings.leo override entries in leoSettings.leo.
If no @openwith nodes are found anywhere the openWith plugin uses hard-coded tables in the plugin itself.
This plugin will use Pythons new subprocess module if it is present. This module comes standard with Python
2.4. For Linux systems, Leo will use subprocess.py in Leos extensions folder if necessary.
For Windows systems you can install Pythons subprocess module in Python 2.2 or 2.3 as follows:
Go to http://www.effbot.org/downloads/#subprocess
Download and execute one of the following installers, depending on your version of Python:
subprocess-0.1-20041012.win32-py2.3.exe
subprocess-0.1-20041012.win32-py2.2.exe
This installer installs the subprocess sources and also _subprocess.pyd in Pythons site-packages folder.
15.6.4 temacs.py & usetemacs.py
temacs is a binding module for the Tkinter Text widget. usetemacs is a Leo plugin that patches the temacs
modules Emacs emulation into the standard Leo Tkinter Text editor.
15.6.5 vim.py
A plugin that communicates with VIM:
When properly installed, this plugin does the following:
15.6. External editors & Open With 135
Leo, Release 4.6-b1
Double clicking on a nodes icon opens that node in VIM.
Leo will put the Vim cursor at same location as the Leo cursor in nodes body if the Leo
vim_plugin_positions_cursor variable is set to True.
Leo will put node in a Vim tab card if the Leo vim_plugin_uses_tab_feature is set to True.
Leo will update the node in the outline when you save the le in VIM.
15.6.6 word_export.py
Use commands in the Plugins:Word Export:Export menu to formats and export the selected outline to a
Word document, starting Word if necessary.
15.6.7 xemacs.py
This plugin allows you to edit nodes in emacs/xemacs. Depending on your preference, selecting or double-clicking
a node will pass the body text of that node to emacs. You may edit the node in the emacs buffer and changes will
appear in Leo.
15.7 Files
15.7.1 empty_leo_le.py
Opens any empty le as a minimal .leo le.
15.7.2 leoOPML.py
Warning: the OPML plugin is not fully functional at present. Use with caution.
The OPML plugin creates two new commands that read and write Leo outlines in OPML format. The read-opml-
le command creates a Leo outline from an .opml le. The write-opml-le command writes the present Leo
outline to an .opml le.
Various settings control what gets written to .opml les, and in what format. As usual, you specify settings for the
OPML plugin using leoSettings.leo. The settings for the OPML are found in the node:
@settings-->Plugins-->opml plugin
Here are the settings that control the format of .opml les. The default values are shown.
@bool opml_read_derived_files = True
If True, Leo reads derived les when reading .opml les.
@string opml_namespace = leo:com:leo-opml-version-1
The namespace urn for the xmlns attribute of <opml> elements. This value typically is not used, but it
should refer to Leo in some way.
@bool opml_use_outline_elements = True
If True, Leo writes body text to <:body> elements nested in <outline> elements. Otherwise, Leo
writes body text to :body attributes of <outline> elements.
Note: Leo-specic attributes and elements are clearly distinguished from standard opml elements: they
are preceded by a colon, which marks them as members of the default namespace specied specied by this
option. Thus, all OPML text generated by this plugin should conform to the OPML 2.0 standard.
Leo, Release 4.6-b1
@string opml_version = 2.0
The opml version string written to the <OPML> element. Use 2.0 unless there is a specic reason to use
1.0.
@bool opml_write_body_text = True
If True, Leo writes body text to the OPML le.
@bool opml_write_derived_files = True
If True, Leo writes derived les when writing .opml les.
@bool opml_write_leo_details = True
If True, Leo writes the native attributes of Leos <v> elements as attributes of the opml <outline>
elements. The native attributes of <v> elements are a, descendentTnodeUnknownAttributes,
expanded, marks, t, and tnodeList.
@bool opml_write_leo_globals_attributes = True
If True, Leo writes body_outline_ratio and global_window_position attributes to the <head> ele-
ment of the .opml le.
@bool opml_write_uAs = True
If True, Leo writes unknown attributes (uAs) in <:uA> sub-elements of <outline> elements.
15.7.3 lineNumbers.py
Adds #line directives in perl and perlpod programs. Currently supports only perl and perlpod.
15.7.4 multile.py
Multipath enables the ability to write a le to multiple locations. It acts as a post-write mechanism, a le must
be written to the le system for it to work. At this point it is not a replacement for @path or an absolute path, it
works in tandem with them. To use, place @multipath at the start of a line in the root node or an ancestor of
the node. The format is (On Unix systems):
@multipath /machine/unit/:/machine/robot/:/machine/
It will place a copy of the written le in each of these directories.
There is an additional directive that simplies common paths, it is called @multiprefix. By typing
@multiprefix with a path following it, before a @multipath directive you set the beginning of the paths in
the @multipath directive. For example:
@multiprefix /leo #@multipath /plugins
or:
@multiprefix /leo/
@multipath plugins: fungus : drain
copies a le to /leo/plugins /leo/fungus /leo/drain.
The @multiprefix stays in effect for the entire tree until reset with another @multiprefix directive.
@multipath is cumulative, in that for each @multipath in an ancestor a copy of the le is created. These
directives must at the beginning of the line and by themselves.
15.7.5 niceNosent.py
Preprocess @file-nosent nodes: make sure each subnode ends with exactly one newline, replace all tabs with
spaces, and add a newline before class and functions in the derived le.
15.7. Files 137
Leo, Release 4.6-b1
15.7.6 leoToRTF
This plugin takes an outline stored in LEO and outputs it as a numbered list to an RTF le. The RTF le can be
loaded into Microsoft Word and formatted as a proper outline.
If this plug-in loads properly, you should have an Outline to Microsoft RTF option added to your File > Export...
menu in Leo.
Settings such as outputting just the headlines (vs. headlines & body text) and whether to include or ignore the
contents of @le nodes are stored in the rtf_export.ini le in your Leoplugins folder.
The default export path is also stored in the INI le. By default, its set to c:so you may need to modify it depending
on your system.
15.7.7 leoToHTML
This plugin takes an outline stored in LEO and converts it to html which is then either saved in a le or shown in
a browser.
The outline can be represented as a bullet list, a numbered list or using html <h?> type headings. Optionally, the
body text may be included in the output.
If desired, only the current node will be included in the output rather than the entire outline.
An xhtml header may be included in the output, in which case the generated html will be valid XHTML 1.0 Strict.
The plugin is fully scriptable as all its functionality is available through a Leo_to_HTML object which can be
imported and used in scripts.
Several commands and menu items are provided to give easy access to the plugins various features and options
may be set via leo_to_html.ini le and the plugins properties dialog.
15.7.8 leoOPML
This plugin reads and writes Leo outlines in .opml (http://en.wikipedia.org/wiki/OPML) format.
The OPML plugin creates two new commands that read and write Leo outlines in OPML format. The read-opml-
le command creates a Leo outline from an .opml le. The write-opml-le command writes the present Leo
outline to an .opml le.
Various settings control what gets written to .opml les, and in what format. As usual, you specify settings for the
OPML plugin using leoSettings.leo. The settings for the OPML are found in the node: @settings>Plugins>opml
plugin
Here are the settings that control the format of .opml les. The default values are shown.
@string opml_namespace = leo:com:leo-opml-version-1
The namespace urn for the xmlns attribute of <opml> elements. This value typically is not used, but it
should refer to Leo in some way.
@bool opml_use_outline_elements = True
If True, Leo writes body text to <:body> elements nested in <outline> elements. Otherwise, Leo writes
body text to :body attributes of <outline> elements.
@string opml_version = 2.0
The opml version string written to the <OPML> element. Use 2.0 unless there is a specic reason to use
1.0.
@bool opml_write_body_text = True
Leo writes body text to the OPML le only if this is True.
Leo, Release 4.6-b1
@bool opml_write_leo_details = True
If True, Leo writes the native attributes of Leos <v> elements as attributes of the opml <outline> elements.
The native attributes of <v> elements are a, descendentTnodeUnknownAttributes, expanded, marks, t, and
tnodeList.
@bool opml_write_leo_globals_attributes = True
If True, Leo writes body_outline_ratio and global_window_position attributes to the <head> element of
the .opml le.
15.8 Guis
15.8.1 __wx_alt_gui.py
This plugin allows wxPython to be used as leos gui instead of TK.
It is a prototype under development and so does not have all the features of Tk leo nor are there many plugins
compatible with it yet.
It is mainly being developed for Linux at the moment, but attempts are being made to keep it working on Windows
as well.
Work on this project has now halted in favor of a gtkLeo plugin.
15.9 Icon and status areas
15.9.1 chapter_hoist.py
This plugin puts two buttons in the icon area. The Save Hoist button hoists the presently selected node and
creates a button which can later rehoist the same node. The Dehoist button performs one level of dehoisting.
This plugin replaces the old chapters plugin.
15.9.2 nav_buttons.py
Adds navigation buttons to icon bar. Tk only.
15.9.3 nav_qt.py
Qt version of nav_buttons.py (history navigation)
15.9.4 newButtons.py
Automatically add nodes for common tasks.
15.9.5 hoist.py
Add Hoist/De-Hoist buttons to the toolbar.
15.9.6 nodenavigator.py
Adds Recent and Marks pulldown buttons to the toolbar.
15.8. Guis 139
Leo, Release 4.6-b1
15.9.7 searchbox.py
Adds a quick search to Leos toolbar, along with a GO button to do quick searches right from the main Leo
window. All the current search options are retained except that search body text is explicitly set - mainly
because this is by far the most common use case. Pressing <CR> while editing the text automatically does a
search. Repeated searches can be done by clicking the GO button. The combo box also stores a list of previous
searches, which can be selected to quickly repeat a search. When activating a previous search the original search
mode is used.
15.9.8 shortcut_button.py
Creates a Shortcut button in the icon area. Pressing the Shortcut button creates another button which when
pressed will select the presently selected node at the time the button was created.
15.9.9 toolbar.py
A plugin that enhances Leos iconBar and script buttons.
This plugin provides:
multiple iconBars each of which automatically collapse and expand so that all the buttons are always
visible.
drag and drop of buttons within and between iconBars.
enhancements to Leos buttons and @button settings to allow icons, menus, tooltips and text and
background colors to be set in @button settings and scripts.
see test/testToolbar.leo for demos and howtos see test/testAtPopup.leo for examples of enhanced buttons
15.9.10 UNL.py
This plugin supports Uniform Node Locators (UNLs). UNLs specify nodes within Leo les. UNLs are not
limited to nodes within the present Leo le; you can use them to create cross-Leo-le links. This plugin consists
of two parts:
1. Selecting a node shows the UNL in the status line at the bottom of the Leo window. You can copy from the
status line and paste it into headlines, emails, whatever.
2. Double-clicking @url nodes containing UNLs select the node specied in the UNL. If the UNL species in
another Leo le, the other le will be opened.
UNLs referring to nodes within the present outline have the form:
headline1-->headline2-->...-->headlineN
where headline1 is the headline of a top-level node, and each successive headline is the headline of a child node.
UNLs of the form:
file:<path>#headline1-->...-->headlineN
refer to a node specied in <path> For example, double clicking the following headline will take you to Chapter 8
of Leos Users Guide:
@url file:c:/prog/leoCvs/leo/doc/leoDocs.leo#Users Guide-->Chapter 8: Customizing Leo
Leo, Release 4.6-b1
For example, suppose you want to email someone with comments about a Leo le. Create a comments.leo le
containing @url UNL nodes. That is, headlines are @url followed by a UNL. The body text contains your
comments about the nodes in the _other_ Leo le! Send the comments.leo to your friend, who can use the
comments.leo le to quickly navigate to the various nodes you are talking about. As another example, you can
copy UNLs into emails. The recipient can navigate to the nodes by hand by following the arrows in the UNL.
Notes:
At present, UNLs refer to nodes by their position in the outline. Moving a node will break the link.
Dont refer to nodes that contain UNLs in the headline. Instead, refer to the parent or child of such nodes.
You dont have to replace spaces in URLs or UNLs by %20.
15.9.11 quicksearch.py
This plugin adds a fast-to-use search widget, in the style of Find in les feature of many editors.
Just load the plugin, activate Nav tab, enter search text and press enter.
15.9.12 colorize_headlines.py
A plugin that manipulates appearance of individual tree widget items.
This plugin is mostly an example of how to change appearance of headlines - as such, it does a relatively mundane
chore of highlighting @thin, @auto, @shadow nodes in bold.
15.10 LeoN
LeoN is Leo over the Network. LeoN is Collaborative Leo. This is an important project for Leos long-term
development. See leo/doc/LeoN for important research papers that form the basis of this project.
15.11 Menus & translations
15.11.1 chinese_menu.py
Translate a few menu items into Simplied Chinese
By Zhang Le <ejoy@xinhuanet.com>
15.11.2 french_fm.py
Translate menus to French
15.11.3 pie_menus.py
Adds pie menus. See http://www.piemenus.com/
15.10. LeoN 141
Leo, Release 4.6-b1
15.12 Nodes
15.12.1 at_folder.py
Synchronizes @folder nodes with folders. If a node is named @folder path_to_folder, the content
(lenames) of the folder and the children of that node will be sync. Whenever a new le is put there, a new node
will appear on top of the children list (with mark). So that I can put my description (i.e., annotation) as the content
of that node. In this way, I can nd any les much easier from leo. Moreover, I add another feature to allow you
to group les(in leo) into children of another group. This will help when there are many les in that folder. You
can logically group it in leo (or even clone it to many groups), while keep every les in a at/single directory on
your computer.
15.12.2 at_produce.py
Executes commands in nodes whose body text starts with @produce. To use, put in the body text of a node:
@produce javac -verbose Test.java
To execute, you goto Outline and look at Produce. Choose Execute All Produce or Execute Tree Produce. The Tree
does the current Tree, All does the whole Outline. Executing will re javac, or whatever your using. @produce
functions as a directive. After executing, a log le/node is created at the top of the Outline. Any output, even error
messages, should be there. It executes in a hierarchal manner. Nodes that come before that contain @produce go
rst. Im hoping that this orthogonal to @run nodes and anything like that. Its not intended as a replacement for
make or Ant, but as a simple substitute when that machinery is overkill. Warning: trying to execute a non-existent
command will hang Leo.
15.12.3 at_view.py
A plugin that supports @clip, @view and @strip nodes.
Selecting a headline containing @clip appends the contents of the clipboard to the end of the body pane.
Double clicking the icon box of a node whose headline contains @view <path-to-file> places the
contents of the le in the body pane.
Double clicking the icon box of a node whose headline contains @strip <path-to-file> places the
contents of the le in the body pane, with all sentinels removed.
This plugin also accumulates the effect of all @path nodes.
15.12.4 autotrees.py
The AutoTrees plugin is a helper plugin designed to make it very easy to write handler plugins to manage
dynamic content in Leo outlines. AutoTrees provides:
Convenient handler base classes which can be specialized for particular uses.
A manager to turn handlers on and off.
A set of example handlers to show the kinds of things that are possible.
AutoTrees doesnt do anything that you cannot do in other ways, but it does provide a consistent way of adding
dynamic content. This means that individual plugin writers dont have to rewrite all the same kinds of code each
time and also makes it easier to maintain Leo, since it standardizes the way that certain classes of plugin interact
with the Leo core. Why use this? Im a plugin writer and I want to write a plugin to display dynamic content, i.e.,
content not directly contained in the .leo or derived les, e.g.,
Leo, Release 4.6-b1
email messages
news feeds
news groups
documentation
remote les
statistics
le system data
data base records
You can do this as a standard plugin, but as an AutoTrees handler you,
dont need to write code that interacts with the tree (this is done for you)
get centralized management
can still do everything else you could as a normal plugin
15.12.5 base64Packager.py
This plugin allows the user to import binary data and store it in Leo as a base64 string. This plugin adds Import
base64 and Export base64 commands to the Import menu and adds the View base64 command to the
outline menu. The Import base64 command creates a new node with the headline:
@base64 <filename>
The body of this node will kill the colorizer, add some info on the original le and create a section reference to
the payload node, which contains the data. The Export base64 command asks for a location to place the le. The
plugin checks that the structure of the base64 node is what it expected, basically what an import operation creates.
If Ok, it will write the le to the selected directory. The View base64 command brings up a Pmw Dialog that
displays the data as a PhotoImage. This currently only supports formats recognized by the PhotoImage class. This
would be the .gif format. This functionality may be enhanced in the future by PIL to support more image types.
Depending on the size of the image, you may have to scroll around to see it. For example, a leo clone icon will
require scrolling to nd. Id like to change this in the future.
15.12.6 fastGotoNode.py
A Leo plugin that adds quick utility commands through a pop-up menu. To summon Menu, type control-space.
To unsummon, Right Click.
1. Movement. If a node has ancestors,siblings or children a menu option will appear offering the user the ability
to jump to the node from the current node. This is an improvement over moving one node at a time with the
keyboard commands.
2. Inserting text. These menus offer the current language keywords, the directives the body recognizes and any
@file type headline directives. It offers the new user easy access to the different directives and ways to write a
le.
3. Moving Nodes(experimental). You can quickly move a node to its parents parent or after a sibling, if they
exist.
15.12. Nodes 143
Leo, Release 4.6-b1
15.12.7 mod_labels.py
This plugin allows you to associate information with nodes. This information is organized around labels, which
is are just strings and freely chosen by the user. The plugin allows you to create such a label quickly for each
marked node, and to mark all nodes which have a certain label. Labels can be converted to subnodes, and vice
versa. This facility allows you to add additional information for each label. You can create clones for each node
which has a label. These clones are created as children of the current node. This last facility can be used to create
clones for each node which has been found or changed by the standard search/replace dialog:
Delete all marks.
Do a nd all / change all.
Convert the marks to a label.
Run the Clone label subnodes command.
Finally, if you read a derived le, and the content of a node changes, the previous content is available under the
label before change:
15.12.8 read_only_nodes.py
A plugin to create and update @read-only nodes. I wanted to have the ability to import les in read-only
mode, that is, in a mode where les could only be read by leo (not tangled), and also kept in sync with the content
on the drive. The reason for this is for example that I have external programs that generate resource les. I want
these les to be part of a leo outline, but I dont want leo to tangle or in any way modify them. At the same time,
I want them to be up-to-date in the leo outline. This plugin has the following characteristics:
It reads the specied le and puts it into the node content.
If the @read-only directive was in the leo outline already, and the le content on disk has changed
from what is stored in the outline, it marks the node as changed and prints a changed message to the log
window; if, on the other hand, the le content has not changed, the le is simply read and the node is not
marked as changed.
When you write a @read-only directive, the le content is added to the node immediately, i.e. as soon as
you press Enter (no need to call a menu entry to import the content).
If you want to refresh/update the content of the le, just edit the headline and press Enter. The le is
reloaded, and if in the meantime it has changed, a change message is sent to the log window.
The body text of a @read-only le cannot be modied in leo.
The syntax to access les in @read-only via ftp/http is the following:
@read-only http://www.ietf.org/rfc/rfc0791.txt
@read-only ftp://ftp.someserver.org/filepath
If FTP authentication (username/password) is required, it can be specied as follows:
@read-only ftp://username:password@ftp.someserver.org/filepath
15.12.9 run_nodes.py
Runs a program and interface Leo through its input/output/error streams. Double clicking the icon box whose
headlines are @run cmd args will execute the command. There are several other features, including @arg
and @input nodes.
The run_nodes.py plugin introduce two new nodes that transform leo into a terminal. It was mostly intended to
run compilers and debuggers while having the possibility to send messages to the program.
Leo, Release 4.6-b1
Double clicking on the icon of an node whose headline is:
@run <command> <args>
will launch <command> with the given arguments. It will also mark the node. # Terminates the argument list.
@run # <comment> is also valid.
@in nodes are used to send input to the running process. Double clicking on the icon of an @in
<message> node will append a n to <message> and write it to the program, no matter where the node
is placed. If no @run node is active, nothing happens.
The body text of every child, in which the headlines do not begin with @run or @in, will be appended to
<command>, allowing you to add an innite number of arguments to <command>.
The output of the program is written in the log pane (Error outputted in red). When the program exit the
node is set unmarked and the return value is displayed...When the enter key is pressed in the body pane of an
active @run node the content of it body pane is written to the program and then emptied ready for another
line of input. If the node have @run nodes in its descendants, they will be launched successively (unless
one returned an exit code other than 0, then it will stop there).
15.12.10 slideshow.py
This plugin supports slideshows in Leo outlines.
It denes four new commands:
next-slide-show: move to the start of the next slide show, or the rst slide show if no slide show has been
seen yet.
prev-slide-show: move to the start of the previous slide show, or the rst slide show if no slide show has
been seen yet.
next-slide: move to the next slide of a present slide show.
prev-slide: move to the previous slide of the present slide show.
Slides shows consist of a root @slideshow node with descendant @slide nodes. @slide nodes may be organized
via non-@slide nodes that do not appear in the slideshow.
All these commands ignore @ignore trees.
15.12.11 startle.py
Launches (starts) a le given by a headline when double-clicking the icon. Ignores headlines starting with an @.
Uses the @folder path if the headline is under an @folder headline. Otherwise the path is relative to the Leo
le.
15.13 Plugins manager & menu
15.13.1 leoupdate.py
A plugin to automatically update Leo from the current CVS version of the code stored on the SourceForge site.
You can view individual les and update your entire Leo installation directly without needing a CVS client.
15.13. Plugins manager & menu 145
Leo, Release 4.6-b1
15.13.2 plugin_manager.py
A plugin to manage Leos Plugins:
Enables and disables plugins.
Shows plugin details.
Checks for conicting hook handlers.
Checks for and updates plugins from the web.
15.13.3 plugins_menu.py
Create a Plugins menu and adds an item to the plugin menu for each active plugin. Selecting this menu item will
bring up a short About dialog with the details of the plugin. Plugins can create additional menu items by dening
functions named cmd_XZY. These will appear in a submenu. If the plugin requires an INI le then a congure
menu item will be created which will show an INI le editor. The plugin can dene an applyConfiguration
function, which will be called when the conguration changes. Plugins can also dene a top level function to be
called instead of the default About dialog by dening a topLevelMenu function in the plugin. This function
will be called when the user clicks on the plugin name in the plugins menu, but only if the plugin was loaded
properly and registered with g.plugin_signon.
Plugins can dene their name by setting the __plugin_name__ property. Plugins can also attempt to select
the order they will appear in the menu by dening a __plugin_prioriy__. The menu will be created with
the highest priority items rst. This behavior is not guaranteed since other plugins can dene any priority. This
priority does not affect the order of calling handlers. To change the order select a number outside the range 0-200
since this range is used internally for sorting alphabetically.
15.14 Scripting
15.14.1 dyna_menu
The dyna_menu plugin is a remarkable body of work by e. This plugin creates a dyna_menu
menu from which you can execute commands. You may download the latest version at:
http://rclick.netrms.com/dyna_menu.py.html
15.14.2 mod_scripting
A plugin to create script buttons and @button, @plugin and @script nodes. This plugin puts two buttons in
the icon area: a button called run Script and a button called script Button. The run Script button
is simply another way of doing the Execute Script command: it executes the selected text of the presently selected
node, or the entire text if no text is selected. The script Button button creates another button in the icon area
every time you push it. The name of the button is the headline of the presently selected node. Hitting this _new_
button executes the buttons script.
For example, to run a script on any part of an outline do the following:
1. Select the node containing the script.
2. Press the scriptButton button. This will create a new button, call it X.
3. Select the node on which you want to run the script.
4. Push button X.
Thats all. You can delete a script button by right-clicking on it. This plugin optionally scans for @button nodes,
@plugin nodes and @script nodes whenever a .leo le is opened.
Leo, Release 4.6-b1
@button nodes create script buttons.
@plugin nodes cause plugins to be loaded.
@script nodes cause a script to be executed when opening a .leo le.
Such nodes may be security risks. This plugin scans for such nodes only if the corresponding atButtonNodes,
atPluginNodes, and atScriptNodes constants are set to True in this plugin.
15.15 Servers
15.15.1 mod_http.py
A minimal http plugin for LEO, based on AsyncHttpServer.py. Use this plugin is as follows:
1. Start Leo with the plugin enabled. You will see a purple message that says something like:
http serving enabled on port 8080, version 0.91
2. Start a web browser, and enter the following url: http://localhost:8080/ You will see a a top level page
containing one link for every open .leo le. Start clicking :-)
You can use the browsers refresh button to update the top-level view in the browser after you have opened or
closed les.
To enable this plugin put this into your le:
@settings
@bool http_active = True
@int port = 8080
@string rst_http_attributename = rst_http_attribute
15.16 Spell checking
15.16.1 spellpyx.py
aspell.pyx: Leos new spell checking plugin that uses aspell.exe. It is much faster than the old mod_spelling
plugin, but requires Python 2.3 or above and a recent version of Aspell. When properly installed and enabled, this
plugin adds a Check Spelling command to Leos Edit menu. This command brings up a spell checking dialog.
You can set options by changing entries in spellpyx.ini in Leos plugins menu. One of these settings is the name of
the dictionary, spellpyx.txt by default. Warning: do not create spellpyx.txt with an @asis tree in leoPlugins.leo:
only the plugin code should typically change spellpyx.txt. You can edit spellpyx.txt yourself in an external
editor: just make sure that Leo isnt running when you do this. You can bring up the spell checker without enabling
the spellpyx plugin by using an @button Check Spelling... script button. LeoDocs.leo contains such a
script button.
15.17 Text formatting
15.17.1 Leo to AsciiDoc
Leo2AsciiDoc is a small Python program which has been built to be used as a plugin module for the Leo outlining
editor. For more information see: http://www.marshallresearch.com/michael-dawson/os/leo.html I am still using
Leo version 4.1 (rc3, build 1.62), as Ive been unable to keep up with the speed of Edwards Leo development.
15.15. Servers 147
Leo, Release 4.6-b1
He has made such signicant changes to Leo since 4.1 that I doubt that Leo2AsciiDoc will work with any version
later than 4.1. I do intend to rewrite Leo2AsciiDoc for the new Leo, but there is no schedule set.
Leo2AscDoc enables the contents of plain text Leo outlines to be published to HTML or PDF via the AsciiDoc
program and the DocBook set of publishing tools. Plain text from the Leo outline can be transformed into a
nal result that has typeset body text, in which bulleted and numbered lists, variable lists, page numbers, URLs,
index terms,and bold and italic text are automatically recognized. typeset Headings a Table of Contents an Index
containing any items marked by the user, and any Python classes or functions. To produce HTML and PDF, youll
need to have the AsciiDoc program installed (a trivial task) and a DocBook tool chain installed, which is not a
trivial task. And, of course, Python and Leo. In sum, this little program is an easy install for people who are
already using Leo and DocBook. As noted later, Leo2AsciiDoc has only been tested on Linux
15.17.2 rst3.py
The rst3 plugin creates output les from Leo outlines containing rST (reStructuredText) markup. rst3 options
control most aspects of this plugins operations. You can set options in @settings trees, in headlines and in body
text. There are too many options to describe here. See: http://webpages.charter.net/edreamleo/rstplugin3.html for
full documentation. To use this plugin effectively, Pythons docutils module must be installed. The rst3 plugin
will use the SilverCity syntax coloring package if it installed.
The rst3 plugin adds the Write Restructured Text command to Leos Edit menu. This command searches
the selected outline looking for rst root nodes whose headline have the form:
@rst <filename>
The plugin then creates the named le in various ways depending which rst3 options are in effect. By default, the
rst3 plugin creates rST headings automatically from outlines, so the higher-level nodes in the outline correspond
to higher-level sections in the output. Creating rST headings automatically eliminates one of the most tedious
chores associated with rST markup. This plugin sends .htm, .html or .tex les to the docutils module for further
processing. Docutils generates HTML les or LaTeXles depending on the les extension. HTML les generated
by docutils refer to three .css (cascading style sheet) les that should exist in the same directory as the generated
HTML le. You can control the formatting of the HTML le by altering these .css les.
For full details on this plugin, see http://webpages.charter.net/edreamleo/rstplugin3.html
A new method has been added to the rst3 plugin to make it more easily to drive the plugin from scripts:
def writeNodeToString (self,p=None,ext=None)
writeNodeToString scans ps tree (p defaults to presently selected node) looking for @rst nodes. When the rst
@rst node is found, writeNodeToString processes the node as usual, with the following changes:
@rst need not be followed by a lename; any lename and its extension are ignored.
Only the ext argument to writeNodeToString determines the type of output produced. The valid values for
the ext argument are None (for rst output), .html, .pdf, and .tex.
Instead of writing the result to a le, writeNodeToString returns the tuple (p,s), where p is the node whose
tree produced the output, and s is the output itself.
writeNodeToString returns after processing at most one @rst node.
Scripts can easily use writeNodeToString to convert @rst trees into various kinds of output. For example, here is
the body of @button rst->html in LeoDocs.leo:
if rst3:
if controller:
p,s = controller.writeNodeToString(ext=.html)
Leo, Release 4.6-b1
print
*
*
40,p
print s
Notes:
This script scans the presently selected tree for @rst nodes, just like the @button rst script does. In particular,
if the presently selected tree does not contain an @rst node the search continues in parent trees. When an
@rst node is found, it converts the node (and descendants) to html and returns p, the found @rst node and
s, the html itself.
The script shown above merely prints the output, but many other actions could be taken. In particular,
because writeNodeToString returns p it would be possible to write a script that would scan multiple @rst
nodes.
None and .tex are also valid values for the ext argument to writeNodeToString. None converts the @rst
tree to a single reStructuredText string, as shown in @button rst->rst.
There is some support for ext=.pdf, but this is experimental code. Expect crashes.
15.17.3 xsltWithNodes.py
Adds XSLT-Node Command submenu item to the Outline menu. This menu contains the following items:
Set StyleSheet Node Selects the current node as the xsl stylesheet the plugin will use.
Process Node with Stylesheet Node Processes the current node as an xml document, resolving sec-
tion references and Leo directives, and creates a sibling containing the results.
Requires 4Suite 1.0a3 or better, downloadable from http://4Suite.org.
15.18 Windows
15.18.1 cleo.py
Cleo allows you to annotate or colour leo outlines based on priority, code archetype, node types or some arbitrary
criteria. The annotations and colour coding can play a similar role like that of syntax highlighting. Right-click on
the icon area to popup its menu to play with it.
15.18.2 footprints.py
A plugin to leave footprints! This colors the Leo nodes so that the ones you have visited most and most recently
will stand out.
15.18.3 EditAttributes.py
A plugin that lets the user to associate text with a specic node. Summon it by pressing button-2 or button-3 on
an icon Box in the outline. This will create an attribute editor where the user can add, remove and edit attributes.
Since attributes use the underlying tnode, clones will share the attributes of one another.
15.18.4 maximizeNewWindows.py
Maximizes all new windows.
15.18. Windows 149
Leo, Release 4.6-b1
15.18.5 nodebar.py
The nodebar plugin adds buttons at the bottom of the tree canvas. The buttons correspond to commands found in
the Outline commands. It is intended to speed up a new users ability to use the outline. Experienced users may
nd value in being able to quickly execute commands they do not use very often.
15.18.6 redirect_to_log.py
Send all output to the log pane.
15.18.7 TabbedLog.py
Turns the log into a tabbed component. Other plugins may add tabs. To get a new tab in TabbedLog:
import TabbedLog
pane = TabbedLog.getPane(name,c)
pane is the pane returned for you to work with.
name is the name of the tab you want for the pane.
c is the commander for the leoFrame.
15.18.8 UASearch.py
A plugin for searching unknownAttributes (uAs).
15.18.9 UniversalScrolling.py
A plugin that enables the user to scroll down with a left mouse click and hold, and to scroll up with a right mouse
click and hold. Scrolling continues until the user releases the mouse. Originally designed as a workaround for
various bugs in Tkinter scrolling, this may actually be superior to wheel scrolling, in that there is little work a user
has to do to scroll except to press a button.
15.18.10 URLloader.py
This plugin uses Pythons urllib module to download les and import them into Leo. It requires the TabbedLog
plugin.
CHAPTER
SIXTEEN
CHAPTER 13: WRITING PLUGINS
16.1 Overview
A plugin is a Python le that appears in Leos plugin directory. Plugins modify how Leo works. With plugins you
can give Leo new commands, modify how existing commands work, or change any other aspect of Leos look and
feel. leoPlugins.leo contains all of Leos ofcial plugins. Studying this le is a good way to learn how to
write plugins.
You enable plugins using @enabled-plugins nodes in leoSettings.leo or myLeoSettings.leo. For more details, see
the @enabled-plugins node in leoSettings.leo. Leo imports all enabled plugins at startup time. Plugins become
active if importing the plugin was successful.
Writing plugins is quite similar to writing any other Leo script. See Chapter 7: Scripting Leo with Python. In
particular:
1. Plugins can use any of Leos source code simply by importing any module dened in leoPy.leo.
2. Plugins can register event handlers just like any other Leo script. For full details, see the section called event
handlers in Leos scripting chapter.
The rest of this chapters discusses topics related specically to plugins.
16.2 Support for unit testing
The plugins test suite creates a new convention: if a plugin has a function at the outer (module) level called
unitTest, Leo will call that function when doing unit testing for plugins. So it would be good if writers
of plugins would create such a unitTest function. To indicate a failure the unitTest just throws an
exception. Leos plugins test suite takes care of the rest.
16.3 Turning script buttons into plugins
This section provides step-by-step instructions for turning a script button into a plugin. The plugin will dene a
minibuffer command that does the same thing as pressing the button.
We shall start with a script button whose script is:
g.es_print(c: %s % (c.fileName()),color=red)
g.es_print(p: %s % (p.h),color=red)
Not very exciting, but it uses the predened c and p constants. Our plugin will create a minibuffer command
called print-cp.
Here are the step-by-step instructions:
151
Leo, Release 4.6-b1
1. Open leoPlugins.leo and use the Copy Node command to copy the tree at:
Plugins> Templates: these show recommended ways of dening plugins.>Template for Tk plugin with per-
commander controller class
1. Paste the tree somewhere else and rename it to @thin print_cp.py. I copied the tree to:
Plugins-->Example code-->@thin print_cp.py
2. Update the docstring, the __version__ constant and the << imports >> section. Note that unlike when using
script buttons, you must have the following imports:
3. Because this plugin doesnt require any gui interface, we simplify the init function:
def init ():
leoPlugins.registerHandler(after-create-leo-frame,onCreate)
return True
The init function registers the onCreate hook and returns True to indicate that it loaded properly.
4. Leave the onCreate function unchanged. It creates a per-commander instance of the pluginController
class. This class exists mainly to bind self.c properly to a commander.
5. Change the constructor (__init__ method) of the pluginController class to this:
def __init__ (self,c):
self.c = c
c.k.registerCommand(print-cp,shortcut=None,func=self.print_cp)
script = "c.k.simulateCommand(print-cp)"
g.app.gui.makeScriptButton(c,script=script,buttonText=Print c & p,bg=red)
This registers the print_cp method of the pluginController class as the print-cp minibuffer command, and
creates a script button with the following script:
c.k.simulateCommand(print-cp)
6. Dene the print_cp method as follows:
def print_cp (self,event=None):
c = self.c ; p = c.p
g.es_print(c: %s % (c.fileName()),color=red)
g.es_print(p: %s % (p.h),color=red)
The print_cp method must have the event argument as shown because it implements a minibuffer command.
The print_cp method gets the proper commander from the c ivar (instance variable) and computes the
current position p as shown.
7. Enable the print_cp plugin by putting the following in an @enabled-plugins node:
print_cp.py
8. Test the plugin by restarting Leo (I just start test.leo). You can test the plugin by pressing the Print c&p
button or by typing <Alt-x> print-cp <Return>.
Thats all. You can nd the completed version of the print_cp plugin in leoPlugins.leo, or leoPluginsRef.leo if you
are using cvs.
152 Chapter 16. Chapter 13: Writing Plugins
Leo, Release 4.6-b1
16.4 Important security warnings
Naively using plugins can expose you and your .leo les to malicious attacks. The fundamental principles are:
Scripts and plugins must never blindly execute code from untrusted sources.
and:
.leo files obtained from other people may potentially contain hostile code.
Stephen Schaefer summarizes the danger this way:
I foresee a future in which the majority of leo projects come from
marginally trusted sources...a world of leo documents sent hither and yon -
resumes, project proposals, textbooks, magazines, contracts - and as a race
of Pandoras, we cannot resist wanting to see "Whats in the box?" And are
we going to fire up a text editor to make a detailed examination of the
ASCII XML? Never! Were going to double click on the cute leo file icon, and
leo will fire up in all its raging glory. Just like Word (and its macros) or
Excel (and its macros).
In other words:
When we share "our" .leo files we can NOT assume that
we know what is in our "own" documents!
Not all environments are untrustworthy. Code in a commercial cvs repository is probably trustworthy: employees
might be terminated for posting malicious code. Still, the potential for abuse exists anywhere.
In Python it is very easy to write a script that will blindly execute other scripts:
# Warning: extremely dangerous code
# Execute the body text of all nodes that start with @script.
def onLoadFile():
h = p.h.lower()
if g.match_word(h,0,"@script"):
s = p.b
if s and len(s) > 0:
try: # SECURITY BREACH: s may be malicious!
exec(s + \n)
except:
es_exception()
Executing this kind of code is typically an intolerable security risk. Important: rexec provides no protection
whatever. Leo is a repository of source code, so any text operation is potentially malicious. For example, consider
the following script, which is valid in rexec mode:
badNode = c.p
<< change rexec to exec in ps body >>
<< delete badNode >>
<< clear the undo stack >>
This script will introduce a security hole the .leo le without doing anything prohibited by rexec, and without
leaving any traces of the perpetrating script behind. The damage will become permanent outside this script when
the user saves the .leo le.
16.4. Important security warnings 153
Leo, Release 4.6-b1
154 Chapter 16. Chapter 13: Writing Plugins
CHAPTER
SEVENTEEN
CHAPTER 14: LEO AND
RESTRUCTUREDTEXT
17.1 Overview
reStructuredText (rST) is a popular markup language for writing documents. rST is simple, yet powerful. All of
Leos documentation is written in rST, and then processed via the docutils and Sphinx processors to produce Leos
web pages.
Leo makes writing rST documents easier. A lot easier. There are several reasons for this:
1. Leo outlines help organize rST source code in all the usual ways. You always clearly see the structure of even
book-length documents. You can rearrange and reorganize chapters, sections and paragraphs effortlessly. You
can use clones to create multiple views of your writing for yourself and your readers. These capabilities, all by
themselves, would make Leo an excellent choice for editing rST documents.
2. Leo xes the clumsiest part of rST markup, namely the markup for headings. Without Leo, you must underline
heading lines manually. The underlining character indicates the level of a heading. Changing the level of a
heading is clumsy and error prone: you must change the underlining character properly. Changing the level of
several headings is a headache.
Leo gets rid of all this bother. Within an outline that gets written to an external rST le, Leos headlines become
section headings. When writing external rST les, Leo generates underlining for headers automatically based
on the outline level of the outline nodes. When you rearrange your outline Leo will recompute the rST markup
needed to recreate the outline structure in the external rST le. In most cases, you wont even see the rST markup
for headings!
3. @auto-rst nodes allow you to edit exising rST les in Leo. The outline structure of such nodes mirrors the level
of the rST section headings. Note: there may be minor variations the rst time you import an existing rST le, but
these differences will not affect the meaning of the rST le. After the rst import, the only changes when writing
the imported rST le will be changes you make.
The three features just discussed (Leos organizational capabilities, automatic generation of markup for rST head-
ings, and @auto-rst trees) are useful for anyone using reStructuredText. In addition Leo provides additional
capabilities for power users:
1. @rst trees can contain settings that affect how Leo writes individual nodes.
@rst trees allows the ultimate in exible formating. Well discuss these options in detail later, but here are a few
examples.
Headlines that starts with @rst-no-head do not create an rST heading.
Body text that starts with:
@rst-option code_mode = True
155
Leo, Release 4.6-b1
causes the body text of the node to be displayed as an rST code block.
Leos rst3 command generates .htm, .html or .tex output les from @rst tree, provided that you have installed
Pythons docutils module. The rst3 command will use the SilverCity syntax coloring package if it installed.
The rst3 command sends .htm, .html or .tex les to the docutils module for further processing. Docutils generates
HTML les or LaTeX les depending on the les extension. HTML les generated by docutils refer to three .css
(cascading style sheet) les that should exist in the same directory as the generated HTML le. You can control
the formatting of the HTML le by altering these .css les. See Required cascading style sheets for more details.
5. The rST options just discussed will sufce to create just about any kind of rST output. But for those desiring
the ultimate in exibility, it is relatively straightforward to create Leo outlines or external les using scripts. For
example, you might want to write a script to format source code to rST markup. A script can give you complete
control over such formatting. This chapter concludes by telling how to write such scripts.
17.2 Power features of @rst trees
1. The rst3 command allows much more exible control over its operations using rst options. You can set options
in @settings trees, in headlines and in body text. Nodes inherit most rst3 options from ancestor nodes much like
nodes inherit Leo directives. See Options.
The most important option is the code_mode option. This option species whether to process the body text of a
node as rst markup (rst mode) or source code that is to be converted to rST markup (code mode). Any node can
be processed in any mode.
2. Headlines can set any option. This turns out to be very convenient. See Headline commands for details. Nodes
whose headlines start with @rst-options are treated specially. The body text of such rst options nodes should
contain nothing but lines of the form:
<option>=<value>
3. You can set any rst options in the body text of any node using doc parts of the form:
@ @rst-options
list of rst options, one per line
@c
Such option doc parts allows you to specify rst options even with source code les.
4. You can embed rST markup in the body text of any node using doc parts of the form:
@ @rst-markup
any rST markup
@c
Such markup doc parts allow you to ne-tune the formatting of your source les. See Using doc parts for full
details.
17.3 Options
You can set any option in any node, so you have complete control over how the rst3 command processes each
node. The following is a list of options that control how the rst3 command formats each particular node.
code_mode (default: False) True: process nodes in code mode. False: process nodes in rst mode. In code mode,
the rst3 command automatically creates rST markup to display the body text as an rst code-block. In rst
mode the rst3 simply copies the body text of the node to the output. That is, the rst3 command assumes that
body text is already valid rST markup.
156 Chapter 17. Chapter 14: Leo and ReStructuredText
Leo, Release 4.6-b1
doc_only_mode (default: False) True: process nodes in doc_only mode. False: process nodes in rst mode or
code_mode, depending on options. In doc_only mode, the rst3 command outputs only regular doc parts and
@ @rst-markup doc parts. Headlines create section in doc_only mode only if a) the node contains a doc
part or b) the show_organizer_nodes option is in effect. As always can use @ @rst-options for per-node
control of the process, especially node-by-node control of the show_organizer_nodes option.
default_path (default: ) The path to be prepended to lenames given in root nodes.
default_encoding (default: utf-8) The default encoding to be used for non-ascii (unicode characters).
encoding (default: the default_encoding setting) The encoding to be used for non-ascii (unicode) characters.
Important: this option has effect only in @rst-options doc parts in root @rst nodes.
generate_rst (default: True) A master switch. True: generate rST markup for rST sections and rST code-blocks.
False: dont generate rST markup and ignore @ @rst-markup doc parts.
generate_rst_header_comment (default: True)
This option has effect only if the generate_rst and write_intermediate_le options are both True.
When this option is in effect, Leo writes a comment line of the form:
.. rst3: filename: <filename>
at the start of intermediate les.
number_code_lines (default: True) Controls whether to number code lines in code mode. This option has no
effect in rst mode.
publish-argv-for-missing-stylesheets (Default: ) The arguments to be passed to docu-
tils.core.Publisher().publish() when no stylesheet is in effect. This is a string that represents a
comma-separated list of strings: For example, the option:
publish-argv-for-missing-stylesheets=--language=de,--documentclass=report,--use-latex-toc
results in the call:
publish([--language=de,--documentclass=report,--use-latex-toc])
show_doc_parts_as_paragraphs (default: False) True: Move doc parts outside of the code-block directive in
code mode. This option has no effect in rst mode. Cool: Any rST markup in doc parts included as the result
of this option will be rendered properly.
show_doc_parts_in_rst_mode (default: True) This option is most useful for rst documents which are not com-
puter code. It allows you to use doc parts to make comments on the draft document which are either
excluded from the output or formatted in a way that highlights their nature as comments rather than con-
tet. For example, youre writing a book, and you want to use a doc part at the top of a section to remind
yourself need to explain how Ted got to Sallys. Note: you may need to add CSS to have them formatted
differently. The option can be True, False, or one or more class names.
True: doc parts have no special signicance in rst mode. That is, the entire doc part from the opening @
to the closing @c and everything in between are treated as normal rST markup.
False: doc parts are removed from the output in rst mode
class name(s):
The contents of the doc part is processed as it if was in an rst container directive. For example:
@ @rst-options
show_doc_parts_in_rst_mode = notes literal
@c
17.3. Options 157
Leo, Release 4.6-b1
would wrap the doc part contents in the output in a div with classes container notes literal.
Furthermore, if one of the class names is literal, then the doc part content will be output as a
literal block wrapped in a container as described above. This allows you to use text which is not
valid rst as rough notes for annotating a draft document.
show_headlines (default: True) True: automatically generate rST sections from headlines. Applies to both code
mode and rst mode. The level of the node in the outline determines the level of the section underling in the
rST markup. Higher-level headlines in the outline correspond to higher-level section headings; lower-level
headlines in the outline correspond to lower-level section headings.
show_leo_directives (default: True) True: include Leo directives in code mode. This option has no effect in rst
mode.
show_markup_doc_parts (default: False) True: include markup doc parts in code mode. This option has no
effect in rst mode.
show_options_doc_parts (default: False) True: include options doc parts in code mode. This option has no
effect in rst mode.
show_options_nodes (default: False) True: show @rst-options nodes.
show_organizer_nodes (default: True) True: generate rST sections for nodes that do not contain body text.
This option has no effect unless the rST section would otherwise be written.
show_sections (default: True) True: generate rST sections corresponding to headlines. False: dont generate
sections. Instead, generate lines of the form:
**
headline
**
strip_at_le_prexes (default: True) True: remove @auto, @le, @nosent and @thin from the start of head-
lines.
stylesheet_name (default: default.css) The name of the stylesheet passed to docutils.
stylesheet_path (default: ) The directory containing the stylesheet passed to docutils.
underline_characters (default: #=+*^~-:><_) The underlining characters to be used to specify rST sec-
tions. The rst character is reserved so you can specify the top-level section explicitly.
verbose (default: True) True: write informational messages.
write_intermediate_le (default: False) True: writes intermediate les before sending them to docutils. This
option only applies to .htm, .html and .tex les. The name of the intermediate le has the name of the output
le with .txt appended. This option has effect only if the generate_rst option is True.
17.3.1 Options supporting the http plugin
The following options are for the use of Bernhard Mulders http plugin. The http plugin creates an http server
running on a local port, typically 8080. When the http plugin is running you will see a purple message in the log
window that looks something like this:
http serving enabled on port 8080, version 0.91
To use the http plugin, start a web browser and enter this url:
http://localhost:8080/
You will see a a top level page containing one link for every open .leo le. Clicking on link will cause the http
server to pass a new page to the browser. You can use the browsers refresh button to update the top-level view in
the browser after you have opened or closed les.
Important: See the docstring for the http plugin for information on conguring the plugin. Some of the following
rst3 settings must match values of settings for the http plugin. Here are the rst3 options that support the http plugin:
Leo, Release 4.6-b1
http_server_support (default: False) A master switch: none of the following options have any effect unless this
option is True. If True, the rst3 command does the following:
Writes node markers in the rst output for use by the http plugin. Node markers are rst named hyperlink
targets. By default they look like:
.. _http-node-marker-N
where N is a unique node number.
Adds additional information to all nodes of the tree being formatted using Leos unknownAttributes
mechanism.
http_attributename (default: rst_http_attribute) The name of the attribute name written to the unknownAt-
tributes attribute of each each outline node in the rst root tree. The default is rst_http_attribute; it should
match the following setting of the http plugin:
@string rst_http_attributename = rst_http_attribute
This option has no effect unless the http_server_support option is True.
clear_http_attributes (default: False) If True the rst3 command initially clears the elds specied by
http_attributename. This option has no effect unless the http_server_support option is True.
node_begin_marker (default: http-node-marker-) The string used for node markers. This option has no ef-
fect unless the http_server_support option is True.
17.3.2 Options that set command names
The following options specify the spelling of headline commands. The option_prex and option_prexes com-
mand also dene the spelling of special doc parts.
You can change these to make them shorter or to avoid conicts with headlines in your Leo les. The list below
merely gives the default value for each setting.
code_prex: @rst-code
ignore_headline_prex: @rst-no-head
ignore_headlines_prex: @rst-no-headlines
ignore_prex_tree: @rst-ignore
ignore_node_prex: @rst-ignore-node
ignore_tree_prex: @rst-ignore-tree
option_prex: @rst-option
options_prex: @rst-options
preformat_prex: @rst-preformat
rst_prex: @rst
show_headline_prex: @rst-head
17.4 Headline Commands
It is often convenient to set options in headlines. This is done with the following headline commands:
@rst TEXT Enter rst mode. Create a section called TEXT provided the show_headlines option is set.
@rst-code TEXT Enter code mode. Create a section called TEXT provided the show_headlines option is set.
@rst-ignore-node TEXT Suppress all output from a single node. TEXT is ignored. Has no effect on descendant
nodes and does not change any rst3 option.
17.4. Headline Commands 159
Leo, Release 4.6-b1
@rst-ignore-tree TEXT and @rst-ignore TEXT Suppress all output from the node and its descendants. TEXT
is ignored. Does not change any rst3 formatting option.
@rst-no-head TEXT Suppress the generation of an rST section for this node only. Does not affect descendant
nodes. Has no effect on descendant nodes and does not change any rst3 option.
@rst-no-headlines TEXT Set the show_headlines option to False. As a result, TEXT is ignored.
@rst-option <option> = <value> Set a single option to the given value. The default value is True.
@rst-options TEXT Set zero or more options from the body text of the node. TEXT is ignored. The entire body
text is treated as if it were in an @ @rst-options doc part.
@rst-preformat TEXT Format the entire body text of the node as if the entire text preformatted. TEXT is
ignored. In effect, a line containing :: is added to the start of the text, and all following lines of the text are
indented. This option has no effect on descendant nodes.
Notes:
Several of these commands affect only the node in which they appear. Such commands set internal settings
variables only: they have no effect on the visible rst3 options.
If a headline generates an rST section, the section name does not include the headline command. Further-
more, no rST section is generated if the TEXT is empty.
17.5 Using doc parts
Recall that in Leo a doc part starts with the @ directive and continues until the end of body text or until the @c
directive is seen. For example:
@c
Leo converts doc parts into comments using whatever comment delimiters are in effect.
Option doc parts are doc parts that start with @ @rst-options. All other lines of such doc parts should be of the
form name=value. (rST comments lines starting with .. are allowed). For example:
@ @rst-options
.. This comment line is ignored.
show_headlines=False
show_leo_directives=False
verbose=True
@c
The rst3 command sets options from option doc parts, even in code mode.
Markup doc parts are doc parts that start with @ @rst-markup. For example:
@ @rst-markup
.. contents::
The rst3 command replaces markup doc parts by the markup they contain, even in code mode.
Option and markup doc parts are especially useful in code mode. They allow you to specify options or insert rST
markup directly from with derived les. This makes your source les self contained: there is no need to add other
nodes to make the rst3 command happy.
A cool feature: In code mode, rST markup in ordinary doc parts will be rendered properly when the
show_doc_parts_as_paragraphs option is in effect. Important: Regardless of the show_doc_parts_as_paragraphs
Leo, Release 4.6-b1
option, doc parts have no special signicance in rst mode. That is, the entire doc part from the opening @
to the closing @c and everything in between are treated as normal rST markup. Update: you can now use the
show_doc_parts_in_rst_mode option to change this behavior and control the processing of doc parts in rst mode.
17.6 Setting defaults
You can set the defaults for any rst3 option in several ways:
1. By setting options in the root node using @ @rst-options doc parts. For example, the root of the le that
generated this documentation contains:
@ @rst-options
code_mode=False
doc_mode_only=False
generate_rst=True
show_organizer_nodes=True
show_headlines=True
show_leo_directives=True
verbose=True
@c
2. By setting options in @settings trees. To do this, you must prex the option name shown in this documentation
with the prex rst3_. For example:
@settings
@bool rst3_write_intermediate_file = True
17.7 The code-block directive
The rst3 command denes a code-block rST directive. The primary purpose of this directive is to show formatted
source code.
In rst mode you can insert the code-block directive like any other rST markup. The rst3 command generates
code-block directives when handling nodes in code mode.
This directive takes one argument, a language name. Like this:
.. code-block:: Python
This directive syntax colors the code in the indented code block that follows the directive. The result looks like
this if the SilverCity syntax coloring module has been installed.
See the Scripting chapter in LeoDocs.leo for many examples of how to use code-blocks.
17.8 Required cascading style sheets
HTML les generated by the rst3 command assume that three .css (cascading style sheet) les exist in the same
directory. For the HTML output to look good the following .css les should exist:
default.css is the default style sheet that docutils expects to exist.
leo_rst.css contains some style improvements based on Gunnar Schwants DocFactory.
silver_city.css is the style sheet that controls the syntax highlighting generated by SilverCity.
17.6. Setting defaults 161
Leo, Release 4.6-b1
The latter two style sheets are imported at the end of the default.css.
Important: You can use cascading style sheets to do things that otherwise wouldnt be possible with plain rST.
For instance, the background color of this page was specied in a body style.
17.9 Notes about rST markup
Leo reserves the # character for your own use so that you can specify an rST headline explicitly. For example,:
#####
Title
#####
You would typically put such a title in the rst root node. Otherwise, you should let the rst3 command automatically
generate rST sections from headlines.
To create a table of contents (TOC) put:
.. contents:: Table of Contents
on its own line wherever you want the TOC to appear. This line can appear in body text in rst mode, or in an @
@rst-markup doc part in code mode.
17.10 Examples
The le ListManagerDocs.html is an impressive example of the kind of output that can be generated relatively
easily using the rst3 command.
The source for ListManagerDocs.html is wxListManager.leo. Important: wxListManager.leo was written for the
old rst2 plugin; it could be greatly simplied if adapted for the rst3 command.
The les in LeoDocs.leo under the node Leos HTML Users Guide contain examples of using the rst3 command.
This documentation was created using the rst3 command. The source code for this documentation is in
LeoDocs.leo. The source code for all the rst3 command is in leoRst.py in leoPy.leo.
17.11 Theory of operation
The code for the rst3 command is more complex than usual. Fortunately, the overall organization is straightfor-
ward.
defaultOptionsDict This dictionary represents each rst3 option. To add another option, just add another entry
to this dictionary. Keys are the option name, including the rst3_ prex. Values are the default value of the
option. The hard values in the dictionary may be changed as the result of @settings entries.
processTree processTree is the top-level code that handles one rst root node. It calls preprocessTree to create the
tnodeOptionDict ivar. processTree then calls either writeNormalTree or writeSpecialTree depending on
whether text will be sent to docutils for further processing. These two methods handle mundane details of
opening an closing les. Both writeNormalTree and writeSpecialTree call writeTree to do the actual work.
tnodeOptionDict The entries in this dictionary represents the options that are set in one particular node. The keys
of tnodeOptionDict are tnodes, the values are anonymous dictionaries. These anonymous inner dictionaries
contain the options that are explicitly set at each tnode (and thus each position). Preprocessing the tree this
way ensures that each node (headline and body text) is parsed exactly once.
writeTree writeTree rst calls scanAllOptions, which has the effect of initializing all options. writeTree then
calls writeNode for each node that will be processed by the rst3 command. Options may cause the rst3
command to skip a node or an entire subtree.
Leo, Release 4.6-b1
writeNode writeNode rst calls scanAllOptions to compute the options that are in effect for that single node.
Once options have computed, processing the node is straightforward. writeNode calls writeBody and write-
Headline to do the real work. These methods generate or skip text based on various options.
scanAllOptions scanAllOptions recreates the optionsDict ivar to represent all the options in effect for for the
particular node being processed by writeNode. Client code gets these options by calling the getOption
method.
scanAllOptions rst inits all options from settings, then updates those options using the anonymous dictio-
naries contained in the tnodeOptionsDict. scanAllOptions works like g.scanAllDirectives, but the code is
much simpler.
17.12 Controlling the rst3 command from scripts
A new method has been added to make it more easily to write rST code from scripts:
c.rstCommands.writeNodeToString(p)
writeNodeToString scans ps tree (p defaults to presently selected node) looking for @rst nodes. When the rst
@rst node is found, writeNodeToString processes the node as usual, with the following changes:
@rst need not be followed by a lename; any lename and its extension are ignored.
Only the ext argument to writeNodeToString determines the type of output produced. The valid values for
the ext argument are None (for rst output), .html, .pdf, and .tex.
Instead of writing the result to a le, writeNodeToString returns the tuple (p,s), where p is the node whose
tree produced the output, and s is the output itself.
writeNodeToString returns after processing at most one @rst node.
Scripts can easily use writeNodeToString to convert @rst trees into various kinds of output. For example, here is
the body of @button rst->html in LeoDocs.leo:
if rst3:
if controller:
p,s = controller.writeNodeToString(ext=.html)
print
*
*
40,p
print s
Notes:
This script scans the presently selected tree for @rst nodes, just like the @button rst script does. In particular,
if the presently selected tree does not contain an @rst node the search continues in parent trees. When an
@rst node is found, it converts the node (and descendants) to html and returns p, the found @rst node and
s, the html itself.
The script shown above merely prints the output, but many other actions could be taken. In particular,
because writeNodeToString returns p it would be possible to write a script that would scan multiple @rst
nodes.
None and .tex are also valid values for the ext argument to writeNodeToString. None converts the @rst
tree to a single reStructuredText string, as shown in @button rst->rst.
There is some support for ext=.pdf, but this is experimental code. Expect crashes.
17.12. Controlling the rst3 command from scripts 163
Leo, Release 4.6-b1
17.13 Acknowledgements
Josef Dalcolmo wrote the initial rst plugin. Timo Honkasalo, Bernhard Mulder, Paul Paterson, Kent Tenney and
Steve Zatz made contributions to the rst and rst2 plugins.
CHAPTER
EIGHTEEN
CHAPTER 15: CONTROLLING
SYNTAX COLORING
This chapter discusses how to control Leos new syntax colorer using Python les derived from jEdits xml lan-
guage description les. It also discusses settings related to syntax coloring.
Important: this material is for those who want to support Leos colorizing code. You do not need to understand
this chapter in order to use Leos colorizers.
The __jEdit_colorizer__.py plugin was an early prototype of the new colorizer. This code has been retired. The
threading_colorizer.py plugin uses a separate helper thread to do the colorizing. Coding details for this plugin are
discussed in this chapter.
18.1 Files
The jEdit editor drives its syntax colorer using xml language description les. jEdits documentation contain a
complete description of these xml les. Each xml le describes one colorizing mode. A mode consists of one
or more rulesets, and each ruleset consists of a list of colorizing rules. In addition, modes, rulesets and rules
may have associated properties and attributes. Various rules may specify that the colorizer uses another ruleset
(either in the same mode or another mode).
Important: jEdits xml language description les contain no explicit <RULE> elements Rules are simply sub-
elements of an enclosing <RULES> element. The element indicates the kind of rule that is specied, for example,
<SPAN>, <SEQ>, etc. By the term rule element we shall mean any sub-element of the <RULES> element.
Rather than using the xml language description les directly, Leo uses Python colorer control les, created
automatically from the xml les by a script called jEdit2Py. These Python les contain all the information in
the jEdits xml les, so we can (loosely) speak of modes, rulesets, rules, properties and attributes in the Python
colorer control les. Later sections of this documentation will make this loose correspondence exact.
Important: throughout this documentation, x.py will refer to the Python colorer for language x, and x.xml will
refer to the corresponding xml language-description le.
Using Python colorer control les has the following advantages:
Running jEdit2Py need only be done when x.xml changes, and the speed of the xml parser in jEdit2Py
does not affect the speed of Leos colorizer in any way. Moreover, the jEdit2Py script can contain
debugging traces and checks.
Colorer control les are valid .py les, so all of Pythons import optimizations work as usual. In particular,
all the data in colorer control les is immediately accessible to Leos colorer.
Colorer control les are easier for humans to understand and modify than the equivalent xml le. Further-
more, it is easy to insert debugging information into Python colorer control les.
It is easy to modify the Python colorer control les by hand without changing the corresponding xml le.
In particular, it would be easy to dene entirely new kinds of pattern-matching rules in Python merely by
creating functions in a colorer control le.
165
Leo, Release 4.6-b1
18.2 The colorizers inner loop
When Leos syntax colorer sees the @language x directive, it will import x.py from Leos modes folder.
The colorer can then access any module-level object obj in x.py as x.obj.
Colorizer control les contain rules functions corresponding to rule elements in x.xml. The colorizer can call
these functions as if they were members of the colorizer class by passing self as the rst argument of these
functions. I call these rules functions to distinguish them from the corresponding rules methods which are actual
methods of the colorizer class. Rules functions merely call corresponding rules methods. Indeed, rules functions
are simply a way of binding values to keyword arguments of rules methods. These keywords arguments correspond
to the xml attributes of rule elements in x.xml.
The colorizer calls rules functions until one matches, at which point a range of text gets colored and the process
repeats. The inner loop of the colorizer is this code:
for f in self.rulesDict.get(s[i],[]):
n = f(self,s,i)
if n > 0:
i += n ; break
else: i += 1
rulesDict is a dictionary whose keys are rulesets and whose values are ruleset dictionaries. Ruleset dic-
tionaries have keys that are single characters and whose values are the list of rules that can start with that
character.
s is the full text to be colorized.
i is the position within s is to be colorized.
Rules methods (and functions) return n > 0 if they match, and n == 0 if they fail.
18.3 Format of colorizer control les
The following sections describe the top-level data in x.py.
18.3.1 Ruleset names
A ruleset name is a Python string having the form x_setname, where setname is the value of the SET
attribute of the <RULES> element in x.xml. For example, the ruleset name of the ruleset whose SET attribute
is JAVASCRIPT in php.xml is php_JAVASCRIPT. Important: by convention, the ruleset name of the
default <RULES> element is x_main; note that default <RULES> element have no SET attributes.
The colorizer uses ruleset names to gain access to all data structures in x.py. To anticipate a bit, ruleset names
are keys into two standard dictionaries, x.rulesDict and x.keywordsDictDict, from which the colorizer
can get all other information in x.py:
# The rules list for the JAVASCRIPT ruleset in php.xml.
rules = x.rulesDict(php_JAVASCRIPT)
# The keywords dict for the JAVASCRIPT ruleset in php.xml.
keywordsDict = x.keywordsDictDict(php_JAVASCRIPT)
In fact, ruleset names (and x.rulesDict and x.keywordsDictDict) are the only names that the colorizer
needs to know in order to access all information in x.py.
166 Chapter 18. Chapter 15: Controlling Syntax Coloring
Leo, Release 4.6-b1
18.3.2 x.properties
x.properties is a Python dictionary corresponding to the <PROPS> element in x.xml. Keys are property names;
values are strings, namely the contents of <PROPERTY> elements in x.xml. x.properties contains proper-
ties for the entire mode. That is, only modes have <PROPS> elements. For example, here is x.properties in
php.py:
# properties for mode php.xml
properties = {
"commentEnd": "-->",
"commentStart": "
print g.app.gui.getTextFromClipboard()
print 
at the end of script B, and back in script A, after youve rebuilt response as shown above, just:
g.app.gui.replaceClipboardWith(response)
c.pasteOutline()
22.2. Running leoBridge from within Leo 189
Leo, Release 4.6-b1
190 Chapter 22. Chapter 19: Embedding Leo with the leoBridge module
CHAPTER
TWENTYTHREE
CHAPTER 20: UNIT TESTING WITH
LEO
This chapter describes how you can execute Python unit test from within Leo outlines.
23.1 Overview
Leos unit test commands run the unit tests created by @test and @suite nodes. run-unit-tests and run-unit-tests-
locally run all unit tests in the presently selected part of the Leo outline; run-all-unit-tests and run-all-unit-tests-
locally run all unit tests in the entire Leo outline.
You must be running Leo from a console to see the output the unit tests. Leos unit test commands run all the
unit tests using the standard unittest text test runner, and the output of the unit tests appears in the console.
test/unitTest.leo contains many examples of using @test and @suite nodes.
23.2 Using @test nodes
@test nodes are nodes whose headlines start with @test. The unit test commands convert the body text of @test
nodes into a unit test automatically. That is, Leos unit test commands automatically create a unittest.TestCase
instances which run the body text of the @test node. For example, let us consider one of Leos actual unit tests.
The headline is:
@test consistency of back/next links
The body text is:
if g.unitTesting:
c,p = g.getTestVars() # Optional: prevents pychecker warnings.
back = p.back()
next = p.next()
if back: assert(back.getNext() == p)
if next: assert(next.getBack() == p)
When either of Leos unit test commands nds this @test node the command will run a unit test equivalent to the
following:
class aTestCase (unittest.TestCase):
def shortDescription():
return @test consistency of back/next links
191
Leo, Release 4.6-b1
def runTest():
c,p = g.getTestVars()
back = p.back()
next = p.next()
if back: assert(back.getNext() == p)
if next: assert(next.getBack() == p)
As you can see, using @test nodes saves a lot of typing:
You dont have to dene a subclass of unittest.TestCase.
Within your unit test, the c, g and p variables are predened, just like in Leo scripts.
The entire headline of the @test node becomes the short description of the unit test.
Important note: notice that the rst line of the body text is a guard line:
if g.unitTesting:
This guard line is needed because this particular @test node is contained in the le leoNodes.py. @test nodes that
appear outside of Python source les do not need guard lines. The guard line prevents the unit testing code from
being executed when Python imports the leoNodes module; the g.unitTesting variable is True only while running
unit tests.
New in Leo 4.6: When Leo runs unit tests, Leo predenes the self variable to be the instance of the test itself,
that is an instance of unittest.TestCase. This allows you to use methods such as self.assertTrue in @test and @suite
nodes.
Note: Leo predenes the c, g, and p variables in @test and @suite nodes, just like in other scripts. Thus, the line:
c,p = g.getTestVars()
is not needed. However, it prevents pychecker warnings that c and p are undened.
23.3 Using @suite nodes
@suite nodes are nodes whose headlines start with @suite. @suite nodes allow you to create and run custom
subclasses of unittest.TestCase.
Leos test commands assume that the body of an suite node is a script that creates a suite of tests and places that
suite in g.app.scriptDict[suite]. Something like this:
if g.unitTesting:
__pychecker__ = --no-reimport # Prevents pychecker complaint.
import unittest
c,p = g.getTestVars() # Optional.
suite = unittest.makeSuite(unittest.TestCase)
<< add one or more tests (instances of unittest.TestCase) to suite >>
g.app.scriptDict[suite] = suite
Note: as in @test nodes, the guard line, if unitTesting:, is needed only if the @suite node appears in a Python
source le.
Leos test commands rst execute the script and then run suite in g.app.scriptDict.get(suite) using the standard
unittest text runner.
You can organize the script in an @suite nodes just as usual using @others, section references, etc. For example:
192 Chapter 23. Chapter 20: Unit testing with Leo
Leo, Release 4.6-b1
if g.unitTesting:
__pychecker__ = --no-reimport
import unittest
c,p = g.getTestVars() # Optional.
# children define test1,test2..., subclasses of unittest.TestCase.
@others
suite = unittest.makeSuite(unittest.TestCase)
for test in (test1,test2,test3,test4):
suite.addTest(test)
g.app.scriptDict[suite] = suite
23.4 How the unit test commands work
The run-all-unit-tests-locally and run-unit-tests-locally commands run unit tests in the process that is running Leo.
These commands can change the outline containing the unit tests.
The run-all-unit-tests and run-unit-tests commands run all tests in a separate process, so unit tests can never have
any side effects. These commands never changes the outline from which the tests were run. These commands do
the following:
1. Copy all @test, @suite and @unit-tests nodes (including their descendants) to the le
test/dynamicUnitTest.leo.
2. Run test/leoDynamicTest.py in a separate process.
leoDynamicTest.py opens dynamicUnitTest.leo with the leoBridge module. Thus, all unit tests get run
with the nullGui in effect.
After opening dynamicUnitTest.leo, leoDynamicTest.py runs all unit tests by executing the
leoTest.doTests function.
The leoTests.doTests function searches for @test and @suite nodes and processes them generally as
described above. The details are a bit different from as described, but they usually dont matter. If you
really care, see the source code for leoTests.doTests.
23.5 @button timer
The timit button in unitTest.leo allows you to apply Pythons timeit module. See
http://docs.python.org/lib/module-timeit.html. The contents of @button timer is:
leoTest.runTimerOnNode(c,p,count=100)
runTimerOnNode executes the script in the presently selected node using timit.Timer and prints the results.
23.6 @button prole
The prole button in unitTest.leo allows you to prole nodes using Pythons proler module. See
http://docs.python.org/lib/module-prole.html The contents of @button prole is:
leoTest.runProfileOnNode(p,outputPath=None) # Defaults to leo\test\profileStats.txt
runProleOnNode runs the Python proler on the script in the selected node, then reports the stats.
23.4. How the unit test commands work 193
Leo, Release 4.6-b1
194 Chapter 23. Chapter 20: Unit testing with Leo
CHAPTER
TWENTYFOUR
CHAPTER 21: IPYTHON AND LEO
Leos ipython plugin provides two-way communication (a bridge) between Leo and IPython: you can run Leo
scripts from IPython, and IPython scripts from Leo. To use this plugin, you must run Leo from a console window.
When this plugin is enabled, Leos start-ipython command starts IPython in this console.
Remarkably, Leo and IPython run simultaneously in the same process, yet their separate event loops do not
interfere with each other. Scripts run from IPython immediately change Leo, exactly as if the script were run
from Leo. Conversely, scripts run from Leo immediately affect the IPython interpreter. As a result, Leo might be
considered an IPython Notebook.
The bridge between Leo and IPython is powerful because it is simple. Indeed,
1. You can run any IPython script from Leo. On the Leo side, a single statement:
ip = IPython.ipapi.get()
assigns ip to IPythons _ip variable. The ip variable allows scripts running in Leo to do anything that an IPython
script can do.
2. You can run any Leo script from IPython. The ipython plugin injects a single object named _leo into the
IPython namespace. IPython scripts access Leos c and g objects as follows:
c,g = _leo.c, _leo.g
The c and g variables allow scripts running in IPython to do anything that a Leo script can do.
This is basically everything that is required for IPython-Leo interaction. However, you probably wont use c
and g directly, but use a series of convenience wrappers described in this document that make interactive work
painless and powerful.
24.1 Introduction
ILeo, or leo-ipython bridge, creates a two-way communication channel between Leo and IPython. The level of
integration is much deeper than conventional integration in IDEs; most notably, you are able to store and manip-
ulate data in Leo nodes, in addition to mere program code - essentially making ILeo a hierarchical spreadsheet,
albeit with non-grid view of the data. The possibilities of this are endless, and the approach can be applied in wide
range of problem domains with very little actual coding.
IPython users are accustomed to using things like %edit to produce non-trivial functions/classes (i.e. something
that they dont want to enter directly on the interactive prompt, but creating a proper script/module involves too
much overhead). In ILeo, this task consists just going to the Leo window, creating a node and writing the code
there, and pressing alt+I (push-to-ipython).
Obviously, you can save the Leo document as usual - this is a great advantage of ILeo over using %edit, you can
save your experimental scripts all at one time, without having to organize them into script/module les (before
you really want to, of course!)
195
Leo, Release 4.6-b1
24.2 Installation and startup
You need at least Leo 4.4.8, and IPython 0.8.3
The ILeo concept is still being developed actively, so if you want to get access to latest features you can get
IPython from Launchpad by installing bzr and doing:
bzr branch lp:ipython
cd ipython
python setupegg.py develop
You need to enable the ipython.py plugin in Leo:
Help -> Open LeoSettings.leo
Edit @settings>Plugins>@enabled-plugins, add/uncomment ipython.py
Alternatively, you can add @settings>@enabled-plugins with body ipython.py to your leo document.
Restart Leo. Be sure that you have the console window open (start leo.py from console, or double-click
leo.py on windows)
When using the Qt ui, add ipython argument to command line (e.g. launchLeo.py ipython).
Press alt+shift+i OR alt-x start-ipython to launch IPython in the console that started leo. You can start
entering IPython commands normally, and Leo will keep running at the same time.
Note that you can just press alt-I (push-to-ipython) - it will start IPython if it has not been previously started.
However, when you open a new leo document, you have to execute start-ipython (alt+shift+I) again to tell
IPython that the new commands should target the new document. IPython session will not be restarted, only
the leo commander object is updated in the existing session.
If you want to specify command line arguments to IPython (e.g. to choose a prole, or to start in pylab
mode), add this to your @settings: @string ipython_argv = ipython -pylab (where -pylab is the command
line argument)
24.3 Accessing IPython from Leo
24.3.1 IPython code
Just enter IPython commands on a Leo node and press alt-I to execute push-to-ipython in order to execute the script
in IPython. commands is interpreted loosely here - you can enter function and class denitions, in addition to
the things you would usually enter at IPython prompt - calculations, system commands etc.
Everything that would be legal to enter on IPython prompt is legal to execute from ILeo.
Results will be shows in Leo log window for convenience, in addition to the console.
Suppose that a node had the following contents:
1+2
print "hello"
3+4
def f(x):
return x.upper()
f(hello world)
If you press alt+I on that node, you will see the following in Leo log window (IPython tab):
196 Chapter 24. Chapter 21: IPython and Leo
Leo, Release 4.6-b1
In: 1+2
<2> 3
In: 3+4
<4> 7
In: f(hello world)
<6> HELLO WORLD
(numbers like <6> mean IPython output history indices; the actual object can be referenced with _6 as usual in
IPython).
24.3.2 Plain Python code
If the headline of the node ends with capital P, alt-I will not run the code through IPython translation mechanism
but use the direct python exec statement (in IPython user namespace) to execute the code. It wont be shown in
IPython history, and sometimes it is safer (and more efcient) to execute things as plain Python statements. Large
class denitions are good candidates for P nodes.
24.4 Accessing Leo nodes from IPython
The real fun starts when you start entering text to leo nodes, and are using that as data (input/output) for your
IPython work.
Accessing Leo nodes happens through the variable wb (short for WorkBook) that exist in the IPython user
namespace. Nodes that are directly accessible are the ones that have simple names which could also be Python
variable names; foo_1 will be accessible directly from IPython, whereas my scripts will not. If you want to
access a node with arbitrary headline, add a child node @a foo (@a stands for anchor). Then, the parent of
@a foo is accessible through wb.foo.
You can see what nodes are accessible be entering (in IPython) wb.<TAB>. Example:
[C:leo/core]|12> wb.
wb.b wb.tempfile wb.rfile wb.NewHeadline
wb.bar wb.Docs wb.strlist wb.csvr
[C:leo/core]|12> wb.tempfile
<12> <ipy_leo.LeoNode object at 0x044B6D90>
So here, we meet the LeoNode class that is your key to manipulating Leo content from IPython!
24.4.1 LeoNode
Suppose that we had a node with headline spam and body:
[12,2222+32]
we can access it from IPython (or from scripts entered into other Leo nodes!) by doing:
C:leo/core]|19> wb.spam.v
<19> [12, 2254]
v attribute stands for value, which means the node contents will be run through eval and everything you would
be able to enter into IPython prompt will be converted to objects. This mechanism can be extended far beyond
direct evaluation (see @cl denitions).
v attribute also has a setter, i.e. you can do:
24.4. Accessing Leo nodes from IPython 197
Leo, Release 4.6-b1
wb.spam.v = "mystring"
Which will result in the node spam having the following text:
mystring
What assignment to v does can be congured through generic functions (simplegeneric module, see ipy_leo.py
for examples).
Besides v, you can set the body text directly through:
wb.spam.b = "some\nstring",
headline by:
wb.spam.h = new_headline
(obviously you must access the node through wb.new_headline from that point onwards), and access the contents
as string list (IPython SList) through wb.spam.l.
If you do wb.foo.v = 12 when node named foo does not exist, the node titled foo will be automatically created
and assigned body 12.
LeoNode also supports go() that focuses the node in the Leo window, and ipush() that simulates pressing alt+I on
the node (beware of the possible recursion!).
You can access unknownAttributes by .uA property dictionary. Unknown attributes allow you to store arbitrary
(pickleable) python objects in the Leo nodes; the attributes are stored when you save the .leo document, and
recreated when you open the document again. The attributes are not visible anywhere, but can be used for domain-
specic metadata. Example:
[C:leo/core]|12> wb.spam.uA[coords] = (12,222)
[C:leo/core]|13> wb.spam.uA
<13> {coords: (12, 222)}
24.4.2 Accessing children with iteration and dict notation
Sometimes, you may want to treat a node as a database, where the nodes children represent elements in the
database. You can create a new child node for node spam, with headline foo bar like this:
wb.spam[foo bar] = "Hello"
And assign a new value for it by doing:
wb.spam[foo bar].v = "Hello again"
Note how you cant use .v when you rst create the node - i.e. the node needs to be initialized by simple assign-
ment, that will be interpreted as assignment to .v. This is a conscious design choice.
If you try to do wb.spam[bar] = Hello, ILeo will assign @k bar as the headline for the child instead, because
bar is a legal python name (and as such would be incorporated in the workbook namespace). This is done to avoid
crowding the workbook namespace with extraneous items. The item will still be accessible as wb.spam[bar]
LeoNodes are iterable, so to see the headlines of all the children of spam do:
for n in wb.spam:
print n.h
Leo, Release 4.6-b1
24.5 @cl denitions
If the rst line in the body text is of the form @cl sometext, IPython will evaluate sometext and call the result
with the rest of the body when you do wb.foo.v or press alt+I on the node. An example is in place here. Suppose
that we have dened a class (I use the term class in a non-python sense here):
def rfile(body,node):
""" @cl rfile
produces a StringIO (file like obj) of the rest of the body """
import StringIO
return StringIO.StringIO(body)
(note that node is ignored here - but it could be used to access headline, children etc.),
Now, lets say you have node spam with text:
@cl rfile
hello
world
and whatever
Now, in IPython, we can do this:
[C:leo/core]|22> f = wb.spam.v
[C:leo/core]|23> f
<23> <StringIO.StringIO instance at 0x04E7E490>
[C:leo/core]|24> f.readline()
<24> uhello\n
<25> uworld\n
<26> uand whatever
<27> u
You should declare new @cl types to make ILeo as convenient your problem domain as possible. For example, a
@cl etree could return the elementtree object for xml content.
In the preceding examples, the return value matter. That, of course, is optional. You can just use the @cl node as
a convenient syntax for run this body text through a function.
Consider this example:
def remote(body, node):
out = sshdo(body)
c = node.append()
c.b = "@nocolor\n" + out
c.h = "Command output"
(sshdo(s) is a just a trivial function implemented using paramiko, that returns the output from command run over
ssh on remote host).
After running the above node (by, say, wb.require(remote_impl) if the function is declared in a node named
remote_impl), you can create nodes that have various little sysadmin tasks (grep the logs, gather data, kick out
all the users) like this:
@cl remote
cd /var/log
ls -l
echo " --- temp ---"
24.5. @cl denitions 199
Leo, Release 4.6-b1
cd /var/tmp
ls -l
Press alt+I on the node to run it. The output will be written to Command output child node.
24.6 Special node types
24.6.1 @ipy-startup
If this node exist, the direct children of this will be pushed to IPython when ILeo is started (you press alt+shift-i).
Use it to push your own @cl denitions, import the modules you will be using elsewhere in the document, etc.
The contents of of the node itself will be ignored.
24.6.2 @ipy-results
If you press alt+I on a node that has @cl, it will be evaluated and the result will be put into this node. Otherwise,
it will just be displayed in log tab.
24.6.3 @ipy-root
You can set up a subportion of the leo document as a sandbox for your IPython work. Only the nodes under
@ipy-root will be visible through the wb variable.
Also, when you create a new node (wb.foo.v = stuff), the node foo will be created as a child of this node.
24.6.4 @a nodes
You can attach these as children of existing nodes to provide a way to access nodes with arbitrary headlines, or to
provide aliases to other nodes. If multiple @a nodes are attached as children of a node, all the names can be used
to access the same object.
24.7 Launching ILeo from IPython
Sometimes you may decide to launch Leo when an IPython session is already running. This is typically the case
when IPython is launched from/as another application (Turbogears/Django shell, Sage, etc.), or you only decide
later on that you might want to roll up some scripts or edit your variables in Leo.
Luckily, this is quite easy, if not automatic (yet) using IPythons %run command that runs python code in the
IPython process. The only special consideration is that we need to run IPython.Shell.hijack_tk() to prevent Leo
Tk mainloop from blocking IPython in %run. Here we launch an embedded Leo instance, and create a macro
embleo for later use (so that we dont have to repeat these steps):
IPython 0.8.3.bzr.r57 [on Py 2.5.1]
[C:opt/Console2]|2> import IPython.Shell
[C:opt/Console2]|3> IPython.Shell.hijack_tk()
[C:opt/Console2]|4> cd c:/leo.repo/trunk
[c:leo/leo.repo/trunk]|5> %run launchLeo.py
reading settings in C:\leo\leo\config\leoSettings.leo
... Leo is starting at this point, but IPython prompt returns ...
[c:leo/leo.repo/trunk]|6> macro embleo 2-5
Leo, Release 4.6-b1
[c:leo/leo.repo/trunk]|7> store embleo
Stored embleo (Macro)
Now, in Leo, you only need to press Alt+Shift+I (launch-ipython) to actually make the document visible in
IPython. Despite the name, launch-ipython will not create a new instance of IPython; if an IPython session
already exists, it will be automatically used by ILeo.
24.8 Declaring custom push-to-ipython handlers
Sometimes, you might want to congure what alt+I on a node does. You can do that by creating your own push
function and expose it using ipy_leo.expose_ileo_push(f, priority). The function should check whether the node
should by handled by the function and raise IPython.ipapi.TryNext if it will not do the handling, giving the next
function in the chain a chance to see whether it should handle the push.
This example would print an uppercase version of node body if the node headline ends with U (yes, this is
completely useless!):
def push_upcase(node):
if not node.h.endswith(U):
raise TryNext
print node.b.upper()
ipy_leo.expose_ileo_push(push_upcase, 12)
(the priority should be between 0-100, with 0 being the highest (rst one to try) - typically, you dont need to care
about it and can usually omit the argument altogether)
24.9 Example code snippets
Get list of all headlines of all the nodes in leo:
[node.h for node in wb]
Create node with headline baz, empty body:
wb.baz
Create 10 child nodes for baz, where i is headline and Hello + i is body:
for i in range(10):
wb.baz[i] = Hello %d % i
Create 5 child nodes for the current node (note the use of special _p variable, which means current node) and
moves focus to node number 5:
for i in range(10):
_p[i] = hello %d % d
_p[5].go()
Sort contents of a node in alphabetical order (after pushing this to IPython, you can sort a node foo in-place by
doing sort_node(wb.foo)):
24.8. Declaring custom push-to-ipython handlers 201
Leo, Release 4.6-b1
def sort_node(n):
lines = n.l
lines.sort()
n.l = lines
24.10 Example use case: pylab
If you install matplotlib and numpy, you can use ILeo to interactively edit and view your data. This is convenient
for storing potentially valuable information in Leo document, and yields an interactive system that is comparable
in convenience to various commercial mathematical packages (at least if you compare it agains plain IPython, that
forgets the data on exit unless explicitly saved to data les or %store:d).
24.10.1 Startup
Its probably safest to rely on TkAgg backend, to avoid two event loops running in the same process. TkAgg is
the default, so the only thing you need to do is to install numpy and matplotlib:
easy_install numpy
easy_install matplotlib
Finally, you need to start up IPython with -pylab option. You can accomplish this by having the following under
some @settings node:
@string ipython_argv = ipython -pylab
Then, you just need to press alt+I to launch IPython.
24.10.2 Usage
The simplest use case is probably pushing an existing array to Leo for editing. Lets generate a simple array and
edit it:
[c:/ipython]|51> a = arange(12).reshape(3,4)
[c:/ipython]|52> a
array([[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]])
[c:/ipython]|53> %lee a
This (the magic command %lee, or leo edit) will open variable a for editing in Leo, in a convenient pretty-
printed format. You can press alt+I on the node to push it back to IPython.
If you want to store the variable in a node with a different name (myarr), you can do:
[c:/ipython]|54> wb.myarr.v = a
Then, you can always get the value of this array with wb.myarr.v. E.g. you could have a node that plots the array,
with content:
# press alt+i here to plot testarr
plot(wb.myarr.v)
And, as per instructions, pressing alt+I will launch a new Tk window with the plotted representation of the array!
Leo, Release 4.6-b1
24.11 Magic functions
24.11.1 %mb
Execute leo minibuffer command. Tab completion works. Example:
mb open-outline
24.11.2 %lee
Stands for LEo Edit. Allows you to open le(s), and even objects in Leo for editing. Examples:
lee
*
.txt
Opens all txt les in @auto nodes
lee MyMacro
Opens the macro MyMacro for editing. Press alt-I to push the edited macro back to IPython.
s = hello word
lee s
Opens the variable s for editing. Press alt+I to push the new value to IPython.
lee hist
Opens IPython interactive history (both input and output) in Leo.
24.12 Acknowledgements and history
This idea got started when I (Ville M. Vainio) saw this post by Edward Ream (the author of Leo) on IPython
developer mailing list:
http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html
I was using FreeMind as mind mapping software, and so I had an immediate use case for Leo (which, incidentally,
is superior to FreeMind as mind mapper). The wheels started rolling, I got obsessed with the power of this
concept (everything clicked together), and Edwards excitement paralleled mine. Everything was mind-bogglingly
easy/trivial, something that is typical of all promising technologies.
Discussions on SourceForge show how the goal of close cooperation between Leo and IPython went from vague
dream to completed reality over the span of about 10 days.
24.11. Magic functions 203
Leo, Release 4.6-b1
CHAPTER
TWENTYFIVE
CHAPTER 22: USING VIM BINDINGS
WITH LEO
This chapter describes Leos vim-like bindings, including how to install them.
25.1 Vim bindings
25.1.1 Installing vim bindings
Place a copy of the @keys Vim bindings node and its sub-nodes, located in the leoSettings.leo le, under the
@settings node in the myLeoSettings.leo le
The same procedure is performed to update to a new version.
Note: Place any local customized key bindings in a separate @keys My Vi node in the myLeoSettings.leo le
to prevent them from being overwritten when updating to a new version.
25.1.2 General commands
The following commands are always available.
State change commands:
i Change state to insert from command state
Esc Change state to command from insert state
Ctrl-[ Same as ESC
Save/Exit/Quite commands:
:e Revert
:w<return> Save .leo file
:wq<return> Save .leo file and quit Leo
:q<return> Quit Leo (Leo will prompt if file not saved)
ZZ Save leo file and exit
Undo/Redo commands:
u Undo previous command
Ctrl-r Redo previous command
Search options:
Ctrl-/ Prompt for option to change
Options:
205
Leo, Release 4.6-b1
a Search all nodes (also <cr> key)
h Toggle headline search
b Toggle body search
m Toggle marking of nodes (specify sub-option)
f Toggle marking of nodes with found text
c Toggle marking of nodes with changed text
(only supported with Alt-/, Alt-p)
r Toggle regex matches
(/ key turns off regex. n key uses regex if turned on)
Note: Whether a search is limited to nodes body or the nodes sub-outline
is determined by which pane has focus when search text specified.
(See "Find text commands:" sub-sections in Outline/Body Pane sections)
Miscellaneous commands:
Tab Toggle focus between Outline and Body pane
= Simulate double-click on current nodes icon box
Alt-G Go to specified line number (relative to derived file)
Ctrl-: Enter Leos command line
25.1.3 Body pane commands
Move cursor commands:
h Go back 1 character
LtArrow Mapped to "h" for convenience
j Go down 1 line
DnArrow Mapped to "j" for convenience
k Go up 1 line
UpArrow Mapped to "k" for convenience
l Go forward 1 character
RtArrow Mapped to "l" for convenience
w Go to beginning of next word
W Mapped to "w" until "stop after blank characters" supported
b Go to beginning of current/previous word
B Mapped to "b" until "stop at blank character" supported
e Go to end of current/next word
E Mapped to "e" until "stop at blank character" supported
Note: Move by word commands stop at non-alpha characters
| Goto beginning of current line
^ Go to 1st non-blank character on current line
$ Goto end of current line
% Go to matching bracket
( Go to beginning of current sentence
) Go to beginning of next sentence
{ Go to beginning of current paragraph
} Go to beginning of next paragraph
gg Go to the first line (Cursor at column 1)
G Go to the last line (Cursor at column 1)
Mark commands:
206 Chapter 25. Chapter 22: Using Vim Bindings with Leo
Leo, Release 4.6-b1
m<label> Assign cursor location to a single character label
<label> Go to location associated with label
Note: Only character count is tracked. Any inserts or deletes will change mark.
Marks are not node specific; <label> will go to location in current node.
Select commands:
Ctrl-v Toggle text select mode (Vims "visual" mode)
V Mapped to Ctrl-v for convenience (Should toggle line select)
Insert/substitute commands:
a Insert at cursor
i Mapped to "a" until "cursor on a character" supported
A Insert at end of line
I Insert at first non-space
o Open new line below current line
O Open new line above current line
R Overwrite text
s Substitute character (Delete character, enter insert state)
S Substitute line (Delete line, enter insert state)
Change commands:
C Change to end of line
cc Change all of current line
cw Change to end of word
cb Change to beginning of word
c) Delete to end of sentence
c( Delete to beginning of sentence
c} Delete to end of paragraph
c{ Delete to beginning of paragraph
c% Change from current bracket type its matching bracket type
ct<char> Selects forward to <char> (follow with i to change selection)
cT<char> Selects backward to <char> (follow with i to change selection)
c<cr> Change selected text
Delete commands:
x Delete next character
delete Delete next character
D Delete to the end of the current line
dd Delete current line
dw Delete to end of word
db Delete to beginning of word
d) Delete to end of sentence
d( Delete to beginning of sentence
d} Delete to end of paragraph
d{ Delete to start of paragraph
d% Delete from current bracket type to its apposing bracket
dt<ch> Delete to character (not limited to current line)
d<cr> Delete selected text
J Join next line to end of current line (deletes carriage return)
Yank text commands:
Y Yank to end of line
yy Yank line
25.1. Vim bindings 207
Leo, Release 4.6-b1
yw Yank to beginning of next word
yb Yank to beginning of current word
y) Yank to end of sentence
y( Yank to beginning of sentence
y} Yank to end of paragraph
y{ Yank to beginning of paragraph
y% Yank from current bracket type to its opposing bracket
yt<char> Select forward to <char> (use y<cr> to yank selection)
yT<char> Select backward to <char> (use y<cr> to yank selection)
y<cr> Yank selected text (Vim uses y in visual mode)
Find character commands:
f Find next occurrence of user specified character
F Find previous occurrence of user specified character
Find text commands:
/ Search forward within current nodes body text
? Search backward within current nodes body text
n Find next (same scope, same direction)
N Find next (same scope, other direction)
Note: See "Search options" in General Commands section to change options.
Replace [and nd next] commands:
Commands using Paste buffer (clipboard)
P Paste text before cursor.
p Mapped to "P" until character based cursor supported.
Ctrl-p Paste then find next match
Note: Use pn instead of Ctrl-p in headlines (Leo limitation)
Command will continue to paste when match no longer found.
Commands prompting for replace string
Note: Scope and direction taken from last use of /,? or Ctrl-/(scope only)
Alt-/ Prompt for search & replace string
Alt-p Replace then search (use after Alt-/)
Note: Works in headlines and body panes.
Doesnt paste unless last search found a match.
Indent/Unindent line commands:
>> Indent the current line
>) Indent to the end of sentence
>( Indent to the beginning of sentence
>} Indent to the end of paragraph
>{ Indent to the beginning of paragraph
>g Indent to the start of buffer
>G Indent to the end of buffer
<> Unindent the current line
<) Unindent to the end of sentence
<( Unindent to the beginning of sentence
<} Unindent to the end of paragraph
<{ Unindent to the beginning of paragraph
<g Unindent to the start of buffer
<G Unindent to the end of buffer
Scroll commands:
Leo, Release 4.6-b1
Ctrl-b Scroll text up by panes height
Ctrl-f Scroll text down by panes height
Ctrl-y Mapped to Ctrl-b until scroll up one line is supported
Ctrl-e Mapped to Ctrl-f until scroll down one line is supported
Ctrl-u Mapped to Ctrl-b until scroll up half a pane height is supported
Ctrl-d Mapped to Ctrl-f until scroll down half a pane height is supported
Window commands:
Ctrl-w s Open another view into current nodes body (Vim: Split window)
Ctrl-w n Mapped to "Ctrl-w s" (Vim: New buffer in split window)
Ctrl-w w Switch to next view (Vim: Go to up/left window w/wrapping)
Ctrl-w p Mapped to "Ctrl-w w" (Vim: Cycle through windows)
Ctrl-w k Mapped to "Ctrl-w w" (Vim: Go to window above current window)
Ctrl-w j Mapped to "Ctrl-w w" (Vim: Go to window below current window)
Ctrl-w c Close current view in body pane (Vim: Close current window)
Ctrl-w q Mapped to "Ctrl-w c" (Vim: Quit current window)
Node commands:
Go to another node while focus remains in the body pane.
Ctrl-j Go to next visible node
Ctrl-k Go to previous visible node
Ctrl-h Hide sub-nodes or, if hidden, go up 1 level
Ctrl-l Display sub-nodes or, if displayed, go down 1 level
Ctrl-DnArrow Mapped to "Ctrl-j" for convenience
Ctrl-UpArrow Mapped to "Ctrl-k" for convenience
Ctrl-LtArrow Mapped to "Ctrl-h" for convenience
Ctrl-RtArrow Mapped to "Ctrl-l" for convenience
25.1.4 Outline commands
The following commands are supported when in a headlines command mode.
State change commands:
Ctrl-i Change state to command from grayed state
return Change state to command from insert state
Ctrl-] Change state to grayed from command state
Cursor movement commands:
h Go to previous character
LtArrow Mapped to h for convenience
l Go to next character
RtArrow Mapped to "l" for convenience
w Go to beginning of next word
W Mapped to "w" until "stop after blank characters" supported
b Go to beginning of current/previous word
B Mapped to "b" until "stop at blank character" supported
e Go to end of current/next word
E Mapped to "e" until "stop at blank character" supported
Note: Move by word commands stop at non-alpha characters
| Go to beginning of line
^ Go to beginning of line
$ Go to end of line
Leo, Release 4.6-b1
% Go to matching bracket
Edit commands:
x Delete next character
delete Delete next character
dd kill-line
s Select current character
v Toggle text select mode (issue cursor movement commands)
y<return> Yank selected text
C Select to end of line (follow with i to change text)
cc Delete line (follow with i to change text)
D Select to end of line (follow with x to delete text)
dd Delete line
Y Select to end of line (follow with y<return> to yank text)
yy Select line (follow with y<return> to yank text)
Find character commands:
f Find next occurrence of user specified character
F Find previous occurrence of user specified character
Find text commands:
/ Search forward within current node and its subnodes
n Find next (same scope, same direction)
N Find next (same scope, other direction)
Note: See "Search options" section above to change options using Ctrl-/
Replace [and nd next] commands:
Commands that use Paste buffer (clipboard)
Note: Paste-then-search command not possible in headlines (Use pn)
P Paste text before cursor.
p Mapped to "P" until character based cursor supported.
Commands that prompt for the replace string
Alt-/ Prompt for search & replace string
Alt-p Replace then search (use after Alt-/)
Note: Works in headlines and body panes.
Doesnt paste unless last search found a match.
Node edit commands:
o Insert node after current node
Ctrl-x Delete current node
Ctrl-c Yank current node
Ctrl-v Paste current node
Node goto commands:
Leo, Release 4.6-b1
G Go to the outlines last node
gg Go to the outlines first node
Ctrl-j Go to next visible node
Ctrl-k Go to previous visible node
Ctrl-h Hide sub-nodes or, if hidden, go up 1 level
Ctrl-l Display sub-nodes or, if displayed, go down 1 level
j Mapped to "Ctrl-j" for convenience
DnArrow Mapped to "Ctrl-j" for convenience
k Mapped to "Ctrl-k" for convenience
UpArrow Mapped to "Ctrl-k" for convenience
Ctrl-DnArrow Mapped to "Ctrl-j" for convenience
Ctrl-UpArrow Mapped to "Ctrl-k" for convenience
Ctrl-LtArrow Mapped to "Ctrl-h" for convenience
Ctrl-RtArrow Mapped to "Ctrl-l" for convenience
Node move commands:
Shift-Ctrl-k Move node down
Shift-Ctrl-h Move node left
Shift-Ctrl-l Move node right
Shift-Ctrl-j Move node up
Shift-Ctrl-DnArrow Mapped to "Shift-Ctrl-k" for convenience
Shift-Ctrl-LtArrow Mapped to "Shift-Ctrl-h" for convenience
Shift-Ctrl-RtArrow Mapped to "Shift-Ctrl-l" for convenience
Shift-Ctrl-UpArrow Mapped to "Shift-Ctrl-j" for convenience
Node mark commands:
m Toggle node mark
Ctrl-m Go to next marked node
Alt-m Clear all marked nodes
Node clone commands:
t Clone the current node (transclude)
Ctrl-t Go to next clone of current node
Outline scroll commands:
Ctrl-y Scroll outline up one line
Ctrl-e scroll outline down one line
Ctrl-u Mapped to Ctrl-y until scroll up by half a pane supported
Ctrl-d Mapped to Ctrl-e until scroll down by half a pane supported
Ctrl-b Mapped to Ctrl-y until scroll up by panes height supported
Ctrl-f Mapped to Ctrl-e until scroll down by panes height supported
25.1.5 Commands not supported
Notable missing editing commands:
t<char> Move cursor to character before specified character
r Replace a single character with a single character
0 Go to 1st column in current line (Use | instead)
bksp Move one character to the left
~ Toggle characters case
Leo, Release 4.6-b1
. Repeat last editing command
; Repeat last cursor movement command
<n><cmd> Perform command n number of times
<cmd><n><object> Perform the command on the nth or up to the nth object
Notable missing body pane commands:
<num>G Go to specified line number
z<movement> Slide buffer to put current line at top/middle/bottom of pane
<command> Go to line of last edit, jump, ...
<command> Go to character of last edit, jump, ...
25.2 Avoiding changes to tag les
If you use the open-with plugin to open node text in Vim and your Vims tag le refers to derived les then
there is a risk that a derived le that is initially displayed via the tag command in Vim is accidentally edited
and saved from the external Vim editor while your Leo session still contains the derived les original text that
may later recreate the original derived le during a Leo save operation (overwriting the changes saved from the
Vim editor).
To prevent this problem, modications to derived les can be avoided by using Vims modeline feature to disable
editing of derived les.
Vims modeline feature scans each loaded buffer for text at the top or bottom of the le containing vim:
followed by a series of Vim options. The text is usually embedded within a comment. The following example
prevents modications to a buffer in a Python le:
# vim:noma (A space is required between the # and "vim:noma")
If this line is placed in a separate Leo node at the top or bottom of the list of nodes under a derived le node (ex:
@thin) then any derived le saved and then later loaded into Vim will, by default, not be modiable. If a derived
le does need to be edited then modications can be re-enabled on a le-by-le basis by issuing Vims :ma
command while viewing the derived le.
The number of lines that Vim checks at the top and bottom of the buffer is congurable. The following Vim
command must be placed in the vimrc le to allow for Leos trailing sentinel lines:
set modelines=8
Issue the :help modeline command within Vim for the more information about modelines.
CHAPTER
TWENTYSIX
CHAPTER 23: ELIMINATING
SENTINEL LINES WITH @SHADOW
This chapter describes an important new feature that debuted in Leo 4.5 b2: @shadow trees. These trees combine
the benets of @auto, @thin, @le and @nosent trees:
The (public) les created by @shadow trees contain no sentinels, but
Leo is able to update @shadow trees in the Leo outline based on changes made to public les outside of
Leo.
@shadow trees are often useful for studying or editing source les from projects that dont use Leo. In such
situations, it is convenient to import the @shadow tree from the (public) sources. As discussed below, Leo can
import @shadow trees automatically, using the same algorithms used by @auto trees.
The crucial ideas and algorithms underlying @shadow trees are the invention of Bernhard Mulder.
26.1 Overview
Using @shadow trees is the best choice when you want to have the full power of Leos outlines, but wish to retain
the source les in their original format, without Leo sentinels (markup) in comments in the source le.
Leos @le and @thin trees create derived les containing comments called sentinels. These sentinel lines allow
Leo to recreate the outlines structure of @le and @thin trees. Alas, many people and organizations nd these
added sentinel lines unacceptable. @nosent nodes create derived les without sentinels, but at a cost: Leo can not
update @nosent trees when the corresponding derived le is changed outside of Leo.
@shadow trees provide a way around this dilemma. When Leo saves an @shadow tree, it saves two copies of
the tree: a public le without sentinels, and a private le containing sentinels. Using Bernhard Mulders brilliant
update algorithm, Leo is able to update @shadow trees in the Leo outline based solely on changes to public les.
Leo writes private les to a subfolder of the folder containing the public le: by default this folder is called
.leo_shadow. You can change the name of this folder using the @string shadow_subdir setting. Note that private
les need not be known to source code control systems such as bzr or cvs.
Thats almost all there is to it. The following sections discuss important details:
How to create @shadow trees.
How @shadow works.
Why the update algorithm is sound.
213
Leo, Release 4.6-b1
26.2 Creating @shadow trees
The rst step in creating an @shadow tree is to create a node whose headline is @shadow <lename>. This is
always safe, even if <lename> already exists: Leo writes the @shadow tree to the public and private les only if
the @shadow tree contains a signicant amount of information. An @shadow tree contains a signicant amount
of information if it has children or if the @shadow node node contains more than 10 characters, excluding Leo
directives.
Thus, you can create an @shadow node and save your outline, regardless of whether the original le exists. The
next time Leo reads the @shadow node, Leo will create the entire @shadow tree using the same logic as for
@auto trees. You can cause Leo to read the @shadow node in two ways: 1) by closing and reloading the Leo
outline or 2) by selecting the @shadow node and executing the File:Read/Write:Read @shadow Node command.
Important: Leo imports the private le into the @shadow tree only if a) the public le exists and b) the private le
does not exist. Thus, Leo will import code into each @shadow node at most once. After the rst import, updates
are made using the update algorithm.
Note: just as for @auto, Leo will never read (import) or write an @shadow tree if the @shadow node is under the
inuence of an @ignore directive.
26.3 What the update algorithm does
Suppose our @shadow tree is @shadow a.py. When Leo writes this tree it creates a public le, a.py, and a private
le, .leo_shadow/xa.p (or just xa.p for short). Public les might can committed to a source code control system
such as cvs or bzr. Private les should not be known to cvs or bzr.
Now suppose a.py has been changed outside of Leo, say as the result of a bzr merge. The corresponding private
le, xa.p, will not have been changed. (Private les should never change outside of Leo.
When Leo reads the new (and possibly updated) public le it does the following:
1. Recreates the old public le by removing sentinels from the (unchanged!) private le.
2. Creates a set of diffs between the old and new public les.
3. Uses the diffs to create a new version of the private le.
4. Creates the @shadow tree using the new private le.
Important: The update algorithm never changes sentinels. This means that the update algorithm never inserts
or deletes nodes. The user is responsible for creating nodes to hold new lines, or for deleting nodes that become
empty as the result of deleting lines.
Step 3 is the clever part. To see all the details of how the algorithm works, please study the
x.propagate_changed_lines method in leoShadow.py. This code is heavily commented.
26.4 Aha: boundary cases dont matter
There is one boundary case that the update algorithm can not resolve. If a line is inserted at the boundary between
nodes, the updated algorithm can not determine whether the line should be inserted at the end of one node of the
start of the next node.
Happily, the inability of the update algorithm to distinguish between these two cases does not matter, for three
very important reasons:
1. No matter which choice is made, the public le that results is the same. The choice doesnt matter, so the
update algorithm is completely and absolutely safe.
214 Chapter 26. Chapter 23: Eliminating sentinel lines with @shadow
Leo, Release 4.6-b1
2. Leo reports any nodes that were changed as the result of the update algorithm. In essence, these reports are
exactly the same as the reports Leo makes when @le or @thin trees were changed as the result of changes
made externally to Leo. It is as easy for the user to review changes to @shadow trees as it is to review
changes to @thin or @le trees.
3. Suppose the user moves a line from the end of one node to the beginning of the following node, or vice
versa. Once the user saves the le, the private le records the location of the moved line. The next time the
user reads the @shadow le, the line will not be subject to the update algorithm because the line has not
been changed externally. The location of the line (on the boundary) will be completely determined and it
will never need to be moved across the boundary.
Understanding these three reasons nally convinced me that @shadow could be made to work reliably.
26.4. Aha: boundary cases dont matter 215
Leo, Release 4.6-b1
216 Chapter 26. Chapter 23: Eliminating sentinel lines with @shadow
CHAPTER
TWENTYSEVEN
APPENDICES
27.1 Bugs
The following bugs can not be xed:
1. The Untangle command has no way of updating a section whose name has been changed in the derived
le.
Because of the @unit directive, there is not even a way to issue a meaningful warning.
2. The Tangle command treats @c like @code in CWEB mode.
I recommend changing @c to @< c @>= throughout your CWEB sources and adding a reference to @< c
@> in all roots of CWEB les.
27.2 Errors while tangling
The following error messages may be generated by the Tangle commands.
Can not re-open temp file A le error occurred while trying to reopen the temporary le used during
tangling.
Can not rename temporary file name A le error occurred while trying to change the name of the
temporary le used during tangling.
@code expects the header: [text of header] to contain a section name An
@code directive appeared in body text whose header does not contain a section name.
@directive not valid here An @directive was seen somewhere other than the start of a line.
Halting Tangle: too many errors Tangle detected more than 20 errors.
Invalid recursive reference of << section name >> A section was dened in terms of it-
self, either directly or indirectly. The trace shows the chain of section denitions that resulted in the illegal
denition.
This message is followed by a walkback of the section names that recursively reference the section.
The walkback looks like this:
called from << section name >>
called from << section name >>
...
Multiple parts not allowed for << section name >> Sections can be dened in several parts
in two ways:
1. Using << section name >>= in several places with the same section name.
217
Leo, Release 4.6-b1
2. Using several @code directives within the same body text.
As a precaution against mistakenly dening a section in more than one place, it is invalid to use @code
in different nodes to dene multiple parts for the same section. In particular, this error may arise when
using cloned nodes. This error may always be eliminated by using << section name >>= instead of
@code.
No file written because of errors Tangle did not write a le because errors were found.
Run on comment A C-language comment was not properly terminated.
Run on file name in @root directive The le name in an @root directive was not terminated with
the proper delimiter.
Run on section name A section name was not properly terminated before the end of the line in which it
started.
Run on string A C-language string or character constant was not properly terminated.
Section definition not valid here. Something that looks like a section denition was seen in the
middle of a line.
Sections nested too deeply A section was dened using more than 100 levels of section denitions
(!) You could easily create an outline containing every computer program ever written in less than 50 levels.
The outline contains no roots The selected outline contained no @root directive.
Undefined section: <<< section name >>> A reference to an undened section was encoun-
tered.
Unexpected @directive while putting code Tangle outputs 2-character WEB control code in a
comment. This message is given if we nd such comments in a code denition.
Warning: possible duplicate definition of: <<< section name >>> (The text of
the duplicate denition follows.) The section may have been dened in more than one place.
Warning: <<< section name >>> has been defined but not used The indicated section
appears in the outline but is never referenced.
27.3 Errors while untangling
The following error messages may be generated by the Untangle commands.
Incompatible denitions of <<< section name >>> Two expansions of << section name >> were differ-
ent in the derived le. This typically arises when the programmer changes one of the expansions but not the
other.
Missing root part No end sentinel line was found for a part of the expansion of the code in the @root node.
This is likely the result of adding, deleting or altering a sentinel line.
Missing root section No end sentinel line was found for the expansion of the code in the @root node.
This is likely the result of adding, deleting or altering a sentinel line.
Missing sentinel line for <<< section name >>> The end sentinel name for << section
name >> was expected but not found. This is likely the result of adding, deleting or altering a sentinel
line.
Unterminated section: <<< section name >>> The end of the le was reached before encoun-
tering the end sentinel line for << section name >>. This is likely the result of adding, deleting or
altering a sentinel line.
218 Chapter 27. Appendices
Leo, Release 4.6-b1
27.4 Errors while reading @le nodes
The following are all serious errors, meaning that the data in a derived le has been corrupted:
Bad @+leosentinel in <filename>
Bad @delims
Bad attribute field in @+node
Bad child index in @+node
File may have damaged sentinels!
Ignoring <sentinel kind> sentinel. Expecting <sentinel kind>
Ignoring unexpected @+leo sentinel
Missing <sentinel kind> sentinel
Missing @file in root @node sentinel
Outline corrupted: different nodes have same clone index!
Replacing body text of orphan <node name>
Unexpected end of file. Expecting <sentinel kind> sentinel
Unknown sentinel: <sentinel line>
You should restore the information from a backup .leo le using the Read Outline Only commands, fol-
lowed by a Write @file Nodes command
27.5 Errors while writing @le nodes
Errors while writing @file nodes are harmless. No information is lost because all information is written to the
.leo le rather than the derived le.
bad @delims directive A node contains an ill-formed @delims directive.
@ignore node <headline> The body text of headline contains an @ignore directive.
orphan node: <headline> The node is referenced by no ancestor node, and no @others directive
applies to it.
@others already expanded in: <headline> The node contains more than one @others direc-
tive.
Rename failed: no file created! (file may be read-only) Leos Save command
writes derived les to a temporary le, and replaces the derived le by the temporary les only if the two
les are different. A problem with the le system prevented the temporary le from being renamed.
Path does not exist: <filename>
undefined section: <section name> referenced from: <headline> The node given
by headline contains a reference to section name but no section denition node for section name exists
in the descendants of headline.
27.6 Format of .leo les
This technical information may be of use to those wanting to process Leo les with special-purpose lters. Leos
uses XML for its le format. The following sections describe this format in detail. Important: The actual
read/write code in leoFileCommands.py is the authoritative guide. When in doubt about what Leo actually writes,
look at an actual .leo le in another editor.
Here are the elements that may appear in Leo les. These elements must appear in this order.
<?xml> Leo les start with the following line:
27.4. Errors while reading @le nodes 219
Leo, Release 4.6-b1
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet> An xml-stylesheet line is option. For example:
<?xml-stylesheet ekr_stylesheet?>
<leo_file> The <leo_file> element opens an element that contains the entire le. </leo_file> ends
the le.
<leo_header> The <leo_header> element species version information and other information that affects
how Leo parses the le. For example:
<leo_header file_format="2" tnodes="0" max_tnode_index="5725" clone_windows="0"/>
The file_format attribute gives the major format number. It is 2 for all 4.x versions of Leo. The
tnodes and clone_windows attributes are no longer used. The max_tnode_index attribute is the
largest tnode index.
<globals> The globals element species information relating to the entire le. For example:
<globals body_outline_ratio="0.50">
<global_window_position top="27" left="27" height="472" width="571"/>
<global_log_window_position top="183" left="446" height="397" width="534"/>
</globals>
The body_outline_ratio attribute species the ratio of the height of the body pane to the
total height of the Leo window. It initializes the position of the splitter separating the outline pane
from the body pane.
The global_window_position and global_log_window_position elements specify
the position of the Leo window and Log window in global coordinates:
<preferences> This element is vestigial. Leo ignores the <preferences> element when reading. Leo
writes an empty <preferences> element.
<find_panel_settings> This element is vestigial. Leo ignores the <find_panel_settings> ele-
ment when reading. Leo writes an empty <find_panel_settings> element.
<clone_windows> This element is vestigial. Leo ignores the <clone_windows> element when reading.
Leo no longer writes <clone_windows> elements.
<vnodes> A single <vnodes> element contains nested <v> elements. <v> elements correspond to vnodes.
The nesting of <v> elements indicates outline structure in the obvious way.
<v> The <v> element represents a single vnode and has the following form:
<v...><vh>sss</vh> (zero or more nested v elements) </v>
The <vh> element species the headline text. sss is the headline text encoded with the usual XML
escapes. As shown above, a <v> element may contain nested <v> elements. This nesting indicates outline
structure in the obvious way. Zero or more of the following attributes may appear in <v> elements:
t=name.timestamp.n
a="xxx"
The t="Tnnn" attribute species the tnode associated with this vnode. The a="xxx" attribute species
vnode attributes. The xxx denotes one or more upper-case letters whose meanings are as follows:
C The vnode is a clone. (Not used in 4.x)
E The vnode is expanded so its children are visible.
M The vnode is marked.
T The vnode is the top visible node.
V The vnode is the current vnode.
Leo, Release 4.6-b1
For example, a="EM" species that the vnode is expanded and is marked.
New in 4.0:
<v> elements corresponding to @file nodes now contain tnodeList attributes. The tnodeList
attribute allows Leo to recreate the order in which nodes should appear in the outline. The
tnodeList attribute is a list of gnxs: global node indices. See Format of derived files
(4.x) for the format of gnxs.
Plugins and scripts may add attributes to <v> and <t> elements. See Chapter 13: Writing plugins for
details.
<tnodes> A single <tnodes> element contains a non-nested list of <t> elements.
<t> The <t> element represents a single tnode and has this form:
<t tx="Tnnn"><tb>sss</tb></t>
The tx attribute is required. The t attribute of <v> elements refer to this tx attribute. The <tb> element
species the body text. sss is the headline text encoded with the usual XML escapes.
New in 4.0: Plugins and scripts may add attributes to <v> and <t> elements. See Chapter 13: Writing
plugins for details.
27.7 Format of derived les
This section describe the format of derived les. Leos sentinel lines are comments, and this section describes
those comments.
The format of derived les produced by Leo 4.0 and later meets the following goals:
The minimum of sentinels needed to properly recreate the outline.
A robust way of telling whether newlines belong to sentinels or not. Prior to Leo 4.0, deleting blank lines
before and after sentinel lines could corrupt the outline structure of the derived le.
A minimum of intrusion and ugliness.
New in Leo 4.2: Files derived from@thin use gnxs in @+node and @-node sentinels. Such gnxs permanently
and uniquely identify nodes. Gnxs have the form:
id.yyyymmddhhmmss
id.yyyymmddhhmmss.n
The second form is used if two gnxs would otherwise be identical.
id is a string unique to a developer, e.g., a cvs id.
yyyymmddhhmmss is the nodes creation date.
n is an integer.
Here are the sentinels used by Leo, in alphabetical order. Unless otherwise noted, the documentation applies to all
versions of Leo. In the following discussion, gnx denotes a gnx as described above.
@<< A sentinel of the form @<<section_name>> represents a section reference.
If the reference does not end the line, the sentinel line ending the expansion is followed by the remainder of
the reference line. This allows the Read code to recreate the reference line exactly.
@@ The @@ sentinel represents any line starting with @ in body text except @
*
whitespace
*
, @doc
and @others. Examples:
27.7. Format of derived les 221
Leo, Release 4.6-b1
@@nocolor
@@pagewidth 80
@@tabwidth 4
@@code
@afterref (Leo 4.0 and later) Marks non-whitespace text appearing after a section references.
@+all (Leo 4.0 and later) Marks the start of text generated by the @all directive.
@-all (Leo 4.0 and later) Marks the end of text generated by the @all directive.
@at and @doc The @+doc and @-doc sentinels delimit doc parts within a node that starts with @doc. These
sentinels are nested within @body directives. Similarly, @+at and @-at sentinels delimit doc parts within
a node that start with @ whitespace. We use the following trailing whitespace convention to determine
where putDocPart has inserted line breaks:
A line in a doc part is followed by an inserted newline
if and only if the newline if preceded by whitespace.
To make this convention work, Leos write code deletes the trailing whitespace of all lines that are followed
by a real newline.
Leo 4.0 and later: The @+doc and @+at sentinels now contain the whitespace that follows the corre-
sponding @doc or @ directives.
@+body (Leo 3.x only) Marks the start of body text.
@-body (Leo 3.x only) Marks the end of body text.
@delims The @delims sentinel inserts @@delims sentinels into the derived le. The new delimiter strings
continue in effect until the next @@delims sentinel in the derived le or until the end of the derived le.
Adding, deleting or changing @@delim sentinels will destroy Leos ability to read the derived le. Mistakes
in using the @delims directives have no effect on Leo, though such mistakes will thoroughly mess up a
derived le as far as compilers, HTML renderers, etc. are concerned.
@+leo Marks the start of any derived le. This sentinel has the form:
<opening_delim>@leo<closing_delim>
The read code uses single-line comments if <closing_delim> is empty. The write code generates
single-line comments if possible.
New in Leo 4.0: The @+leo sentinel contains other information following @leo. For example:
<opening_delim>@leo-ver=4-thin<closing_delim>
@-leo Marks the end of the Leo le. Nothing but whitespace should follow this directive.
@+middle (Leo 4.0 and later) Marks the start of intermediate nodes between the node that references a section
and the node that denes the section. Typically no such sentinels are needed: most sections are dened in a
direct child of the referencing node.
@-middle (Leo 4.0 and later) Marks the end of intermediate nodes between the node that references a section
and the node that denes the section.
@+node and @-node Mark the start and end of a node.
Leo 4.2 and later:: @+node and @-node sentinels use gnxs as described above:
@+node:gnx:<headline>
@-node:gnx:<headline>
Leo generates these sentinels only for nodes containing body text. Leo no longer generates other @+node
sentinels to indicate outline structure. As a result, there is no longer any need for @+body sentinels.
Before Leo 4.2:: @+node and @-node sentinels used child indices, and status elds as described below:
Leo, Release 4.6-b1
@+node:<child_index>:<status_fields>:<headline>
@-node::<child_index>:<status_fields>:<headline>
<child_index> is a number from1 to n indicating the index of the node in the list of its parents children.
<status_field> is the cloneIndex eld of the form: C=nnn, where nnn is an immutable clone index.
<headline> contains headline text, not reference text.
@nl (Leo 4.0 and later) Adds a newline to the body text.
@nonl (Leo 4.0 and later) Suppresses a newline from the body text.
@others The @+others sentinel indicates the start of the expansion of an @+others directive, which contin-
ues until the matching @-others sentinel. @others sentinels are nested within @body sentinels; the
expansion of the @others directive always occurs within the body text of some node.
@verbatim @verbatim indicates that the next line of the derived le is not a sentinel. This escape convention
allows body text to contain lines that would otherwise be considered sentinel lines.
@@verbatimAfterRef @verbatimAfterRef is generated when a comment following a section reference
would otherwise be treated as a sentinel. In Python code, an example would be:
<< ref >> #+others
This sentinel is required only when blank lines are suppressed between sentinel lines.
27.8 Unicode reference
Leo uses unicode internally for all strings.
1. Leo converts headline and body text to unicode when reading .leo les and derived les. Both .leo les and
derived les may specify their encoding. The default is utf-8. If the encoding used in a derived le is not
utf-8 it is represented in the @+leo sentinel line. For example:
The utf-8 encoding is a lossless encoding (it can represent all unicode code points), so converting to
and from utf-8 plain strings will never cause a problem. When reading or writing a character not in a lossy
encoding, Leo converts such characters to ? and issues a warning.
2. When writing .leo les and derived les Leo uses the same encoding used to read the le, again with utf-8
used as a default.
3. leoSettings.leo contains the following Unicode settings, with the defaults as shown:
default_derived_file_encoding = UTF-8
new_leo_file_encoding = UTF-8
These control the default encodings used when writing derived les and .leo les. Changing the
new_leo_file_encoding setting is not recommended. See the comments in leoSettings.leo. You
may set default_derived_file_encoding to anything that makes sense for you.
4. The @encoding directive species the encoding used in a derived le. You cant mix encodings in a single
derived le.
27.8. Unicode reference 223
Leo, Release 4.6-b1
CHAPTER
TWENTYEIGHT
GLOSSARY
Important: We often refer to outline nodes by the directives they contain. For example, an @root node is a node
containing an @root directive, etc. Exception: An @le node is a node whose headline starts with @file.
@file node An @file node is a node whose headline starts with @file. Important: Headlines that
start with @file-asis, @file-noref, @file-nosent (and their abbreviations @asis, @noref,
@nosent) are collectively called @file nodes.
@file tree, @others tree, @root tree, etc. An @le tree is a tree whose root is an @le
node, etc.
@asis, @auto, @file, @noref, @nosent, @thin Headlines that start with one of these create
(correspond to) derived les. The following synonyms exist:
@asis, @file-asis
@noref, @file-noref
@nosent, @file-nosent
For more information, see the documentation for @asis, @auto, @le, @noref, @nosent and @thin in
Leos programming reference chapter.
@auto trees allow you to edit derived les that contain no sentinels. Leo will import the @auto les when
reading .leo les. Be careful when rst creating the @auto node. Before saving the .leo le containing the
new @auto node, use the read-at-auto-nodes command to do the initial import.
@all A directive that copies the body text of all nodes in an @thin tree to the corresponding derived le. For
more information, see directives for programming in Leos tutorial.
@others A directive that copies the body text of all nodes except section denition nodes in an @thin tree to
the corresponding derived le. For more information, see directives for programming in Leos tutorial.
@unit A directive that expands the scope of denitions in @root trees. For more information, see the @unit
documentation in Leos programming reference.
Body pane The pane containing the body text of the currently selected headline in the outline pane.
Body text The text in the body pane. Body text is always associated with a particular node.
Body text box A small blue box in the icon box indicating that the node contains body text.
Child A node directly contained by a node.
Chunk A section (noweb terminology).
225
Leo, Release 4.6-b1
Clone A copy of a tree that changes whenever the original changes. The original and all clones are treated
equally: no special status is given to the original node.
Clone Arrow A small red arrow in the icon box indicating that the node is a clone.
Code part A part of a section denition that contains code. Code parts start with @c or @code directives and
continue until the next doc part
Contract: To hide all descendants of a node.
CWEB A literate programming language invented by Donald Knuth and Silvio Levy. The CWEB language pro-
duces derived les for the C language.
Demote To move all siblings that follow a node so that they become children of the node.
Derived file The le created as the result of tangling a node containing an @root directive. The le consists
of the expansion of the text following the @root directive. For more information, see the derived les
section of Leos tutorial.
Descendant An offspring of a node. That is, a child, grandchild, etc. of a node.
Directive A keyword, preceded by an @ sign, in body text that controls Leos operation. The keyword is
empty for the @ directive. For more information, set the Leo directives section of Leos tutorial.
Doc part, @doc part, document part, etc. A part of a section denition that contains com-
ments. Doc parts start with @ and continue until the @c directive or the end of the body text. In @root
trees, doc parts are associated with the immediately following code part, if any.
Escape convention A convention for representing sequences of characters that would otherwise have spe-
cial meaning. Leo has only one such convention: in @root trees, @@ in the leftmost column of a code part
stands for a single @ character. Important: Leo does not support nowebs @<< and @>> escape conven-
tions. Any line containing matched << and >> is a section reference, regardless of context. To use << and
>> as ordinary characters, place them on separate lines.
expand To make the children of a node visible.
Grandchild The child of a child of a node.
Headline The headline text of a node. The part of the node visible in the outline pane
Hoist & dehoist Hoisting a node redraws the screen that node and its descendants becomes the only visible
part of the outline. Leo prevents the you from moving nodes outside the hoisted outline. Dehoisting a node
restores the outline. Multiple hoists may be in effect: each dehoist undoes the effect of the immediately
preceding hoist.
LaTex A markup language often used in literate programming environments. See: http://www.latex-project.org/
Icon box An icon just to the left of headline text of a node indicating whether the node is cloned, marked or
dirty, and indicating whether the node contains body text.
Leo1 and Leo2 Leo1 denotes all versions of Leo that write version 1 .leo les, that is, all Windows version
of Leo prior to version 2.0. The last version of Leo1, version 1.15, understands enough about Leo2 to issue
a warning when opening version 2 les.
Leo2 denotes all versions of Leo that write version 2 .leo les, that is, all versions of leo.py and all Windows
versions with version number 2.0 and above. Only Leo2 can generate derived les from @le trees.
226 Chapter 28. Glossary
Leo, Release 4.6-b1
Literate programming Astyle of programming that aims at producing the highest quality programlistings.
Literate programming languages apply two fundamental operations to text: weaving and tangling. Leo sup-
ports two literate programming languages, CWEB and noweb. For more links see the literate programming
web page.
Mark A red vertical line in the icon box of a node.
Node The organizational unit of an outline. The combination of headline text and body text. Sometimes used as
a synonym for tree.
noweb A literate programming language invented by Norman Ramsey. The noweb language can produce derived
les for any text-based programming language.
Offspring The children, grandchildren, etc. of a node.
Organizing node, organizer node A node containing no body text. Organizing nodes may appear any-
where in an @le tree; they do not affect the derived le in any way. In particular, organizing nodes do not
affect indentation in derived les.
Orphan node A node that would not be copied to a derived le. Orphan nodes can arise because an @thin tree
has no @others or @all directives. Sections that are dened but not used also create orphan nodes.
Leo issues a warning when attempting to write an @thin tree containing orphan nodes, and does not save
the derived le. No information is lost; Leo saves the information in the @thin tree in the .leo le. Leo will
load the @thin tree from the .leo le the next time Leo opens the .leo le.
Outline A node and its descendants.
A tree
All the nodes of a .leo le.
Outline Order The order that nodes appear on the screen when all nodes are expanded.
Outline pane The pane containing a visual representation of the entire outline, or a part of the outline if the
outline is hoisted.
Parent The node that directly contains a node.
Part A synonym for section. See also code part and doc part.
pdf file A le that can be read by Adobe Acrobat.
Plugin A Python le in Leos plugins folder.
A way to modify and extend Leo without changing Leos core code. leoPlugins.leo contains all
of Leos ofcial plugins.
See Writing plugins and hooks.
Promote To move all children of a node in an outline so that they become siblings of the node.
reStructuredText (rST) A simple, yet powerful markup language for creating .html, or LaTeX output
les. See the rST primer.
Root The rst node of a .leo le.
The rst node of an @root tree or @le tree.
227
Leo, Release 4.6-b1
rST plugin A plugin that supports reStructuredText. Unlike previous rst plugins, the rst3 plugin supports
per-node options.
Scope The portion of the outline in which a section denition is known.
Section A fragment of text that can be incorporated into derived les. See the Quick start for programmers in
Leos tutorial for more details.
Section definition: The body text of a section denition node. See the Quick start for programmers in
Leos tutorial for more details.
Section definition node A node whose headline starts with a section name and whose body text denes
a section. See the Quick start for programmers in Leos tutorial for more details.
Section name A name enclosed in << and >>. Section names may contain any characters except newlines
and >>. See the Quick start for programmers in Leos tutorial for more details.
Section reference A section name appearing in a code part. Tangling replaces all references by their
denitions. See the Quick start for programmers in Leos tutorial for more details.
Sentinels, sentinel lines Comment lines in les derived from @le nodes. Such lines start with an
@ following the opening comment delimiter. Sentinels embed outline structure into derived les. Do not
alter sentinel lines. Doing so can corrupt the outline structure. For more information see Sentinel lines in
Leos tutorial.
Setting: Plugins and other parts of Leo can get options from @settings trees, outlines whose headline is
@settings. When opening a .leo le, Leo looks for @settings trees in the outline being opened and
also in various leoSettings.leo files. @settings trees allow plugins to get options without any
further support from Leos core code. For a full discussion of @settings trees, see Chapter 8: Customizing
Leo.
Sibling Two nodes are siblings if they have the same parent. Siblings of the root have no parent.
Tangling The process of creating derived les from @root trees or @le trees. Leo tangles @le trees au-
tomatically when writing a .leo le. You must explicitly tangle @root trees using the Tangle command.
Tangling expands all section references in an @root node or @le node. For more information, see Tangling
@root trees in Leos programming reference.
Target language The language used to syntax color text. This determines the default comment delimiters
used during tangling and untangling.
Tree An outline. A node and its descendants.
Untangling Updating an outline based on changes to derived les. Untangling allows changes to be propa-
gated from derived les back to the outline. Especially useful when xing syntax errors outside Leo. For
more information, see Untangling @root trees in Leos programming reference.
View node A node that represents a view of an outline. View nodes are typically ordinary, non-cloned nodes
that contain cloned descendant nodes. The cloned descendant nodes comprise most of the data of the view.
Other non-cloned nodes may add additional information to the view. See clones & views in the Leos tutorial
for more information.
Weaving The process of creating typeset documentation from a noweb or CWEB source le. Weaving creates
documentation. Tangling creates derived les. Leo does not support weaving directly. To weave a le you
can create noweb or CWEB les using Leos Export commands, then use the noweb or CWEB systems
to weave those les.
228 Chapter 28. Glossary
CHAPTER
TWENTYNINE
FAQ
This is Leos Frequently Asked Questions document.
29.1 Getting Leo
Where can I get ofcial releases of Leo?
You can get the latest ofcial releases of Leo at http://sourceforge.net/project/showles.php?group_id=3458&package_id=29106
However, if at all possible, it is better to use bzr to get the latest sources. See the next entry.
How do I use bzr to get the latest sources from Leos launchpad site?
Many users will want to track the development version of Leo, in order to stay on top of the latest features and
bugxes. Running the development version is quite safe and easy, and its also a requirement if you want to
contribute to Leo.
1. First, you need to get Bazaar (bzr) from http://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:
And thats it! You can run the launchLeo script (in the top-level branch directory) directly. When you want to
refresh the code with latest modications from Launchpad, run bzr pull.
If you make modications 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 on 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 Code tab
-> Register Branch, select Branch type Hosted and ll 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://my_name@bazaar.launchpad.net/~leo-editor-team/leo-editor/mod_rclick
229
Leo, Release 4.6-b1
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 execute bzr push.
After your branch is pushed, you can email the Leo mailing list and request it to be reviewed and merged to trunk.
Ville M. Vainio - vivainio.googlepages.com
How can I get recent bzr snapshots of Leo?
Daily snapshots are available at http://www.greygreen.org/leo/
29.2 Installing Leo
Leos installer failed, what do I do?
@nocolor
You can simply unpack Leo anywhere and run from there. You dont need the installer.
From a console window, cd to the top-level leo folder. Run Leo as follows:
python launchLeo.py
To run Leo with Qt look and feel, use the gui=qt option:
python launchLeo.py --gui=qt
To load Leos source, load leoPyRef.leo:
python launchLeo.py --gui=qt leo\core\leoPyRef.leo
Nothing (or almost nothing) happens when I start Leo. What should I do?
Missing modules can cause installation problems. If the installer doesnt work (or puts up a dialog containing no
text), you may install Leo from the .zip le as described at How to install Leo on Windows. However you are
installing Leo, be sure to run Leo from a console window. because as a last resort Leo prints error messages to the
console.
Leo is hanging on my Linux box. What should I do?
From: http://sourceforge.net/forum/message.php?msg_id=1685399
When building Tcl on Linux, do not specify enable-threads Only use Tcl with the default threads not enabled
case.
Here is how to build Tk without thread support:
Go to www.tcl.tk, and download the sources for Tcl and Tk.
Build those two packs as is told in the How to Compile Tcl Source Releases
Go to www.python.org and download your favorite Python (2.3.5 for me).
Build it as is told on the download page.
Enjoy using Leo on Linux.
Running Python setup.py install from the leo directory doesnt work. Why not?
Leos setup.py script is intended only to create source distributions. It cant be used to install Leo because Leo is
not a Python package.
230 Chapter 29. FAQ
Leo, Release 4.6-b1
29.3 Learning to use Leo
Whats the best way to learn to use Leo?
First, read the tutorial. This will be enough to get you started if you just want to use Leo as an outliner. If you
intend to use Leo for programming, read the Quick start for programmers, then look at Leos source code in the
le LeoPy.leo. Spend 5 or 10 minutes browsing through the outline. Dont worry about details; just look for
the following common usage patterns:
The (Projects) tree shows how to use clones to represent tasks.
Study @thin leoNodes.py. It shows how to dene more than one class in single le.
Most other les show how to use a single @others directive to dene one class.
Most methods are dened using @others, not section denition nodes.
Why should I use clones?
You will lose much of Leos power if you dont use clones. See Clones & views for full details.
Which should I use: @root trees or @thin trees?
Use @thin trees unless you are sure you must have the extra exibility of @root trees. Indeed, @thin trees are
much easier to use than @root trees:
@thin trees use less markup than @root trees. In particular, the @others directive is valid only within
@thin trees.
However, @root trees are more exible than @thin trees:
When is using a section better than using a method?
Use methods for any code that is used (called or referenced) more than once.
Sections are convenient in the following circumstances:
When you want to refer to snippets of code the can not be turned into methods. For example, many plugins
start with the code like this:
<< docstring >>
<< imports >>
<< version history >>
<< globals >>
None of these sections could be replaced by methods.
When you want to refer to a snippet of code that shares local variables with the enclosing code. This is
surprisingly easy and safe to do, provided the section is used only in one place. Section names in such
contexts can be clearer than method names. For example:
<< init ivars for writing >>
29.3. Learning to use Leo 231
Leo, Release 4.6-b1
In short, I create sections when convenient, and convert them to functions or methods if they need to be used in
several places.
When is deleting a node dangerous?
A dangerous delete is a deletion of a node so that all the data in the node is deleted everywhere in an outline. The
data is gone, to be retrieved only via undo or via backups. It may not be obvious which deletes are dangerous in
an outline containing clones. Happily, there is a very simple rule of thumb:
Deleting a non-cloned node is
*
always
*
dangerous.
Deleting a cloned node is
*
never
*
dangerous.
We could also consider a delete to be dangerous if it results in a node being omitted from a derived le. This
can happen as follows. Suppose we have the following outline (As usual, A indicates that A is marked with a
clone mark):
- @thin spam.py
- A
- B
- Projects
- A
- B
Now suppose we clone B, and move the clone so the tree looks like this:
- @thin spam.py
- A
- B
- Projects
- A
- B
- B
If (maybe much later), we eliminate B as a child of A will get:
- @thin spam.py
- A
- Projects
- A
- B
B has not been destroyed, but B is gone from @thin spam.py! So in this sense deleting a clone node can also be
called dangerous.
29.4 How should I use Leo with bzr/git/hg/svn/cvs?
Using @thin trees can eliminate most problems with using Leo in VCS environments:
Developers should use @thin trees to create derived les in any kind of cooperative environment.
If sentinels are frowned upon in your development community, use @auto or @shadow instead of @thin.
The VCS repository contains reference .leo les. These reference les should contain nothing but @thin
nodes. Reference les will change only when new derived les get added to the project.
Important: Leos bzr repository contains the reference versions of the following .leo les:
LeoPyRef.leo and LeoPluginsRef.leo. However, Leos distributions contain the non-reference
versions of those les: LeoPy.leo and LeoPlugins.leo. These two les have many @thin nodes.
There is no reference le for test.leo even though it contains @thin leoTest.py. It would be
clumsy to use testRef.leo, and there is less need to do so. Reference .leo les (or any .leo les) rarely need
232 Chapter 29. FAQ
Leo, Release 4.6-b1
to be checked into VCS repository. If you nd yourself checking in a .leo le frequently, consider migrating
valuable content to @thin nodes.
Developers will use local copies of reference les for their own work. For example, instead of using
LeoPyRef.leo directly, I use a copy called LeoPy.leo. My local copy can contain nodes other than
@thin nodes.
29.5 Using derived les
How do I inhibit sentinels in derived les?
You have two options, depending on whether you want to be able to use sections or not.
Use @nosent trees. Files derived from @nosent trees contain no sentinels. However, Leo create the de-
rived le just as in @thin trees. In particular, Leo expands section references and understands the @others
directive.
Use @asis trees. Files derived from @asis trees contain no sentinels. Moreover, Leo does not expand
section references in asis trees. In other words, Leo creates the derived le simply by writing all body
text in outline order. Leo cant update the outline unless the derived le contains sentinels, so Leo does not
update @nosent trees or @asis trees automatically when you change the derived le in an external editor.
How do I prevent Leo from expanding sections?
You have two options, depending on whether you want sentinel lines in your derived le or not.
Use @noref trees. Leo creates les derived from @noref trees by writing all the nodes of the tree to the
derived le in outline order. The derived le does contain some sentinels, so you can update @noref trees
from changes made to derived les.
Use @asis trees. Files derived from@asis trees contain no sentinels. Leo creates the derived le simply by
writing all body text in outline order. Leo cant update the outline unless the derived le contains sentinels,
so Leo does not update @asis trees automatically when you change the derived le in an external editor.
How can I create Javascript comments?
Question: Im writing a Windows Script Component, which is an XML le with a CData section containing
javascript. I can get the XML as I want it by using @language html, but how can I get the tangling comments
inside the CData section to be java-style comments rather than html ones?
Answer: In @thin trees you use the @delims directive to change comment delimiters. For example:
@delims /
* *
/
Javascript stuff
@delims <-- -->
HTML stuff
Important: Leo can not revert to previous delimiters automatically; you must change back to previous delimiters
using another @delims directive.
In @root trees you can work around this problem using the @silent directive.
How can I disable PHP comments?
By Zvi Boshernitzan: I was having trouble disabling <?php with comments (and couldnt override the comment
character for the start of the page). Finally, I found a solution that worked, using phps heredoc string syntax:
@first <?php
@first $comment = <<<EOD
EOD;
29.5. Using derived les 233
Leo, Release 4.6-b1
// php code goes here.
echo "boogie";
$comment2 = <<<EOD
@last EOD;
@last ?>
or:
@first <?php
@first /
*
*
/
echo "hi";
@delims /
* *
/
@last ?>
How can I use Leo with unsupported languages?
Here is a posting which might be helpful: http://sourceforge.net/forum/message.php?msg_id=2300457 The
@first directive is the key to output usable code in unsupported languages. For example, to use Leo with
the Basic language, use the following:
@first $IFDEF LEOHEADER
@delims
@c
$ENDIF
So this would enable a basic compiler to jump over the true LEO-header-lines. Like this:
$IFDEF LEOHEADER <-conditional compilation directive
#@+leo-ver=4 <-these lines not compiled
#@+node:@file QParser005.INC
#@@first
#@delims
@@c
$ENDIF <-... Until here!
<rest of derived code file ... >
This changes the comment symbol the apostrophe, making comments parseable by a BASIC (or other language.)
How do I make derived les start with a shebang line?
Use the @rst directive in @thin trees or @nosent trees. Use the @silent directive in @root trees.
The @first directive puts lines at the very start of les derived from @thin. For example, the body text of
@thin spam.py might be:
The body text of @thin foo.pl might be:
@first #/usr/bin/perl
Leo recognizes the @first directive only at the start of the body text of @thin nodes. No text may precede
@first directives. More than one @first directive may exist, like this:
@first # more comments.
234 Chapter 29. FAQ
Leo, Release 4.6-b1
How do I use Leo to create CWEB les?
Leo has good support for CWEB. @thin trees can organize any part of CWEB code using noweb sections. You
can also use @asis, @noref or @nosent trees to create cweb les. See CWEB mode for full details.
Can @le trees contain material not in the derived le?
No. Everything in an @thin trees must be part of the derived le: orphan and @ignore nodes are invalid in
@thin trees. This restriction should not be troublesome. For example, you can organize your outline like this:
+ myClass
..+ ignored stuff
..+ @file myClass
(As usual, + denotes a headline.) So you simply create a new node, called myClass, that holds your @thin trees
and stuff you dont want in the @thin trees.
How can I use Leo with older C compilers
By Rich Ries. Some older C compilers dont understand the // comment symbol, so using @language C
wont work. Moreover, the following does not always work either:
@comment /
* *
/
This generates the following sentinel line:
/
*
@@comment /
* *
/
*
/"
in the output le, and not all C compilers allow nested comments, so the last
*
\/ generates an error. The solution
is to use:
#if 0
@comment /
* *
/
#endif
Leo is happy: it recognizes the @comment directive. The C compiler is happy: the C preprocessor strips out the
offending line before the C compiler gets it.
Why cant I use @ignore directives in @thin trees?
@ignore can only be used in the root node of @thin trees. It tells Leo to ignore the tree.
The @ignore directive can not be used elsewhere in @thin trees because of the way Leo recreates outlines from
derived les. This is an absolutely crucial restriction and will never go away. For a few more details, see Leo 4.0:
Eliminating error recovery in Chapter 9: History of Leo.
There are several workaround, as shown in LeoPy.leo:
keep notes in the outline outside of any derived le.
Use @all to gather notes in a derived le, as in done in @thin leoProjects.txt.
How can I avoid getting long lines in derived les?
Question: I must follow a coding standard when writing source code. It includes a maximum line length restric-
tion. How can I know the length of a line when it gets written to the derived le?
Answer: If a node belongs to a derived le hierarchy, its body might get indented when it is written to the
derived le. It happens when an @others directive or a section name appears indented in a higher-level node body.
While (line, col) in status area show the line and column containing the body texts cursor, fcol shows the cursor
coordinate relative to the derived le, not to the curent node. The relation fcol >= col is always true.
29.5. Using derived les 235
Leo, Release 4.6-b1
29.6 Customizing Leo
How can I add support for a new language?
See the instructions are in LeoPy.leo in:
Notes:How To:How to add support for a new language section.
This section contains clones of all relevant parts of Leo that you will change. Coming in Leo 4.4: Leo will use
JEdits language description les to drive the syntax colorer. To add support for a new language, just add another
such description le.
How do I submit a plugin?
You have two options:
Get cvs write access, and add the @thin le to the plugins directory.
Just send the @thin le to me at edreamleo@gmail.com. Thats all you need to do. In particular that there
is no need to change leoPlugins.leo.
How do I add a new menu item from a plugin?
c.frame.menu.createMenuItemsFromTable will append items to the end of an existing menu. For
example, the following script will add a new item at the end of the File menu:
def callback(
*
args,
**
keys):
g.trace()
table = (("Test1",None,callback),)
c.frame.menu.createMenuItemsFromTable(File,table)
Plugins can do anything that can be done with Tk using the menu returned by c.frame.menu.getMenu. For
example, here is a script that adds a Test menu item after the Open With menu item in the File menu:
def callback(
*
args,
**
keys):
g.trace()
fileMenu = c.frame.menu.getMenu(File)
# 3 is the position in the menu. Other kinds of indices are possible.
fileMenu.insert(3,command,label=Test2,command=callback)
How can I use Leos legacy key bindings?
You can revert to old key bindings as follows:
1. Open leoSettings.leo.
2. Find the node Keyboard shortcuts.
3. Disable the old bindings by moving the node @keys EKR bindings: Emacs keys + modes so that it is a
child of the node: @ignore Unused key bindings.
4. Notice that there are two child nodes of the node @ignore Unused key bindings that refer to legacy key
bindings:
@keys Legacy Leo shortcuts with important Emacs bindings
@keys Legacy Leo bindings.
5. Move one of these two legacy nodes up one level so that it is a child of the node Keyboard shortcuts. It
should not be a child of the node @ignore Unused key bindings.
236 Chapter 29. FAQ
Leo, Release 4.6-b1
How can I enable and disable support for psyco?
Find the @thin leoApp.py node in leoPy.leo. In the ctor for the LeoApp class set self.use_psyco to True or
False. You will nd this ctor in the node:
Code-->Core classes...-->@thin leoApp.py-->app.__init__
Note that this ivar can not be set using settings in leoSettings.leo because Leo uses g.app.use_psyco before pro-
cessing conguration settings.
29.7 Tips and techniques
What is an easy way to prole code?
I had a need to gure out why a part of some python code I had written was taking too long.
I pulled the code into LEO and the relevant part of the outline looked something like this:
+ Main module
-- Generate cryptographic key
-- Hashing algorithm
etc. So I cloned just the segment I wanted to prole and pulled it under a new section:
+ Main module
-- [clone] Generate cryptographic key
-- Hashing algorithm
+ Profiling Experiment
-- [clone] Generate cryptographic key
And in the body of the Proling experiment, I used this code:
code_under_here = """
@others
"""
from timeit import Timer
t = Timer("print my_key_generator()", code_under_here)
print t.timeit(number = 10)
And then I hit Control-B to execute the Proling Experiment body. This let me make adjustments to the code in
the clone body and keep hitting Control-B to execute the code with the timeit module to see immediately if what
I had done was making a difference.
The great thing about this was that I just used the LEO @others construct to create a wrapper around the code and
did not need to litter my code with debug or proling statements. Kayvan
How can I do a simple nd and replace?
The ofcial way to start a replace command is:
<Ctrl-shift-r>find-pattern<return>replace-text<return>
But suppose you with start with:
<ctrl-f>find-pattern
and then realize you want to do a replace instead of a nd. No problem. The following also works:
29.7. Tips and techniques 237
Leo, Release 4.6-b1
<Ctrl-f>find-pattern<Ctrl-shift-r>replace-text<return>
In other words, you can think of <ctrl-f> as meaning show the nd dialog. There is another trick you should
know. After typing <ctrl-f> or <shift-ctrl-r> you can use <alt-ctrl> keys to set or clear nd options. For example:
<ctrl-f><alt-ctrl-w><find-pattern><return>
That is, <ctrl-f>shows the nd dialog, <alt-ctrl-w> toggles the Whole Word checkbox and <return> starts the
search. You can type the <alt-ctrl> keys anytime after <ctrl-f> (or <shift-ctrl-r>) and before <return>. You can
also type multiple <alt-ctrl-keys> to toggle multiple checkboxes.
How can I use Leo to develop Leo itself?
The trick is to create a workow that separates editing from testing. Putting test code in LeoPy.leo would waste
a lot of time. To run tests you would have to exit Leo and reload LeoPy.leo. A much quicker way is to put all
test code in a test.leo le. So to change and test code, do the following:
1. Save LeoPy.leo but do not exit Leo.
2. Quit the copy of Leo running test.leo, then reload test.leo.
3. Run test scripts from test.leo.
Thats all. Python will recompile any changed .py les in the new copy of Leo. Note: I create a batch le called
t.bat that runs test.leo, so to the edit-reload-test cycle is just:
1. Control-S (in LeoPy.leo: saves the .leo le)
2. t (in a console window: runs test.leo, compiling all changed .py les as a side effect)
3. Control-E (in test.leo: runs the test script)
The benets of the new workow:
test.leo loads _much_ more quickly than LeoPy.leo does. This new approach can increase the speed of
the edit-reload-test cycle by more than a factor of 10. Hitting Control-S, t, Control-E takes about 5 seconds.
LeoPy.leo runs with the old code, so it is much easier to x syntax errors or exceptions in the new code:
just x the problem and save LeoPy.leo without closing LeoPy.leo, then restart test.leo. You run your
tests on the new code, but you edit the new code with the old, stable code.
test.leo is the perfect place to develop test. I can create and organize those tests and when I am done,
test.leo is a log of my work.
How can I import many les at once?
The Import Files dialog allows you to select multiple les provided you are running Python 2.3 or above. There is
also an importFiles script in LeoPy.leo. You can use that script as follows:
import leo.core.leoImport as leoImport
leoImport.importFiles(aDirectory, ".py")
This will import all .py les from aDirectory, which should be a full path to a particular directory. You could use
.c to import all .c les, etc.
How can I use two copies of Leo to advantage?
By Rich Ries. I often rework C code thats already been Leo-izedthe rst pass was quick and dirty to get it
going. When I do subsequent passes, I wind up with subnodes that are out of order with the sequence found in
the main node. Its not a big deal, but I like em ordered. With just one editor pane, clicking on the node to move
would switch focus to that node. Id then need to re-focus on the main node. A minor nuisance, but it does slow
you down.
238 Chapter 29. FAQ
Leo, Release 4.6-b1
My solution is to open a second editor with its focus on the main node. Switch to the other editor, and, referring
to the rst editor pane, move the nodes as you like. The second editors pane will change focus to the node youre
moving, but the rst editor will stay focused on the main node. Its a lot easier to do than to describe!
How can I display graphics in Leo?
One way is to link directly to the media le from a Leo node (with @url) and write a scriptbutton to
wrap all URL-nodes under the current node in a single HTML page (using the HTML browser trick at
http://sourceforge.net/forum/forum.php?thread_id=1201579&forum_id=10226).
Then, you can view your media in two ways:
Individually. You can directly click on the @url link to display the media in the browser (assuming you
have your MIME/letype associations set up correctly for your browser).
In a group. You can click on a script button (you have to code this yourself, very simple) which should
collect all @url nodes under the current node and dynamically generate a HTML page displaying either
links to or embedded versions of the media (using the HTML trick described above to invoke the browser).
This way, you can create collections of @url nodes under a single node (like a bookmark folder), and press
a single button to view the @url collection as a single entity in the browser (with all browser capabilities
like displaying the media).
You could probably generalize this idea of collect all @url nodes under current node and display as HTML in
browser into a general-purpose plugin. However, the plugin would have to be somewhat smart in mapping a link
to its corresponding HTML code (e.g. an image link gets mapped to an <img> HTML tag, a link to a Flash le
gets mapped to an <embed> tag, etc).
How can I create a template .leo le?
Question: It would be nice if Leo could open empty les. I tend to be document oriented rather than application
oriented in my thinking and prefer create empty le at location -> open it with program to start program ->
create new le -> save it at location.
Answer by Paul Paterson: If you are on Windows 98/2000/XP then the procedure is as follows...
1. Start Leo
2. Click New
3. Click Save as...
4. Save the le as c:windowsshellnewleole.leo (or c:winnt for 2000/XP)
5. Open regedit start...run...regedit
6. Open HKEY_CLASSES_ROOT and nd the .leo extension type
7. Go New ... Key from the context menu
8. Call the new key ShellNew
9. Select the new key, right-click, choose New...String Value from the context menu
10. Call it FileName
11. Double-click on the string, and modify it to be the lename of the leole.leo le you created, including the
extension
12. Exit the registry editor and restart Windows Explorer (you may need to reboot on Windows 98)
Now you should have a New:Leo File option in Explorer. This creates a duplicate of the le you saved. This can
be useful because you could make a template Leo le containing some standard nodes that you always have and
then save this.
How can I show Leo les with Excel?
29.7. Tips and techniques 239
Leo, Release 4.6-b1
From: http://sourceforge.net/forum/message.php?msg_id=3240374 Using Leos File-Export-Flatten
Outline commands creates a MORE style outline which places all Leo body sections on the left margin. The
headlines are indented with tabs which Excel will read as a tab delimited format. Once inside Excel there are
benets.
1. The most obvious benet inside Excel is that the body sections (Excel rst column) can be selected easily
and highlighted with a different font color. This makes the MORE format very readable. Save a copy of your
sheet as HTML and now you have a web page with the body sections highlighted.
2. It is possible to hide columns in Excel. Hiding the rst column leaves just the headlines showing.
3. Formulas based on searching for a string can do calculations in Excel. For example if a heading "Current
Assets" appears on level 4 then the body formula:
=INDEX(A:A,MATCH("Current Assets",D:D,0)+1)
will retrieve it. The +1 after match looks down one row below the matched headline. The trick is to place all
your headlines in quotes because Excel will see + "Current Assets" from the MORE outline. When
Excel tries without the quotes it thinks it is a range name and displays a #N/A error instead of the headline.
Also you must place a child node below to get the + sign instead of a - sign which would give a MORE
headline of -"Current assets" , also is an error.
I think there is some interesting possibility here because of the enforcement of Leo body text being always in the
rst column. The Leo outline provides additional reference to organizing the problem not typical of spreadsheet
models. Beyond scripting in Python, Excel is good at doing interrelated calculations and detecting problems like
circular references. In Excel Tools-Options-General is a setting for r1c1 format which then shows numbers instead
of letters for column references. Using this would allow entries like this in the leo body:
1000
3500
=R[-1]C+R[-2]C
In Excel you would see 4500 below those two numbers. This is completely independent of where the block of
three cells exists on the sheet.
How can I reuse @button nodes in multiple les?
By Rich Ries
There is no direct way to make script buttons available in multiple Leo les. Sure, you could copy and paste the
@button nodes, but there is a slightly easier way using the New Buttons plugin.
1. Create and test and debug your desired Script Button.
2. With the Script Button node selected, run Plugins > New buttons > Make Template From
Open a new Leo le.
1. Assuming you have only the one New Button Template dened, left-click the New button, and a new node
will be added to your outline. (Otherwise, youll need to select the Template you want.)
2. Press [Script Button] to create the new script button.
Its easier to do this than to explain it!
29.8 Trouble shooting
How do I get help?
All questions are welcome at http://groups.google.com/group/leo-editor
240 Chapter 29. FAQ
Leo, Release 4.6-b1
How do I report bugs?
You can discuss possible bugs at http://groups.google.com/group/leo-editor
Please report bugs at http://bugs.launchpad.net/leo-editor
When reporting a bug, please include all of the following:
The version of Leo used.
The version of Python used.
The platform or platforms used: Linux, Windows, MacOs.
A clear description of the problem.
Information sufcient to recreate the problem.
Its polite to make the bug report self contained, so that six weeks later somebody will be able to understand the
report as it stands.
My old .leo les wont load using Leo 4.5 or later. What should I do?
In version 4.5, Leo changed to using a sax parser for .leo les. This can cause problems if your .leo le contains
invalid characters. Bugs in previous versions of Leo permitted these bad charactgers to appear.
The sax parser complains that these characters are not valid in .xml les. Remove these invalid characters as
follows:
1. Run Leo from a console, and load the .leo le. Near the bottom of the error message you will see a line like:
SAXParseException: <unknown>:123:25: not well-formed (invalid token)
This line reports a bad character at character 25 of line 123.
2. Open the .leo le in an external editor. The Scite editor, http://www.scintilla.org/SciTE.html, is a good
choice because it clearly shows non-printing characters. Remove the invalid character, save the .leo le.
Repeat steps 1 and 2 until all invalid characters are gone.
Can I scroll the outline pane with the mouse wheel?
This is a known bug in Tk that prevents this on Windows. The obvious Tk code causes a hard crash in the Python
dll: its the only time Leo has taken such a hard crash. The UniversalScrolling plugin is an attempt at a
workaround.
Scrolling with the mouse wheel may be possible on Linux. See the code in createTkTreeCanvas in leoTkinter-
Frame.py
Control-Shift backspace doesnt work. What should I do?
By Dave Hein: The cause of the keymapping problem is a issue with the X11 keyboard mapping, not with Tk. If
you have this problem on your system, issue the command:
xmodmap -pke
and look in the results for the line for keycode 22. Ill bet it shows something like:
keycode 22 = BackSpace Terminate_Server
That second token (Terminate_Server) is what is supposed to be mapped to Shift-Backspace. You want this
second token to be either not present or to be BackSpace. To x this, create a le (e.g. .Xmodmap) and give it the
content:
keycode 22 = BackSpace
29.8. Trouble shooting 241
Leo, Release 4.6-b1
then run the command:
xmodmap .Xmodmap
This xes the problem. On my system this also disables the ability to terminate the X server using Ctrl-Alt-
BackSpace. This is because of some conict with xdb (xdb is the newer keyboard mapping facility in XFree86;
xmodmap is the old original X11 keyboard mapping facility). Im still working on that. Im also not able to get
xmodmap to make this change during X11 startup (again because of conicts with xdb). But Im working on that
as well.
Error messages from the rst3 plugin arent helpful. What can I do?
For the most part, docutils does a good job of reporting errors. docutils prints a message to the console and inserts
an unmistakable error message in the generated .html le. Important: On Windows it is helpful to run Leo from
a console window.
However, in some cases, docutils crashes instead of properly reporting the problem. There are several
workarounds:
1. The crashes I have seen arise from the following bug in docutils. Hyperlinks in image:: markup must be
lower case. This will work:
.. .. |back| image:: arrow_lt.gif
:target: faq_
This will crash:
.. .. |back| image:: arrow_lt.gif
:target: FAQ_
So avoid this crash by making sure to use lower case targets in :target: markup.
2. You can change the docutils source slightly so that it prints a traceback when it crashes. (The rst3 plugin
should be able to do this, but I havent gured out how yet.) Its easy enough to do this:
Find the le core.py in top-level docutils folder. Typically this folder will be in Pythons
site-packages folder.
Open core.py in some editor other than Leo.
Find the method called report_Exceptions.
Insert the following lines at the very start of this method:
print EKR: added traceback
import traceback ; traceback.print_exc()
This will cause a traceback whenever docutils crashes. I have found that such tracebacks are generally
enough to locate the general area of the problem. Note: These tracebacks go to the console window, so you
should run Leo from a console window.
3. As a last resort, you can isolate syntax errors by reducing your input les until they work again, then adding
sections until you get a crash. This is easy enough to do (when using the rst3 plugin) by change a headline
x to @rst-ignore-tree x.
How can I run Leo from a console window?
Leo (and other programs) often send more detailed error messages to stderr, the output stream that goes to the
console window. In Linux and MacOS environments, python programs normally execute with the console window
visible. On Windows, can run Leo with the console window visible by associating .leo les with python.exe
not pythonw.exe. For full instructions about how to do this, see Associating Leo with .leo Files.
How can I use Pythons pdb debugger with Leo?
Just run Leo in a console window. At the point you want to drop into the debugger, execute this line:
242 Chapter 29. FAQ
Leo, Release 4.6-b1
g.pdb()
All output from pdb goes to stdout, which is the console window. It would be good to create a subclass of pdb.Pdb
that uses Leos log pane rather than a console window, but I havent done that. It could be done easily enough in
a plugin...
Important: I recommend using g.trace instead of pdb. For example:
g.trace(x)
prints the name of the function or method containing the trace, and the value of x. g.callers is often useful in
combination with g.trace. g.callers(5) returns the last 5 entries of the call stack. For example:
g.trace(x,g.callers(5))
Used this way, g.trace shows you patterns that will be invisible using pdb.
I cant write Imported les. Whats going on?
The import commands insert @ignore directives in the top-level node. Leo does this so that you wont acciden-
tally overwrite your les after importing them. Change the lename following @thin or @root as desired, then
remove the @ignore directive. Saving the outline will then create the derived le.
I dont see the Leo icon in Leo windows
For versions of Leo before 4.0 and for versions of Python before 2.3, Leo will draw a Leo icon in Leo windows
only if you have installed Fredrik Lundhs PIL and tkIcon packages.
Download PIL from http://www.pythonware.com/downloads/index.htm#pil
Download tkIcon from http://www.effbot.org/downloads/#tkIcon
Leo doesnt recognize commands with the caps-lock key down
This is a known bug in Tk/Tkinter and there is no good workaround. Some keyboards allow you to disable the
caps-lock key.
Leo is hanging on my Linux box. What should I do?
From: http://sourceforge.net/forum/message.php?msg_id=1685399
When building Tcl on Linux, do not specify enable-threads Only use Tcl with the default threads not enabled
case.
Here is how to build Tk without thread support:
Go to www.tcl.tk, and download the sources for Tcl and Tk.
Build those two packs as is told in the How to Compile Tcl Source Releases
Go to www.python.org and download your favorite Python (2.3.5 for me).
Build it as is told on the download page.
Enjoy using Leo on Linux.
Leos Recent Files menu doesnt work from a cvs shandbox. Whats going on?
You must create .leoRecentFiles.txt in the cong directory. .leoRecentFiles.txt is part of the standard releases but
is not part of the cvs repository.
Nothing (or almost nothing) happens when I start Leo. What should I do?
Missing modules can cause installation problems. If the installer doesnt work (or puts up a dialog containing no
text), you may install Leo from the .zip le as described at How to install Leo on Windows. However you are
29.8. Trouble shooting 243
Leo, Release 4.6-b1
installing Leo, be sure to run Leo from a console window. because as a last resort Leo prints error messages to the
console.
The new Python decorator syntax causes problems. What can I do?
Pythons decorator syntax is ill-conceived. This syntax le hack works well enough anyway to work with Leo @
markup:
syn region leoComment start="^@\s
*
" end="^@c\s
*
$"
syn match pythonDecorator "@\S\S+" display nextgroup=pythonFunction skipwhite
Running Python setup.py install from the leo directory doesnt work. Why not?
Leos setup.py script is intended only to create source distributions. It cant be used to install Leo because Leo is
not a Python package.
I cant run the LeoBridge module outside of leo/core. What should I do?
Question and answer from plumloco.
Add the equivalent of:
import sys
leocore = "path/to/leo/core"
if leocore not in sys.path: sys.path.append(leocore)
at the head of each le that uses leoBridge.
The problem is not importing leoBridge itself but (if I use from leo.core) the importing of plugins, who get a
different leoGlobals from leoBridge, without g.app etc, and so do not work if they rely on dynamic values in g.etc.
> Why cant you simply add leo/core to sys.path in sitecustomize.py?
Putting leocore on the python path as you suggest would put forty python modules in the global module namespace
for all python programs when I want just one. Also, I have a safe working copy of leo and a cvs/testing version.
I would wish to test any programs against the testing version while using the working version, but both /core
directories cant be exposed at the same time.
> Do you need plugins while running from the leoBridge?
Afraid so, at least the rst3 plugin. The solution I am using now is to place:
sys.modules[leoGlobals] = leoGlobals
in leoBridge after import leo.core.leoGlobals as leoGlobals
This allows my scripts to be portable over the several computers/platforms I need to use them on, and makes
testing scripts against multiple leo versions easy. It does mean that my scripts are not portable to other leo users
but that is not likely to be a problem.
29.9 Unicode issues
I can not enter non-ascii characters. What can I do?
Set @bool ignore_unbound_non_ascii_keys = False in LeoSettings.leo or myLeoSettings.leo.
Some characters in derived les look funny. What can I do?
Internally, Leo represents all strings as unicode. Leo translates from a particular encoding to Unicode when
reading .leo les or derived les. Leo translates from Unicode to a particular encoding when writing derived les.
You may see strange looking characters if your text editor is expecting a different encoding. The encoding used in
any derived le is shown in the #@+leo sentinel line like this:
244 Chapter 29. FAQ
Leo, Release 4.6-b1
Exception: the encoding is UTF-8 if no -encoding= eld exists. You can also use the @encoding directive
to set the encoding for individual derived les. If no @encoding directive is in effect, Leo uses the following
settings to translate to and from unicode:
default_derived_le_encoding The encoding used for derived les if no @encoding directive is in effect. This
setting also controls the encoding of les created by the Tangle commands. The default is UTF-8 (case
not important).
new_leo_le_encoding The encoding specied in the following line of new .leo les:
<?xml version="1.0" encoding="UTF-8">
The default is UTF-8 (upper case for compatibility for old versions of Leo). Important: once a .leo le is
created the <?xml..."> line can only be changed by hand. This may cause unicode errors the next time
the .leo le is loaded, so you should change the <?xml..."> line by hand only when rst creating a .leo
le.
tk_encoding The encoding that Leo uses to communicate with Tk text widgets. You would typically use this
setting only in an emergency. The section called:
<< set app.tkEncoding >>
in app.nishCreate sets this encoding as follows:
1. using the tk_encoding setting if it exists,
2. using locale.getpreferredencoding if it exists, or the equivalent code in pre-python 2.3
versions,
3. using sys.getdefaultencoding
4. defaulting to "utf-8"
Neither b nor c are guaranteed to give a valid encoding in all systems, and Leo will ignore invalid encodings
returned from b or c. Therefore, setting the tk_encoding setting may be needed.
I get weird results when dening unicode strings in scripts. What is going on?
Add the following to the start of your scripts:
@first # -
*
- coding: utf-8 -
*
-
Without this line, constructs such as:
u = ua-(unicode characters here)-z
u = a-(yet more unicode characters here)-z
will not work when executed with Leos execute script command. Indeed, the Execute Script command creates
the script by writing the tree containing the script to a string. This is done using Leos write logic, and this logic
converts the unicode input to a utf-8 encoded string. So all non-ascii characters get converted to their equivalent
in the utf-8 encoding. Call these encoding <e1> and <e2>. In effect the script becomes:
u = ua-<e1>-<e2>-z
u = a-<e2>-<e>-z
which is certainly not what the script writer intended! Rather than dening strings using actual characters, Instead,
one should use the equivalent escape sequences. For example:
u = ua-\u0233-\u8ce2-z
u = a-\u0233-\u8ce2-z
29.9. Unicode issues 245
Leo, Release 4.6-b1
Some characters are garbled when importing les. What can I do?
The encoding used in the le being imported doesnt match the encoding in effect for Leo. You have two options:
Use the @encoding directive in an ancestor of the node selected when doing the Import command to
specify the encoding of le to be imported.
Set the tk_encoding setting (see the previous answer) to the encoding you normally use.
Pythons print statement shows byte hash for unicode characters. What can I do?
First, you must change Pythons default encoding to something other than ascii. To do this, put the following in
your sitecustomize.py le in Pythons Lib folder:
import sys
sys.setdefaultencoding(utf-8) # iso-8859-1 is another choice.
You must restart Python after doing this: sys.setdefaultencoding can not be called after Python starts up.
Leos g.es_print and g.pr functions attempts to convert incoming arguments to unicode using the default encoding.
For example, the following Leo script shows various ways of printing La Pea properly:
@first # -
*
- coding: utf-8 -
*
-
import sys
e = sys.getdefaultencoding()
print encoding,e
table = (
La Pea,
unicode(La Pea,utf-8),
uLa Pea,
uLa Pe\xf1a,
)
for s in table:
print type(s)
g.es_print(g.es_print,s)
if type(s) != type(ua):
s = unicode(s,e)
print print ,s
print repr(s) ,repr(s)
For still more details, see: http://www.diveintopython.org/xml_processing/unicode.html
246 Chapter 29. FAQ
CHAPTER
THIRTY
WHATS NEW IN LEO 4.6
30.1 Improved unit testing
leoDynamicTest.py now supports a path argument giving the .leo le. This is so useful!
leoDynamicTest.py now honors the silent argument.
leoTest.runUnitTestLeoFile runs all unit tests in a given .leo le in a separate process.
leoTest.runTestsExternally calls runUnitTestLeoFile after creating dynamicUnitTest.leo.
When reporting that no unit tests were found, all unit tests commands tell whether the entire outline or just
the selected outline was searched. This xes sometimes-misleading error messages.
test.leo contains a run-test.leo-tests button.
leoPy.leo contains a run-all-core-tests button.
30.2 Improved le handling
Leo opens a default .leo le if no other is specied, using the @string default_leo_le setting. The default
for this setting is ~/.leo/workbook.leo
Added escapes for underindented lines. The escape is specied by the @string underindent-escape-string
setting. By default, this escape is \- If a line starts with -N, Leo will write the line with N fewer spaces
than expected.
Leo now warns when attempting to write a le that has been changed outside of Leo. This prevents bzr
reversions.
Leo tests syntax of .py les when saving them.
Leo can now open any le into an @edit node. This allows Leo to be associated with the edit action of .py
les. Like this:
C:\Python26\python.exe "c:\leo.repo\trunk\launchLeo.py" --gui=qt %1 %2
30.3 Improved handling of rST les
Added support for @auto-rst nodes. These import reStructuredText (rST) les so that the les can be round-
tripped without introducing extraneous changes. This makes Leo a superb environment for using rST.
247
Leo, Release 4.6-b1
30.4 New code features
Added autoCompleter.getExternalCompletions. See http://groups.google.com/group/leo-
editor/browse_thread/thread/4ad91984a6d0acac
Added g.posList.
c.cong.doEnabledPlugins sets g.app.cong.enabledPluginsFileName
Added the following properties: p.b, t.b and v.b return the body string of the position or node.
p.h, t.h and v.h return the head string of the position or node.
t.u and v.u return the uA of the node.
p.gnx, t.gnx and v.gnx return the gnx of the position or node.
Added script to leoSettings.leo to ensure all menu items are valid.
c.cong.getSettingSource(setting_name) returns the name of the le which Leo used to determine the set-
ting:
D indicates default settings.
F indicates the le being loaded
L indicates leoSettings.leo
M indicates myLeoSettings.leo
Predened self in @test/@suite nodes.
Added c.getNodePath and c.getNodeFileName. See http://groups.google.com/group/leo-
editor/browse_thread/thread/3b5f1232ecc6bba7
30.5 New command-line options
The cong command-line option species a single cong (.leo) le to use for conguration. See
http://groups.google.com/group/leo-editor/browse_thread/thread/f3f95d93bcd93b94
The le=leName command-line option load a le. Only .zip and .leo extensions are allowed at present.
The gui=name command-line option species the gui to use. The valid values are gui=qt, gui=tk
30.6 New commands
Added smart home (back-to-home) command.
Added support for standard behavior of Tab and Shift-Tab keys. The tab key indents the text selection, if
there is one; otherwise, the tab key insert a tab or blanks, depending on the @tabwidth setting. Shift-Tab
always unindents one or more lines.
The open command creates @edit nodes when opening non-.leo les The open le dialog now shows all
les by default. Selecting a non-.leo le will load that le into a new node in the present outline.
Added added pdb minibuffer command. This works, but stops Leo in the middle of the command-
handling logic. You may get the commander c by stepping out into k.masterKeyHandler or
k.masterCommandHandler. Using c, you can then get all other info.
Improved the isearch commands.
nd-clone-all is a synonym for clone-nd-all.
248 Chapter 30. Whats New in Leo 4.6
Leo, Release 4.6-b1
30.7 New and improved directives
Added @nocolor-node directive.
Improved @path handling.
30.8 New settings
@string default_leo_le = ~/.leo/workbook.leo
@string underindent-escape-string = -
@int icon_bar_widgets_per_row
Added support for meta keys. http://groups.google.com/group/leo-
editor/browse_thread/thread/b6a39ed672a28c65?pli=1
The qt gui is now the default.
30.9 Plugins
Improved nav_buttons plugin and corresponding nodeHistory class.
Created qtGui and tkGui plugins.
Created leoGuiPluginsRef.leo.
30.7. New and improved directives 249
Leo, Release 4.6-b1
CHAPTER
THIRTYONE
31.1 Major new features
Added support for @shadow les. This is a major breakthrough. See Chapter 23 for full details.
Added much improved support for vim bindings.
Allow v.uAs in @thin and @shadow nodes. See http://groups.google.com/group/leo-
editor/browse_thread/thread/750bb3099090f5b
31.2 Major code reorganizations
Leo now uses a sax-based parser to read .leo les. This makes it possible to extend Leos le format without
invalidating previous versions of Leo.
Leo now supports the so-called Graph World. When g.unied_nodes is True, Leo moves all information
from tnodes into vnodes.
Leo now uses a new key binding scheme. This allows substantially simpler key bindings. Indeed, most
per-pane bindings have been eliminated. Added support for kill bindings.
Leo is now an installable package. To make this work, Leo adds os.curdir to sys.path if needed on startup.
Reorganized Leos drawing and focus code. As a result, calls to c.beginUpdate and c.endUpdate are no
longer needed.
Leo is now ready for Python 3.x: Change most print statements to calls to g.pr.
31.3 Minor new features
Added g.Tracer class. This is a Python debugger that computes a call graph. To trace a function and its
callers, put the following at the functions start:
g.startTracer()
The nd-character command now nds characters across line boundaries.
Set cwd in read/write commands. This affect the following commands: open, save, save-as, save-to, read-
outline-only, read-le-into-node, write-le-from-node and all the import/export commands.
Leo creates the .leo folder in the users HOME directory, and puts several conguration les there. Leo
looks for myLeoSettings.leo in HOME/.leo. Leo uses os.path.expanduser(~) if there is no home setting.
251
Leo, Release 4.6-b1
31.4 New settings
The default settings for @shadow les are now located in leoSettings.leo in the node:
@settings-->File options-->Shadow files
The defaults for these settings are:
@string shadow_prefix = x
@string shadow_subdir = .leo_shadow
Added support for @bool xedWindow option. Leo suppresses marks, expansion state, orphan bits and
current position bits when writing xed .leo les. As a result, all nodes will be collapsed and the root node
will always be selected when Leo opens a xed .leo le.
You can optionally specify the size and position on the screen of xed .leo les by putting an @data
xedWindowPosition node in the @settings tree of myLeoSettings.leo or leoSettings.leo. You should not
put such a node in the xed .leo le itselfeveryone who opens the le would get that xed position.
The body of the @data xedWindowPosition node should contain something like this:
# Must be four entries: width,height,left,top.
# Put this in myLeoSettings.leo,
**
not
**
in individual .leo files.
1200
800
50
50
Added @bool cleo_color_ignore = True This determines whether cleo colors @ignore headlines. The de-
fault is True.
CHAPTER
THIRTYTWO
WHATS NEW IN LEO 4.4.7 AND LEO
4.4.8
32.1 New features
Better support for unicode in @auto trees.
All import commands now honor @path
Leo now supports arguments to minibuffer commands.
Leo can now translate messages sent to Leos log. Rather than using an _ function to denote strings to be
translated, Leos g.es and g.es_print functions translate odd (rst, third, fth) arguments, leaving even
arguments untranslated. Keyword arguments, color, newline, etc. are never translated. g.translateString
does the actual translation using Pythons gettext module.
@menu items may not refer to commands created by @button and @command nodes.
32.2 New and improved plugins
The ipython plugin creates a simple, powerful, effective bridge between IPython and Leo. See
http://webpages.charter.net/edreamleo/IPythonBridge.html
Improved marks/recent buttons plugin.
32.3 New settings
Added support for @commands trees in leoSettings les.
Added support for @bool open_with_save_on_update setting. If True, Leo will automatically save the
outline whenever an external editor changes the outline.
253
Leo, Release 4.6-b1
254 Chapter 32. Whats New in Leo 4.4.7 and Leo 4.4.8
CHAPTER
THIRTYTHREE
WHATS NEW IN LEO 4.4.6
Leo 4.4.6 xes all known bugs and adds a few new features.
33.1 New commands
find-next-clone
toggle-sparse-move
Replaced the delete-all-icons command with a script in scripts.leo. This command was too dangerous.
33.2 New features
Added support for @auto xml and @auto javascript. Use @data import_xml_tags setting to specify the xml
tags that act as organizers. Javascript regexps that look like section references cause problems, but that can
not be helped.
33.3 New settings
Added support for @data nodes in settings les.
The @data import_xml_tags setting species the xml tags that act as organizers. This settings is used by
@auto when importing xml les.
255
Leo, Release 4.6-b1
256 Chapter 33. Whats New in Leo 4.4.6
CHAPTER
THIRTYFOUR
Leo 4.4.5 xes several long-delayed bug xes and adds several new features.
The highlights of Leo 4.4.5:
Fixes all known bugs.
Adds 3 new sort-lines commands.
Adds commands to insert and delete icons from headlines.
Adds all the Tango 16x16 icons to Leos icon library.
Adds support for @rst-preformat nodes to the rst3 plugin.
34.1 Bug xed
Fixed hung (zombie) windows. http://sourceforge.net/forum/message.php?msg_id=3768494
Fixed resurrected (vampire) nodes. http://sourceforge.net/forum/message.php?msg_id=3525277
34.2 New features
Leo now supports all directives in headlines.
Moved all unit tests to unitTest.leo and reorganized the unit tests by Leo source le.
Installed small icon set from Tango library.
The rst3 plugin now supports @rst-preformat nodes.
34.3 New commands
delete-all-icons
delete-first-icon
delete-last-icon
delete-node-icons
insert-icon
reverse-sort-lines
reverse-sort-lines-ignoring-case.
sort-lines-ignoring-case
toggle-collapse_nodes_during_finds
257
Leo, Release 4.6-b1
34.4 New settings
@bool at_auto_warns_about_leading_whitespace
This option has effect only when importing so-called non-strict languages, for which leading whitespace is
not terribly signicant.
@bool diagnose-aspell-installation
This provides further information when there are problems using aspell.
@bool warn_when_plugins_fail_to_load
There is also an @bool trace_plugins setting.
@bool vim_plugin_opens_url_nodes
vim.py does not open url nodes if this setting is False.
CHAPTER
THIRTYFIVE
Leo 4.4.4 contains many important features originally planned for later releases. The highlights of Leo 4.4.4:
The Great Graph Aha: A Leo outline doesnt have to be an arbitrary graph in order to represent an
arbitrary graph.
That is, simple scripts allow Leo outlines to represent arbitrary directed graphs. There is no need for a
separate graph world. The graphed.py plugin is a direct result of this Aha. It allows you to create general
graphs from Leo outlines.
Support for @auto nodes. Such nodes allow people to collaborate using Leo without inserting Leo sentinels
in the les Leo generates.
@menus trees in settings les create all of Leos menus. It is now dead easy to make Leos menus look the
way you want.
@buttons trees in settings les create common @button nodes created in all Leo outlines.
A new, faster, colorizer plugin replaces the __jEdit_colorizer__ plugin.
New commands for resolving cvs conicts.
Leos core is now compatible with jython.
35.1 The Great Graph Aha
The Great Graph Aha is:
A Leo outline doesnt have to be an arbitrary graph in order to represent an arbitrary graph.
So the graph world is unnecessary because we can use Leo nodes and trees as data to other graphing packages.**
That is, Python scripts can build arbitrary graphs using Leos existing nodes and trees. And Python scripts can
manipulate those graphs. And Python scripts could do the reverse: manipulate the Leo outline by traversing
general graphs. So there is no need to complicate Leos fundamental data structures. Hurray! Instead, we build
on the strengths of already existing graphing packages.
The Great Graph Aha created the opportunity for immediate action:
1. test.leo contains the essential scripts to implement graphs in Leo les. These short, simple, self-contained,
easily modiable scripts make possible everything ever envisaged by the (now-defunct) graph world project:
leo2graph: convert a normal Leo tree to a NetworkX graph.
at-graph2graph: convert an @graph tree to a NetworkX graph.
at-networkx2graph: convert an @networkx tree to a NetworkX graph
at-networkx2at-graph: create an @graph tree from an @networkx tree.
2. The graphed plugin allows users to manipulate parts of Leo outlines as if they were general graphs. It is still
early days for this exciting plugin.
259
Leo, Release 4.6-b1
35.2 Added support for @auto les
35.2.1 What @auto does
@auto trees allows people to use Leo in collaborative environments without using sentinels in the les Leo gener-
directive.
2. Saving a .leo le does not save @auto nodes if a) they havent been changed or b) they do not contain a
signicant amount of information. An @auto tree contains a signicant amount of information if it has children
or if the root node contains more than 10 characters.
Leo creates @auto trees by parsing the corresponding derived le. Parsers create descendant nodes of the @auto
tree: one node for each class, method and function in the derived le.
Parsers presently exist for C, elisp, Java, Pascal, PHP and Python. Leo determines the language using the les
extension. If no parser exists for a language, the entire body of an @auto tree contains a signicant amount of
information if it has any children or if the root node contains more than 10 non-blank lines. the derived le is
copied to the body of the @auto node.
Leo does not write the contents of @auto trees to .leo les. In this respect, @auto trees work much like @thin
trees. @auto trees whose root node is under the scope of an @ignore directive will be written to the .leo, just like
@thin trees.
35.2.2 Perfect import checks
Leo performs several checks to ensure that the result of importing an external le will be equivalent to the le that
writing the @auto tree would produce.
These checks can produces errors or warnings. Errors indicate a potentially serious problem. Leo inserts an
@ignore directive in the @auto tree if any error is found. This @ignore directive prevents the @auto tree from
modifying the external le. If you @ignore directive, a later write of the @auto tree will attempt to x the problems
that gave rise to the errors. There are no guarantees however.
Strict languages are languages like Python for which leading whitespace is especially signicant. Before import-
ing a le for a strict language, Leo regularizes the leading whitespace of all lines of the original source le. That
is, Leo converts blanks to tabs or tabs to blanks depending on the value of the @tabwidth directive in effect for the
@auto node. Leo cannot guarantee to reproduce the original source le exactly if problems are discovered while
regularizing leading whitespace.
After importing a le, Leo veries that writing the @auto node would create the same le as the original le.
For strict languages, the comparison must be exact, or nearly so. For non-strict languages, differences in leading
whitespace generate warnings, not errors.
File comparison mismatches can arise for several reasons:
1. Bugs in the import parsers. Please report any suspected bugs immediately.
2. Underindented lines in classes, methods or functions in strict languages. An underindented line is a line
that is indented less then the starting line of the class, method or function in which it appears. Leo out-
lines can not represent such lines exactly: every line of node implicitly has at least the indentation of any
unindented line of the node.
Leo will issue a warning (not an error) for underindented Python comment lines. Such lines can not change the
meaning of Python programs.
Leo, Release 4.6-b1
35.2.3 Commands related to @auto
Three new commands in the File:Read/Write menu allow you to manually read and write @auto nodes from the
presently selected outline. As always, an @ignore directive in the @auto node or its ancestors will suppress any
of these commands:
The Read @auto Nodes (read-at-auto-nodes) command reads all @auto nodes in the presently selected
outline. An @ignore directive will suppress this import.
The Write @auto Nodes (write-at-auto-nodes) command writes all @auto nodes. An @ignore directive will
suppress this import. Caution: the write will occur even if Leo has not previously read the @auto node.
The Write Dirty @auto Nodes (write-dirty-at-auto-nodes) is the same as the write-at-auto-nodes command,
except that only changed @auto trees are written.
Most users will rarely use these explicit commands, because reading and writing .leo les handles @auto nodes
well enough. However, you can use the read-at-auto-nodes command to update @auto nodes without having to
reload the .leo le.
35.2.4 Extending the code: adding new parsers
All present parsers are short overrides of a powerful base parser class. Thus, it would be simple to add support for
other languages. See the node
@thin leoImport.py>Import>Scanners for createOutline
in leoPy.leo to see how easy it is to create new parsers.
35.3 New commands for resolving cvs conicts
The so-called resolve-cvs-conict project has resolved itself into small, easily understood commands.
The read-le-into-node command prompts for a lename, and creates an node whose headline is @read-le-into-
node <lename> and whose body text is the entire contents of the le.
The write-le-from-node command writes the body text of the selected not to a le. If the headline of the
presently selected node starts with @read-le-into-node the command use the lename that follows in the headline.
Otherwise, the command prompts for a lename.
When a cvs conict occurs, the user will:
read the le into a node using the read-le-into-node command,
x the conict, as with any other editor, and
write the le with the write-le-from-node command.
Any le can be xed in this way, including derived les and .leo les. The only complication is that the user
must not change sentinel lines. Two new commands check the contents of a node: The check-derived-le and
check-leo-le commands tell whether a trial read of the presently selected node can be done successfully. The
check-derived-le command assumes the body text is a derived le; the check-leo-le command assumes the body
text is an entire .leo le.
The compare-leo-outlines command prompts for another (presumably similar) .leo le that will be compared
with the presently selected outline le (main window). It then creates clones of all inserted, deleted and changed
nodes.
35.3. New commands for resolving cvs conicts 261
Leo, Release 4.6-b1
35.4 New kinds of settings trees
35.4.1 @buttons trees
All @buttons tree in a settings le denes global buttons that are created in the icon area of all .leo les. You
dene @button nodes in the @buttons tree as usual.
35.4.2 @menus trees
Leo creates its menus from the @menu and @item nodes in the @menus tree. Within @menus trees, @menu
nodes create menus and @item nodes create menu items.
The menu name always follows @menu. If the menu name is Plugins, Leo will create the Plugins menu and
populate the menu by calling the create-optional-menus hook. This creates the Plugins menu as usual. Nested
@menu nodes dene submenus.
The command name follows @item. If the body text of an @item node exists, this body text is the menu name.
Otherwise, the menu name is the command name. However, if the command name starts with a *, hyphens are
removed from the menu name. Menu names and command names may contain a single ampersand (&). If present,
the following character is underlined in the name. If the command name in an @item node is just a hyphen (-),
the item represents a menu separator.
35.5 New plugins
The graphed plugin allows users to manipulate parts of Leo outlines as if they were general graphs. It is still
early days for this exciting plugin.
The threading_colorizer plugin replaces the __jEdit_colorizer__ plugin. This plugin features an elegant new
algorithm that has much better performance and eliminates almost all ash.
35.6 Leos core is now compatible with jython
Essentially all of Leos startup code now runs with jython 2.2 and the (unnished!) swing gui.
35.7 Improved prototype for icons in headlines
The prototype in test.leo now will use PIL (Python Imaging Library) if available, so many more kinds of icons can
be used. Buttons now exist to add icons to do the following:
Add any icon to any node.
Delete all icons from a single node or the entire tree.
Print the icon les associated with a node.
Print the sizes of icons in a directory.
Fixed a bug in the icon handling in the outline widget that caused duplicate icons not to be drawn properly.
35.8 Minor improvements
See the release notes for a list of bugs xed in Leo 4.4.4.
Leo, Release 4.6-b1
Added the clear-all-marks hook.
Added button font setting. See the node: @settings>Fonts>@font button font in leoSettings.leo.
Plugins and scripts may call the c.frame.canvas.createCanvas method to create a log tab containing a
Tk.Canvas widget. Here is an example script:
w = log.canvasDict.get(tag)
if not w:
w = log.createCanvas(tag)
w.configure(bg=yellow)
log.selectTab(tag)
Improved the yank and yank-pop commands and added @bool add_ws_to_kill_ring setting.
Improved the debug command: it now adds the following code to the beginning of debug scripts:
class G:
def es(s,c=None):
pass
g = G()
Added the @bool rst3 strip_at_le_prexes setting.
Added the g.app.inBridge ivar.
Added @bool big_outline_pane setting. False (legacy): Top pane contains outline and log panes. True: Top
pane contains only the outline pane. Bottom pane contains body and log panes.
35.9 Summary of new commands
check-derived-file
check-leo-file
compare-leo-outlines
insert-child
read-at-auto-nodes
read-file-into-node
write-at-auto-nodes
write-dirty-at-auto-nodes
write-file-from-node
35.9. Summary of new commands 263
Leo, Release 4.6-b1
CHAPTER
THIRTYSIX
The highlights of Leo 4.4.3:
@test and @suite nodes may now be embedded directly in derived les.
Added support for chapters in Leos core.
Added support for zipped .leo les.
The new leoBridge module allows full access to all of Leos capabilities from programs running outside of
Leo.
Better support for the winpdb debugger.
Added support for @enabled-plugins and @open-with nodes in settings les.
Removed all gui-dependent code from Leos core.
The__wx_gui plugin is now functional.
36.1 Important new features
@test and @suite nodes may now be embedded in derived les.
Added support for chapters to Leos core
Chapters are regions of a Leo outline whose root is an @chapter node. @chapter nodes may appear any-
where in an outline, but the create-chapter command (see below) creates @chapter nodes as children of a
single @chapters node.
Selecting a chapter shows the nodes in the selected chapter; in this respect, chapters are like hoists. The
main chapter represents the entire outline and can not be deleted by name. When chapters are in effect, Leo
creates a hidden @chapters node containing one @chapter node for every chapter except the main chapter.
Associated settings:
The @bool use_chapters setting determines whether chapters are enabled.
The @bool use_chapter_tabs setting determines whether the chapters pop-up menu appears in the icon
area. Choosing a chapter name from this list selects a chapter.
When chapters are enabled, the Cmds:Chapters menu shows all available chapter commands:
The create-chapter command creates an @chapter node and with a single node.
The delete-chapter command deletes the presently selected chapter.
The select-chapter command makes only the nodes of the selected chapter visible.
The move-node-to-chapter, clone-node-to-chapter and copy-node-to-chapter commands add a node
(and its descendants) to another chapter.
265
Leo, Release 4.6-b1
Added support for compressed .leo les
Leo now has save-le-as-zipped and save-le-as-unzipped commands, and corresponding Save File As
Zipped and Save File as Unzipped items in the File menu. These are exactly the same as Leos Save As
commands except that they temporarily force Leo to write the le in either zipped or unzipped format. Leo
remembers whether a le was originally zipped. The read logic handles either zipped or unzipped .leo
les automatically. The write logic will zip the le if it was originally zipped or if the save-le-as-zipped
command is being executed. Leo writes les with .leo extension, regardless of whether the le is zipped or
not. Zipped .leo les contain a single archive, whose name is the same as the .leo le itself.
Notes: The new save commands sufce to compress and expand .leo les on a le-by-le basis. In partic-
ular, there is no need for any user settings. Outside of Leo you can change the extension to .leo.zip and use
stuft or other program to expand the .leo le contained within. Ive only tested this on XP, but it should
work everywhere...At present the code uses Pythons ziple module to read and write zipped les.
Added leoBridge module. See the leoBridge chapter for full details.
Removed all (or almost all) gui-independent from Leos core.
Improved support for the winpdb debugger. See the debugging with Leo chapter for full details.
36.2 New commands
apropos-debugging-commands
clean-all-lines
clone-node-to-chapter
copy-node-to-chapter
create-chapter
delete-chapter
goto-first-visible-node
move-node-to-chapter
print-plugin-handlers
print-plugins
print-settings
save-file-as-unzipped
save-file-as-zipped
select-chapter
36.3 New settings
@openwith nodes
@enabled-plugins nodes
@bool center_selected_tree_node
@bool chdir_to_relative_path
@bool contractVisitedNodes
@bool force_newlines_in_at_nosent_bodies
@bool invisible_outline_navigation
@bool show_full_tracebacks_in_scripts
@bool use_chapter_tabs
@bool use_chapters
For details of these new settings, see leoSettings.leo
36.4 Plugins
The __wx_gui.py plugin is now minimally functional. Alas, some problems remain. See the bug list in the
plugin for details.
Leo, Release 4.6-b1
Changed bindings in the UniversalScrolling plugin.
Registered the write-restructured-text command in rst3 plugin.
See the release notes for a list of the many bugs xed in Leo 4.4.3.
Warn on dubious section brackets. For details, see http://sourceforge.net/forum/message.php?msg_id=4162357
Added Find and Spell tabs to log pane on startup. The spell tab is only shown if Aspell was properly
imported.
Added shortcuts for goto-rst/last-sibling commands.
Made escape in the minibuffer work like ctrl-g.
Only do one message re writing recent les.
Added handleUrlInUrlNode helper for OnIconDoubleClick.
Made copied nodes valid Leo les. For details, see http://sourceforge.net/forum/message.php?msg_id=4014079
changeAll now works like ndAll
Clear status line in repeat-complex-command.
36.5. Minor improvements 267
Leo, Release 4.6-b1
CHAPTER
THIRTYSEVEN
This page summarizes the changes made in Leo 4.4.2 For full details see the release notes section in LeoDocs.leo.
37.1 A major code reorg
Leos vnode and tnode classes are now completely independent of the rest of Leo. Some apis have been changed.
This big reorg and may affect scripts and plugins.
37.2 New commands
extend-to-line
extend-to-paragraph
extend-to-sentence
forward-end-word
forward-end-word-extend-selection
37.3 New features
Added support for controlling Leo from Emacs with pymacs. See Chapter 18: Leo and Emacs for full
details.
Added Minibuffer and Settings submenus of the Cmds menu.
At long last Leo creates a proper help menu on the Mac.
Added a new convention for menu tables. If the rst item (a string representing the menu label) starts
with * Leo will convert hyphens to spaces and upcase the label. This convention allows a single string
to represent both the menu label and its associated minibuffer command. As part of this reorganization,
all menu tables in Leos core now use only strings. This is an essential precondition to supporting @menu
nodes in leoSettings.leo.
Leos Help menu now contains the Open scripts.leo command.
Leo uses ctypes to import Aspell when run from Python 2.5 or later. Leo no longer needs Python-specic
versions of aspell.dll.
Added support for x-windows middle-button paste. This only works when the paste is made in the pane
containing the selected text.
Leo looks for myLeoSettings.leo les in the same place Leo looks for leoSettings.leo les.
Created three scripts (in test.leo) that help create unit tests for Leos edit commands. Create Created runEd-
itCommandTest for use by these scripts.
269
Leo, Release 4.6-b1
Improved print-bindings command. The bindings are sorted by prex: this is a big help in understanding
bindings. For each prex, rst print items with only a single character after the prex.
Made writing .leo les faster. The new code almost exactly twice as fast as the old.
Added p.archivedPosition. This is a key rst step towards Leap 204.
Integrated sax with read logic.
You can now store settings in myLeoSettings.leo without fear of those settings being changed by cvs updates
or in future versions of Leo.
Eliminated unnecessary redraws when moving the cursor in the outline pane.
Much faster navigation through the outline using Alt-arrow keys.
When focus is in the outline pane, you can move to headlines by typing the rst letter of headlines.
The nd command now closes nodes not needed to show the node containing the present match.
Numerous changes that make Leo easier to use without using a mouse.
Many new minibuffer commands now appear in the Cmds menu.
Further improved outline navigation:
Generalized navigation in outline pane to ignore @le, @thin, etc prexes.
Made outline navigation cumulative. When keystrokes in the outline pane are typed close together Leo
rst tries to look for prex + ch, where ch is the character just typed and prex is the previous match.
The term close together is specied by the setting @oat outline_nav_extend_delay. The outline search
revers to a single-character if the extended search fails, so in fact the delay is not too signicant. In practice
everything works well without me thinking at all about what is happening.
Improved the mod_scripting plugin. Every button created by the plugin creates a corresponding command.
The command name is the cleaned version of the button name. Likewise, the plugin also creates a delete-
x-button command, where x is the command name as just discussed. So now you can delete script buttons
without right-clicking.
Made About Plugin dialog scrollable.
Fixed bugs in groupoperations, multile, nodenavigator and shortcut_button plugins.
The rst3 plugin now registers the rst3-process-tree command.
The leoOPML.py plugin denes commands to read and write OPML les.
The slideshow.py plugin allows Leo to run slideshows dened by @slideshow and @slide nodes.
The leo_to_rtf and leo_to_html plugins create rtf and html les from Leo outlines.
The paste_as_headlines.py plugins creates multiple headlines at once.
The word_count.py plugin.
Improved the mod_scripting plugin:
Made showing the Run Script button optional.
The Script Button button now creates the press-script-button-button command.
A new utility method does a much better job of massaging button and command names.
Leo, Release 4.6-b1
37.5 Settings
Removed .leoRecentFiles.txt from the distribution and cvs and added @bool write_recent_les_as_needed.
The presence or absence of .leoRecentFiles.txt no longer controls whether Leo creates and updates .leoRe-
centFiles.txt.
Added @bool insert_new_nodes_at_end.
Added @bool select_all_text_when_editing_headlines. Creating a new node always selects the entire text,
regardless of this option.
Leo looks for myLeoSettings.leo les in the same place Leo looks for leoSettings.leo les.
Added settings for all mod_scripting switches.
Added @bool collapse_nodes_during_nds. This greatly speeds searches that used to open many nodes.
See: http://sourceforge.net/forum/message.php?msg_id=3935780
Added @bool outline_pane_has_initial_focus.
Added @bool sparse_move_outline_left.
Added bindings for Alt-Shift-Arrow keys to force an outline move.
Added @bool use_sax_based_read = False. True: Use a sax-based parser to read .leo les. This is slower
than using Leos legacy xml parser, but may solve some unicode problems.
Changed default settings:
focus-to-body = Alt-D
focus-to-tree = Alt-T
toggle-extend-mode = Alt-3
37.6 ZODB scripting
Leos vnode and tnode classes can optionally be compatible with ZODB databases, i.e., they can optionally derive
from ZODB.Persistence.Persistent. See Chapter 17: Using ZODB with Leo for details.
37.5. Settings 271
Leo, Release 4.6-b1
CHAPTER
THIRTYEIGHT
This page summarizes the changes made in Leo 4.4.1. For full details see the release notes section in LeoDocs.leo.
The main features of Leo 4.4.1 are:
Multiple editors in Leos body pane and
A new colorizer plugin controlled by jEdit language description les.
Search commands now support regex replace patterns: 1, 2, etc.
Support for external debuggers: see http://webpages.charter.net/edreamleo/debuggers.html
The scripting plugin now creates a Debug Script button.
Several new commands including run-unit-test, python-help and toggle-invisibles.
The help-for-command commands now contains information for almost all commands.
A new shortcut_button plugin.
38.1 New commands
cycle-focus
debug
find-character
find-word
hide-invisibles
isearch-with-present-options
open-users-guide
python-help
run-unit-test
toggle-autocompleter
toggle-calltips
toggle-invisibles
38.2 New features
Removed warning about changed node.
Added scroll-outline-left/right commands.
Leo outputs decorators correctly, assuming the decorator does not conict with a Leo directive.
Wrote script to convert g.es to g.et where appropriate. The rst step in translating all Leo messages.
Leo highlights (ashes) matching brackets when typing typing (, ), [, ], { or }.
273
Leo, Release 4.6-b1
Fixed long-standing problem reporting indentation errors.
Fixed long-standing bug in Remove Sentinels command.
Fixed long-standing bugs in import commands.
The scroll-up/down commands now scroll the outline if focus is in outline pane. However, his can be done
better using per-pane bindings as in the default leoSettings.leo.
Incremental searches are (properly) conned to a single body text.
Backspace now handled properly in incremental searches.
The add-editor command adds a new editor in the body pane. The delete-editor command deletes the
presently selected editor, and the cycle-editor-focus command cycles focus between editors in the body
text.
The standard 1, 2, etc. replacements can now be performed in regular expression searches.
The standard escapes n and t are now valid in plain searches.
The shortcut for the replace-string command now changes from the nd command to the replace command.
The slideshow plugin
The mod_scripting plugin now creates a press-x-button command for every button x. You can specify
settings for such commands using @shortcuts nodes.
The shortcut_button plugin plugin creates a Shortcut button in the icon area. Pressing the Shortcut button
creates another button which when pressed will select the presently selected node at the time the button was
created.
Added Debug button to scripting plugin.
38.4 New settings
@bool autoindent_in_nocolor_mode
@bool flash_matching_brackets
@bool idle_redraw
@bool trace_bind_key_exceptions
@bool warn_about_redefined_shortcuts
@color flash_brackets_background_color
@color flash_brackets_foreground_color
@int flash-brackets-delay
@int flash_brackets_count
@string close_flash_brackets
@string open_flash_brackets
@string editor_orientation
38.5 Improved settings
Added @font menu font setting.
Added support for commands to be executed on entry to a mode.
Added support for bindings that are active only in command, enter and insert key states.
Leo, Release 4.6-b1
Added support for @abbrev nodes in leoSettings.leo.
Improved check bindings script in leoSettings.leo.
Allow @mode outside of leoSettings.leo.
Added warnings about the @bool expanded_click_area setting.
The print-bindings command now properly sorts bindings.
The help-for-command command now works for almost all commands.
Improved lename completion.
Better listings for print-commands and print-bindings & mode-help commands.
Allow shortcuts to be overridden outside of leoSettings.leo.
Finished Cmds menu.
Improved show-fonts command.
Strip quotes from color, font settings.
Warn about invalid Enter and Leave key bindings.
38.6. Minor improvements 275
Leo, Release 4.6-b1
CHAPTER
THIRTYNINE
This page summarizes the changes made in Leo 4.4. For full details see the release notes section in LeoDocs.leo.
The main features of Leo 4.4 are:
An Emacs-like mini-buffer: you can now execute any command by typing its long name, with tab comple-
tion.
Many new commands, including cursor and screen movement, basic character, word and paragraph manip-
ulation, and commands to manipulate buffers, the kill ring, regions and rectangles. You can use Leo without
using a mouse.
Flexible key bindings and input modes. You can emulate the operation of Emacs, Vim, or any other editor.
A tabbed log pane. The Find and Spell Check commands now use tabs instead of dialogs, making those
commands much easier to use. Plugins or scripts can easily create new tabs. The Completion tab shows
possible typing completions.
Autocompletion and calltips. Autocompletion works much like tab completion. To enable autocompletion,
bind a key to the auto-complete command.
39.1 New commands
activate-cmds-menu
activate-edit-menu
activate-file-menu
activate-help-menu
activate-outline-menu
activate-plugins-menu
activate-window-menu
add-space-to-lines
add-tab-to-lines
clean-lines
clear-selected-text
click-click-box
click-headline
click-icon-box
clone-find-all
contract-and-go-right
contract-body-pane
contract-log-pane
contract-outline-pane
contract-pane
double-click-headline
double-click-icon-box
dump-all-objects
dump-new-objects
277
Leo, Release 4.6-b1
expand-body-pane
expand-log-pane
expand-outline-pane
expand-pane
find-again
find-all
find-tab-change
find-tab-change-all
find-tab-change-then-find
find-tab-find command
find-tab-find-previous
free-text-widgets
fully-expand-body-pane
fully-expand-log-pane
fully-expand-outline-pane
fully-expand-pane
goto-first-sibling
goto-global-line
goto-last-sibling
help
help-for-command
hide-body-pane
hide-find-tab
hide-log-pane
hide-minibuffer
hide-outline-pane
hide-pane,
open-find-tab
open-find-tab
open-outline-by-name (uses filename completion)
open-spell-tab
print-bindings
print-commands re-search-backward
re-search-forward
remove-space-from-lines
remove-tab-from-lines
replace-string
scroll-down
scroll-down-extend-selection
scroll-outline-down-line
scroll-outline-down-page
scroll-outline-up-line
scroll-outline-up-page
scroll-up
scroll-up-extend-selection
search-backward
search-forward
search-with-present-options
set-find-everywhere
set-find-node-only
set-find-suboutline-only
show-colors
show-fonts
show-minibuffer
show-search-options
simulate-begin-drag
simulate-end-drag
toggle-find-ignore-case-option
toggle-find-in-body-option,
toggle-find-in-headline-option
toggle-find-mark-changes-option
toggle-find-mark-finds-option
Leo, Release 4.6-b1
toggle-find-regex-option
toggle-find-reverse-option
toggle-find-word-option and
toggle-find-wrap-around-option
toggle-mini-buffer
verbose-dump-objects
word-search-backward
word-search-forward
39.2 New features
Added script to update new copies of leoSetttings.leo from previous copies.
Made all edit command undoable.
Improved registerCommand.
Suppressed autocompletion after numbers.
Added colorizing support for Lua language.
Added run-unit-test command.
Autocompletion and calltips.
Leo remembers the previous open directory.
Fixed problem with view plugin.
Installed cleo patch.
User input modes.
Installed many standard bindings to leoSettings.leo.
Added Check Bindings script in leoSettings.leo.
Scripts now maintain original focus.
Improved cursor move/extend commands.
Added support for @mode nodes.
keyboard-quit restores default input mode.
Created ut.leo, ut.py and ut.bat.
Added modes/*.xml to distribution.
Revised cursor movement commands and added selection-extension commands.
Added classic key bindings in leoSettings.leo.
Allow multiple key bindings to the same command.
Settings command now opens leoSettings.leo.
Moved all scripts into scripts.leo.
Improved how the New Tab and Rename Tab commands work in the log pane.
Improved the appearance of the Spell tab.
Added Clone-nd checkbox to the Find tab.
Improved nd tab.
39.2. New features 279
Leo, Release 4.6-b1
Improved formatting of shortcuts in print-commands and print-bindings.
Added settings for vim plugin.
Put up a dialog if cant import Pmw.
Bound <Return> to end-edit-headline.
Leo now ignores key bindings in menu tables.
Created scripts.leo and unitTest.leo.
c.executeMinibufferCommand executes a minibuffer command by name.
Improved perl entries in language dicts.
The tabbed log.
The Find tab replaces the old Find panel; the old Find panel is deprecated.
39.3 Added new convenience methods for scripts and plugins
The c.frame.logcreateCanvas convenience method create a canvas tab in the log pane. Here is a sample script:
w = log.canvasDict.get(tag) if not w: ..w = log.createCanvas(tag) ..w.congure(bg=yellow)
log.selectTab(tag)
Changed path to stylesheet in the rst3 plugin.
Fixed crasher in Word (and other) plugins.
Fixed problem with labels plugin.
Added the following commands for the groupoperations plugin:
group-operations-clear-marked
group-operations-mark-for-copy
group-operations-mark-for-move
group-operations-mark-for-clone
group-operations-mark-target
group-operations-operate-on-marked
group-operations-transfer
Installed cleo patch.
The scripting plugin now supports shortcuts in @button nodes:
@button name @key=shortcut
The scripting plugin now supports @command nodes:
@command name @key=shortcut
Leo, Release 4.6-b1
39.5 New and improved settings
Added new settings:
@bool allow_idle_time_hook
@bool autocomplete-brackets.
@bool gc_before_redraw
@bool minibufferSearchesShowFindTab
@bool show_only_find_tab_options
@bool show_tree_stats
@bool trace_autocompleter
@bool trace_bindings
@bool trace_doCommand
@bool trace_f.set_focus
@bool trace_focus
@bool trace_g.app.gui.set_focus
@bool trace_gc
@bool trace_gc_calls
@bool trace_gc_verbose
@bool trace_key_event
@bool trace_masterClickHandler
@bool trace_masterCommand
@bool trace_masterFocusHandler
@bool trace_masterKeyHandler
@bool trace_minibuffer
@bool trace_modes
@bool trace_redraw_now
@bool trace_select
@bool trace_status_line
@bool trace_tree
@bool trace_tree_alloc
@bool trace_tree_edit
@bool useCmdMenu
@bool useMinibuffer
@bool use_syntax_coloring
@color body_text_selection_background_color
@color body_text_selection_foreground_color.
@color log_pane_Find_tab_background_color
@color log_pane_Spell_tab_background_color, etc.
@int max_undo_stack_size,
@string trace_bindings_filter
@string trace_bindings_pane_filter
Added @shortcuts nodes.
Leo now supports per-pane bindings of the form:
command-name ! pane = shortcut
The spelling settings replace the settings in spellpyx.ini.
39.5. New and improved settings 281
Leo, Release 4.6-b1
CHAPTER
FORTY
INDICES AND TABLES
Index
Module Index
Search Page
283

Python Leodocumentation

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Python Leodocumentation

Încărcat de

Drepturi de autor:

Formate disponibile

Leo

S-ar putea să vă placă și