.. rst3: filename: leoUserGuide.txt


@language rest

.. This node represents the entire users guide.
.. It may be useful for generating the pdf docs.

@all

Front matter
++++++++++++


@language rest

@rst html\frontMatter.html
*********************


############
Front Matter
############

.. .. contents::


.. External links...
.. _`Open Software`:    http://www.opensource.org/
.. _Python:             http://www.python.org/
.. _`SourceForge`:      http://sourceforge.net/projects/leo/

.. Relative links...
.. _clones:             intro.html#clones-views
.. _leo:                front.html
.. _outline:            intro.html#introduction
.. _outlines:           intro.html#introduction
.. _plugins:            intro.html#plugins-settings
.. _scripting:          intro.html#scripting-leo
.. _users:              http://sourceforge.net/projects/leo/

Acknowledgements
^^^^^^^^^^^^^^^^


Leo owes much of its visual design to ``MORE``, possibly the most elegant
computer program ever written. Leo's 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, Wenshan 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 Munslow,
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 Schöön, Wolfram Schwenzer, Casey Wong Kam Shun,
Gil Shwartz, Jim Sizelove, Paul Snively, Jurjen Stellingwerff, Phil Straus, David Szent-Györgyi,
Kent Tenney, Jeffrey Thompson,
Gabriel Valiente, 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,
Frédéric Momméja, 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 Leo's 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 Leo's minibuffer.
LeoUser also wrote jyLeo: Leo for Jython.
Bernhard Mulder proposed a new way of untangling derived files.
John K. Ousterhout created tcl/Tk. Neal Norwitz wrote PyChecker.
Marc-Antoine Parent urged me to use XML for Leo's file format and helped improve it.
Paul Paterson suggested the plugin architecture,
suggested an approach to spell checking and has contributed many excellent plugins.
François 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.
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 first step.

Leo's MIT License
^^^^^^^^^^^^^^^^^


All parts of Leo are distributed under the following copyright. This is intended
to be the same as the MIT license, namely that Leo is absolutely free, even for
commercial use, including resale. There is no GNU-like "copyleft" restriction.
This license is compatible with the GPL.

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

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

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

**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 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.**

Preface
+++++++


@language rest

@rst html\preface.html
*****************


############
Preface
############

.. .. contents::


.. links...
.. _`SourceForge`:      http://sourceforge.net/projects/leo/
.. _`noweb`:            http://www.eecs.harvard.edu/~nr/noweb/
.. _reStructuredText:   http://docutils.sourceforge.net/rst.html

.. _outline:            intro.html#introduction
.. _plugins:            intro.html#plugins-settings
.. _scripting:          intro.html#scripting-leo
.. _users:              http://sourceforge.net/projects/leo/

.. _`cloned nodes`:     intro.html#clones-views
.. _`derived files`:     intro.html#derived-files

.. _`Chapter 14\: Using the Rst3 Plugin`:           rstplugin3.html


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 IDE's. How can Leo possibly compete with such strong competition? What does Leo offer that these other tools don't? 

Leo does have something unique to offer--something missing from Emacs,Vim, Visual Studio and Eclipse. Leo's 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. We'll see why in a moment. 

In architectural terms, nodes are bricks that make up a building. In computer
programming terms, nodes make up methods, classes, files and entire
applications. So the term 'node' does *not* have a fixed meaning--it 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 specific things: 

1. Because nodes are true objects, Leo commands understand what a node is, and
   where a node fits into the entire outline. I'll 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 node's parent,
   children and siblings are real properties of the node, *completely
   independent* of the node's headline or body text. Furthermore, any of Leo's
   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 *something 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 Leo's commands. For example,
   headlines that start with @thin, @file, @asis, @auto, etc. serve to guide and
   control Leo's read and write commands. Headlines that start with @test,
   @suite and @mark-for-unit-tests guide Leo's unit testing commands. Moreover,
   it is easy to create new conventions for headlines that control user-written
   scripts or plugins. For example, plugins define specific meanings for
   headlines that start with @url, @rst, @bookmark, @slideshow, etc., etc. So
   the separation of headline and body text, **as true components of a node
   object**, is a very big deal.

3. One application of these ideas deserves special mention. Leo's scripting
   plugin provides support for @button nodes. The headline is @button
   <command-name>. The body text contains a script. When Leo opens 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 aren't 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 descendants of any node--changing 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 'architecture'. 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-specified* 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. 

That's 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. Leo's **chapters** are simply views created as I have just described. When you select one chapter, you only see the nodes of that chapter in Leo's 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 experience is this:
Outlines are more than mere eye candy. Having organization be real data creates
an entirely new dimension, literally and figuratively, in computer programming,
computer design and data organization, including web-site design, database
design, etc. Leo's commands use headline and body text in many creative ways. So
can you and your scripts. It's easy, it's fun, and it's revolutionary.

That's 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 won't learn it all in a day or so.
   Please be patient. Start by learning Leo's 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 shamelessly 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 Leo's 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

What people are saying about Leo
++++++++++++++++++++++++++++++++


@language rest

@rst html\testimonials.html
**********************


###################################
What People Are Saying About Leo
###################################

.. .. contents::


.. Relative links...

.. _quotes:         testimonials.html
.. _toc:            leo_TOC.html

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 it's 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 isn't the main focus any more.
You focus on the non-linear, hierarchical, collapsible outline of the source code." -- Korakot Chaovavanich

"Leo is a quantum leap for me in terms of how many projects I can manage and
how much information I can find and organize and store in a useful way." -- Dan Winkler

"Wow, wow, and wow...I finally understand how to use clones and I realized that this is exactly how I want to organize my information.
Multiple views on my data, fully interlinkable just like my thoughts." -- Anon

"Edward... you've 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

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 what's 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 can't other Open Source projects change the way I think?" -- Anon

Leo is fun, even addicting
^^^^^^^^^^^^^^^^^^^^^^^^^^


"When first I opened Leo, it was out of curiosity. But having used it...I'll never go back.  They'll have to pry Leo out of my cold, dead fingers!  Seriously, it should be renamed 'Crack Cocaine' because it's that addictive. I'm 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...I'm already bursting with new ways I'd like to use the tool in the future." -- Lyn Adams Headley

Thanks for the great work--I love Leo!!! -- Josef Dalcolmo

Leo has simplified 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

Leo is a flexible, 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 doesn't 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 2--3 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 IDE's like Idle. Leo clearly solves that problem and in a way that commercial tools can't touch." -- Marshall Parsons

"I have been using Leo for about 3 weeks and I hardly use my other programming editor anymore...I find it easy and enjoyable to use. I plan to adopt it as my presentation tool for code reviews." -- Jim Vickroy

"I'm absolutely astounded by the power of such a simple idea! It works great and I can immediately see the benefits of using Leo in place of the standard flat file editor." -- Tom Lee

I think you're 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

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 files 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 files, hierarchically grouped into folders,
with hierarchical or sequential organization of text within the files, and
without arbitrary limits on the size and number of files and the depth of the
hierarchy of folders and text nesting within the files." -- Alex Abacus

"Leo reminds me a great deal of things I loved when I used Userland's Frontier
(an outlining cms with a native oodb) - but Frontier wasn't hackable enough for
me, and it wasn't oriented towards coding and literate programming, and you
couldn't round-trip rendered pages (big Leo win). This is really a super tool -
in a matter of days I've started to use it on all my projects and I still
haven't figured out how I lived without it." -- John Sequeira

"Leo is EXACTLY the kind of outliner I was looking for--fantastic job!"
-- Steve Allen

"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

Leo is an excellent PIM
^^^^^^^^^^^^^^^^^^^^^^^


"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. It's sooo much better than anything the browsers have built in and it lets me easily use different browsers on different platforms and different machines (try that with the browsers' built-in bookmark managers)." -- Dan Winkler

"I am an amateur photographer. I use plain old 35mm. film for my pictures. Over the weekend, I used Leo to organize my lists of pictures. It is quite helpful--I 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!... Leo's 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 I'm done, I'll have some nice libraries...I can re-use later in other projects." -- Michael Manti

Leo extends, completes and simplifies literate programming
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


"I've tried Literate Programming tools off and on for more than 10 years, mainly because the promise was so great. I've abandoned them every time because working with the various Cweb-like tools was so awkward. Leo changes all that. The most important benefits promised by Literate Programming are realized by using Leo, without the awkwardness of the other tools." -- Dave Hein

"[Leo] has enabled me to use Literate Programming in production for the first time. When I figured out I could do it in plain text and export to DocBook for automated typesetting, I was on my way. Because I only do business and utility software, I don't 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 you've put into Leo.  It looks fantastic.  I've always though that Literate Programming was a good idea, but the tools were completely un-workable. -- Bob Hustead

Leo is a superb documentation tool
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


"I've written documentation in WordPerfert, Ventura, Word, PageMaker, and FrameMaker and even though they create wonderfully looking and useful documents, they've never been able to do what I've been looking for. HTML, compiled help files, and later PDF came closer, but still not there...I think I've found it in LEO, a way to make a "living" document. A document built out of discrete parts that can be re-organized on the fly to meet the needs of a varying audience...I've already started converting the IT Procedures manual from Open Office to LEO because I know it's going to be much more useful to me and anyone else...just the possibility of keeping system maintenance scripts in the IT manual is mind boggling." -- David Nichols

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

"A Leo file is an ideal documentation tool, collecting the assorted readme.txt files, the comments from the source files...as well as the config files themselves." -- Kent Tenney

Leo simplifies the understanding of complex systems
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


"Just as structured programming reveals and disciplines the flow 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 people's code, Leo makes the code's 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: 'You'd 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 it's 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 else's 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 isn't doubling every few months like it would be in another designer's hands. Adding features by removing constraints, hot refactoring while adding unit tests. Forget the book. I would pay to see the movie."

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 find 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 first 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

Longer quotes...
^^^^^^^^^^^^^^^^



Speed Ream's 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 files that are written using Leo.

My comments are from two points of view, the first being software project manager for a complicated, multi-module software product, and the second being as a production line coder. For me, Leo’s 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 don’t teach him Leo, even though all source code in our company must reside in Leo files for the reasons I won’t go into now.

I consider that my coders are 15 to 30 percent more efficient in their daily operations than my competition’s 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 first sitting down to solve a new problem.
   Then the documentation becomes quite long-winded and pontificatory,
   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 find the documentation insufficient to
   understand 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 Leo’s outlining and organizing ability, and Leo’s ability to create source files from within the outline that give me what I think is a tremendous competitive advantage. Each of my company’s products run on all versions of windows from Win 3.1 to XP. In our flagship software piece, there are ten main modules, and each module is maintained by one single Leo file. In the CODEC module, one Leo file named compress.leo organizes and creates seven .asm files, forty-four .c files, twenty .h files, two .def files, four .mak files, etc. etc. etc. This one file 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 definition that must change between different versions of Windows. These sections could be from six different c source files, two assembly files, and eight .h files. Another clone section groups together those sections relating to memory problems, which change according to the memory configuration and TSR configuration (or lack thereof) on the target machine. Another clone section groups sections that fail (or don’t 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 fixed when the engineer who fixed the bug grouped a bunch of routines, definitions, etc. together to fix the bug.

None of the above clone sections was ‘designed’ into the document. Just the opposite happens. When the codec was first written, there was just a single Leo file 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 fixed. 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 fix (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 can’t begin to describe it. A ‘REVERSE LEARNING CURVE’ happens when an engineer gets a Leo file 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 find this particularly true in my own case. Often I’ll look at some code that seems totally unfamiliar and think ‘what idiot wrote this crap’. Then I’ll 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.

Joe Orr
~~~~~~~


The Word outlines are very useful. But Leo makes Word look like a clunky toy.

#1 Reason would probably be clone nodes. One node can point to another. Another
way of putting this is is that a leaf can be on more than one tree. For
example, suppose you have a list of recipes. You simultaneously put a single
recipe under multiple categories or even multiple hierarchies. You could put "3
bean enchilada" simultaneously under Recipes-Mexican and Food-Gas. Another
example would be, if you are a biologist trying to decide under which genus to
put a new species, you could put the species under two simultaneously. In
effect, you can build a 3-D tree. For a further illustration see
http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htm

#2 Reason would probably be that Leo outlines can be embedded in external text
files. So, a Leo outline is more than an outline, it is a meta-structure that
can be added to another text without changing that text, but rather providing
an external road map to the text. Microsoft Word has a text (xml) version with a
commenting convention, so Leo can even be used to add outlines into Word docs,
although it isn't 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 file to which
the meta-structure is being applied, viewed one node at a time.

I may not have made #2 very clear, but it is actually a very useful feature. It
takes some getting used to before one sees all of the possibilities tho. One
way to think of it is that Leo allows you to throw external documents into your
outline, and yet the external document remains independent and can still be
edited separately.

Some other cool things about Leo which Word doesn't 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 files can be transformed pretty easily
to web pages with their outlining capability intact.
2. Easy to add features since is programmed in Tk and open source. Maybe
your average user can't start hacking on it, but a surprising amount can be
tacked on by flipping through the Tk manual.
3. Free, opensource, multi-platform
4. Leo is scriptable with Python. It should be possible to build a Tickler
into Leo using Python scripting, for example.

Dan Winkler
~~~~~~~~~~~


First of all, kudos to you for the excellent progress you've 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 you're really showing what open source can do and your current trajectory puts you on track to kick Emacs into the dustbin of computing history.

So today I copied all my data (personal information manager and project management stuff) out of my old outliner (ThoughtManager, which syncs with and runs on the Palm) and put it into Leo.  It took me hours to do it and then to rearrange it the way I really wanted it.  But having the ability to make clones and have different ways to view my data is, as you know, fabulous.  In my case, for personal information and project management things, I used the flexibility of clones to allow me to see my data in several different views: 1) by project, the logical hierarchical breakdown by topic, 2) by person, so whenever I'm 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 I'm going to focus on in the coming hours.

Now here's why I don't miss the ability of my old outliner to synch the entire outline with the Palm.  It turns out the main thing I really want in the Palm is the top category "Today" so all I have to do is have Leo flatten that one heading into a text file (and it kindly remembers the name and directory of the file I used last time) and then I'm done because I've told the Palm Hotsync manager that that file should be sent to Palm memo pad every time I synch.  The Palm Hotsync manager does a nice job of sending a text file to the Palm memo pad and even breaks the file up into multiple memo records if it's too big to fit in just one.  So that gives me enough to be able to browse (or full text search) the small amount of data that I really want right inside my Palm (which is also my cell phone).  Quick and dirty but it works.

For times when I want my whole outline with me, Leo wins again because thanks to its cross platform nature I can take my whole outline with me on my Mac iBook, even though I usually edit it on a Windows PC (which is the only kind of machine my old outliner would run on).  Quite frankly, although my old outliner was able to shoehorn the whole thing into my palm/cellphone, it was a pain to access it on the small screen and slow processor.  Now when I anticipate I'll need the whole thing, for example when I'm going to a meeting, I can put it on my Mac iBook (under X and Fink for now until Python can do it native under Aqua) and have real, full access to it all.

I think now in addition to being great for programming Leo is also a great PIM.  Being able to flatten a strategically chosen portion of the outline into a known file 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 @flatten directive so I can have that done automatically for me every time I save my outline?  For now it's up to me to flatten the node I want manually, although once I've done that the transfer to the Palm is automatic.

You're my hero!  Thank you so much.

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.  It's 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, they're not 
just for web pages or HTML documents;  I can link to any file 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 find and organize and store in a useful 
way.  I'm a data-mining army of one now and the web is my playground. 
Every time I find a web page that has interesting links to others, 
those links get stored in my Leo outline too, right where I can find 
them and make practical use of them.  I can easily accept dozens of 
valuable links every day and integrate them into what I'm doing in a way 
that I'm confidant they won't get lost or forgotten.  Before I always 
used to get bogged down by the difficulty of managing bookmarks inside 
the browser.  But now I'm no longer the victim of information overload 
buried in the knowledge landslide of the Internet;  instead I'm the 
professional strip miner with the world's 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 flexible thing where I can reorganize and prioritize and 
massage the data to my heart's content as I learn more about it and 
decide to use it in different ways for different purposes.  It's the 
difference between the pick axe and the steam shovel for me.

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 file 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 fill in 
additional numbers just by typing them and can even annotate them with 
comments.  So in the middle of generating a LaTeX file 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

That's 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 I'd also like some more processing done 
on those tables (which I had to do by hand this time) -- I'd like the 
rows sorted in reverse order by magnitude (so that the big numbers jump 
out at you from the start of the tables) and I'd 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 I'll use 
s-expressions that generate whole tables, formatted for LaTex, from the 
underlying data.  So I'm 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.  It's sort of a poor 
man's 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, I'd 
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

FAQ
++++


@language rest

@rst html\FAQ.html
*************


####
FAQ
####

This is Leo's Frequently Asked Questions document.

.. .. contents::
..    :depth: 2


.. Links used in this document...

.. ----- External links.

.. _`cvs repository`:   http://sourceforge.net/cvs/?group_id=3458
.. _decorator:          http://www.python.org/peps/pep-0318.html
.. _docutils:           http://docutils.sourceforge.net/
.. _unicode:            http://www.unicode.org/
.. _`bzr repository`:   https//code.launchpad.net/leo-editor/

.. ----- Relative links into Leo's documentation.

.. _`Associating Leo with .leo Files`:  install.html#how-to-associate-leo-with-leo-files-on-windows
.. _`How to install Leo on Windows`:    install.html#how-to-install-leo-on-windows

.. _`CWEB mode`:                                directives.html#cweb-mode
.. _command:                                    commands.html
.. _commands:                                   commands.html
.. _`quick start for programmers`:              intro.html#quick-start-for-programmers
.. _`rst3 plugin`:                              rstplugin3.html

.. _`Tangle and Untangle`:                      commands.html#tangling-an-outline-producing-derived-files
.. _tutorial:                                   intro.html
.. _`Leo 4.0: Eliminating error 'recovery'`:    history.html#leo-4-0-eliminating-error-recovery
.. _`Chapter 9: History of Leo`:                history.html
.. .. _`Run Leo in a console window`:            `How can I run Leo from a console window?`_
.. _`Run Leo in a console window`:              install.html#running-leo-from-a-console-window
.. _`run Leo in a console window`:              install.html#running-leo-from-a-console-window
.. _`console window`:                           install.html#running-leo-from-a-console-window

.. ----- References to the glossary: the glossary now contains references to the tutorial.
.. _`@asis`:                glossary.html#asis-trees
.. _`@auto`:                glossary.html#auto-trees
.. _`@file`:                glossary.html#file-trees
.. _`@others directive`:    glossary.html#others
.. _`@noref`:               glossary.html#noref
.. _`@nosent`:              glossary.html#nosent
.. _`@root`:                glossary.html#root
.. _`@shadow`:              glossary.html#shadow-trees
.. _`@thin`:                glossary.html#thin-trees
.. _`@unit`:                glossary.html#unit
.. _`body text`:            glossary.html#body-text
.. _cweb:                   glossary.html#cweb
.. _directive:              glossary.html#directive
.. _directives:             glossary.html#directives
.. _`derived file`:         glossary.html#derived-file
.. _`derived files`:        glossary.html#derived-files
.. _headline:               glossary.html#headline
.. _headlines:              glossary.html#headlines
.. _node:                   glossary.html#node
.. _nodes:                  glossary.html#nodes
.. _outliner:               glossary.html#outliner
.. _sections:               glossary.html#sections
.. _`section name`:         glossary.html#section-name
.. _`section names`:        glossary.html#section-names
.. _sentinels:              glossary.html#sentinels
.. _`sentinel line`:        glossary.html#sentinel
.. _`sentinel lines`:       glossary.html#sentinel
.. _setting:                glossary.html#setting
.. _settings:               glossary.html#settings
.. _tangle:                 glossary.html#tangle
.. _untangle:               glossary.html#untangle

Getting Leo
^^^^^^^^^^^






**Where can I get official releases of Leo?**


You can get the latest official releases of Leo at
http://sourceforge.net/project/showfiles.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 Leo's launchpad site?**


Many users will want to track the development version of Leo, in order to stay
on top of the latest features and bugfixes. Running the development version is
quite safe and easy, and it's 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 standalone 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
   recommended as it's the easiest one to install. It provides command like
   ``bzr qlog``, ``bzr qannotate`` etc.

2. Get Leo from launchpad by doing::

    bzr branch lp:leo-editor

And that's it! You can run the launchLeo script (in the top-level branch directory) directly.
When you want to refresh the code with latest modifications from Launchpad, run ``bzr pull``.

If you make modifications to Leo (with the interest in sharing them with the Leo
community), you can check them in to your local branch by doing ``bzr checkin``.
Now, to actually request your changes to be merged to Leo trunk, you need a
Launchpad account with RSA keys in place. There is showmedo video about how to
accomplish this 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 fill in descriptive details about the branch. After
that, go to the branch home page from Code tab again, and copy-paste the push
command line to terminal. For example, for branch::

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

The push command is::

 bzr push bzr+ssh://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.

-- 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/

Installing Leo
^^^^^^^^^^^^^^






**Leo's installer failed, what do I do?**


You can simply unpack Leo anywhere and run from there.  You don't 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 Leo's 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 doesn't work (or puts up a dialog containing no text), you may install Leo from the .zip file
as described at `How to install Leo on Windows`_.
However you are installing Leo,
be sure to `run Leo in 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 pack's 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 doesn't work.  Why not?**


Leo's setup.py script is intended only to create source distributions. It can't
be used to install Leo because Leo is not a Python package.

Learning to use Leo
^^^^^^^^^^^^^^^^^^^






**What's 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 Leo's source code in the file ``LeoPy.leo``.
Spend 5 or 10 minutes browsing through the outline. Don't 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 define more than one class in single file.

-   Most other files show how to use a single ``@others`` directive to define one class.

-   Most methods are defined using ``@others``, *not* section definition nodes.


**Why should I use clones?**


.. _`Clones & views`:   intro.html#clones-views

You will lose much of Leo's power if you don't 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 flexibility 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.

- You must explicitly tangle_ and untangle_ `@root`_ trees using the `Tangle and Untangle`_ commands.

However, `@root`_ trees are more flexible than ``@thin`` trees:

- Sections_ may be defined anywhere within ``@root`` trees.
  Moreover, the `@unit`_ directive_ expands the scope of section definitions in ``@root`` trees
  so that a section may be referenced in several ``@root`` trees.

- The meaning of section definitions in `@root`_ trees are independent of their position within the tree.


**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 >>

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 file.**  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.

How should I use Leo with bzr/git/hg/svn/cvs?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Using `@thin`_ trees can eliminate most problems with using Leo in cooperative
(SCCS) environments:

- Developers should use `@thin`_ trees to create derived files in any kind of
  cooperative environment.

- If sentinels are frowned upon in your development community, use `@auto`_ or
  `@shadow`_ instead of ``@thin``.

- The repository contains "reference" .leo files. These reference files
  should contain nothing but ``@thin`` nodes. Reference files will change only
  when new derived files get added to the project.

  **Important**: Leo's `bzr repository`_ contains the *reference* versions of
  the following .leo files: ``LeoPyRef.leo`` and ``LeoPluginsRef.leo``. However,
  Leo's distributions contain the *non-reference* versions of those files:
  ``LeoPy.leo`` and ``LeoPlugins.leo``. These two files have many ``@thin``
  nodes. There is no reference file 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 files (or any .leo files) rarely need to be
  checked into the repository. If you find yourself checking in a .leo file
  frequently, consider migrating valuable content to `@thin`_ nodes.

- Developers will use local copies of reference files 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.

How can I use Leo cooperatively without sentinels?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Leo's sentinels add outline structure to source files.
However, those sentinels annoy some people who don't use Leo.

You can use @auto, @shadow or @nosent trees to edit
files that are shared with those who don't want to see sentinel comments.

- ``@auto`` is best for files whose imported outline structure often changes. In
  most cases, this will be the best option. The drawback of @auto files are a)
  you can't use clones and b) you can't add your own organizer nodes.

- ``@shadow`` will work for files whose outline structure seldom changes.
  The advantage of ``@shadow`` is that you can add your own structure.

- ``@nosent`` is appropriate only for files that you alone modify.

Using derived files
^^^^^^^^^^^^^^^^^^^






**How do I inhibit sentinels in derived files?**


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 `derived file`_ 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 file` simply by writing all body text in outline order.
    Leo can't update the outline unless the derived file contains sentinels,
    so Leo does not update ``@nosent`` trees or ``@asis`` trees automatically when
    you change the derived file 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 file or not.

-   Use `@noref`_ trees.
    Leo creates files derived from ``@noref`` trees by writing all the nodes of the
    tree to the derived file in outline order.
    The derived file *does* contain some sentinels,
    so you *can* update ``@noref`` trees from changes made to derived files.

-   Use `@asis`_ trees.
    Files derived from ``@asis`` trees contain no sentinels.
    Leo creates the derived file simply by writing all body text in outline order.
    Leo can't update the outline unless the derived file contains sentinels,
    so Leo does not update ``@asis`` trees automatically when you change the derived file in an external editor.


**How can I create Javascript comments?**


**Question**: I'm writing a Windows Script Component, which is an XML file 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 couldn't override the
comment character for the start of the page).
Finally, I found a solution that worked, using php's heredoc string syntax::

    @first <?php
    @first $comment = <<<EOD
    EOD;

    // 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 files start with a shebang line?**


Use the @first directive_ in `@thin`_ trees or `@nosent`_ trees.
Use the @silent directive in `@root`_ trees.

The ``@first`` directive puts lines at the very start of files derived from ``@thin``.
For example, the body text of ``@thin spam.py`` might be::

    @first #! /usr/bin/env python

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 #! /usr/bin/env python
    @first # more comments.


**How do I use Leo to create CWEB files?**


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 files.
See `CWEB mode`_ for full details.


**Can @file trees contain material not in the derived file?**


No.  Everything in an `@thin`_ trees must be part of the derived file: 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 don't want in the `@thin`_ trees.


**How can I use Leo with older C compilers**


By Rich Ries.
Some older C compilers don't understand the "//" comment symbol, so using ``@language C`` won't work.
Moreover, the following does not always work either::

    @comment /* */

This generates the following sentinel line::

    /*@@comment /* */*/"

in the output file, 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 can't 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 files. 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 file.

- Use @all to gather notes in a derived file, as in done in @thin leoProjects.txt.


**How can I avoid getting long lines in derived files?**


**Question**: I must follow a coding standard when writing source code. It
includes a maximum line length restriction. How can I know the length of a
line when it gets written to the derived file?

**Answer**: If a node belongs to a derived file hierarchy, its body might get
indented when it is written to the derived file. 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 text's cursor, **fcol** shows the cursor coordinate
relative to the derived file, not to the curent node. The relation
**fcol >= col** is always true.

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 ``JEdit``'s language description files to drive the syntax colorer.
To add support for a new language, just add another such description file.


**How do I submit a plugin?**


You have two options: 

-   Get cvs write access, and add the `@thin`_ file to the plugins directory.

-   Just send the `@thin`_ file to me at edreamleo@gmail.com.
    That's 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 Leo's 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'.


**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 find 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 processing configuration settings.

Tips and techniques
^^^^^^^^^^^^^^^^^^^






**What is an easy way to profile code?**


I had a need to figure 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 profile 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 "Profiling 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 Profiling 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 profiling statements.  -- Kayvan


**How can I do a simple find and replace?**


The 'official' 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 find.
No problem.  The following also works::

    <Ctrl-f>find-pattern<Ctrl-shift-r>replace-text<return>

In other words, you can think of `<ctrl-f>` as meaning 'show the find 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 find options.
For example::

    <ctrl-f><alt-ctrl-w><find-pattern><return>

That is, `<ctrl-f>`shows the find 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 workflow 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`` file. 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.

That's all. Python will recompile any changed .py files in the new copy of Leo.
**Note**: I create a batch file 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 file)
2. t         (in a `console window`_: runs test.leo, compiling all changed .py files as a side effect)
3. Control-E (in test.leo: runs the test script)

The benefits of the new workflow:

- 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 fix syntax errors or exceptions in the *new* code:
  just fix 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 files at once?**


The Import Files dialog allows you to select multiple files 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 files from aDirectory, which should be a full path to a particular directory.
You could use ".c" to import all .c files, etc.


**How can I use two copies of Leo to advantage?**


By Rich Ries.
I often rework C code that's already been "Leo-ized"--the first 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_. It's 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_. I'd then need to re-focus on the main
node_. A minor nuisance, but it does slow you down.

My solution is to open a second editor with its focus on the main node_. Switch
to the other editor, and, referring to the first editor pane, move the nodes as
you like. The second editor's pane will change focus to the node_ you're moving,
but the first editor will stay focused on the main node_. It's a lot easier to
do than to describe!


**How can I display graphics in Leo?**


One way is to link directly to the media file 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/filetype 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 file gets mapped to an <embed> tag, etc).


**How can I create a template .leo file?**


**Question**:
It would be nice if Leo could open empty files. I tend to be "document oriented"
rather than "application oriented" in my thinking and prefer "create empty file
at location -> open it with program" to "start program -> create new file ->
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 file as "c:\windows\shellnew\leofile.leo" (or c:\winnt for 2000/XP)
5. Open regedit "start...run...regedit"
6. Open HKEY_CLASSES_ROOT and find 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 filename of the leofile.leo file 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 file you saved. This can be useful because you could make a template Leo
file containing some standard nodes_ that you always have and then save this.


**How can I show Leo files with Excel?**


From: http://sourceforge.net/forum/message.php?msg_id=3240374
Using Leo's ``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 benefits.

1.  The most obvious benefit inside Excel is that the body sections (Excel first
    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 first 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 first 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 files?**


By Rich Ries

There is no direct way to make script buttons available in multiple Leo files.
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 file.

3) Assuming you have only the one New Button Template defined, left-click the
   New button, and a new node will be added to your outline. (Otherwise, you'll
   need to select the Template you want.)

4) Press [Script Button] to create the new script button.

It's easier to *do* this than to *explain* it!

Trouble shooting
^^^^^^^^^^^^^^^^






**How do I get help?**


All questions are welcome at http://groups.google.com/group/leo-editor


**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 sufficient to recreate the problem.

It's 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 files won't load using Leo 4.5 or later. What should I do?**


In version 4.5, Leo changed to using a sax parser for .leo files. This can cause
problems if your .leo file 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 files.
Remove these invalid characters as follows:

1. `run Leo in a console window`_, and load the .leo file.
   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 file 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 file.

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: it's 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 leoTkinterFrame.py


**Control-Shift backspace doesn't 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. I'll 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 fix this, create a file (e.g. .Xmodmap) and give it the content::

    keycode 22 = BackSpace

then run the command::

    xmodmap .Xmodmap

This fixes the problem. On my system this also disables the ability to terminate
the X server using Ctrl-Alt-BackSpace. This is because of some conflict with xdb
(xdb is the newer keyboard mapping facility in XFree86; xmodmap is the old
original X11 keyboard mapping facility). I'm still working on that. I'm also not
able to get xmodmap to make this change during X11 startup (again because of
conflicts with xdb). But I'm working on that as well.


**Error messages from the rst3 plugin aren't 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 file.
**Important**: On Windows it is helpful to `run Leo in 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 haven't figured
    out how yet.) It's easy enough to do this:

    - Find the file ``core.py`` in top-level ``docutils`` folder.
      Typically this folder will be in Python's ``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 in a console window`_.

3.  As a last resort, you can isolate syntax errors by reducing your input files
    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
files with ``python.exe`` *not* ``pythonw.exe``. For full instructions about how
to do this, see `Associating Leo with .leo Files`_.


**How can I use Python's pdb debugger with Leo?**


Just `run Leo in a console window`_. At the point you want to drop into the
debugger, execute this line::

    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 Leo's log pane rather than a
console window, but I haven't 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 can't write Imported files.  What's going on?**


The import commands insert ``@ignore`` directives_ in the top-level node_.
Leo does this so that you won't accidentally overwrite your files after importing them.
Change the filename following ``@thin`` or ``@root`` as desired,
then remove the ``@ignore`` directive_.
Saving the outline will then create the `derived file`_.


**I don't 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 Lundh's 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 doesn't 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 pack's 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.


**Leo's Recent Files menu doesn't work from a cvs shandbox.  What's going on?**


You must create .leoRecentFiles.txt in the config 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 doesn't work (or puts up a dialog containing no text), you may install Leo from the .zip file
as described at `How to install Leo on Windows`_.
However you are installing Leo,
be sure to `run Leo in 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?**


Python's decorator_ syntax is ill-conceived.
This syntax file 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 doesn't work.  Why not?**


Leo's setup.py script is intended only to create source distributions. It can't
be used to install Leo because Leo is not a Python package.


**I can't 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) 
    import leo.core.leoBridge as leoBridge

at the head of each file 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 can't you simply add leo/core to sys.path in sitecustomize.py?  

Putting leo\core 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 can't 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.

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 files look funny. What can I do?**


Internally, Leo represents all strings as unicode. Leo translates from a
particular encoding to Unicode_ when reading .leo files or `derived files`_. Leo
translates from Unicode_ to a particular encoding when writing `derived files`_. You
may see strange looking characters if your text editor is expecting a different
encoding. The encoding used in any `derived file`_ is shown in the ``#@+leo`` `sentinel line`_
like this::

    #@+leo-encoding=iso-8859-1.

**Exception**: the encoding is ``UTF-8`` if no ``-encoding=`` field exists.
You can also use the ``@encoding`` directive_ to set the encoding for individual `derived files`_.
If no ``@encoding`` directive_ is in effect,
Leo uses the following settings_ to translate to and from unicode:

default_derived_file_encoding
    The encoding used for derived files if no ``@encoding`` directive_ is in effect.
    This setting also controls the encoding of files created by the ``Tangle`` commands.
    The default is ``UTF-8`` (case not important).

new_leo_file_encoding
    The encoding specified in the following line of new .leo files::

        <?xml version="1.0" encoding="UTF-8">

    The default is ``UTF-8`` (upper case for compatibility for old versions of Leo).

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.finishCreate sets this encoding as follows:

    a) using the ``tk_encoding`` setting if it exists,
    b) using ``locale.getpreferredencoding`` if it exists,
       or the equivalent code in pre-python 2.3 versions,
    c) using ``sys.getdefaultencoding``
    d) 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 defining 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 = u'a-(2 unicode characters here)-z'
    u = 'a-(2 unicode characters here)-z'

will not work when executed with Leo's 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 Leo's 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 = u'a-<e1>-<e2>-z'
    u = 'a-<e2>-<e>-z'

which is certainly *not* what the script writer intended!
Rather than defining strings using actual characters, Instead, one should use
the equivalent escape sequences. For example::

    u = u'a-\u0233-\u8ce2-z'
    u = 'a-\u0233-\u8ce2-z'


**Some characters are garbled when importing files. What can I do?**


The encoding used in the file being imported doesn't 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 file to be imported.

- Set the ``tk_encoding`` setting_ (see the previous answer) to the encoding you normally use.


**Python's print statement shows 'byte hash' for unicode characters.  What can I do?**


First, you must change Python's default encoding to something other than 'ascii'.  To do this, put the following in your sitecustomize.py file in Python's 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. 

Leo's 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 Peña properly::

    @first # -*- coding: utf-8 -*-

    import sys
    e = sys.getdefaultencoding()
    print 'encoding',e
    table = (
        'La Peña',
        unicode('La Peña','utf-8'),
        u'La Peña',
        u'La Pe\xf1a',
    )

    for s in table:
        print type(s)
        g.es_print('g.es_print',s)
        if type(s) != type(u'a'):
            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

Chapter 1: Installing Leo
+++++++++++++++++++++++++


@language rest

@rst html\install.html
*****************


##########################################
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 Leo's help forum:


.. Links used in this document...
.. _`Pmw`:                  http://pmw.sourceforge.net/
.. _run:                    `Running Leo`_
.. _`run Leo`:              `Running Leo`_
.. _`Leo's download page`:  http://sourceforge.net/project/showfiles.php?group_id=3458&package_id=29106
.. _`associating leo with .leo files`:   `How to associate Leo with .leo files on Windows`_
.. _`associated .leo files with Leo`:   `How to associate Leo with .leo files on Windows`_

System requirements
^^^^^^^^^^^^^^^^^^^


Leo will work on any platform that supports Python 2.5 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 `Leo's download page`_.

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

-   Most installations of Python have Tk pre-installed.
    If your doesn't, 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). Leo's extensions folder contains a copy
    of Pmw for use if needed. Leo first tries to import Pmw normally. If that
    fails, Leo will use the version of Pmw in the extensions folder.

Leo's HOME directory
^^^^^^^^^^^^^^^^^^^^


Python's HOME environment variable specifies Leo's 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 files in your HOME/.leo directory:
.leoID.txt, .leoRecentFiles.txt, and myLeoSettings.leo.

How to install Leo on Linux
^^^^^^^^^^^^^^^^^^^^^^^^^^^


If you are using Debian/Ubuntu, find and install the debian package. This
provides the best integration with your desktop (file associations, icons, launcher
item). Failing that, follow the instructions below.

Download the latest version of Leo (a .zip file) from `Leo's download page`_.

Unzip the downloaded .zip file into the **unpacked folder** in your home directory.
The unpacked folder will be called something like leo-4-5.

You now have two choices:

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

2. You can install leo into /usr/local/lib and /usr/local/bin by running Leo's 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`_.

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 file just downloaded.

3. Get Leo's sources from Leo's 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 don't 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 development 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

Installing Leo on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^


1. Install Python from http://www.python.org/download/releases/

2. Install PyQt. Get binary package from
   http://www.riverbankcomputing.co.uk/software/pyqt/download which
   matches installed Python version.
   Then run the installer.

3. Install Leo.  Get Leo's .zip file from http://sourceforge.net/projects/leo/
   You can unpack the .zip file anywhere, including Python's *site-packages* folder,
   for example, C:\Python25\Lib\site-packages

4. [optional] Generate/update a junction link from unpacked
   leo folder to ...\site-packages\leo

      cd C:\Python25\Lib\site-packages\
      junction leo leo-4-6-2-final

5. Create windows shortcut (edit paths as necessary):

      Target   =  C:\Python25\pythonw.exe "C:\Python25\Lib\site-packages\leo\launchLeo.py"
      Start in =  D:\code

6. Associate .leo filetype batch file:

      ftype LeoFile=C:\Python25\pythonw.exe "C:\Python25\Lib\site-packages\leo\launchLeo.py" "%1"
      assoc .leo=LeoFile

7. [optional] Put this leo.bat in %PATH%:

      @C:\Python25\python.exe -i "C:\Python25\Lib\site-packages\leo\launchLeo.py" %*


For more information see::

    Junction links:
        http://technet.microsoft.com/en-gb/sysinternals/bb896768.aspx,
        http://groups.google.com/group/leo-editor/msg/30116f9193241dc4
    ftype:
        http://ss64.com/nt/ftype.html
    assoc:
        http://ss64.com/nt/assoc.html

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 bugfixes. Running the development version is
quite safe and easy, and it's 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 standalone 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
   recommended as it's the easiest one to install. It provides command like
   ``bzr qlog``, ``bzr qannotate`` etc.

2. Get Leo from launchpad by doing::

     bzr branch lp:leo-editor

And that's it! You can run leo/core/leo.py directly. When you want to refresh the
code with latest modifications from Launchpad, run ``bzr pull``.

If you make modifications to Leo (with the interest in sharing them with the Leo
community), you can check them in to your local branch by doing ``bzr checkin``.
Now, to actually request your changes to be merged to Leo trunk, you need a
Launchpad account with RSA keys in place. There is showmedo video about how to
accomplish this in Windows using puttygen and pageant at
``http://showmedo.com/videos/video?name=1510070&fromSeriesID=151``.

After your Launchpad account is set up, go to
``https://launchpad.net/leo-editor``, choose "Code" tab -> Register Branch,
select Branch type "Hosted" and fill in descriptive details about the branch.
After that, go to the branch home page from Code tab again, and copy-paste the
push command line to terminal. For example, for branch::

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

The push command is::

    bzr push bzr+ssh://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.

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 files 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 files with Leo`_ you may run Leo by double-clicking any .leo file.
    You can also use a batch file.
    Put the following .bat file in c:\\Windows::

        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 file specified by the first argument (%1).

The first time you start Leo, a dialog will ask you for a unique identifier. If
you are using cvs, use your cvs login name. Otherwise your initials will do. Leo
stores this identifier in the file ``.leoID.txt``. Leo attempts to create
``leoID.txt`` in the .leo sub-directory of your home directory, then in Leo's config directory, and
finally in Leo's core directory. You can change this identifier at any time by
editing ``.leoID.txt``.

Running Leo from a console window
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Leo sends 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
files with ``python.exe`` *not* ``pythonw.exe``. For full instructions about how
to do this, see `Associating Leo with .leo Files`_.

Running Leo in batch mode
^^^^^^^^^^^^^^^^^^^^^^^^^


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

    --script scriptFile

If found, Leo enters batch mode. In batch mode Leo does not show any windows.
Leo assumes the scriptFile contains a Python script and executes the contents of
that file using Leo's ``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 Leo's commands except the ``Edit Body``
and ``Edit Headline`` commands. Those commands require interaction with the user.
For example, the following batch script reads a Leo file and prints all the
headlines in that file::

    path = r"<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"))

How to install the Aspell spell checker
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


You must install the Aspell package if you want to use Leo's Spell tab.

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

2.  Specify the location of the Aspell and Aspell/bin directories using
    the aspell_dir and aspell_bin_dir settings in LeoSettings.leo.

Chapter 2: A Tutorial Introduction to Leo
+++++++++++++++++++++++++++++++++++++++++


@language rest

@rst html\intro.html
***************


##########################################
Chapter 2: A Tutorial Introduction to Leo
##########################################

This tutorial shows you Leo's basic features.
These features are simple to use, yet they interact with each other in powerful ways.
All Leo's features relate in some way to outlines_.
Indeed, `outline structure is significant everywhere`_.

`Quick start for programmers`_ contains the heart of this chapter.
It briefly describes everything a Python programmer needs to know in order to understand Leo's 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`_.

.. .. contents::


.. Links used in this document...

.. ----- External references.

.. _`Leo's help forum`:         http://sourceforge.net/forum/forum.php?forum_id=10227
.. _`Literate Programming`:     http://www.literateprogramming.com/
.. _`noweb`:                    http://www.eecs.harvard.edu/~nr/noweb/

.. ----- Relative links....

.. _directive:              `Leo directives`_
.. _directives:             `Leo directives`_
.. _`derived file`:         `Derived files`_
.. _glossary:               glossary.html
.. _`Good style and bad`:   `Good style and bad:  sections vs. @others`_
.. _outline:                `Leo's main window`_
.. _outlines:               `Leo's main window`_
.. _plugin:                 `Plugins & settings`_
.. _plugins:                `Plugins & settings`_
.. _quickstart:             `Quick start for programmers`_
.. _scripts:                `Scripting Leo`_
.. _settings:               `Plugins & settings`_

.. ----- References to other chapters.

.. _`@auto trees`:                                  directives.html#auto-trees
.. _command:                                        commands.html
.. _commands:                                       commands.html
.. _`editing commands`:                             commands.html#the-edit-menu
.. _front:                                          front.html
.. _`install Leo`:                                  install.html
.. _`launch Leo`:                                   install.html#running-leo
.. _`Leo's Users Guide`:                            leo_TOC.html
.. _`Chapter 4: Writing Programs in Leo`:           directives.html
.. _`Chapter 5: Using Leo's Commands`:              commands.html
.. _`Chapter 6: Leo and Literate Programming`:      design.html
.. _`Chapter 7: Scripting Leo with Python`:         scripting.html
.. _`Chapter 8: Customizing Leo`:                   customizing.html

.. ----- References to the glossary

.. _`@auto`:                    glossary.html#auto
.. _`@file`:                    glossary.html#file
.. _`@nosent`:                  glossary.html#nosent
.. _`@others`:                  glossary.html#others
.. _`@thin`:                    glossary.html#thin
.. _`@thin trees`:              glossary.html#thin-trees
.. _`body text`:                glossary.html#body-text
.. _ancestor:                   glossary.html#ancestor
.. _children:                   glossary.html#child
.. _clone:                      glossary.html#clone
.. _cloned:                     glossary.html#cloned
.. _cloning:                    glossary.html#clone
.. _clones:                     glossary.html#clones
.. _`code part`:                glossary.html#code-part
.. _`doc part`:                 glossary.html#doc-part
.. _descendant:                 glossary.html#descendant
.. _descendants:                glossary.html#descendants
.. _`doc part`:                 glossary.html#doc-part
.. _grandchildren:              glossary.html#grandchildren
.. _headline:                   glossary.html#headline
.. _headlines:                  glossary.html#headlines
.. _`organizer node`:           glossary.html#organizer-node
.. _`organizer nodes`:          glossary.html#organizer-nodes
.. _`outline order`:            glossary.html#outline-order
.. _node:                       glossary.html#node
.. _nodes:                      glossary.html#nodes
.. _reference:                  glossary.html#reference
.. _references:                 glossary.html#references
.. _root:                       glossary.html#root
.. _`root node`:   	            glossary.html#root
.. _section:                    glossary.html#section
.. _sections:                   glossary.html#section
.. _`section definition`:       glossary.html#section-definition
.. _`section definitions`:      glossary.html#section-definitions
.. _`section definition nodes`: glossary.html#section-definition-nodes
.. _`section name`:             glossary.html#section-name
.. _`section names`:            glossary.html#section-names
.. _`section reference`:        glossary.html#section-reference
.. _`section references`:       glossary.html#section-references
.. _siblings:                   glossary.html#siblings

.. For reasons unknown, this image must appear in the _images folder on the web site.
.. |leoMainWindow| image:: screen-shots/leo-qt-main-window.JPG

Introduction
^^^^^^^^^^^^


**Important**: please `install Leo`_ before reading this tutorial,
If you have any problem, please do ask for help on `Leo's help forum`_.

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

|leoMainWindow|

Leo's main window
~~~~~~~~~~~~~~~~~


The main window represents an entire project and is stored in a single **Leo file**,
a file with a .leo extension.
As you can see, the main window contains three panes:
the **outline 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 project's 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 node's 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 text's 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.

Mini-buffer
    It is used like the Emacs mini-buffer to invoke commands. For full details, see `Chapter 5: Using Leo's Commands`_.

Now that we are familiar with Leo's main window,
let's see how to use Leo as a simple outliner.

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 
  structure 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 command 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.

- We'll discuss the ``Clone Node`` command in the next section.

You enter `body text`_ for any node by selecting the node's 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.

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.

Derived files
~~~~~~~~~~~~~


You don't have to store all outline data in Leo (.leo) files.
Leo allows you to store outline data in external files called **derived files**.
This is useful for creating programming files, documentation files such as LaTeX files, and web pages.

**Important**:
You can edit `derived files`_ outside of Leo.
Leo will update the outline to reflect those changes when Leo next opens the outline_.

It is easy to create derived files; just put ``@thin`` *filename* in a headline_.
That creates an **@thin node**.
The **@thin tree** (the ``@thin`` node and all its descendants) corresponds to the derived file *filename*.
Leo writes a `derived file`_ corresponding to the ``@thin`` tree to your hard drive when Leo saves your outline (.leo file).
When opening a .leo file, Leo reads all the `derived files`_ corresponding to ``@thin`` nodes in the outline_.

A good rule of thumb is to use ``@thin`` nodes unless you have a specific reason to do otherwise.
See `Chapter 4: Writing Programs in Leo`_ for a full discussions of the various ways of creating `derived files`_.

**Important**:
You must tell Leo the order in which to write data from the ``@thin`` tree to the `derived file`_.
The simplest way to specify the contents of a derived file is to insert::

    @all

in the body text of the `@thin`_ node_.
``@all`` is a Leo `directive`_.

When writing a `derived file`_, Leo writes the `body text`_ of the `@thin`_ node_,
replacing the ``@all`` directive by the `body text`_ of all the descendant_ nodes_ in **outline order**,
the order that nodes appear on the screen when all nodes are expanded.
`Leo for Programmers`_ discusses other, more flexible, ways of creating derived files from `@thin`_ trees.
**Note**: Leo copies headlines to the derived file as comments.
This means that headlines_ do not affect the meaning of `derived files`_ and
you can use headlines_ to contain whatever data you wish.
Usually, headlines_ describe what's in the node.

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 Leo's 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 don't 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 fix a bug I first create a view node to represent
the bug. I then create a component node (not cloned) that contains the original
bug report. I may also create other non-cloned nodes to contain notes and
documentation. Next, I go looking throughout Leo's code for nodes that relate in
some way to the bug. When I find such a node I clone it and move one of the
clones so it becomes a component of the view node for the bug. **Note**: I can
organize the components of the view node as I please. In particular, I can
create **organizer nodes** whose only purpose is to contain groups of component
nodes. In other words, the full power of Leo outlines is available within view
nodes.

**Important**: Once I have created the view of the bug, I can concentrate *only*
on that view. In particular, I can fix 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 Leo's project management capabilities. Indeed, the
ability to create multiple views of a project is most helpful.

Outline structure is significant everywhere
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


So far we have been focusing on Leo's 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 directive in an ancestor_ node.

-   Programs in `body text`_ can contain optional markup consisting of sections_ and section references_.
    (See `Quick start for programmers`_ for details.)
    Leo outlines limits the visibility of such sections:
    sections_ must be defined in a node descending from the node containing the `section reference`_.

-   You can organize scripts and programs using outlines, and scripts can use
    outline structure to access data. Plugins_ and scripts_ often confine their
    effects to the presently selected outline.

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 recommended for Python programming.)

- **\@wrap** and **\@nowrap** enable or disable line wrapping the Leo's body pane.

**Note**:
You can mix ``@nocolor`` and ``@color`` directives in a single node_,
but these directives apply to descendant_ nodes only if they are **unambiguous**, that is,
only if the ancestor node contains exactly one ``@color`` or ``@nocolor`` directive.

Leo for Programmers
^^^^^^^^^^^^^^^^^^^


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

The following sections tell how to create derived files that contain computer
programs. Yes, you could create program files using the ``@all`` directive, but
the following section explain how you can take advantage of **power-user**
features designed specifically for computer programmers. Even if you don't read
manuals, please read the following short `Quick start for programmers`_ section.

Quick start for programmers
~~~~~~~~~~~~~~~~~~~~~~~~~~~


`@thin trees`_ (parts of the outline whose *headline* starts with @thin)
create `derived files`_ 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 file`_,
Leo replaces all section references by their definition.
You define sections with **section definition nodes**.
A section definition node is a node_ whose headline_ starts with a `section name`_::

    << imports >>   (in a headline)

The `body text`_ of this node_ is its definition.  For example::

    import leo.core.leoGlobals as g
    import sys

As you can see, `section definitions`_ can be *fragments* of code;
they don't have to be complete functions or methods.

**Notes**:

-   `Section definition nodes`_ must be descendants_ of the node_ containing the `section reference`_.
    Leo's syntax colorer underlines undefined `section references`_.

-   `Section definitions`_ 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 definition nodes`_.
    That's how ``@others`` got its name.
    For example, the `root node`_ of Python `derived files`_ typically is something like this::

        << docstring >>
        << imports >>
        @others

    The `derived file`_ 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 file`_ 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 Leo's 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 files that do not contain sentinels.
Leo imports such derived files every time Leo reads the .leo file.

Beginner`s 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::

    << 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 Ramsey's `noweb`_ markup language,
but without noweb's 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 files.
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 specified 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 specifies 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 identifiers.
Whitespace separate the identifiers; everything else is taken to be the
identifiers. This construct is a convention of the noweb_ language, and will be
of use *only* for those who want to create .nw output files for use with the
official 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 file.

- **@c** Starts code parts (and ends doc parts).

- **@encoding** Sets the Unicode encoding used in derived files.

- **@first** Forces lines to appear before the first sentinel of a derived file.

- **@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 file.

- **@lineending** Specifies the line ending to be used in derived files.

- **@others** Copies all nodes *except section definition nodes* to the derived file.

- **@pagewidth** Sets the page width used to break doc parts into lines.

- **@path** Sets the path to be prepended to filenames 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 file`_. Orphan nodes can arise because an `@thin`_ tree has no
``@others`` or ``@all`` directives. Sections that are defined 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 file. Instead Leo
saves the information in the `@thin`_ tree in the .leo file. No information is
lost; Leo will load the `@thin`_ tree from the .leo file the next time Leo
opens the .leo file.

Sentinel lines
""""""""""""""


When writing `derived files`_, 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 file 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 file`_ in another
editor! Doing so will corrupt the derived file and make it impossible for Leo to
read it normally. If you do accidentally alter a sentinel line, don't panic!
Leo's ``Import Derived File`` command_ can recover information from corrupted
derived files.

The main difference between `@file`_ trees, `@thin`_ trees (and other kinds of trees that create derived files)
is the kind of sentinel lines that Leo writes:

- Sentinels in files derived from `@thin`_ reduce spurious cvs conflicts by
  marking each node with unique, unchanging **timestamp** as shown above.

- Sentinels in files derived from `@file`_ 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 files.
This is a highly complex subject: you should ignore these details at first.
Just use ``@thin`` to create your `derived files`_.

Leo and literate programming
""""""""""""""""""""""""""""


Leo can support a style of programming similar to `Literate Programming`_ (LP).
LP has a bad reputation in some quarters. That's too bad; Leo fixes all the
problems with traditional LP. See `Chapter 6: Leo and Literate Programming`_ in
`Leo's Users Guide`_ for more details. *Please* don't let the words 'Literate
Programming' get in the way of your using Leo effectively. That would be *your*
mistake, and a big one.

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 file`_ matters. For example, Python programmers
put docstrings and imports at the start of files. So the `body text`_ of
`@file`_ nodes typically look something like this::

    << docstring >>
    @language python
    @tabwidth -4
    << imports >>
    @others

This ensures that the docstring is first in the file, followed by imports,
followed by everything else. Note that the order in which functions are defined
in a file, or methods defined within a class, typically does *not* matter. Thus,
it is good style to define classes like this::

  class myClass:
        << class attributes >>
        @others

It would be bad style to define a class like this::

  class myClass:
        << class attributes >>
        << method 1 >>
        << method 2 >>
        ...

Not only does this over-specify the order in which methods are defined, 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::

    ###########
    # 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 file immune from such movements.

One last word about style. The world won't 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."

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 exactly the same way that Leo writes derived files.
That is,
**Leo expands section references and processes @others directives** before executing the script.
This allows you to use all of Leo's 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.

Plugins & settings
~~~~~~~~~~~~~~~~~~


**Plugins** are Python modules that change how Leo works, yet are not part of Leo's core code. 
Leo's user have contributed dozens of plugins that have extended Leo's capabilities in many new directions.
The file ``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 file, 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 Leo's core code. For a full discussion of
``@settings`` trees, see `Chapter 8: Customizing Leo`_.

Further study
~~~~~~~~~~~~~


``LeoPyRef.leo`` (in the core subdirectory of the leo folder) contains almost all of Leo's source code.
It provides hundreds of examples of everything discussed here.
This file will repay close study.
For full details on all aspects of Leo see ``LeoDocs.leo`` or `Leo's Users Guide`_.

Chapter 3: Using Outlines
+++++++++++++++++++++++++


@language rest

@rst html\outlines.html
******************


##########################################
Chapter 3: Using Outlines
##########################################

This chapter tells how to use Leo's outlines.

.. .. contents::


.. _`Chapter 2\: A Tutorial Introduction to Leo`:   intro.html
.. _`Chapter 4\: Writing Programs in Leo`:          directives.html
.. _`Clones and views`:                             intro.html#clones-views

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 doesn't 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 finished.

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 Python's global function. Examples:

a)  'g.toUnicode('  gives 'g.toUnicode(s, encoding, reportErrors=False'
b) 'c.widgetWantsFocusNow' gives 'c.widgetWantsFocusNow(w'
c) '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 enable_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.

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.

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.

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.

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 Leo's .leo file 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.

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.

Editing body text
^^^^^^^^^^^^^^^^^


Leo auto indents unless ``@nocolor`` is in effect. Typing a newline
automatically inserts the same leading whitespace present on the previous line.
If Python is the present language, Leo inserts an additional tab if the previous
line ends with a colon.

The default features of Leo's 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 following features are derived from the Tk Text widget. Some default
behaviors have been changed because they conflict 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.

-   ``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 don't affect the current selection.

-   ``Shift-Select`` and ``Control-Shift-Space`` adjust the selection to the current position of the
    insertion 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.

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.)

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.

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.

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.

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.

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 first 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
first looks for prefix + ch, where ch is the character just typed and prefix is
the previous match. The term 'close together' is defined by the setting: 

@float 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 significant. In practice
everything works well without thinking about what is happening.

Opening URL's 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}~``

Url's should contain no spaces: use ``%20`` to indicate spaces. You may use any
type of url that your browser supports: http, mailto, ftp, file, etc.

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
fills half of the main window.

Undoing operations
^^^^^^^^^^^^^^^^^^


Leo supports unlimited undo for all typing and all commands. The
'undo_granularity' setting controls the granularity 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 memory.

``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.

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 first @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 4: Programming with Leo
+++++++++++++++++++++++++++++++


@language rest

@rst html\directives.html
********************


#####################################
Chapter 4: Writing Programs in Leo
#####################################


.. External links...
.. _`CWEB`:     http://www-cs-faculty.stanford.edu/~knuth/cweb.html
.. _`noweb`:    http://www.eecs.harvard.edu/~nr/noweb/

.. Relative links...
.. _`@root reference`:      directives.html#id5 
.. _front:                  front.html
.. _`Leo's tutorial`:       intro.html
.. _`@auto reference`:      directives#id1


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 `Leo's 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.

.. .. contents::

Overview: the 9 ways of accessing external files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


You can create external files using ``@<file>`` directives.
Most of these directives may only appear in headlines.

Here are all the ways of creating external files:

\@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 file.

\@auto
  Imports the external file when Leo reads an outline. See the `@auto
  reference`_ for full details.

\@edit
  Reads the external file into a single node.

\@file
  ``@file`` is like ``@thin``,
  but ``@file`` sentinels are more readable than ``@thin`` sentinels.
  However,``@file`` is not as friendly to cvs or bzr as ``@thin``.
  Avoid ``@file`` in cooperative environments.

\@thin
  Creates external files containing sentinels that minimize conflicts
  in source code control systems such as bzr.
  Use ``@thin`` unless you have a good reason not to.

\@noref
  This directive produces external files with minimal sentinels.
  Section references are not allowed.
  This is the least often used way of producing external files.
  Don't use this unless you are sure you must.

\@nosent
  Creates external files 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 files.

  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 flexible, and the most difficult to use.
  **Note**: ``@root`` is a true directive: you put ``@root`` in body text.
  Historically, this was the first directive that created external files.
  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 files, a **public** file without sentinels,
   and a **private** file (by default in the .leo_shadow subfolder) containing sentinels.
   This allows Leo to get the benefits of ``@thin`` or ``@file`` trees,
   without having sentinels in the public files that people care about.

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 files.

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 file.
  Not valid in ``@root`` trees.

- **\@asis**
  Creates an external file without sentinels,
  containing exactly the data in the ``@asis`` tree,
  without expanding section references or ``@others`` directives.

- **\@auto**
  Imports the external file 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 file into a single node.

- **\@encoding**
  Sets the Unicode encoding used in external files.

- **\@file**
  Creates an external file containing sentinels.
  Thin external files contains simpler sentinels than ``@thin``.
  The @file tree in the outline contains a copy of all information in the external file.

- **\@first**
  Forces lines to appear before the first sentinel of an external file.

- **\@ignore**
  Causes Leo to ignore all or part of an external file.
  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 file.

- **\@lineending**
  Sets the line ending to be used in external files.

- **\@others**
  Copies all nodes *except* section definition nodes to the external file.

- **\@nosent**
  Same as ``@file``, but the external file contains no sentinels.

- **\@pagewidth**
  Sets the page width used to break doc parts into lines.

- **\@path**
  Set the path to be appended to filenames.

- **\@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 files, a **public** file without sentinels,
  and a **private** file containing sentinels.
  Imports the file just as ``@auto`` does if the private file does not exist.

- **\@tabwidth**
  Sets the width of tabs.
  Negative tab widths cause Leo to convert tabs to spaces.

- **\@thin**
  Creates an external file containing sentinels.
  Thin external files miminize cvs and bzr conflicts.
  All essential information is stored in the thin external file.

- **@verbose**, **@terse**, **@quiet** and **@silent**
  Set the verbosity of sentinels in external files from ``@root``.

- **\@wrap** and **\@nowrap**
  Enable or disable line wrapping the Leo's body pane.

Reference: all about directives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The following sections give full details about each directive.
The directives listed here may appear in headlines or body text.

@ and @doc
~~~~~~~~~~


The ``@`` directive starts a doc part.
Doc parts 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`` is a synonym for ``@``, but ``@`` is preferred.

@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 file, including ``@ignore`` nodes and nodes that
in an ``@others`` tree would be considered to be orphan nodes.

The ``@all`` directive is required for files such as ``@thin leoProjects.txt`` in ``LeoPy.leo``.
``leoProjects.txt`` contains so-called project nodes.
It doesn't have any meaning as a program file: it is simply a collection of unrelated data.
``@others`` would not work at all: it would complain about lots of orphan nodes.

\@asis and @noref
~~~~~~~~~~~~~~~~~


The only difference between ``@asis`` and ``@noref`` trees is that external
files created from ``@noref`` contain sentinels while external files created
from``@asis`` do not.

Leo creates files 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 definitions, 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 file 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 first line from the next node will concatenated to the last line
  of the preceding node.

\@auto
~~~~~~


@auto trees allow people to use Leo in collaborative environments without using
sentinels in the files Leo generates. In contrast to @nosent, @auto trees can
change when the corresponding file changes outside of Leo.

Leo will automatically recreate (import) all @auto trees when reading a .leo
file, and will write all dirty @auto trees when saving a .leo file. 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 influence of an @ignore directive.

2. Saving a .leo file does not save @auto nodes if:

a) they haven't been changed or,

b) they do not contain a **significant** amount of information. An @auto tree
   contains a significant 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 file. Parsers
create descendant nodes of the @auto tree: one node for each class, method and
function in the external file.

Parsers presently exist for C, elisp, Java, Javascript, Pascal, PHP, Python and xml. Leo
determines the language using the file's extension.  Notes:

- If no parser exists for a language, the entire body of the external file 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.

@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.

@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 affected.

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 unambiguously 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 definitions as usual even
after an ``@nocolor`` directive is seen.

@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 because
``Untangle`` can't be sure of properly parsing an external file if the language of the external file isn't 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 tangling start with ``///``,
while documentation parts are surrounded by ``/*`` and ``*/``.
The ``@comment`` directive allows you to use ``Tangle`` to produce shell and make files,
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 files.

The ``@comment`` directive is only recognized in ``@root``, ``@unit`` or ``@file`` nodes,
and the ``@comment`` directive must precede the first section name or ``@code`` directive.
An ``@comment`` directive in the body text of an ``@unit`` directive specifies 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 significant spaces.  For example::

    @comment REM_

causes the comment delimiter to be "REM " (Note the trailing space).

@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 files.
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 file,
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 file.
The new delimiter strings continue in effect until the next ``@@delims`` sentinel in the external file or
the end of the external file.

**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 Leo's ability to read the external file.
Mistakes using the ``@delims`` directive have no effect on Leo,
though such mistakes will thoroughly mess up a external file as far as compilers,
HTML renderers, etc. are concerned.

@edit
~~~~~


Reads a file into a single node.
@edit is similar to @auto; saving a .leo file does not save dirty @edit nodes
if they do not contain a **significant** amount of information. An @edit tree
contains a significant amount of information if it has children or if the root
node contains more than 10 characters.

@encoding
~~~~~~~~~


You may use the ``@encoding`` directive to specify the encoding used in an external file.
You can't mix encodings in a single external file.  For example::

    @encoding iso-8859-1

If the encoding used in an external file 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 unicode 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.

\@file
~~~~~~


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 file containing sentinels.
External files contain sentinels different from ``@thin``.
The ``@file`` tree in the outline contains a copy of all information in the external file.

@first
~~~~~~


The ``@first`` directive allows you to place lines at the very start of external files 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 #! /usr/bin/env python
	@first # more comments.

The ``@first`` directive is not valid in ``@root`` or ``@unit`` trees.

@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 file. 

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 that's how Leo works.

4. ``@ignore`` can be used by scripts and plugins as they like, but should preserve the behavior in item 1 above.

@language
~~~~~~~~~


The ``@language`` directive specifies the comment delimiters and string types used by the
``Tangle`` and ``Untangle`` commands.
This directive over-rides the default specified 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 file 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 files have comments that start with `#`.
Case is ignored in the language specifiers, but not in the ``@language`` itself.
Thus, the following are equivalent::

    @language html
    @language HTML
    @language hTmL

but the following is invalid::

    @LANGUAGE html

@last
~~~~~


The ``@last`` directive allows you to place lines at the very end of external files
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 file might be set up::

	@first <?php
	...
	@last ?>

@lineending
~~~~~~~~~~~


The ``@lineending`` directive sets the line endings for individual external files.
This directive will override the ``output_newline`` setting.
The ``@lineending`` *never* affects the line endings in .leo files themselves:
.leo files 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.
======================= ======================================================

@others
~~~~~~~


The ``@others`` directive refers to the body text of all nodes *except* section definition nodes.
The ``@others`` directive places the body text of section definition nodes in the external file 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 definition node may intervene between an non-section definition 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.

\@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.

@path
~~~~~


The ``@path`` directives override the deprecated ``default_tangle_directory`` setting.

The form of the @path directive is ``@path`` *filename*,
where *filename* is taken to be everything following @path to the end of the line.

If *filename* is an absolute filename the location of the external file is specified only by the filename.
Otherwise, if *filename* is a relative filename, the location of the external file is relative to:

1. the directory specified 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 file resides if the .leo file has ever been saved.

An error occurs if no absolute path can be computed according to these rules,
or if *filename* does not exist.

@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.

@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 file.

\@root
~~~~~~


``@root`` creates external files that are more flexible than
``@file``, ``@thin``, ``@shadow``, etc.

- Sections may be defined anywhere within ``@root`` trees.
  Moreover, the ``@unit`` directive expands the scope of section definitions in ``@root`` trees
  so that a section may be referenced in several ``@root`` trees.

- The meaning of section definitions in ``@root`` trees are independent of their position within the tree.

However, this flexibility 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.

\@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`` *filename* and ``@root-code`` *filename* 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.
It's better to be explicit.
By default, ``at_root_bodies_start_in_doc_mode = 1`` for compatibility for old ``@root`` trees.
I actually don't think this option is good for much;
I created it before I created ``@root-doc`` and ``@root-code`` settings,
and I decided it wouldn't hurt to leave it in.
Anyway, you now have complete flexibility about how ``@root`` works,
and in particular you can make ``@root`` work just like ``@file``.

\@shadow
~~~~~~~~


When writing an @shadow tree, Leo writes *two* files, a **public** file without sentinels,
and a **private** file (by default in the .leo_shadow subfolder) containing sentinels.
The primary sources for @shadow trees are the private files, updated by changes to the public file.

When reading an @shadow tree,
Leo will import the tree from the public file if the private file 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 influence of an @ignore directive.

2. Saving a .leo file does not save @shadow nodes if:

  a) they haven't been changed or,

  b) they do not contain a **significant** amount of information. An @auto tree
     contains a significant amount of information if it has  children or if the
     root node contains more than 10 characters.

Leo imports shadow trees by parsing the corresponding public file,
exactly as is done for @auto node.
See the discussion of @auto above for details.

\@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.

\@thin
~~~~~~


Creates an external file containing sentinels.

Thin exteral files 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.

@unit
~~~~~


The ``@unit`` directive expands the scope of section definitions in ``@root`` trees
so that a section may be referenced in several ``@root`` trees.
The ``@unit`` directive is ignored outside of ``@root`` trees.

@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.

@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 first ``@wrap`` or ``@nowrap`` directive in a node has any effect.

Reference: the 9 ways of accessing external files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


In the following table all terms in each row are equivalent.
The spelling in the first column is preferred:

=========== =============== =================
\@asis      \@file-asis     \@silent
----------- --------------- -----------------
\@nosent    \@file-nosent   \@nosentinelsfile
----------- --------------- -----------------
\@noref     \@file-noref    \@rawfile
=========== =============== =================

You can get any combination of sentinels/no sentinels and references/no references using
``@auto``, ``@file``, ``@thin``, ``@nosent``, ``@noref`` and ``@asis`` trees:

+---------+------------+-------------------+
|         |            | Sections and      |
| Type    | Sentinels? | @others expanded? |
+---------+------------+-------------------+
| @asis   | no         | no                |
+---------+------------+-------------------+
| @auto   | no         | no                |
+---------+------------+-------------------+
| @edit   | no         | yes               |
+---------+------------+-------------------+
| @file   | 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 files unless those files contain sentinels.
The primary source for ``@nosent`` and ``@asis`` trees are the outlines from which those files were created.

@shadow trees create *two* files, a **public** file without sentinels, and a **private** file (by default in the .leo_shadow subfolder) containing sentinels.  The primary sources for @shadow trees are the private files, updated by changes to the public file.

\@auto
~~~~~~


@auto trees allow people to use Leo in collaborative environments without using
sentinels in the files Leo generates. In contrast to @nosent, @auto trees can
change when the corresponding file changes outside of Leo.

Leo will automatically recreate (import) all @auto trees when reading a .leo
file, and will write all dirty @auto trees when saving a .leo file. 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 influence of an @ignore directive.

2. Saving a .leo file does not save @auto nodes if:

a) they haven't been changed or,

b) they do not contain a **significant** amount of information. An @auto tree
   contains a significant 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 file. Parsers
create descendant nodes of the @auto tree: one node for each class, method and
function in the external file.

Parsers presently exist for C, elisp, Java, Javascript, Pascal, PHP, Python and xml. Leo
determines the language using the file's extension.  Notes:

- If no parser exists for a language, the entire body of the external file 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.

Perfect import checks
"""""""""""""""""""""


Leo performs several checks to ensure that the result of importing an external
file will be equivalent to the file 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 file. If you @ignore directive, a later write of the
@auto tree will attempt to fix the problems that gave rise to the errors. There
are no guarantees however.

Before importing a file, Leo **regularizes** the leading whitespace of all lines
of the original source file. 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 specified by the @tabwidth directive in effect for
the @auto node.

Leo cannot guarantee to reproduce the original source file exactly if problems
are discovered while regularizing leading whitespace. **Strict languages** are
languages such as Python for which leading whitespace must be preserved exactly
as it appears in the original source file. Problems during regularizing generate
errors for strict languages and warnings for non-strict languages.

After importing a file, Leo verifies that writing the @auto node would create
*exactly* the same file as the original file. Such file comparison mismatches
generate errors unless the problem involves only leading whitespace for
non-strict languages. Whenever a mismatch occurs the first 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 files 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 file.

\@edit
~~~~~~


Initially, Leo's File:Open command creates such nodes when opening any
non-.leo file.

When writing @edit nodes, Leo uses Leo's @auto write logic.  That is,
no sentinels are written.

When reading @edit nodes, Leo just puts then entire text of the file
into the node, along with @language or @nocolor directives as
appropriate.  These added directives will not change the file when it
gets written because no sentinels are written.

\@file
~~~~~~


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 file containing sentinels.
External files contain sentinels different from ``@thin``.
The ``@file`` tree in the outline contains a copy of all information in the external file.

\@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.

\@asis and @noref
~~~~~~~~~~~~~~~~~


The only difference between ``@asis`` and ``@noref`` trees is that external
files created from ``@noref`` contain sentinels while external files created
from``@asis`` do not.

Leo creates files 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 definitions, 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 file 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 first line from the next node will concatenated to the last line
  of the preceding node.

\@root reference
~~~~~~~~~~~~~~~~


This section discusses all aspects of ``@root`` trees.
You should carefully consider whether the extra flexibility 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.

- You must explicitly tangle and untangle ``@root`` trees using the ``Tangle`` and ``Untangle`` commands.

However, ``@root`` trees are more flexible than ``@file`` trees:

- Sections may be defined anywhere within ``@root`` trees.
  Moreover, the ``@unit`` directive expands the scope of section definitions in ``@root`` trees
  so that a section may be referenced in several ``@root`` trees.

- The meaning of section definitions in ``@root`` trees are independent of their position within the tree.

Sections and section definitions
""""""""""""""""""""""""""""""""


Just as with ``@file`` trees, ``@root`` trees may contain code parts and doc parts.
Code parts start with section definition 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 node's headline starts with ``<<section name>>``.
Otherwise, the ``@c`` directive is invalid.

**Section definition 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 defined in several places.
The definition of a named code part is the concatenation of all code parts with the same name.
Body text that defines no code part is ignored.
At least one non-blank line must follow the section definition 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 node's headline starts with <<atFile methods>>,
the example above is equivalent to::

    @ This method puts an open node sentinel for node v.
    @c
    def putOpenNodeSentinel(self,v):
        if v.isAtFileNode() and v != self.root:
            << issue an error message >>
        else:
            s = self.nodeSentinelText(v)
            self.putSentinel("@+node:" + s)

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.
    def putOpenNodeSentinel(self,v):
        if v.isAtFileNode() and v != self.root:
            << issue an error message >>
        else:
            s = self.nodeSentinelText(v)
            self.putSentinel("@+node:" + s)

The following escape convention applies only in ``@root`` trees.
Within a code part ``@@`` in the first column (and only in the first column) stands for a single ``@`` sign.

Tangling @root trees with the Tangle commands
"""""""""""""""""""""""""""""""""""""""""""""


Each ``@root`` tree represents a single external file.
**Tangling** is the process of creating external files 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 files 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 definition 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 files from ``@root`` node.
The ``@root`` directive indicates which sections constitute an output file.
The text following a @root directive forms the entire content of the file,
that is, after section references are expanded.
An outline can contain arbitrarily many ``@root`` directives:
Leo's ``Tangle`` commands will create one output file for each.
The process of creating external files is called "tangling" because
the code from the outline is rearranged to create the external files.

For example, the following ``@root`` section shows a typical way of specifying a header file ``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 file ``xx.h`` from this body text by expanding all the section references.
Incidentally, the introductory documentation will be included in the header file:
any text preceding the ``@root`` directive is treated just like the doc part of a section definition.

As another example, the following shows a typical way of specifying the corresponding ``xx.c`` file::

    @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>

If *filename* is an absolute filename the location of the external file is specified only by the filename.
Otherwise, if the ``@root`` node contains a relative filename, the location of the external file is relative to:

1. the directory specified 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 file has ever been saved.

An error occurs if no absolute path can be computed according to these rules,
or if the filename or directory does not exist.

The scope of a definition is the tree in which the definition is known.
By default, ``Tangle`` commands look for section definitions only
in the suboutline of the ``@root`` node being tangled.
That is, all sections are assumed to be defined 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 definitions.
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 definitions.

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 defined in the unit can affect files A and B and
that all sections definitions 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 definition 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 files.

For example, suppose you create a new part of the outline and tangle it for the first time.
When you compile external files for the first you are likely to get many syntax errors.
You could fix those errors in the outline and tangle the outline again, but there is a much easier way:
you fix the errors in the external files using the compiler's editor,
then run the untangle command on the part of the outline that created the external file.
The ``Untangle`` command updates the selected outline to match the changes in the external files.
It's 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 fixed;
``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.
Don't attempt to change the structure of an outline by modifying external files; it won't work.
Also, never delete, move or alter the sentinel lines in external files 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 file but not in the outline.
``Untangle`` has no trouble with changed section references in external files;
it is only changed sentinel lines that cause problems.

Cloned nodes that generate code in several files may cause problems for ``Untangle``.
If ``Untangle`` is run separately on these external files,
``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 file rather than the external files.

\@thin
~~~~~~


Creates an external file containing sentinels.

Thin exteral files 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.

\@shadow
~~~~~~~~


When writing an @shadow tree, Leo writes *two* files, a **public** file without sentinels,
and a **private** file (by default in the .leo_shadow subfolder) containing sentinels.
The primary sources for @shadow trees are the private files, updated by changes to the public file.

When reading an @shadow tree,
Leo will import the tree from the public file if the private file 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 influence of an @ignore directive.

2. Saving a .leo file does not save @shadow nodes if:

  a) they haven't been changed or,

  b) they do not contain a **significant** amount of information. An @auto tree
     contains a significant amount of information if it has  children or if the
     root node contains more than 10 characters.

Leo imports shadow trees by parsing the corresponding public file,
exactly as is done for @auto node.
See the discussion of @auto above for details.

Converting @root trees to @file 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 definition.

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 ``@``

3.  Replace all section definition 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 files whose ``@file`` trees contain orphan or ``@ignore`` nodes.

5.  Make sure that all nodes defining 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 defining node and move one clone under each referencing node.

7.  If a node contains the definitions of several sections,
    place each different definition in a different node.

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 files in cweb mode.
However, Leo *does* expand *noweb* section references,
so you may use noweb sections to organize cweb files!
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 5: Using Leo's Commands
+++++++++++++++++++++++++++++++


@language rest

@rst html\commands.html
******************


##########################################
Chapter 5: Using Leo's Commands
##########################################

This chapter discusses all of Leo's menu commands.
It starts with a discussion of the Emacs-like minibuffer,
then continues with a discussion of commands in each of Leo's menus.

.. .. contents::


.. External links...
.. _CWEB:       http://www-cs-faculty.stanford.edu/~knuth/cweb.html
.. _noweb:      http://www.eecs.harvard.edu/~nr/noweb/

.. Relative links...
.. _`Chapter 4\: Writing Programs in Leo`:              directives.html
.. _`Chapter 6\: Leo and Literate Programming`:         design.html
.. _`Chapter 8: Customizing Leo`:                       customizing.html
.. _`Clones and views`:                                 intro.html#clones-views
.. _`Creating script buttons`:                          scripting.html#creating-script-buttons
.. _`Tangling @root trees with the Tangle commands`:    directives.html#tangling-root-trees-with-the-tangle-commands

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 file names.

.. - **quick-command-mode**: (default shortcut: Alt-x) Like Emacs Control-C. This mode is
..   defined in leoSettings.leo. It is useful for commonly-used commands.

- **universal-argument**: (default shortcut: Alt-u) Like Emacs Ctrl-u. Adds a repeat
  count for later command. Ctrl-u 999 a adds 999 a's.

- **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.

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
    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

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

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
    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
    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
    yank-pop
    yank-rectangle
    zap-to-character

Find commands
~~~~~~~~~~~~~


Here is a list of all of Leo's find commands.
The apropos-find-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

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
    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
    toggle-mini-buffer
    toggle-split-direction

Help commands
~~~~~~~~~~~~~


The following commands print various helpful messages.
Apropos commands print longer discussions of specific 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

Mode commands
~~~~~~~~~~~~~


These commands put Leo into various kinds of modes.

- The ``enter-*-mode`` commands enter modes defined by @mode nodes in leoSettings.leo
  (or in other .leo files).

- 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 selected 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
    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

Outline commands
~~~~~~~~~~~~~~~~


The following commands invoke Leo's 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
    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

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
    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

The File Menu
^^^^^^^^^^^^^



Loading, Saving and Reverting Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


-   The ``New`` command creates a new Leo main window.

-   The ``Open`` command opens an existing Leo file 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 haven't yet done so.

-   The ``Save``, ``Save As`` and ``Save To`` commands save the Leo window to a file.
    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 file is compressed with Python's zipfile module.
    Similarly, the ``Save File As Unzipped`` command is the same as the ``Save As`` command
    except that the resulting .leo file is not compressed.
    The ``Save``, ``Save As`` and ``Save To`` commands compress the file if it was originally compressed.
    **Note**: Leo writes files with .leo extension, regardless of whether the file is zipped or not.
    Zipped .leo files contain a single archive, whose name is the same as the .leo file itself.
    Outside of Leo you can change the extension to .leo.zip and use stuffit or other program to expand the .leo file
    contained within.

-   The ``Revert`` command reloads a file, discarding any changes made to the file since it was last saved.

-   The ``Recent Files`` command brings up a submenu containing a list of recently
    opened files. Choosing an item in this submenu opens the selected file or brings
    it to the front.

-   The ``Clear Recent Files`` command deletes all entries in the Recent
    Files submenu except the most recent file. The files 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 file, not any files 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 files derived
    from ``@file`` nodes. 

-   The ``Write Outline Only`` command saves an outline without writing any ``@file``
    trees. Useful for inserting an @file node into an outline without modifying a
    derived file with the same name.

-   The ``Write @file Nodes`` command forces an update of all @file trees.

-   The ``Write Dirty @file Nodes`` command writes all ``@file`` trees that have been changed.

Communicating with external editors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The ``Open With`` command allows you to communicate with external editor. When
you select this command Leo creates a temporary file and invokes an external
program. Leo periodically checks whether this temporary file 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.

Tangling an outline: Producing Derived Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The ``Tangle``, ``Tangle All`` and ``Tangle Marked`` commands create derived
files from portions of an outline. These commands indent and format the derived
files so that they are easy to read and so that it is clear what sections
produced the code. The .c file 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 file, 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
definition. Substitution continues until all references to sections are replaced
with their definitions. By default, ``Tangle`` commands look for section
definitions only in the suboutline containing the ``@root`` directive being
tangled. That is, all sections are assumed to be defined 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`_

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 files. These are exceptionally useful
commands. For example, suppose you create a new part of the outline and
``Tangle`` it for the first time. When you compile the resulting derived files
for the first time, you are likely to get many syntax errors. You could fix
those errors in the outline and Tangle the outline again, but there is a much
easier way: you fix the errors in the derived files using the compiler's editor,
then run the untangle command on the part of the outline that created the
derived file. The ``Untangle`` command updates the selected outline to match the
changes in the derived files. It's 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 fixed; ``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. Don't attempt to change the structure of an outline by
modifying derived files; it won't work. Also, never delete, move or alter the
sentinel lines in derived files 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 file but not in the outline. Untangle has no trouble with
changed section references in derived files; it is only changed sentinel lines
that cause problems. Cloned nodes that generate code in several files may cause
problems for ``Untangle`` if not all the code is changed the same way in derived
files. If ``Untangle`` is run separately on these derived files, 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 file rather than the
derived files.

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 file.

-   The ``Import to @root`` command creates an ``@root node`` from a file.

-   The ``Import CWEB Files`` command creates an @file node from a `CWEB`_ file.

-   The ``Import noweb Files`` command creates an @file node from a `noweb`_ file.

-   The Import Derived File command imports all the nodes in a derived file 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 file. If that file 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.

Exporting Files from Leo Outlines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


-   The ``Outline To CWEB`` command creates a `CWEB`_ file from the selected outline.

-   The ``Outline TO noweb`` command creates a `noweb`_ file from the selected outline.

-   The ``Flatten Outline`` command creates a text file 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 file derived from an ``@file`` node.

-   The ``Weave`` Command formats the selected text and writes it to a file.

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 file that has been altered but not
saved.

The Edit Menu
^^^^^^^^^^^^^



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 first bead; the ``Redo``
command is disabled when the bead pointer points to the last bead.

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.

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.

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 specified by the ``Add Comments`` command.

Creating nodes from body text
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The Extract, Extract Section and Extract Section Names commands create child nodes whose headline is the first line of the selected body text.

-   The ``Extract command`` creates a new node whose headline is the first 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 first line of selected text and
    whose body is ``@code`` followed by all the other lines of selected text.
    All selected text lines except the first line are deleted from the original body text.
    This command is enabled only if the first 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.

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.

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-defines 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 Leo's features to organize scripts that you execute
interactively. Section definitions must appear in the node containing the script
or in descendant nodes.

Leo preprocesses all scripts by simulating the writing of a derived file 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.

Finding and changing text
~~~~~~~~~~~~~~~~~~~~~~~~~


The following check boxes options appear in the search dialog and control the operations of the find 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 it's 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 find 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 file.

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.

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 headline and its offspring.

Whole Word
    When checked, the find 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 file when
    the command reaches the bottom of the file.
    For reverse searches, the find or change command continues at the bottom of the file when
    the command reaches the top of the file.

Script search
~~~~~~~~~~~~~


**Important**: Script buttons are easier to use than the script-oriented
find/change commands described next. I recommend using script buttons whenever
possible. See `Creating script buttons`_.
You are not likely to need all the firepower that script-orient find/change commands,
but it could save you lots of time for complex jobs.

Leo's find 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 find-change turns Leo's Find/Change panel into a platform for
running scripts interactively. The script writer need not write code to control
interactive searches.

Here's 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 "find", "change", "findAll" 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 find script once. Typically, the find script would traverse
    the tree and highlight the found text or otherwise indicate to the user that
    the find operation has succeeded. However, the script can do anything it
    pleases.

``Find All`` button
    Leo executes the find script repeatedly until ``g.app.searchDict["continue"]`` evaluates
    to ``False``. Initially there is no entry for ``g.app.searchDict["continue"]``, so the
    find 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 find 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 Leo's 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.
    # 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 find text of Leo's Find/Change dialog.
- Puts the body of the "Change script" into the change text of Leo's 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 find/change scripts.

Here are some ideas for using script find/change.

-   Find and change scripts may use Python's re module.  For
    example, the find script could set ``g.app.searchDict["m"]`` to the match object
    returned by re's 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-find scripts could traverse your file system.
    Scripts could even pull data from the file system
    into the outline so that you can see the effects of changes as the scripts
    operate.

Go To Line Number
~~~~~~~~~~~~~~~~~


The ``Go To Line Number`` command selects the locations in your outlines corresponding to a line in a derived file.

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 headline.
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 specified 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

Reformatting paragraphs in body text
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The Reformat Paragraph command rearranges the words in a text paragraph to fill
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``).

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.

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.

The Outline Menu
^^^^^^^^^^^^^^^^



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 customize this code by overriding the following methods of class ``prettyPrinter`` in ``leoCommands.py``::

        putOperator:      puts whitespace around operators.
        putNormalToken:   puts whitespace around everything else.

Creating & cloning nodes
~~~~~~~~~~~~~~~~~~~~~~~~


-   The ``Insert Headline`` command inserts a new headline after the presently selected headline,
    either as the next sibling or the first 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.

Cutting, pasting and deleting nodes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


-   The ``Cut Outline`` and ``Copy Outline`` commands copy a text
    representation of the outline to the clipboard. This representation is the same
    as the file 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 gnx's).

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 node's parent and selects the parent node.

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 file 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.

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 headlines.

-   The ``Sort Siblings`` command sorts all siblings of the present node in alphabetical order.

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.

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 files, one containing sentinels and one not.

The Help Menu
^^^^^^^^^^^^^


-   The ``About Leo`` command puts up a dialog box showing the version of Leo.
-   The ``Online Home Page`` command opens Leo's home page at http://webpages.charter.net/edreamleo/front.html.
-   The Open Online Tutorial command opens Joe Orr's excellent ScreenBook tutorial at
    http://www.evisa.com/e/sbooks/leo/sbframetoc_ie.htm.
-   The Open Offline Tutorial command opens the file sbooks.chm if it exists.
    Otherwise, you will be asked whether you want to download it from Leo's SourceForge web site.
    If you say yes, the page http://sourceforge.net/project/showfiles.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``.

Chapter 6: Leo and Literate Programming
+++++++++++++++++++++++++++++++++++++++


@language rest

@rst html\design.html
****************


##########################################
Chapter 6: Leo and Literate Programming
##########################################

This chapter discusses Leo's relationship with traditional `literate programming`_.

.. .. contents::


.. Relative links...
.. _`Chapter 5\: Using Leo's Commands`:             commands.html
.. _`Chapter 7\: Scripting Leo with Python`:        scripting.html
.. _`Clones & views`:                               intro.html#clones-views
.. _`Organizer nodes`:                              intro.html#good-style-and-bad-sections-vs-others

.. _`@file trees`:          glossary.html#file-trees
.. _`@root node`:           glossary.html#root-node
.. _child:                  glossary.html#child
.. _clones:                 glossary.html#clones
.. _commands:               `Chapter 5\: Using Leo's Commands`_
.. _cweb:                   glossary.html#cweb
.. _`literate programming`: glossary.html#literate-programming
.. _node:                   glossary.html#node
.. _outline:                glossary.html#outline
.. _outlines:               glossary.html#outlines
.. _`reference`:            glossary.html#reference
.. _`referenced`:           glossary.html#referenced
.. _reStructuredText:       glossary.html#restructuredtext
.. _`rst3 plugin`:          glossary.html#rst3-plugin
.. _section:                glossary.html#section
.. _sections:               glossary.html#sections
.. _`section name`:         glossary.html#section-name
.. _`section names`:        glossary.html#section-names
.. _`section reference`:    glossary.html#section-reference
.. _`section references`:   glossary.html#section-references
.. _tangling:               glossary.html#tangling
.. _tree:                   glossary.html#tree
.. _untangling:             glossary.html#untangling

Why I like Literate Programming
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The following paragraphs discuss the main benefits of traditional `literate programming`_.
**Note**: none of these benefits depends on printed output.

**Design and coding happen at the highest possible level**.
The names of sections_ are constrained only by one's 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 definition 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 apparently 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 function's greater generality
outweighs the inconvenience of having to declare and define the function.

**Complex section names invite improvements**.
A `section name`_ is complex when it implies unwholesome dependencies 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 didn't 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 definition
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 >>

In the derived file 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 file. 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 clarifies 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 don't 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 Aha's 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 doesn't 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 don't 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.

How Leo Improves Literate Programming
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Outlines_ add something brand new to traditional `literate programming`_, namely an
explicit mechanism for expressing 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
difficult 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 flexibility**.
`Organizer nodes`_ do not affect derived files 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 flexibility: 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 files, or the organization of a single file as a set of
functions, etc. An outline_ directly expresses hierarchy. Many of Leo's 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.**
Leo's `rst3 plugin`_ makes it easy to use reStructuredText_ (rST) instead of CWEB_
markup. For most purposes, rST suffices, 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 files derived from `@file trees`_ automatically. This
is an important convenience.

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 finished
with topic x, we turn now to topic y." Leo's outlines tend to be far less
chatty than flat 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 Leo's 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 defined 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 maintenance problems. The narrative is
soon forgotten, and when that happens it becomes difficult to find anything. The
few times I have tried narrative organization I soon regretted it: things just
weren't 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. Leo's outlines provide
a more regular organization, while providing space for the most lengthy
discussions when those discussions are required.

Chapter 7: Scripting Leo with Python
++++++++++++++++++++++++++++++++++++


@language rest

@rst html\scripting.html
*******************


####################################
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 Leo's, **vnode**, **tnode**
and **position** classes to access data in Leo outlines. The combination of a
vnode v and its tnode v.t represents a node's data. Leo needs both vnodes and
tnodes to represent clones efficiently. 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 define various kinds of tree traversals.

Leo's execute-script command predefines several symbols.  This makes it easy to
access the data in Leo outlines and the Leo's own source code. g is predefined
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 Leo's global variables and constants. The execute-script command
predefines 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 predefines p to be the presently selected position.

This chapter describes only some of Leo's functions, classes and methods.
However, your scripts have complete access to all of Leo's source code, that
is, all the code in ``LeoPy.leo``. You are not limited by what you see in this
chapter.

.. .. contents::


.. Links used in this document.
.. _front:          front.html
.. _chapter6:       design.html
.. _chapter8:       customizing.html
.. _`rst3 plugin`:  rstplugin3.html

Commonly used classes
^^^^^^^^^^^^^^^^^^^^^


@language python

Leo's 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 Leo's global variables.

**g.app.gui**
    This is a wrapper class that shields Leo's 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 frame's 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 ``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. We'll see how this works in detail in `About
    copying positions`_.  This section is **supremely important**.

**baseTextWidget and its subclasses**

Leo's body pane (c.frame.body.bodyCtrl, aka w), is an instance of
(a subclass of) baseTextWidget.
Gui plugins implement Leo's 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 v's 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.

Predefined objects
^^^^^^^^^^^^^^^^^^


Leo's ``Execute Script`` command predefines ``c`` to be the commander of the
outline containing the script. ``g`` and ``p`` are predefined as follows::

    import leo.core.leoGlobals as g
    p = c.p

These definitions 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

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::

    g.es("Hello","world")

To create a tab named 'Test' or make it visible if it already exists::

    c.frame.log.selectTab('Test')

When first 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')

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 f's 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.

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 isn't.
In such cases, you can use g.angleBrackets.  For example::

    g.es(g.angleBrackets('abc'))

Getting and setting body text directly
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


As stated above, Leo's 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::

    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 Leo's source code.

- i and j are zero-based indices into the the text.
  When j is not specified, 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.

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 find 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'

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

This creates a dictionary of (unchanging!) positions, indexed via tnode.
**Warning** The positions in this dictionary will become invalid when the
outline's 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 Leo's
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.

Traversing outlines
^^^^^^^^^^^^^^^^^^^


The proper way to traverse an outline is with an iterator.
Iterators are defined only by the position class;
vnodes can not have iterators because vnodes may appear in multiple places in an outline.

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
    for p in c.allNodes_iter():
        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 = {}
    for p in c.allNodes_iter():
        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()))

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)

p.parents_iter & p.self_and_parents_iter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The ``p.parents_iter`` iterator returns a list of all parents of position ``p``, excluding ``p``::

    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)

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)

p.subtree_iter & p.self_and_subtree_iter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The p.subtree_iter iterator returns a list of all positions in ``p``'s 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 ``p``'s 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)

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**::


    if p is None:       # Wrong
    if p is not None:   # Wrong

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 = {}
    for p in c.allNodes_iter():
        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.

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.

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")

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'.

Getting settings from @settings trees
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Any .leo file 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.

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',
    )

    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)

Functions for finding and changing text from scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The file ``leoFindScript.py`` contains functions for finding and changing text
from within scripts.  See ``leoFindScript.py`` in ``LeoPy.leo`` for full details.

The findall function returns a list of tuples ``(v,pos)`` describing matches in
``c``'s 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 flags 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))

Functions defined in leoGlobals.py
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


``leoGlobals.py`` contains many utility functions and constants.
The following script prints all the names defined 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)

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.

============================= ======== =================================== =============================
Event name (tag argument)     Stop?    When called                         Keys in keywords dict
============================= ======== =================================== =============================
'after-auto'                           after each @auto file 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.finishCreate           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 file             c,old_c,new_c,fileName (note 4)
'open2'                                after  opening any file             c,old_c,new_c,fileName (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
'recentfiles1'                 yes     before Recent Files command         c,p,v,fileName,closeFlag
'recentfiles2'                         after  Recent Files command         c,p,v,fileName,closeFlag
'redraw-entire-outline'        yes     start of tree.redraw                c (note 6)
'save1'                        yes     before any Save command             c,p,v,fileName
'save2'                                after  any Save command             c,p,v,fileName
'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.finishCreate()            None
'start2'                               after opening first Leo window      c,p,v,fileName
'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)
============================= ======== =================================== =============================

**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 'official'
    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.
    - fileName:   The name of the file 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 file is not already open. Leo
    will also call the 'open1' and 'open2' hooks if: a) a file is opened using the
    Recent Files menu and b) the file 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 filename.ext'

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.

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 substantially reduce the number of ``u.beforeX`` and ``afterX`` methods
needed.

Plugins and scripts may define 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 vnodes 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 Leo's core calls the ``u.beforeX`` and ``afterX`` methods.

Redirecting output from scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


``leoGlobals.py`` defines 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()
    print "stdout isRedirected:", g.stdOutIsRedirected()
    print "stderr isRedirected:", g.stdErrIsRedirected()

    g.redirectStdout()
    print "stdout isRedirected:", g.stdOutIsRedirected()
    print "stderr isRedirected:", g.stdErrIsRedirected()

    g.restoreStderr()
    print "stdout isRedirected:", g.stdOutIsRedirected()
    print "stderr isRedirected:", g.stdErrIsRedirected()

    g.restoreStdout()
    print "stdout isRedirected:", g.stdOutIsRedirected()
    print "stderr isRedirected:", g.stdErrIsRedirected()

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 specified 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)

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 file dialogs, look for examples in Leo's own
source code. The runOpenFileDialog returns a list of file names.

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 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()

Customizing panes with different widgets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Tk/Tkinter make it easy to customize the contents of any of Leo's panes. The
following sections will discuss the 'official' 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.

Official ivars
~~~~~~~~~~~~~~


The c.frame.log class contains the following 'official' 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 Leo's 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.

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 = c.frame.log.logCtrl
    w.insert('end','This is a test\n')

To get the entire contents of the log::

    w = c.frame.log.logCtrl
    g.es(w.get('1.0','end')+'\n')

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.
    w = c.frame.log.logCtrl
    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 = c.frame.log.logCtrl
    w.pack(side='left',expand=1,fill='both')

Customizing the body pane
~~~~~~~~~~~~~~~~~~~~~~~~~


Warning: you will find 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::

    import Tkinter as Tk

    w = c.frame.body.bodyCtrl
    parent =  w.pack_info().get('in')
    w.pack_forget()

    f = c.frame.newBody = Tk.Frame(parent,background='red')
    f.pack(side='left',expand=1,fill='both')

To restore::

    c.frame.newBody.pack_forget()
    w = c.frame.body.bodyCtrl
    w.pack(side='left',expand=1,fill='both')

Customizing the outine pane
~~~~~~~~~~~~~~~~~~~~~~~~~~~


The following replaces the outline pane with a red frame::

    import Tkinter as Tk

    w = c.frame.tree.canvas
    parent =  w.pack_info().get('in')
    w.pack_forget()

    f = c.frame.newTree = Tk.Frame(parent,background='red')
    f.pack(side='left',expand=1,fill='both')

And this script restores the outline::

    c.frame.newTree.pack_forget()
    c.frame.tree.canvas.pack(side='left',expand=1,fill='both')

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 @file node
(including @thin, @auto, @nosent, @shadow, etc.), the following script will
print the full path to the created file::

    path = d.get('path')
    name = p.anyAtFileNodeName()
    if name:
       name = g.os_path_finalize_join(path,name)
       g.es(name)

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``.

Iterators
~~~~~~~~~


Iterators exist only in the position class::

	c.allNodes_iter            # returns all positions in c's 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.
	p.subtree_iter             # returns all positions in p's subtree, excluding p.
	p.self_and_subtree_iter    # returns all positions in p's subtree, including p.

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()

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 n'th 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 c's tree.
    p.clearVisited()
    p.setVisited()

Creating script buttons
^^^^^^^^^^^^^^^^^^^^^^^


Creating a script button should be your first 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 N's headline
text. The script associated with the new button is N's body text. Now whenever
you press the new button, N's script is executed on the **presently** selected
node. Script buttons are extraordinarily useful. In effect, each script button
defines an instant command! For example, sometimes my fingers get tired of
saving a file. I simply put ``Save`` in a node's 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.

Here's 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 don't 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-defines 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 button's 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 file 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``.

Running Leo in batch mode
^^^^^^^^^^^^^^^^^^^^^^^^^


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

    --script scriptFile

If found, Leo enters batch mode. In batch mode Leo does not show any windows.
Leo assumes the scriptFile contains a Python script and executes the contents of
that file using Leo's ``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 Leo's commands except the ``Edit Body``
and ``Edit Headline`` commands. Those commands require interaction with the user.
For example, the following batch script reads a Leo file and prints all the
headlines in that file::

    path = r"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"))

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()

Let's look at this in detail.  The lines::

    stateName = 'get-input'
    k = c.k
    state = k.getState(stateName)

define a state *name*, 'get-input', unique to this code.
k.getState returns the present state (an int) associated with this state.

When getInput() is first 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 can't delete the label by backspacing.
getArg, and the rest of Leo's 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 finished 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::

    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.

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 file.
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.

Chapter 8: Customizing Leo
++++++++++++++++++++++++++


@language rest

@rst html\customizing.html
*********************


#############################################
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 Leo's settings.

.. .. contents::


.. _`Chapter 7\: Scripting Leo with Python`:    scripting.html
.. _`Chapter 9\: History of Leo`:               history.html
.. _`rst3 plugin`:                              glossary.html#rst3-plugin
.. _`Specifying settings`:                      commands.html#specifying-settings

Specifying settings
^^^^^^^^^^^^^^^^^^^


Leo stores options in **@settings trees**, outlines whose headline is
@settings. When opening a .leo file, Leo looks for @settings trees not only
in the outline being opened but also in various leoSettings.leo files.
This scheme allows for the following kinds of settings:

- Per-installation or per-machine settings.
- Per-user settings.
- Per-folder settings.
- Per-file settings.

There are four kinds of settings files:

1. **Default settings files**, named **leoSettings.leo**.
   Although they can be used in other ways, they typically contain default settings.

2. **Personal settings files**, named **myLeoSettings.leo**. They provide a way
   of ensuring that your customized settings are not altered when updating Leo
   from bzr or while installing a new version of Leo. The myLeoSettings.leo acts
   much like Python's site-customize.py file. myLeoSettings.leo will never be
   part of any Leo distribution, and it will never exist in Leo's cvs
   repository. This solution is *much* better than trying to update
   leoSettings.leo with scripts.

3. **Machine settings files**, named **LeoSettings.leo** (note the capital 'L'),
   and appearing in a unique directory.

4. **Command-line settings files**, specified using Leo's -c command-line
   option. Any .leo file may be used, provided it has an @settings tree. These
   files typically provide a common set of settings for files scattered in
   various places on the file system.

The following sections describe the kinds of nodes in @settings trees.

Configuration directories
~~~~~~~~~~~~~~~~~~~~~~~~~


Settings files can be found in the following directories:

- **homeDir**, the HOME/.leo directory. HOME is given by Python's HOME
  environment variable, or by os.expanduser('~') if no HOME environment variable
  exists.

- **configDir**, Leo's configuration directory: leo/config.

- **machineDir**, the HOME/.leo/MACHINE directory. MACHINE is given by Python's
  HOSTNAME environment variable, or by Python's 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 file being loaded.

In addition, Leo's -c command-line option can specify any .leo file anywhere.

Search order for settings files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


When reading a .leo file, Leo looks for settings in default settings
files first, then settings in personal settings files, and finally
settings in local settings files.  The exact search order is:

1. Default settings files:

   a. configDir/leoSettings.leo
   b. homeDir/leoSettings.leo
   c. localDir/leoSettings.leo

2. Personal settings files:

   a. configDir/myLeoSettings.leo
   b. homeDir/myLeoSettings.leo
   c. homeDir/<machine-name>LeoSettings.leo (note capitalization)
   d. localDir/myLeoSettings.leo

3. Local settings files:

   a. The file specified by the -c command-line option.
   b. The file 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 file-by-file basis.  In other words, each individual
setting overrides only the *corresponding* setting in previously-read
files.  Reading a setting file does *not* reset all previous settings.
Note that the same file might appear several times in the search list.
Leo detects such duplicate file names and only loads each settings file once.
Leo remembers all the settings in settings files and does not reread those
settings when reading another .leo file.

**Caution**: This search order offers almost too much flexibilty. This can be
confusing, even for power users. It's important to choose the "simplest
configuration scheme that could possibly work".  Something like:

- Use a single leoSettings.leo file for installation-wide defaults.
- Use a single myLeoSettings.leo files 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.

Safe rules for local settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


You should use special care when placing default or personal settings files in
**local** directories, that is, directories other than homeDir, configDir or
machineDir. In particular, the value of localDir can change when Leo reads
additional files. This can result in Leo finding new default and personal
settings files. The values of these newly-read settings files 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 file A.leo **covers** settings file if B.leo
if all volatile settings in B.leo occur in A.leo. With these definitions, the
**safe rule** for placing settings files in local directories is::

   Settings files in local directories should
   cover all other settings files.

Following this rule will ensure that the per-directory defaults specified in the
local settings file will take precedence over all previously-read default and
personal settings files. Ignore this principle at your peril.

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.

\@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 isn't necessary to import sys.

- ``@ifhostname`` *hostA,!hostB*

  Evaluates to True iff: h=g.computeMachineName(); h==hostA and h!=hostB.
  The "!" version allows matching to every machineName except the given one
  to allow differing settings on only a few machines.

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
\@float          A floating 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 file
\@ratio          A floating 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['flat','groove','raised']='groove'
=============== =========================================================================================

**Note**: For a list of Tk color specifiers see:

- http://www.tcl.tk/man/tcl8.4/TkCmd/colors.htm
- 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.

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 specifiers.
\@recentfiles       Body text contains a list of file paths.
\@shortcuts         Body text contains a list of shortcut specifies.
=================== =====================================================================

Complex nodes specify settings in their body text.
See the following sections for details.

\@button
""""""""


An @buttons tree in a settings file defines global buttons that
are created in the icon area of all .leo files.
All @button nodes in the @commands tree create global buttons.
All @button nodes outside the commands tree create buttons local to the settings file.

\@commands
""""""""""


An @commands tree in a settings file defines 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 file.

\@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 files in the order
specified by `Search order for settings files`_. Leo will enable all plugins
found in the @enabled-plugins node it finds *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 file that appears early in the search list**. Instead, the last
@enabled-plugins node found in the search list specifies all and *only* the plugins
that will be enabled.

Let us distinguish two different situations. First, what Leo does when loading a
file, say x.leo. Second, what Leo does when loading a second file, say y.leo,
*from x.leo*. When loading the first .leo file, Leo enables plugins from the
@enabled-plugins node it finds *last* in the search order. But after plugins
have *already* been loaded and enabled, there is no way to disable previously
loaded-and-enabled plugins. But local settings files can enable additional
plugins.

To avoid confusion, I highly recommend following another kind of safe rule.
We say that an @enabled-plugin node in file A.leo **covers** an @enabled-plugin
node in file B.leo if all plugins specified in B's @enabled-plugin node appear
A's @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 modifies the menu tree created by @menus.
It is intended to be used in myLeoSettings.leo to modify the menu tree created
in leoSettings.leo. This allows you to change the menus without having to
re-create the entire menu tree from leoSettings.leo, and ensures you don't 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 file .../leo/core/test/menuAtTest.leo.

The **path** argument specifies a target location in the menu tree as defined by
@menus and modified 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 specifies 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 modifies 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.

\@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 define 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 specifiers. ``@mode`` nodes work just
like ``@shortcuts`` nodes, but in addition they have the side effect of creating
the ``enter-<mode name>-mode`` command.

\@recentfiles
"""""""""""""


The body text contains a list of paths of recently opened files, one path per
line. Leo writes the list of recent files to ``.leoRecentFiles.txt`` in Leo's
``config`` directory, again one file per line.

\@shortcuts
"""""""""""


The body text contains a list of shortcut specifiers.

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 specified in the ``@mode`` node. In particular, the bindings specified 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 isn't 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.

- 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.

Adding extensible attributes to nodes and .leo files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Leo's .leo file format is extensible. The basis for extending .leo files are the
``t.unknownAttributes`` and ``v.unknownAttributes`` ivars of tnodes and vnodes,
or uA's for short. Leo translates between uA's and xml attributes in the
corresponding ``<v>`` and ``<t>`` elements in .leo files. Plugins may also use
``v.tempAttributes`` or ``t.tempAttributes`` ivars to hold temporary information
that will *not* be written to the .leo file.

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 Python's 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 tnode's 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 files 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 files. 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 gnx's in
thin derived files**. 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 files, but that would be much more
complicated than using ``t.unknownAttributes``

Here are the details about how Leo associates uA's with ``<v>`` and ``<t>`` elements in .leo files:

- **Native xml attributes** are the attributes of ``<v>`` and ``<t>`` elements that are
  known (treated specially) by Leo's 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 file, 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 file, 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.

Specifying Tk options using .leo_xresources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Leo looks for a file called ``.leo_xresources`` in the users home directory. If
found, Leo will pass that file to Tk's ``option_readfile`` method for the top
widget. This allows users to set Tk options.

Translating Leo's menus and messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. _gettext: http://docs.python.org/lib/module-gettext.html

It is easy to translate Leo's 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 Leo's log:

- Rather than using an '_' function to denote strings to be translated, Leo's
  g.es and g.es_print functions translate "odd" (first, third, fifth) arguments,
  leaving "even" arguments untranslated. Keyword arguments, color, newline, etc.
  are never translated.

- All calls to g.es and g.es_print in Leo's core follow this convention.

- g.translateString does the actual translation using Python's `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 Python's gettext module. (This script was also used to check that
  the proper arguments to g.es and g.es_print were translated.)

Chapter 9: History of Leo
+++++++++++++++++++++++++


@language rest

@rst html\history.html
*****************


##########################################
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 Leo's history:

.. .. contents::


.. Relative links...
.. _`Chapter 7\: Scripting Leo with Python`:    scripting.html
.. _`Chapter 8\: Customizing Leo`:              customizing.html
.. _`Chapter 10\: Theory of Operation`:         theory.html
.. _`Chapter 15\: Controlling Syntax Coloring`:     coloring.html
.. _`Chapter 16\: Debugging with Leo`:              debuggers.html
.. _`Chapter 17\: Using ZODB with Leo`:             zodb.html
.. _`Chapter 18\: Leo and Emacs`:                   emacs.html
.. _`Chapter 19\: Embedding Leo with the leoBridge Module`: leoBridge.html
.. _`Chapter 20\: Unit testing with Leo`:           unitTesting.html
.. _`Chapter 21\: ILeo - the IPython bridge`:       IPythonBridge.html

.. Absolute links..
.. _OPML:   http://en.wikipedia.org/wiki/OPML

Beginnings
^^^^^^^^^^


Leo grew out of my efforts to use Donald Knuth's "CWEB system of Structured
documentation." I had known of literate programming since the mid 1980's, 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.

Breakthrough
^^^^^^^^^^^^


March 5, 1996, is the most important date in Leo's 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 first 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 ``MORE``'s outlines could form the basis for Leo's 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 simplified ``CWEB``. Much later Leo started supporting the noweb
language.

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 Apple's YellowBox environment. Alas,
Apple broke its promises to Apple developers. I had to start again.

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 first
version to use xml as the format of .leo files. The last version of Borland Leo,
3.12 Final went out the door July 17, 2003.

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 first time in my career I was no longer
anxious while programming; it simply isn't possible to create bad bugs in
Python. The Python version of Leo was the first officially OpenSoftware version of
Leo. The first functional version of Leo in Python was 0.05 alpha, December 17,
2001.

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.

Allowing sentinel lines in derived files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


In the summer of 2001 I began to consider using sentinel lines in derived files.
Previously I had thought that outline structure must be 'protected' by remaining
inside .leo files. Accepting the possibility that sentinels might be corrupted
opened vast new design possibilities. In retrospect, problems with sentinel
almost never happen, but that wasn't obvious at the time! The result of this
design was known at first as ``Leo2``. That terminology is extinct. I think of
this version as the first version to support ``@file`` and automatic tangling
and untangling.

Untangling @file is easy!
^^^^^^^^^^^^^^^^^^^^^^^^^


The biggest surprise in Leo's history was the realization it is **much** easier
to untangle files 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 Leo's preferred markup language. My decision not to support noweb's
escape sequences made Leo's read code much more robust.

Leo 3.x: Continuous improvement
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


I spent 2002 taking advantages of Python's 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.
- @first and @last appeared in 3.7
- @asis and @nosent appeared in 3.8.
- Incremental syntax coloring and incremental undo appeared in 3.9.
- Paul Paterson created Leo's plugin architecture sometime during this period.
  Plugins have been a driving force in Leo's development because people can
  change how Leo works without altering Leo's core.
- 3.12 fixed a huge memory leak.
- 3.12 Final, the last 3.x version, appeared July 17, 2003.

Leo 4.0: Eliminating error 'recovery'
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


In late 2002 and throughout 2003 I worked on an entirely new file format.
4.0 final went out the door October 17, 2003 after almost a year intense
design work trying to improve error recovery scheme used while reading
derived files. In the summer of 2003 I realized that orphan and ``@ignore``'d
nodes must be prohibited in ``@file`` trees. With this restriction, Leo
could finally recreate ``@file`` trees in outlines using **only** the
information in derived files. This made the read code much more robust, and
eliminated all the previous unworkable error recovery schemes. At last Leo
was on a completely firm foundation.

Leo 4.1: The debut of gnx's
^^^^^^^^^^^^^^^^^^^^^^^^^^^


Leo first used gnx's (global node indices) as a foolproof way of associating
nodes in .leo files with nodes in derived files. 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.

Leo 4.2: Complete at last
^^^^^^^^^^^^^^^^^^^^^^^^^


Leo 4.2 Final went out the door September 20, 2004.
This surely is one of the most significant dates in Leo's history:

-   This marked the end worries about consistency of outlines and derived files:
    Leo recreates all essential information from thin derived files,
    so *there is nothing left in the .leo file to get out of synch*.

-   Thin derived files use gnx's extensively.  This simplifies the file format and makes thin derived files
    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 significant improvements in Unit testing.

-   As if this were not enough, 4.2 marked the 'great divide' in Leo's 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 Leo's 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 significant changes. I often find it hard to remember
what life with Leo was like before it.

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 dialog.  However,
the settings dialog proved not to be useful (worse, it inhibited design) and
the settings dialog was retired in Leo 4.4.

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-defined key-binding modes.

Development on long-delayed projects accelerated after 4.4 final went out the door.
Recent projects include:

- Controlling syntax coloring with jEdit's xml language-description files.
  See Chapter 15.
- Support for debugging scripts using external debuggers.
  See Chapter 16.
- Modifying Leo's vnodes and tnodes so that Leo's 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.

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.

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.

Leo 4.4.2
~~~~~~~~~


- Added support for myLeoSettings.leo
- The 'Big Reorg' made Leo's 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 finds.
- Added new commands and options to make Leo usable without a mouse.
- Added an option sax parser for reading .leo files.

Leo 4.4.3
~~~~~~~~~


- Added support for chapters in Leo's core.
- Added support for zipped .leo files.
- Added the leoBridge module. See `Chapter 19: Embedding Leo with the leoBridge Module`_.
- Removed all gui-dependent code from Leo's core.
- Added better support for the winpdb debugger.
- Added support for @enabled-plugins and @open-with nodes in settings files.

Leo 4.4.4
~~~~~~~~~


- The Great Graph Aha: Outlines don't 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 files.
- Added perfect import of foreign files with @auto nodes.
- Added new commands for resolving cvs conflicts.
- Replaced the jEdit_colorizer plugin with the threading_colorizer plugin.
- Made Leo compatible with jython.
- Added better support for icons in headlines.

Leo 4.4.5
~~~~~~~~~


- Leo now recognizes directives in headlines.
- Added support for @rst-preformat nodes to the rst3 plugin.

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 Leo's log.

Chapter 10: Theory of Operation
+++++++++++++++++++++++++++++++


@language rest

@rst html\theory.html
****************


##########################################
Chapter 10: Theory of Operation
##########################################

This chapter discusses how Leo's code works,
paying particular attention to topics that have caused difficulties in design or implementation.
This chapter will be of use primarily to those wanting to change Leo's code.

.. .. contents::


.. _`Chapter 9\: History of Leo`:   history.html
.. _`Chapter 11\: White Papers`:    whitepapers.html

Overview
^^^^^^^^


All versions of Leo are organized as a collection of classes. The general
organization of Leo has remained remarkably stable throughout all versions of
Leo, although the names of classes are different in different versions.
Smalltalk's Model/View/Controller terminology is a good way think about Leo's
classes. **Model classes** represent the fundamental data. The vnode and tnode
classes are Leo's 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. Leo's 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 files 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 Leo's global variables.
leo.py uses no global Python variables, except the gApp variable returned by
app(). leoGlobals.py defines 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 find 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 defined in ``leoNodes.py``.

Nodes
^^^^^


The vnode and tnode classes represent most of the data contained in the outline.
These classes are Leo's fundamental 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, firstChild,
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 Python's and
Tkinter's reference counting mechanisms will eventually delete vnodes, tnodes
and other data when a window closes.

Leo's XML file 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 file, the file format
would still need an unambiguous way to denote that tnodes are shared. Present
versions of Leo use **gnx's** (global node indices) as node indices. These indices
do not change once a node has created. This reduces cvs conflicts.

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 flicker and handling events properly.
These topics are interrelated.

**Eliminating flicker**. Leo must update the outline pane with minimum flicker.
Various versions of Leo have approached this problem in different ways. The
drawing code in leo.py is robust, flexible, 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 flag 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 simplification compared to previous versions of Leo. The entire
machinery of drawing icons in the vnode class has been eliminated. 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 don't 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
difficult 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 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 defines the following simplified event
handlers: ``onBodyChanged``, ``onBodyWillChange``, ``onBodyKey``, ``onHeadChanged`` and
``onHeadlineKey``. Commanders and subcommanders 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.

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 represent 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 compatibility 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``.

Find and change commands
^^^^^^^^^^^^^^^^^^^^^^^^


The find 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 particular, 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 simplifies the code
    because most ivars do not persist. 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 execution. That would cause severe flashing 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.

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 simplification 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.

Tangle and untangle commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^


This section describes Leo's 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 processes used to read and write
``@file`` trees.

The ``Tangle`` command translates the selected ``@root`` tree into one or more
well-formatted C source files. The outline should contain directives, sections
references and section definitions, as described in Chapter 4. The Untangle
command is essentially the reverse of the ``Tangle`` command. The Tangle command
creates a derived file from an ``@root`` tree; the Untangle command incorporates
changes made to derived files back into the ``@root`` tree.

The ``Tangle`` command operates in two passes. The first pass discovers the complete
definitions of all sections and places these definitions in a symbol table. The
first pass also makes a list of root sections. Definitions can appear in any
order, so we must scan the entire input file to know whether any particular
definition has been completed.

This second pass creates one file 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 section's definition. This is a recursive process
because any definition may contain other references. We can not allow a section
to be defined in terms of itself, either directly or indirectly. We check for
such illegally recursive definitions 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 indentation
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 create 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 definitions 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
file; within the derived file, the programmer may have 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 files 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 define a section in several ways: with an ``@c`` or ``@code``
directive or with a section definition line. To be useful, Untangle must handle
all these complications flawlessly. 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 first pass finds definitions in the
derived file and enters them into the **Untangle Symbol Table**, or UST.
Definitions often include references to other sections, so definitions often
include nested definitions of referenced sections. The first pass uses a
definition stack to keep track of nested definitions. The top of the stack
represents the definition following the latest reference, except for the very
first 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 definitions of a section should
match--otherwise there is an inconsistent definition. 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 definitions from the outline into the
**Tangle Symbol Table**, or TST. The second pass simultaneously updates all
sections in the outline whose definition in the TST does not match the
definition in the UST. The central coding insight of the Untangle command is
this:  **the second pass of Untangle is almost identical to the first 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 definition
into the symbol table, all the information is present that ``Untangle`` needs to
update that definition.

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 doesn't matter how the unicode string was created. This is the key
that makes Leo's 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 files.

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 can't assume that we know what it is, so for
safety we should assume the most restrictive encoding, namely "ascii". With this
assumption, Leo's code can't throw an exception during these promotions provided
that: 

- All strings are converted to unicode when Leo reads files or gets text from Tk.Text widgets.

- All string literals in Leo's code have only ascii characters.

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 first 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.

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 first came across it in the documentation for Apple's Yellow Box classes.

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 insufficient enough information
to tell what key actually caused the key event(!)
This is a significant hole in Tkinter's 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 specifiers.
  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 11: White papers
++++++++++++++++++++++++


@language rest

@rst html\whitepapers.html
*********************


##########################
Chapter 11: White Papers
##########################

I wrote the first 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.

.. .. contents::


.. External links...
.. _pychecker:              http://pychecker.sourceforge.net/
.. _`region inference`:     http://en.wikipedia.org/wiki/Region_inference

.. Relative links...
.. _chapter10:              theory.html
.. _appendices:             appendices.html
.. _`Rst3 plugin`:          rstplugin3.html
.. _`Scripting plugin`:     plugins.html#mod-scripting
.. _`test buttons`:         scripting.html#test-and-suite-nodes

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 simplifies the vnode class, and having
access to the vnode class simplifies 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 Leo's code. I am
about to convert Leo from wxPython to Python + Tk.
Edward K. Ream, November 4, 2001

Why I like Python
^^^^^^^^^^^^^^^^^


I've 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.

Clarity
~~~~~~~


What struck me first 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 don't 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! It's no accident that
Leo's new log pane was created first in Python.

Functions returning tuples are a "minor" feature with a huge impact on code
clarity. No more passing pointers to data, no more defining (and allocating and
deallocating) temporary structs to hold multiple values.

Python can't check declarations because there aren't any. However, there is a
really nifty tool called Pychecker that does many of the checks typically done
by compilers. See `pychecker`_ for details.

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.

-   Python's slicing mechanism is very powerful and applies to any sequence (string, list or tuple).
    Python's 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.

-   Python's special functions,  ``__init__``, ``__del__``, ``__repr__``, ``__cmp__``, etc.
    are an elegant way to handle any special need that might arise.

Safety
~~~~~~


Before using Python I never fully realized how difficult 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-find 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 don't have to
plan a debugging strategy! Finally, Python recovers from exceptions, so Leo can
keep right on going even after a crash!

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.

In fact, Python encourages optimization by moving to higher levels of
expression. For example, Leo's Open command reads an XML file. If this command
is too slow I can use Python's XML parser module. This will speed up Leo while
at the same time raising the level of the code.

Conclusions
~~~~~~~~~~~


Little of Python is completely new. What stands out is the superb engineering
judgment evident in Python's 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.

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.

Lifetime allocation
~~~~~~~~~~~~~~~~~~~


CC2 allocated objects one-at-a-time (simple allocation), in blocks of
fixed-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 CC2's 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 first to discover it. The Aha is
that a lifetime is defined 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::

    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.

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 C's 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 file lifetime are deallocated after the compiler completes
  a source file.

That's 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 file) 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.

Implications for pypy
~~~~~~~~~~~~~~~~~~~~~


Lifetime allocation isn't 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 Leo's 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 flow analysis may be sufficient to
discover lifetimes for a significant 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 benefit 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.

Chapter 12: Plugins
+++++++++++++++++++


@language rest

@rst html\plugins.html
*****************


##########################
Chapter 12: Plugins
##########################

This chapter discusses the plugins contained in leoPlugins.leo.
These plugins are part of Leo's official 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 buttons** in a matter of seconds. See `Creating
script buttons`_. Script buttons are extraordinarily useful. Try them, you'll be
instantly hooked.

.. .. contents::


.. External links...
.. _docutils:             http://docutils.sourceforge.net
.. _LaTeX:                http://www.latex-project.org/
.. _reStructuredText:     http://docutils.sourceforge.net/rst.html
.. _SilverCity:           http://silvercity.sourceforge.net

.. Relative links...
.. _`Specifying settings`:              customizer.html#specifying-settings
.. _`Chapter 8\: Customizing Leo`:      customizing.html
.. _`Chapter 13\: Writing Plugins`:     writingPlugins.html
.. _`Creating script buttons`:          scripting.html#creating-script-buttons

Enabling plugins
^^^^^^^^^^^^^^^^


You enable or disable plugins using @enabled-plugins nodes in leoSettings files (leoSettings.leo, myLeoSettings.leo or the .leo file being loaded).  See `Specifying settings`_ for full details of settings files.

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 already been loaded, Leo silently ignores the request to
   re-enable the plugin. Leo never attempts to disable 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.

Body pane
^^^^^^^^^



arrows.py
~~~~~~~~~


Rebinds up/down arrow keys.

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

rClick.py
~~~~~~~~~


This plugin provides a simple but powerful and flexible system of managing
scriptable context menus.

Named menus defined 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 howto's, demos and examples can be found in::

    test/testAtPopup.leo

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 file 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 doesn't find one it will attempt to create this directory.
This directory should contain what are called .ato files ( pronounced auto ).
Autocompleter will scan each .ato file that has a first part that matches a
languages name. For example: python.ato autocompleter recognizes python, and
will scan this file. The contents are read with the same mechanism that reads
the information in the nodes, so calltip and autocompleter information is added
to autocompleter's runtime database. If a new language has been added in the
autocompleter.ini file then an .ato file 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 file is a mechanism by which a user can carry
autocompletion and calltip information between .leo files/sessions.

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.

-   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.

script_io_to_body.py
~~~~~~~~~~~~~~~~~~~~


Send output from the Execute Script command to the end of the body pane.

Commands & directives
^^^^^^^^^^^^^^^^^^^^^



add_directives.py
~~~~~~~~~~~~~~~~~


Supports new Leo directives.

bibtex.py
~~~~~~~~~


This plugin manages BibTeX files 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 defined in dictionary ``templates`` in the \<\<globals\>\>
section, by default containing all required fields for every entry.

The file 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 file 'biblio.bib' as::

    @book{key,
    author = {A. Uthor},
    year= 1999}

Strings are defined in ``@string`` nodes and they can contain multiple entries.
All ``@string`` nodes are written at the start of the file. Thus the following
outline::

    -@bibtext biblio.bib
     +@string
      j1 = {Journal}
     +@article AUj1
      author = {A. Uthor},
      journal = j1
     +@string
      j2 = {Journal2}
      j3 = {Journal3}

Will be written as::

    @string{j1 = {Journal1}}
    @string{j2 = {Journal2}}
    @string{j3 = {Journal3}}

    @article{AUj1,
    author = {A. Uthor},
    journal = j1}

No error checking is made on the syntax. The entries can be organized under
nodes--if the headline doesn't start with '@', the headline and body text are
ignored, but the child nodes are parsed as usual. BibTeX files can be imported
by creating an empty node with ``@bibtex filename`` in the headline.
Double-clicking it will read the file ``filename`` and parse it into a
``@bibtex`` tree. No syntax checking is made, ``filename`` is expected to be a
valid BibTeX file.

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 flexibility 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 defined. 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 first level
since indentation is added at compile time.

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 month's-worth at a
time, or a year's-worth at a time. The format of the headlines is
configurable in the ini file.

FileActions.py
~~~~~~~~~~~~~~


Leo plugin that permits the definition of actions for double-clicking on file
nodes. Double-clicking in a ``@file`` node writes out the file 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 first one in outline order is used. The children of that node are expected
to contain a file pattern in the headline and the script to be executed in the
body. The file name is matched against the patterns (which are Unix-style shell
patterns), and the first matching node is selected. If the filename 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 filename from the ``@file`` directive.

-   ``shellScriptInWindow``, a utility function that runs
    a shell script in an external windows, thus permitting
    programs to be called that require user interaction

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 files purely for the purpose of
file actions, Leo does not do anything with or to such files.

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 maintained.

-   Clear Marked: unmarks all marked nodes and removes the roundup node.

-   Transfer Lassoed Nodes: this is a menu for inter-window communication.
    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.

import_cisco_config.py
~~~~~~~~~~~~~~~~~~~~~~


This plugin adds a menu item under the File->Import menu to import
Cisco configuration files.
The plugin will:

1)  Create a new node, under the current node, where the configuration 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
    config file. 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 configuration file).

3)  Create sections for the custom keywords specified in the customBlocks[] list in
    importCiscoConfig(). 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.

Library.py
~~~~~~~~~~


A plugin to store Leo trees in anydbm files. Note: there isn't such a thing as an
anydbm file: it's 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 Edward's Leo outline. Id like it to be able to
store unicode, but that may require a more specific db background, than anydbm.
Also note, that your library files 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.

macros.py
~~~~~~~~~


Creates new nodes containing parameterized section references.

mod_autosave.py
~~~~~~~~~~~~~~~


Autosave the Leo document every so often. The time between saves is given in
seconds in autosave.ini.

mod_read_dir_outline.py
~~~~~~~~~~~~~~~~~~~~~~~


This plugin allows Leo to read a complete directory's outline into a Leo's
Outline. Directories are converted into headlines and files names are listed
into the bodies.

mod_timestamp.py
~~~~~~~~~~~~~~~~


Timestamp all save operations to show when they occur.

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 node's 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`__.

__ nA_Directives_

.. _nA_Patterns:

Patterns:
   The patterns are defined in the headlines of sub-nodes of a single
   "nodeActions" node.

   The "nodeActions" node can be located anywhere within the same Leo file as
   the node that will be double-clicked.  For example, a pattern that matches a
   URL and a pattern that matches any python files stored as an @thin derived
   file could be stored under an @settings node as follows::

      @settings
      |
      +- nodeActions
         |
         +- http:\\*
         |
         +- @thin *.py

   __ nA_Directives_

   Pattern matching is performed using python's 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:

      .. table::

         ======= =========== ==============
         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 @file node (@thin, @shadow, ...),
   the pattern can use "@files" at the beginning of the pattern to match on any
   derived file type.  For example, the pattern "@files \*.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 first sub-node under the "nodeActions" node to the last
   sub-node.  Only the script associated with the first matching pattern is
   invoked unless overwritten by the "V" `pattern directive`__.

   __ nA_Directives_

   This can be used to define a broad pattern such
   as "@files \*.py", and then, by placing a more restrictive pattern above it,
   such as "@files \*_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
      file 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 pattern's 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

.. _nA_Directives:

Directives:
   The following pattern specific directives can be appended to the end of a
   pattern (do not include the ':'):

   :[X]:
      Use python's 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 remaining patterns.
      The "V" represents a down arrow that symbolizes the passing of the event
      to the next pattern below it.

      __ nA_Patterns_

      For example, adding the "[V]" directive to the "@files \*_test.py" in
      the `Patterns`__ section above, changes its script from being 'an
      alternate to' to being 'a pre-processor for' the "@files \*.py" script::

         +- nodeActions
            |
            +- @files *_test.py [V]
            |
            +- @files *.py

   :[>]:
      Matching the pattern will not block the double-click event from being
      passed to other plugins.
      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 specifies all three directives::

      ^@files .*\.py$ [X,V>]

Configurations:
   The nodeActions plugin supports the following global configurations using
   Leo's support for setting global variables within an @settings node's
   sub-nodes in the leoSettings.leo, myLeoSettings.leo, and the project Leo
   file:

   @bool nodeActions_save_atFile_nodes = False

      :True:
         The nodeActions plugin will save a double-clicked derived file node
         to disk, if a pattern match occurred, before executing its script.  

      :False:
         A pattern match to a double-clicked derived file node will **not**
         cause the derived file to be saved to disk.
         (default)

   @int nodeActions_message_level = 1

      Specifies 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 associated with the
      "http:\\\\\*" pattern.  The following script in the body of the pattern's
      node displays the URL in a browser::

         import webbrowser
         hClicked = pClicked.h     #Clicked node's Headline text
         webbrowser.open(hClicked) #Invoke browser

   Executing commands (tested with WinXP):

      The following script can be placed in the body of a pattern's node to
      execute a command in the first line of the body of a double-clicked node::

         g.os.system('"Start /b ' + pClicked.bodyString() + '"')

outline_export.py
~~~~~~~~~~~~~~~~~


Modify the way exported outlines are displayed.

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.

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 file 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
define your own class entirely, provided you implement the prettyPrintNode
method.

scheduler.py
~~~~~~~~~~~~


A plugin to schedule commands for later execution. It's 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 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.

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.

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 Leo's ``@nosent`` write machinery to create one
string out of possibly many nodes. This plugin requires the simplified atFile
write code that is new in 4.2.1.

This plugin creates two buttons in Leo's 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 first 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 file, as your template mark will be erased between
sessions.

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'.

Dialogs
^^^^^^^



gtkDialogs
~~~~~~~~~~


gtkDialogs replaces Tk's file dialogs with Gtk file 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.

Debugging &  testing
^^^^^^^^^^^^^^^^^^^^



failed_import.py
~~~~~~~~~~~~~~~~


A plugin to test import problems.

dump_globals.py
~~~~~~~~~~~~~~~


Dump Python globals at startup.

enable_gc.py
~~~~~~~~~~~~


Enable debugging and tracing for Python's garbage collector.

trace_gc.py
~~~~~~~~~~~


Trace changes to Leo's objects at idle time.

trace_keys.py
~~~~~~~~~~~~~


Trace keystrokes in the outline and body panes.

trace_tags.py
~~~~~~~~~~~~~


Trace the most common hooks, but not key, drag or idle hooks.

External editors & Open With
^^^^^^^^^^^^^^^^^^^^^^^^^^^^



mod_tempfname.py
~~~~~~~~~~~~~~~~


Replaces ``Commands.openWithTempFilePath`` so Leo opens temporary
files with a filename that begins with the headline text, and
located in a ``username_Leo`` subdirectory of the temporary
directory. The ``LeoTemp`` prefix is omitted.  This makes it easier to
see which temporary file is related to which outline node.

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.

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

name is name of the menu item. shortcut specifies 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 file. The ext argument specifies the extension of
the temp file.

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 file extension base on what
  @language directive is in effect.

- If the .leo file being loaded contains @openwith nodes, the File:Open With
  menu contains only the items created 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.

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.

vim.py
~~~~~~


A plugin that communicates with VIM:

When properly installed, this plugin does the following:

- Double clicking on a node's icon opens that node in VIM.

- Leo will put the Vim cursor at same location as the Leo cursor in node's 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 file in VIM.

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.

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.

Files
^^^^^



empty_leo_file.py
~~~~~~~~~~~~~~~~~


Opens any empty file as a minimal .leo file.

leoOPML.py
~~~~~~~~~~


.. _OPML:                   http://en.wikipedia.org/wiki/OPML
.. _`OPML 2.0 standard`:    http://www.opml.org

**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-file command creates a Leo outline from an .opml file.
The write-opml-file command writes the present Leo outline to an .opml file.

Various settings control what gets written to .opml files, 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 files.
The default values are shown.

- ``@bool opml_read_derived_files = True``

  If True, Leo reads derived files when reading .opml files.

- ``@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-specific 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 specified specified
  by this option.  Thus, all OPML text generated by this plugin should conform to the `OPML 2.0 standard`_.

- ``@string opml_version = 2.0``

  The opml version string written to the ``<OPML>`` element.
  Use ``2.0`` unless there is a specific reason to use ``1.0``.

- ``@bool opml_write_body_text = True``

  If True, Leo writes body text to the OPML file.

- ``@bool opml_write_derived_files = True``

  If True, Leo writes derived files when writing .opml files.

- ``@bool opml_write_leo_details = True``

  If True, Leo writes the native attributes of Leo's ``<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 file.

- ``@bool opml_write_uAs = True``

  If True, Leo writes unknown attributes (uA's) in <:uA> sub-elements of <outline> elements.

lineNumbers.py
~~~~~~~~~~~~~~


Adds #line directives in perl and perlpod programs.
Currently supports only perl and perlpod.

multifile.py
~~~~~~~~~~~~


Multipath enables the ability to write a file to multiple locations. It acts as
a post-write mechanism, a file must be written to the file 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 file in each of these directories.

There is an additional directive that simplifies 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 file 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 file is created. These
directives must at the beginning of the line and by themselves.

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 file.

leoToRTF
~~~~~~~~


This plugin takes an outline stored in LEO and outputs it as a numbered list to
an RTF file. The RTF file 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 @file nodes are stored in the rtf_export.ini file
in your Leo\plugins folder.

The default export path is also stored in the INI file. By default, it's set to c:\ so
you may need to modify it depending on your system.

leoToHTML
~~~~~~~~~


This plugin takes an outline stored in LEO and converts it to html which is
then either saved in a file 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 file and the plugins
properties dialog.

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-file command creates a Leo outline from an .opml file.
The write-opml-file command writes the present Leo outline to an .opml file.

Various settings control what gets written to .opml files, 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 files. 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 specific reason to use 1.0.

- @bool opml_write_body_text = True

  Leo writes body text to the OPML file only if this is True.

- @bool opml_write_leo_details = True

  If True, Leo writes the native attributes of Leo's <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 file.

Guis
^^^^



__wx_alt_gui.py
~~~~~~~~~~~~~~~


This plugin allows wxPython to be used as leo's 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.

Icon and status areas
^^^^^^^^^^^^^^^^^^^^^



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.

nav_buttons.py
~~~~~~~~~~~~~~


Adds navigation buttons to icon bar. Tk only.

nav_qt.py
~~~~~~~~~


Qt version of nav_buttons.py (history navigation)

newButtons.py
~~~~~~~~~~~~~


Automatically add nodes for common tasks.

hoist.py
~~~~~~~~


Add Hoist/De-Hoist buttons to the toolbar.

nodenavigator.py
~~~~~~~~~~~~~~~~


Adds "Recent" and "Marks" pulldown buttons to the toolbar.

searchbox.py
~~~~~~~~~~~~


Adds a quick search to Leo's 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.

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.

toolbar.py
~~~~~~~~~~


A plugin that enhances Leo's 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 Leo's 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 demo's and howto's
see test/testAtPopup.leo for examples of enhanced buttons

UNL.py
~~~~~~


This plugin supports Uniform Node Locators (UNL's). UNL's specify nodes within
Leo files. UNL's are not limited to nodes within the present Leo file; you can
use them to create cross-Leo-file 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 UNL's select the node specified in the
   UNL. If the UNL species in another Leo file, the other file will be opened.

UNL's 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.  UNL's of the form::

    file:<path>#headline1-->...-->headlineN

refer to a node specified in <path> For example, double clicking the following
headline will take you to Chapter 8 of Leo's Users Guide::

    @url file:c:/prog/leoCvs/leo/doc/leoDocs.leo#Users Guide-->Chapter 8: Customizing Leo

For example, suppose you want to email someone with comments about a Leo file.
Create a comments.leo file 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 file! Send the comments.leo to your friend, who can use the
comments.leo file to quickly navigate to the various nodes you are talking
about. As another example, you can copy UNL's into emails. The recipient can
navigate to the nodes 'by hand' by following the arrows in the UNL.

**Notes**:

- At present, UNL's refer to nodes by their position in the outline. Moving a
  node will break the link.

- Don't refer to nodes that contain UNL's in the headline. Instead, refer to the
  parent or child of such nodes.

- You don't have to replace spaces in URL's or UNL's by '%20'.

quicksearch.py
~~~~~~~~~~~~~~


This plugin adds a fast-to-use search widget, in the style of "Find in files" feature of many editors.

Just load the plugin, activate "Nav" tab, enter search text and press enter.

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.

LeoN
^^^^


LeoN is Leo over the Network. LeoN is Collaborative Leo. This is an important
project for Leo's long-term development. See leo/doc/LeoN for important research
papers that form the basis of this project.

Menus & translations
^^^^^^^^^^^^^^^^^^^^



chinese_menu.py
~~~~~~~~~~~~~~~


Translate a few menu items into Simplified Chinese

By Zhang Le <ejoy@xinhuanet.com>

french_fm.py
~~~~~~~~~~~~


Translate menus to French

pie_menus.py
~~~~~~~~~~~~


Adds pie menus.  See http://www.piemenus.com/

contextmenu.py
~~~~~~~~~~~~~~


Define various useful actions for context menus (for Qt ui)

Examples are:

- Edit in $EDITOR
- Edit @thin node in $EDITOR (remember to do "refresh" after this!)
- Refresh @thin node from disk (e.g. after editing it in external editor)
- Go to clone

Here's an example on how to implement your own context menu items 
in your plugins::

    def nextclone_rclick(c,p, menu):
        """ Go to next clone """

        # only show the item if you are on a clone
        # this is what makes this "context sensitive"
        if not p.isCloned():
            return    

        def nextclone_rclick_cb():
            c.goToNextClone()

        # 'menu' is a QMenu instance that was created by Leo 
        # in response to right click on tree item

        action = menu.addAction("Go to clone")
        action.connect(action, QtCore.SIGNAL("triggered()"), nextclone_rclick_cb)

And call this in your plugin *once*::

    g.tree_popup_handlers.append(nextclone_rclick)

Nodes
^^^^^



at_folder.py
~~~~~~~~~~~~


Synchronizes ``@folder`` nodes with folders. If a node is named ``@folder
path_to_folder``, the content (filenames) of the folder and the children of that
node will be sync. Whenever a new file 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 find any files much
easier from leo. Moreover, I add another feature to allow you to group files(in
leo) into children of another group. This will help when there are many files in
that folder. You can logically group it in leo (or even clone it to many
groups), while keep every files in a flat/single directory on your computer.

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 fire javac, or whatever your using. ``@produce`` functions
as a directive. After executing, a log file/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 first. I'm
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.

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 file in the body pane.

-   Double clicking the icon box of a node whose headline contains ``@strip <path-to-file>``
    places the contents of the file in the body pane, with all sentinels removed.

This plugin also accumulates the effect of all ``@path`` nodes.

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 doesn't 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 don't 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? I'm 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 files, e.g.,

- email messages 
- news feeds
- news groups
- documentation
- remote files
- statistics
- file system data
- data base records

You can do this as a standard plugin, but as an AutoTrees handler you,

- don't 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

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
file and create a section reference to the payload node, which contains the
data. The Export base64 command asks for a location to place the file. 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 file 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 find. Id like to change this in the future.

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 file.

3. Moving Nodes(experimental). You can quickly move a node to its
parent's parent or after a sibling, if they exist.

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 "find all" / "change all".
- Convert the marks to a label.
- Run the "Clone label subnodes" command.

Finally, if you read a derived file, and the content of a node changes, the
previous content is available under the label "before change:"

read_only_nodes.py
~~~~~~~~~~~~~~~~~~


A plugin to create and update ``@read-only`` nodes. I wanted to have the ability to
import files in "read-only" mode, that is, in a mode where files 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 files. I want these files to be part of a leo outline, but I don't 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 specified file and puts it into the node content.

- If the ``@read-only`` directive was in the leo outline already, and the file 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 file content has *not* changed, the file is simply read and the node is
  not marked as changed.

- When you write a ``@read-only`` directive, the file 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 file, just edit the headline
  and press Enter. The file 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`` file cannot be modified in leo.

The syntax to access files 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 specified as follows::

    @read-only ftp://username:password@ftp.someserver.org/filepath

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.

- 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 infinite 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).

slideshow.py
~~~~~~~~~~~~


This plugin supports slideshows in Leo outlines.

It defines four new commands:

- next-slide-show:  move to the start of the next slide show,
  or the first slide show if no slide show has been seen yet.

- prev-slide-show:  move to the start of the previous slide show,
  or the first 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.

startfile.py
~~~~~~~~~~~~


Launches (starts) a file 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 file.

Plugins manager & menu
^^^^^^^^^^^^^^^^^^^^^^



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
files and update your entire Leo installation directly without needing
a CVS client.

plugin_manager.py
~~~~~~~~~~~~~~~~~


A plugin to manage Leo's Plugins:

- Enables and disables plugins.
- Shows plugin details.
- Checks for conflicting hook handlers.
- Checks for and updates plugins from the web.

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 defining
functions named ``cmd_XZY``. These will appear in a submenu. If the plugin
requires an INI file then a configure menu item will be created which will show
an INI file editor. The plugin can define an ``applyConfiguration`` function,
which will be called when the configuration changes. Plugins can also define a
top level function to be called instead of the default "About" dialog by
defining 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 define their name by setting the ``__plugin_name__`` property.
Plugins can also attempt to select the order they will appear in the menu by
defining a ``__plugin_prioriy__``. The menu will be created with the highest
priority items first. This behavior is not guaranteed since other plugins can
define 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.

Scripting
^^^^^^^^^



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.netfirms.com/dyna_menu.py.html

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 button's 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.

That's 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 file is opened.

- ``@button`` nodes create script buttons.
- ``@plugin`` nodes cause plugins to be loaded.
- ``@script`` nodes cause a script to be executed when opening a .leo file.

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.

Servers
^^^^^^^



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
   file.  Start clicking :-)

You can use the browser's refresh button to update the top-level view in the browser after you have opened or closed files.

To enable this plugin put this into your file::

    @settings
        @bool http_active = True
        @int  port = 8080
        @string rst_http_attributename = 'rst_http_attribute'

Spell checking
^^^^^^^^^^^^^^



spellpyx.py
~~~~~~~~~~~


aspell.pyx: Leo's 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 Leo's Edit menu. This command brings up a spell
checking dialog. You can set options by changing entries in spellpyx.ini in
Leo's 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 isn't 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.

Text formatting
^^^^^^^^^^^^^^^



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 I've been unable to keep
up with the speed of Edward's Leo development. He has made such significant
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 final 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, you'll 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

rst3.py
~~~~~~~


The rst3 plugin creates output files from Leo outlines containing rST
(reStructuredText_) markup. rst3 options control most aspects of this plugin's
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, Python's 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 Leo's 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 file 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 files to the docutils module for further
processing. Docutils generates HTML files or LaTeX files depending on the file's
extension. HTML files generated by docutils refer to three .css (cascading style
sheet) files that should exist in the same directory as the generated HTML file.
You can control the formatting of the HTML file by altering these .css files.

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 p's tree (p defaults to presently selected node) looking for @rst nodes.
When the first @rst node is found, writeNodeToString processes the node as usual, with the following changes:

- @rst need not be followed by a filename; any filename 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 file, 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::

    import leo.core.leoPlugins as leoPlugins
    rst3 = leoPlugins.getPluginModule('rst3')
    if rst3:
        controller = rst3.controllers.get(c)
        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.

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 section references and Leo directives,
    and creates a sibling containing the results.

Requires 4Suite 1.0a3 or better, downloadable from http://4Suite.org.

Windows
^^^^^^^



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.

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.

EditAttributes.py
~~~~~~~~~~~~~~~~~


A plugin that lets the user to associate text with a specific 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.

maximizeNewWindows.py
~~~~~~~~~~~~~~~~~~~~~


Maximizes all new windows.

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 find value in
being able to quickly execute commands they do not use very often.

redirect_to_log.py
~~~~~~~~~~~~~~~~~~


Send all output to the log pane.

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.

UASearch.py
~~~~~~~~~~~


A plugin for searching unknownAttributes (uA's).

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.

URLloader.py
~~~~~~~~~~~~


This plugin uses Python's urllib module to download files and import them into Leo.
It requires the TabbedLog plugin.

Chapter 13: Writing Plugins
+++++++++++++++++++++++++++


@language rest

@rst html\writingPlugins.html
************************


####################################
Chapter 13: Writing Plugins
####################################

.. .. contents::


.. External links...
.. _docutils:             http://docutils.sourceforge.net
.. _LaTeX:                http://www.latex-project.org/
.. _reStructuredText:     http://docutils.sourceforge.net/rst.html
.. _SilverCity:           http://silvercity.sourceforge.net

.. Relative links...
.. _`Event handlers`:                           scripting.html#event-handlers
.. _`Chapter 7\: Scripting Leo with Python`:    scripting.html
.. _`Chapter 8\: Customizing Leo`:              customizing.html

Overview
^^^^^^^^


A **plugin** is a Python file that appears in Leo's 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 Leo's look and feel.
``leoPlugins.leo`` contains all of Leo's official plugins. Studying this file 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 Leo's source code simply by importing any module
   defined 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 Leo's scripting chapter.

The rest of this chapters discusses topics related specifically to plugins.

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. Leo's plugins test suite takes care of the rest.

Turning script buttons into plugins
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


This section provides step-by-step instructions for turning a script button into a plugin.
The plugin will define 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 predefined ``c`` and ``p`` constants.
Our plugin will create a minibuffer command called print-cp.

Here are the step-by-step instructions:

1. Open leoPlugins.leo and use the Copy Node command to copy the tree at:

Plugins--> Templates: these show recommended ways of defining plugins.-->Template for Tk plugin with per-commander controller class

2. 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

3. Update the docstring, the __version__ constant and the << imports >> section.
   Note that unlike when using script buttons, you must have the following imports::

    import leo.core.leoGlobals as g
    import leo.core.leoPlugins as leoPlugins

4. Because this plugin doesn't 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.

5. 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.

6. 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')

7. Define 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.

8. Enable the print_cp plugin by putting the following in an @enabled-plugins node::

    print_cp.py

9. 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>.

That's all.  You can find the completed version of the print_cp plugin in leoPlugins.leo,
or leoPluginsRef.leo if you are using cvs.

Important security warnings
^^^^^^^^^^^^^^^^^^^^^^^^^^^


Naively using plugins can expose you and your .leo files 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 Pandora's, we cannot resist wanting to see "What's in the box?" And are
    we going to fire up a text editor to make a detailed examination of the
    ASCII XML? Never! We're 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():
        for p in c.allNodes_iter():
            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
    for p in c.allNodes_iter():
        << change `rexec` to `exec` in p's body >>
    << delete badNode >>
    << clear the undo stack >>

This script will introduce a security hole the .leo file 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 file.

Chapter 14: Leo and reStructuredText
++++++++++++++++++++++++++++++++++++


@language rest

@rst html\rstplugin3.html
********************


.. publish_argv_for_missing_stylesheets = --language=de,--documentclass=report,--use-latex-toc

######################################
Chapter 14: Leo and ReStructuredText
######################################

.. .. contents::


.. rST links used in this document...

.. External links...
.. _docutils:           http://docutils.sourceforge.net
.. _LaTeX:              http://www.latex-project.org/
.. _reStructuredText:   http://docutils.sourceforge.net/rst.html
.. _SilverCity:         http://silvercity.sourceforge.net
.. _Sphinx:             http://sphinx.pocoo.org/

.. Hard links to Leo's web site...
.. _ListManagerDocs.html: http://webpages.charter.net/edreamleo/ListManagerDocs.html
.. _wxListManager.leo:    http://webpages.charter.net/edreamleo/wxListManager.leo

Overview
^^^^^^^^


reStructuredText_ (rST) is a popular markup language for writing documents. rST
is simple, yet powerful. All of Leo's documentation is written in rST, and then
processed via the docutils_ and Sphinx_ processors to produce Leo's 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 fixes 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 file, Leo's headlines become section headings. When writing
external rST files, **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 file. In most cases, you won't even see the rST markup for
headings!

3. @auto-rst nodes allow you to edit exising rST files in Leo. The outline
structure of such nodes mirrors the level of the rST section headings. Note:
there may be minor variations the first time you import an existing rST file,
but these differences will not affect the meaning of the rST file. After the
first import, the only changes when writing the imported rST file will be
changes *you* make.

The three features just discussed (Leo's organizational capabilities, automatic
generation of markup for rST headings, and @auto-rst trees) are useful for
anyone using reStructuredText. In addition Leo provides additional capabilities
for power users:

4. @rst trees can contain settings that affect how Leo writes individual nodes.

@rst trees allows the ultimate in flexible formating.
We'll 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

causes the body text of the node to be displayed as an rST code block.

Leo's rst3 command generates .htm, .html or .tex output files from @rst tree,
provided that you have installed Python's docutils_ module.  The rst3 command
will use the SilverCity_ syntax coloring package if it installed.

The rst3 command sends .htm, .html or .tex files to the docutils module for further
processing. Docutils generates HTML files or LaTeX files depending on the file's
extension. HTML files generated by docutils refer to three .css (cascading style
sheet) files that should exist in the same directory as the generated HTML file.
You can control the formatting of the HTML file by altering these .css files.
See `Required cascading style sheets`_ for more details.

5. The rST options just discussed will suffice to create just about any kind of
rST output. But for those desiring the ultimate in flexibility, it is relatively
straightforward to create Leo outlines or external files 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.

Power features of @rst trees
^^^^^^^^^^^^^^^^^^^^^^^^^^^^


1. The rst3 command allows much more flexible 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 specifies 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 files.

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 fine-tune the formatting of your source files.
See `Using doc parts`_ for full details.

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.

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 filenames 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: don't 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_file
    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 files.

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 docutils.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 computer 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 contet.  For example, you're 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 Sally's".    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 significance 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

      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: don't generate sections.  Instead, generate lines of the form::

        **headline**

strip_at_file_prefixes (default: True)
    True: remove @auto, @file, @nosent and @thin from the start of headlines.

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 sections.
    The first character is reserved so you can specify the top-level section explicitly.

verbose (default: True)
    True: write informational messages.

write_intermediate_file (default: False)
    True: writes intermediate files before sending them to docutils.
    This option only applies to .htm, .html and .tex files.
    The name of the intermediate file has the name of the output file with .txt appended.
    This option has effect only if the generate_rst option is True.

Options supporting the http plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The following options are for the use of Bernhard Mulder's 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 file.  Clicking on link will cause the http server to pass a new page to the browser.  You can use the browser's refresh button to update the top-level view in the browser after you have opened or closed files.

**Important**: See the docstring for the http plugin for information on
configuring 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:

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 Leo's
      unknownAttributes mechanism.

http_attributename (default: 'rst_http_attribute')
    The name of the attribute name written to the unknownAttributes 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 fields specified 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 effect unless the http_server_support option is True.

Options that set command names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The following options specify the 'spelling' of headline commands. The
option_prefix and option_prefixes command also define the spelling of special
doc parts.

You can change these to make them shorter or to avoid conflicts with headlines
in your Leo files. The list below merely gives the default value for each
setting.

`code_prefix`: '\@rst-code'

`ignore_headline_prefix`: '\@rst-no-head'

`ignore_headlines_prefix`: '\@rst-no-headlines'

`ignore_prefix_tree`: '\@rst-ignore'

`ignore_node_prefix`: '\@rst-ignore-node'

`ignore_tree_prefix`: '\@rst-ignore-tree'

`option_prefix`: '\@rst-option'

`options_prefix`: '\@rst-options'

`preformat_prefix`: '\@rst-preformat'

`rst_prefix`: '\@rst'

`show_headline_prefix`: '\@rst-head'

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. 

@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.  Furthermore, no rST section is generated if the TEXT is empty.

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::

    @ This is a comment in a doc part.
    Doc parts can span multiple lines.
    The next line ends the doc part
    @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 files. This
makes your source files 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 option, doc parts
have no special significance 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.

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 file 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 prefix the option name shown in this documentation with the prefix 'rst3\_'.  For example::

    @settings
        @bool rst3_write_intermediate_file = True

The code-block directive
^^^^^^^^^^^^^^^^^^^^^^^^


The rst3 command defines 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

        import leo.core.leoPlugins as leoPlugins
        import leo.core.leoGlobals as g

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.

.. .. code-block:: Python

    .. import leo.core.leoPlugins as leoPlugins
    .. import leo.core.leoGlobals as g

.. Otherwise, the output looks like this::

    .. import leo.core.leoPlugins as leoPlugins
    .. import leo.core.leoGlobals as g

See the Scripting chapter in LeoDocs.leo for many examples of how to use
code-blocks.

Required cascading style sheets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


HTML files generated by the rst3 command assume that three .css (cascading style
sheet) files exist in the same directory. For the HTML output to look good the
following .css files should exist:

- default.css is the default style sheet that docutils expects to exist.

- leo_rst.css contains some style improvements based on Gunnar Schwant's DocFactory.

- silver_city.css is the style sheet that controls the syntax highlighting generated by SilverCity.

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
wouldn't be possible with "plain" rST. For instance, the background color of
this page was specified in a body style.

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.

Examples
^^^^^^^^


The file 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
simplified if adapted for the rst3 command.

The files in LeoDocs.leo under the node 'Leo's 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.

Theory of operation
^^^^^^^^^^^^^^^^^^^


The code for the rst3 command is more complex than usual. Fortunately, the
overall organization is straightforward.

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_` prefix.
    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 files.
    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 first 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.

writeNode
    writeNode first 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 writeHeadline
    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 first inits all options from settings,
    then updates those options using the anonymous
    dictionaries contained in the tnodeOptionsDict.
    scanAllOptions works like g.scanAllDirectives, but the code is much simpler.

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 p's tree (p defaults to presently selected node) looking for @rst nodes.
When the first @rst node is found, writeNodeToString processes the node as usual, with the following changes:

- @rst need not be followed by a filename; any filename 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 file, 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::

    import leo.core.leoPlugins as leoPlugins
    rst3 = leoPlugins.getPluginModule('rst3')
    if rst3:
        controller = rst3.controllers.get(c)
        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.

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 15: Controlling syntax coloring
+++++++++++++++++++++++++++++++++++++++


@language rest

@rst html\coloring.html
******************


#########################################
Chapter 15: Controlling Syntax Coloring
#########################################

This chapter discusses how to control Leo's new syntax colorer using Python
files derived from jEdit_'s xml language description files. It also discusses
settings related to syntax coloring.

**Important**: this material is for those who want to support Leo's colorizing
code. You do *not* need to understand this chapter in order to use Leo's
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.

.. .. contents::


.. External links...
.. _jEdit:                      http://www.jedit.org/
.. _`jEdit's documentation`:    http://www.jedit.org/42docs/users-guide/writing-modes-part.html

.. Relative links...
.. _`Ruleset name`:      `Ruleset names`_
.. _`Chapter 8`:           customizing.html

Files
^^^^^


The jEdit_ editor drives its syntax colorer using xml **language description files.**
`jEdit's documentation`_ contain a complete description of these xml files.
Each xml file 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**: jEdit's xml language description files contain no explicit ``<RULE>`` elements
Rules are simply sub-elements of an enclosing ``<RULES>`` element.
The element indicates the kind of rule that is specified,
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 files directly,
Leo uses Python **colorer control files**,
created automatically from the xml files by a script called ``jEdit2Py``.
These Python files contain all the information in the jEdit's xml files,
so we can (loosely) speak of modes, rulesets, rules, properties and attributes in the Python colorer control files. 
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 file.

Using Python colorer control files 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 Leo's colorizer in any way.
  Moreover, the ``jEdit2Py`` script can contain debugging traces and checks.

- Colorer control files are valid .py files, so all of Python's import optimizations work as usual.
  In particular, all the data in colorer control files is immediately accessible to Leo's colorer.

- Colorer control files are easier for humans to understand and modify than the equivalent xml file.
  Furthermore, it is easy to insert debugging information into Python colorer control files.

- It is easy to modify the Python colorer control files 'by hand' without changing the corresponding xml file.
  In particular, it would be easy to define entirely new kinds of pattern-matching rules in Python merely
  by creating functions in a colorer control file.

The colorizer's inner loop
^^^^^^^^^^^^^^^^^^^^^^^^^^


When Leo's syntax colorer sees the ``'@language x'`` directive,
it will import ``x.py`` from Leo's ``modes`` folder.
The colorer can then access any module-level object ``obj`` in ``x.py`` as ``x.obj``.

Colorizer control files 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 first 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 dictionaries 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.

Format of colorizer control files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The following sections describe the top-level data in ``x.py``.

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``.

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 properties 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": "<!--",
        "indentCloseBrackets": "}",
        "indentOpenBrackets": "{",
        "lineUpClosingBracket": "true",
    }

Attribute dictionaries and x.attributesDictDict
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


``x.py`` contains a **attribute dictionary** for each ruleset in ``x.xml``.
Keys are attribute names, values strings representing the values of the attributes.
This dictionary is empty if a ruleset contains no attributes.
The valid keys are:

- ``'default'``: the default token type.  ``'null'`` is the default.

- ``'digit_re'``: a regular expression.
  Words matching this regular expression are colored with the ``digit`` token type.

- ``'ignore_case'``: ``'true'`` or ``'false'``.  Default is ``'true'``.

- ```highlight_digits'``: ``'true'`` or ``'false'``.  Default is ``'true'``.

- ``'no_word_sep'``: A list of characters treated as 'alphabetic' characters when matching keywords.

For example, here is one attribute dictionary in php.py::

    # Attributes dict for php_javascript ruleset.
    php_javascript_attributes_dict = {
        "default": "MARKUP",
        "digit_re": "",
        "highlight_digits": "true",
        "ignore_case": "true",
        "no_word_sep": "",
    }

``x.py`` also contains **x.attributesDictDict**.
Keys are ruleset names, values are attribute dictionaries.
Here is ``attributesDictDict`` for php.py::

    # Dictionary of attributes dictionaries for php mode.
    attributesDictDict = {
        "php_javascript": php_javascript_attributes_dict,
        "php_javascript_php": php_javascript_php_attributes_dict,
        "php_main": php_main_attributes_dict,
        "php_php": php_php_attributes_dict,
        "php_php_literal": php_php_literal_attributes_dict,
        "php_phpdoc": php_phpdoc_attributes_dict,
        "php_tags": php_tags_attributes_dict,
        "php_tags_literal": php_tags_literal_attributes_dict,
    }

**Note**:
The ``jEdit2Py`` script creates 'friendly' names for attribute dictionaries *solely* as an aid for people reading the code.
Leo's colorer uses only the name ``x.attributeDictDict``;
Leo's colorer never uses the actual names of attribute dictionaries.

Keyword dictionaries and x.keywordsDictDict
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


``x.py`` contains a **keyword dictionary** for each ruleset in ``x.xml``.
``x.py`` contains an empty keywords dictionary if a ruleset contains no ``<KEYWORDS>`` element.

Keys are strings representing keywords of the language describe by the mode.
Values are strings representing syntactic categories,
i.e. a ``TYPE`` attribute valid in ``x.xml``, namely:
``COMMENT1``, ``COMMENT2``, ``COMMENT3``, ``COMMENT4``,
``FUNCTION``,
``KEYWORD1``, ``KEYWORD2``, ``KEYWORD3``, ``KEYWORD4``,
``LABEL``, ``LITERAL1``, ``LITERAL2``, ``LITERAL3``, ``LITERAL4``,
``MARKUP``, ``NULL`` and ``OPERATOR``.

For example, here (parts of) some keyword dictionaries in php.py::

    # Keywords dict for mode php::PHP
    php_PHP_keywords_dict = {
        "COM_invoke": "keyword2",
        "COM_load": "keyword2",
        "__CLASS__": "keyword3",
        ...
        "abs": "keyword2",
        "abstract": "keyword1",
        "accept_connect": "keyword2",
        ...
    }

    # Keywords dict for mode php::JAVASCRIPT_PHP
    php_JAVASCRIPT_PHP_keywords_dict = {}

    # Keywords dict for mode php::PHPDOC
    php_PHPDOC_keywords_dict = {
        "@abstract": "label",
        "@access": "label",
        "@author": "label",
        ...
        "@var": "label",
        "@version": "label",
    }

``x.py`` also contains **x.keywordsDictDict**.
Keys are ruleset names, values are keywords dictionaries.
Here is ``keywordsDictDict`` for php.py::

    # Dictionary of keywords dictionaries for php mode.
    keywordsDictDict = {
        "php_javascript": php_javascript_keywords_dict,
        "php_javascript_php": php_javascript_php_keywords_dict,
        "php_main": php_main_keywords_dict,
        "php_php": php_php_keywords_dict,
        "php_php_literal": php_php_literal_keywords_dict,
        "php_phpdoc": php_phpdoc_keywords_dict,
        "php_tags": php_tags_keywords_dict,
        "php_tags_literal": php_tags_literal_keywords_dict,
    }

The colorizer can get the keywords dictionary for a ruleset as follows::

    keywordsDict = x.keywordsDictDict(rulesetName)

**Note**:
The ``jEdit2Py`` script creates 'friendly' names for keyword dictionaries *solely* as an aid for people reading the code.
Leo's colorer uses only the name ``x.keywordsDictDict``;
Leo's colorer never uses the actual names of keywords dictionaries such as ``php_PHPDOC_keywords_dict``.

Rules, rules dictionaries and x.rulesDictDict
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


``x.py`` contains one **rule function** for every rule in every ruleset (``<RULES>`` element) in ``x.xml``.
These rules have names ``rule1`` through  ``ruleN``,
where ``N`` is the total number of rules in all rulesets in ``x.xml``.

Each rules *function* merely calls a rules *method* in Leo's colorizer.
Which method gets called depends on the corresponding element in `x.xml`.
For example, the first rule in php.xml is::

    <SPAN TYPE="MARKUP" DELEGATE="PHP">
		<BEGIN>&lt;?php</BEGIN>
		<END>?&gt;</END>
	</SPAN>

and the corresponding rule function is::

    def php_rule0(colorer, s, i):
        return colorer.match_span(s, i, kind="markup", begin="<?php", end="?>",
            at_line_start=False, at_whitespace_end=False, at_word_start=False,
            delegate="PHP",exclude_match=False,
            no_escape=False, no_line_break=False, no_word_break=False)


``php_rule0`` calls ``colorer.match_span`` because the corresponding xml rule is a ``<SPAN>`` element.

For each ruleset, ``x.py`` also contains a **rules dictionary**,
a Python dictionary whose keys are characters and whose values are all lists
of rules functions that that can match the key.
For example::

    # Rules dict for phpdoc ruleset.
    rulesDict8 = {
        "*": [rule64,],
        "0": [rule70,],
        "1": [rule70,],
        "2": [rule70,],
        "3": [rule70,],
        "4": [rule70,],
        "5": [rule70,],
        "6": [rule70,],
        "7": [rule70,],
        "8": [rule70,],
        "9": [rule70,],
        "<": [rule65,rule66,rule67,rule68,rule69,],
        "@": [rule70,],
        "A": [rule70,],
        "B": [rule70,],
        ...
        "X": [rule70,],
        "Y": [rule70,],
        "Z": [rule70,],
        "_": [rule70,],
        "a": [rule70,],
        "b": [rule70,],
       ...
        "x": [rule70,],
        "y": [rule70,],
        "z": [rule70,],
        "{": [rule63,],
    }

**Note**: The order of rules in each rules list is important;
it should be the same as rules element in ``x.xml``.

Finally, ``x.py`` contains **x.rulesDictDict**.
Keys are ruleset names, values are rules dictionaries.
The colorer can get the rules list for character ch as follows::

    self.rulesDict = x.rulesDictDict.get(rulesetName) # When a mode is inited.
    ...
    rules = self.rulesDict.get(ch,[]) # In the main loop.

For example, here is the rules dictionary for php.py::

    # x.rulesDictDict for php mode.
    rulesDictDict = {
        "php_javascript": rulesDict6,
        "php_javascript_php": rulesDict7,
        "php_main": rulesDict1,
        "php_php": rulesDict4,
        "php_php_literal": rulesDict5,
        "php_phpdoc": rulesDict8,
        "php_tags": rulesDict2,
        "php_tags_literal": rulesDict3,
    }

**Note**:
The ``jEdit2Py`` script creates 'friendly' names for rules lists *solely* as an aid for people reading the code.
Leo's colorer uses only the name ``x.rulesDictDict``;
Leo's colorer never uses the actual names of rules lists such as ``rulesDict8``,
and Leo's colorer never uses the actual names of rules functions such as ``rule64``.

x.importDict and imported versus delegated rulesets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


``x.importDict`` is a Python dictionary.
Keys are ruleset names; values are a list of ruleset names.
For example::

    # Import dict for php mode.
    importDict = {
        "php_javascript_php": ["javascript::main"],
    }

For any ruleset ``R`` whose ruleset name is ``N``, ``x.importDict.get(N)``
is the list of rulesets names whose rulesets appear in
a ``DELEGATE`` attribute of an ``<IMPORT>`` rule element in ``R's`` ruleset.
Such **imported** ruleset are copied to the end of the ``R's`` rules list.
Leo's colorizer does this copying only once, when loading ruleset ``R`` for the first time.

**Note 1**: Loading imported rulesets must be done at 'run time'.
It should definitely not be done by ``jEdit2Py`` at 'compile time';
that would require running ``jEdit2Py`` on *all* .xml files whenever any such file changed.

**Note 2**:  Multiple ``<IMPORT>`` rule elements in a single ruleset are allowed:
delegated rules are copied to the end of ``N's`` rules list in the order they appear in the ruleset.

**Note 3**: The ``DELEGATE`` attribute of ``<IMPORT>`` elements is, in fact,
completely separate from the ``DELEGATE`` attributes of other rules as
discussed in `Arguments to rule methods`_.
Indeed, the ``DELEGATE`` attribute of ``<IMPORT>`` elements creates entries in
``x.importDict``, which in turn causes the colorizer to append the rules of the imported ruleset
to the end of the present rules list.
In contrast, the ``DELEGATE`` attributes of other rules sets the ``delegate`` argument to rules methods,
which in tern causes the colorizer to recursively color the matched text with the **delegated** ruleset.
In short:

- The rules of **imported** rulesets are appended to the end of another rules list;
  the rules of **delegated** rulesets never are.

- **Imported** ruleset names appear as the values of items in ``x.importDict``;
  **delegated** ruleset names appear as ``delegate`` arguments to rule methods.

Rule methods
^^^^^^^^^^^^


This section describes each rules method in Leo's new colorizer.
Rules methods are called by rules functions in colorizer control file;
they correspond directly to rules elements in jEdit's language description files.
In fact, this documentation is a 'refactoring' of `jEdit's documentation`_.

All rule methods attempt to match a pattern at a particular spot in a string.
These methods all return True if the match succeeds.

Arguments to rule methods
~~~~~~~~~~~~~~~~~~~~~~~~~


All rule methods take three required arguments and zero or more optional keyword arguments.

Here is a list of the required arguments and their meaning:

- **self**: An instance of Leo's colorizer.

- **s**: The string in which matches may be found.

- **i**: The location within the string at which the rule method looks for a match.

Here is a list of all optional keyword arguments and their meaning:

- **at_line_start**:
  If ``True``, a match will succeed only if ``i`` is at the start of a line.

- **at_whitespace_end**:
  If ``True``, the match will succeed only if ``i`` is at the first non-whitespace text in a line.

- **at_word_start**:
  If ``True``, the match will succeed only if ``i`` is at the beginning of a word.

- **delegate**:
  If non-empty, the value of this argument is a `ruleset name`_.
  If the match succeeds, the matched text will be colored recursively with the indicate ruleset.

- **exclude_match**:
  If ``True``, the actual text that matched will not be colored.
  The meaning of this argument varies slightly depending on whether one or two sequences are matched.
  See the individual rule methods for details.

- **kind**: A string representing a class of tokens, i.e., one of:
  ``'comment1'``, ``'comment2'``, ``'comment3'``, ``'comment4'``, ``'function'``,
  ``'keyword1'``, ``'keyword2'``, ``'keyword3'``, ``'keyword4'``,
  ``'label'``, ``'literal1'``, ``'literal2'``, ``'literal3'``, ``'literal4'``,
  ``'markup'``, ``'null'`` and ``'operator'``.

- **no_escape**:
  If ``True``, the ruleset's escape character will have no effect before the ``end`` argument to ``match_span``.
  Otherwise, the presence of the escape character will cause that occurrence of the end string to be ignored.

- **no_line_break**:
  If ``True``, the match will not succeed across line breaks.

- **no_word_break**:
  If ``True``, the match will not cross word breaks.

New in Leo 4.4.1 final: the regular expression rule matchers no longer get a ``hash_char`` argument
because such matchers are called only if the present search pattern starts with ``hash_char``.

match_eol_span
~~~~~~~~~~~~~~


::

    def match_eol_span (self,s,i,kind,begin,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = '',
        exclude_match = False):

``match_eol_span`` succeeds if ``s[i:].startswith(begin)`` and
the ``at_line_start``, ``at_whitespace_end`` and ``at_word_start`` conditions are all satisfied.

If successful, ``match_eol_span`` highlights from i to the end of the line
with the color specified by ``kind``.
If the ``exclude_match`` argument is ``True``, only the text before the matched text will be colored.
The ``delegate`` argument, if present, specifies the ruleset to color the colored text.

match_eol_span_regexp
~~~~~~~~~~~~~~~~~~~~~


::

    def match_eol_span_regexp (self,s,i,kind,regex,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = '',
        exclude_match = False):

``match_eol_span_exp`` succeeds if:

1. The regular expression ``regex`` matches at ``s[i:]``, and

2. The ``at_line_start``, ``at_whitespace_end`` and ``at_word_start`` conditions are all satisfied.

If successful, ``match_eol_span_regexp``  highlights from i to the end of the line.
If the ``exclude_match`` argument is ``True``, only the text before the matched text will be colored.
The ``delegate`` argument, if present, specifies the ruleset to color the colored text.

match_keywords
~~~~~~~~~~~~~~


::

    def match_keywords (self,s,i):

``match_keywords`` succeeds if ``s[i:]`` starts with an identifier contained in the mode's keywords dictionary ``d``.

If successful, ``match_keywords`` colors the keyword.
``match_keywords`` does not take a ``kind`` keyword argument.
Instead, the keyword is colored as specified by ``d.get(theKeyword)``.

match_mark_following
~~~~~~~~~~~~~~~~~~~~


::

    def match_mark_following (self,s,i,kind,pattern,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False):

match_mark_following succeeds if s[i:].startswith(pattern), and
the ``at_line_start``, ``at_whitespace_end`` and ``at_word_start`` conditions are all satisfied.

If successful, ``match_mark_following`` colors from ``i`` to the start of the next token
with the color specified by ``kind``.
If the ``exclude_match`` argument is ``True``, only the text after the matched text will be colored.

match_mark_previous
~~~~~~~~~~~~~~~~~~~


::

    def match_mark_previous (self,s,i,kind,pattern,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False):

``match_mark_previous`` succeeds if s[i:].startswith(pattern),and
the ``at_line_start``, ``at_whitespace_end`` and ``at_word_start`` conditions are all satisfied.

If successful, ``match_mark_previous`` colors from the end of the previous token to ``i``
with the color specified by ``kind``.
If the ``exclude_match`` argument is ``True``, only the text before the matched text will be colored.

match_seq
~~~~~~~~~


::

    def match_seq (self,s,i,kind,seq,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = ''):

``match_seq`` succeeds if ``s[i:].startswith(seq)`` and
the ``at_line_start``, ``at_whitespace_end`` and ``at_word_start`` conditions are all satisfied.

If successful, ``match_seq`` highlights from ``i`` to the end of the sequence
with the color specified by ``kind``.
The ``delegate`` argument, if present, specifies the ruleset to color the colored text.

match_seq_regexp
~~~~~~~~~~~~~~~~


::

    def match_seq_regexp (self,s,i,kind,regex,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        delegate = ''):

``match_seq`` succeeds if:

1. The regular expression ``regex`` matches at ``s[i:]``, and

2. The ``at_line_start``, ``at_whitespace_end`` and ``at_word_start`` conditions are all satisfied.

If successful, ``match_seq_regexp`` highlights from ``i`` to the end of the sequence
with the color specified by ``kind``.
The ``delegate`` argument, if present, specifies the ruleset to color the colored text.

match_span
~~~~~~~~~~


::

    def match_span (self,s,i,kind,begin,end,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False,
        delegate = ''
        no_escape = False,
        no_line_break = False,
        no_word_break = False):

``match_span`` succeeds if there is an index ``j > i`` such that
``s[:i].startswith(begin)`` and ``s[i:j].endswith(end)`` and the
``at_line_start``, ``at_whitespace_end``, ``at_word_start``,
``no_escape``, ``no_line_break`` and ``no_word_break`` conditions are all satisfied.

If successful, ``match_span`` highlights from ``s[i:j``
with the color specified by ``kind``;
but if the ``exclude_match`` argument is ``True``, the ``begin`` and ``end`` text are not colored.
The ``delegate`` argument, if present, specifies the ruleset to color the colored text.

match_span_regexp
~~~~~~~~~~~~~~~~~


::

    def match_span (self,s,i,kind,regex,end,
        at_line_start = False,
        at_whitespace_end = False,
        at_word_start = False,
        exclude_match = False,
        delegate = ''
        no_escape = False,
        no_line_break = False,
        no_word_break = False):

``match_span_regex`` succeeds if:

1. The regular expression ``regex`` matches at ``s[i:]``,

2. There is an index ``j > i`` such that ``s[i:j].endswith(end)``,

3. The ``at_line_start``, ``at_whitespace_end``, ``at_word_start``,
   ``no_escape``, ``no_line_break`` and ``no_word_break`` conditions are all satisfied.

If successful, ``match_span`` colors ``s[i:j]``,
with the color specified by ``kind``;
but if the ``exclude_match`` argument is ``True``, the ``begin`` and ``end`` text are not colored.
The ``delegate`` argument, if present, specifies the ruleset to color the colored text.

match_terminate
~~~~~~~~~~~~~~~


::

    def match_terminate (self,s,i,kind,at_char):

``match_terminate`` succeeds if ``s[i:]`` contains at least ``at_char`` more characters.

If successful, ``match_terminate`` colors ``at_char`` characters
with the color specified by ``kind``.

Syntax coloring settings
^^^^^^^^^^^^^^^^^^^^^^^^


This section discusses only those settings that affect syntax coloring.
See `Chapter 8`_ for a general discussion of Leo's settings.

Both the old colorizer (in Leo's core) and the new colorizer (the threading_colorizer plugin)
now support @font settings for colorizing options.
The settings for the old colorizer are::

    comment_font, cweb_section_name_font, directive_font,
    doc_part_font, keyword_font, leo_keyword_font, section_name_font,
    section_name_brackets_font, string_font, undefined_section_name_font,
    latexBackground_font, and latex_background_font.

The settings for the new colorizer are all of the above (except keyword_font) plus the following::

    comment1, comment2_font, comment3_font, comment4_font, function_font,
    keyword1_font, keyword2_font, keyword3_font, keyword4_font, label_font,
    literal1_font, literal2_font, literal3_font, literal4_font, markup_font,
    null_font, and operator_font.

To specify a font, say for keyword_font, to be used as the default font for **all** languages,
put the following in the body text of an @font node in leoSettings.leo::

    # keyword_font_family = None
    keyword_font_size = 16
    keyword_font_slant = roman
        # roman, italic
    keyword_font_weight = bold
        # normal, bold

Comments are allowed and undefined settings are set to reasonable defaults. 
At present, comments can not follow a setting: comments must start a line.

You can specify per-language settings by preceding the settings names by a prefix x.
Such settings affect only colorizing for language x (i.e., all the modes in modes/x.py when using the new colorizer).
For example, to specify a font for php (only), put the following in the body text of an @font node in leoSettings.leo::

    # php_keyword_font_family = None
    php_keyword_font_size = 16
    php_keyword_font_slant = roman
        # roman, italic
    php_keyword_font_weight = bold
        # normal, bold

The threading_colorizer plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


This section contains code-level notes for the threading colorizer. You do not
need to understand this material in order to use the threading colorizer.

The threading_colorizer plugin uses a separate **helper thread** to compute the
ranges of text that should be colored. **The helper thread must not contain any
calls to Tk**. Tk is not thread safe--calling Tk in the helper thread will cause
hard crashes in the Tk dll. However, the code in the helper thread is gui
independent. The **main thread** contains all of Leo's code except for a helper
thread. The main thread contains all calls to Tk, all entry points to the
colorizer, and idleHandler, an idle-time handler.

Only one helper thread is ever active at any one time. If a keystroke occurs
while the helper thread is active, the colorizer code in the main thread sets
the killFlag ivar and calls join to wait for the helper thread to terminate. The
helper thread will terminate promptly because it looks at killFlag each time
through its main loop. Using a separate helper thread allows the main thread to
continue working while the helper thread computes. This allows Tk (in the main
thread) to respond to events. This in turn allows the colorizer code in the main
thread to kill the helper thread if it is still working.

The helper thread runs to completion before the main thread
uses any of its results. Thus, no thread locking is needed, an important
simplification. Once the helper thread completes, the main thread computes the
tags to be sent to Tk, and actually sends those tags. When the user is typing
rapidly, the colorizer will ignore the results of all helper threads except the
last.

After the helper thread generates the list of all requested
tags, the main thread uses a kind of sort-merge algorithm to compare the
existing tags (obtained from Tk) with the requested tags. In many cases, the
lists are the same and colorizer issues *no* calls to Tk. This is a sensational
optimization.  It absolutely minimizes the load on Tk.

When the 'interruptible' argument to the colorizer is False,
no threading is used and the main thread completely colors the entire text. This
must be done when multiple body editors are present.

Chapter 16: Debugging with Leo
++++++++++++++++++++++++++++++


@language rest

@rst html\debuggers.html
*******************


#######################################
Chapter 16: Debugging with Leo
#######################################

This chapter discusses debugging Python scripts with Leo.
Be aware of the distinction between **Leo-specific** scripts and **general** scripts.
Leo-specific scripts access data in the Leo outline in which they are contained;
general scripts do not.

.. .. contents::


.. External links...
.. _Idle:                       http://www.python.org/idle/
.. _pdb:                        http://docs.python.org/lib/module-pdb.html
.. _winpdb:                     http://www.digitalpeers.com/pythondebugger/
.. _`the FAQ`:                  http://webpages.charter.net/edreamleo/FAQ.html#how-can-i-use-python-s-pdb-debugger-with-leo
.. _`embedded winpdb`:          http://www.digitalpeers.com/pythondebugger/embedded.htm
.. _`Leo's forums`:             http://sourceforge.net/forum/?group_id=3458
.. _`work flow`:                http://webpages.charter.net/edreamleo/FAQ.html#how-can-i-use-leo-to-develop-leo-itself

.. .. _`running Leo in a console`: http://webpages.charter.net/edreamleo/FAQ.html#how-can-i-run-leo-from-a-console-window
.. _`running Leo from a console window`:    install.html#running-leo-from-a-console-window
.. _`run Leo in a console window`:          install.html#running-leo-from-a-console-window
.. _`console window`:                       install.html#running-leo-from-a-console-window

Using g.trace and g.pdb
^^^^^^^^^^^^^^^^^^^^^^^


Inserting g.trace statements in my Python code is usually my first debugging
choice. The g.trace statement prints the name of the function in which the call
to g.trace occurs, followed by the value of its arguments. The output of the
g.trace goes to the console, so you must `run Leo in a console window`_ to use
g.trace.

Inserting and deleting g.trace statements is fast, provided that your `work
flow`_ makes it easy to restart the program under test. As a result, using
g.trace statements is similar to setting tracepoints in a debugger, with the
advantage that (disabled) tracepoints remain in the source code for future use.
You will find many examples of using g.trace throughout Leo's source code.

My second choice is using g.pdb to set breakpoints for the pdb_ debugger. Pdb
uses the console for all interaction, so you must `run Leo in a console window`_.
See `the FAQ`_ for a discussion of both g.trace and g.pdb.

Settings for winpdb
^^^^^^^^^^^^^^^^^^^


The following settings in leoSettings.leo control debugger operation.
The settings shown here will be assumed to be in effect throughout this chapter.

``@string debugger_kind = winpdb``

This setting controls what debugger the 'Debug Script' script button uses.
Eventually this setting will control what debugger the debug command uses.
At present the only valid value is 'winpdb'

``@bool write_script_file = True``

True: The execute script command writes the script to be executed to a file,
then executes the script using Python's execFile function. The script_file_path
setting specifies the path to this file. False (legacy): The execute script
command uses Python's exec command to execute the script.

``@string script_file_path = ../test/scriptFile.py``

The path to the file to be written by the execute-script command. Notes:

- This setting has effect only if the write_script_file setting is True.
- Use ``/`` as the path delimiter, regardless of platform.
- The default path is ``../test/scriptFile.py`` if no path is given.
- The path starts at g.app.loadDir, so for example ``../test/scriptFile.py`` is equivalent to ``leo/test/scriptFile.py``.
- The filename should end in ``.py``.

``@string debugger_path`` = None

Debugging scripts with winpdb
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The following three section discuss three ways of debugging scripts with winpdb_.
The first two sections tell how to debug general scripts;
the last section tells how to debug Leo-specific scripts.

winpdb_ and its documentation have been improved recently.
For more details, see the `embedded winpdb`_ docs.
The discussion of embedded debugging may have been written specifically with Leo in mind.

The debug command
~~~~~~~~~~~~~~~~~


This way of debugging can only be used for general scripts, not leo-specific scripts.  
The debug command writes the script to scriptFile.py and invokes winpdb.
winpdb opens and is already 'attached' to the script to be debugged.
You can single-step as you like.
Leo continues to run, but killing the debugger will also kill Leo.

@button winpdb
~~~~~~~~~~~~~~


``test.leo`` contains an ``@button windpdb`` node.
Select the test to be debugged, then press the winpdb button or do ``<Alt>x winpdb<return>``.
This way is essentially the same as using the debug command, though the code is slightly different.

The execute-script command with explicit debugger breaks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


This way of debugging scripts allows winpdb to debug scripts that use c, g and p.
A bit more work is needed because winpdb does not start automatically.
Here are step-by step instructions:

1. Insert the following two lines of code at the start of the script to be debugged::

    import rpdb2
    rpdb2.start_embedded_debugger('go',fAllowUnencrypted=True)

2. Execute Leo's execute-script command (*not* the debug command).
   Leo will appear to hang: start_embedded_debugger is waiting for *another* copy of winpdb to 'attach' to the script's process.
   The default timeout is 5 minutes, after which an exception gets thrown.

3. Start winpdb explicitly by executing something like the following in a console::

    python /python25/Scripts/_winpdb.py -t

   The -t option tells winpdb that no encoding of password is necessary.
   The password is specified in the call to rpdb2.start_embedded_debugger in your script.
   In our example, the password is 'go'.

4. Use winpdb's ``File:Attach`` command to attach winpdb to Leo.
   Specify the password as 'go' and you will see the scriptFile.py containing your entire script.
   You can now execute or single-step through the script. 
   To repeat, c, g and p are defined, so you can debug any script this way.

Chapter 17: Using ZODB with Leo
+++++++++++++++++++++++++++++++


@language rest

@rst html\zodb.html
**************


#######################################
Chapter 17: Using ZODB with Leo
#######################################

This chapter discusses how to write Leo scripts that store and retrieve data using ZODB_.

.. .. contents::


.. External links...
.. _ZODB:               http://www.zope.org/Wikis/ZODB/guide/zodb.html
.. _`Installing ZODB`:  http://www.zope.org/Wikis/ZODB/guide/node3.html#SECTION000310000000000000000

Configuring Leo to use zodb
^^^^^^^^^^^^^^^^^^^^^^^^^^^


To enable zodb scripting within Leo, you must set ``use_zodb = True`` in the root node of leoNodes.py.
You must also install ZODB itself.  See `Installing ZODB`_ for details.

When ZODB is installed and ``use_zodb`` is ``True``
Leo's vnode and tnode classes become subclasses of ZODB.Persistence.Persistent.
This is all that is needed to save/retrieve vnodes or tnodes to/from the ZODB.

**Important notes**:

- Scripts **should not** store or retrieve positions using the ZODB!
  Doing so makes sense neither from Leo's point of view nor from ZODB's point of view.

- The examples below show how to store or retrieve Leo data by accessing
  the so-called root of a ZODB connection.
  However, these are only examples.
  Scripts are free to do with Leo's vnodes and tnodes *anything* that can
  be done with ZODB.Persistence.Persistent objects.

Initing zodb
^^^^^^^^^^^^


Scripts should call g.init_zodb to open a ZODB.Storage file.
g.init_zodb returns an instance of ZODB.DB.  For example::

    db = g.init_zodb (zodbStorageFileName)

You can call g.init_zodb as many times as you like.
Only the first call for any path actually does anything:
subsequent calls for a previously opened path simply return the same value as the first call.

Writing data to zodb
^^^^^^^^^^^^^^^^^^^^


The following script writes v, a tree of vnodes, to zodb::

    db = g.init_zodb (zodbStorageFileName)
    connection = db.open()
    try:
        root = connection.root()
        root[aKey] = v # See next section for how to define aKey.
    finally:
        get_transaction().commit()
        connection.close()

Notes:

- v must be a vnode (or a tnode).
  Scripts should *not* attempt to store Leo positions in the zodb.
  v can be the root of an entire outline or a subtree.
  For example, either of the following would be reasonable::

    root[aKey] = c.rootPosition().v
    root[aKey] = c.p.v

- To write a single vnode without writing any of its children you can use v.detach.
  For example::

    root[aKey] = v.detach()

- **Important**: It is simplest if only one zodb connection is open at any one time,
  so scripts would typically close the zodb connection immediately after processing the data.
  The correct way to do this is in a finally statement, as shown above.

- The script above does not define aKey.
  The following section discusses how to define reasonable zodb keys.

Defining zodb keys
^^^^^^^^^^^^^^^^^^


The keys used to store and retrieve data in connection.root() can be any string that uniquely identifies the data.
The following are only suggestions: you are free to use any string you like.

1. When saving a file, you would probably use a key that is similar to a real file path.
   For example::

        aKey = c.fileName()

2. When saving a single vnode or tree of vnodes, say v,
   a good choice would be to use v's gnx, namely::

        aKey = g.app.nodeIndices.toString(v.t.fileIndex)

   Note that v.detach() does not automatically copy v.t.fileIndex to the detached node,
   so when writing a detached node you would typically do the following::

       v2 = v.detach()
       v2.t.fileIndex = v.t.fileIndex
       aKey = g.app.nodeIndices.toString(v2.t.fileIndex)

Reading data from zodb
^^^^^^^^^^^^^^^^^^^^^^


The following script reads a tree of vnodes from zodb and sets p as the root position of the tree::

    try:
        connection = db.open()
        root = connection.root()
        v = root.get(aKey)
        p = leoNodes.position(v)
    finally:
        get_transaction().commit()
        connection.close()

About connections
^^^^^^^^^^^^^^^^^


The scripts shown above close the zodb connection after processing the data.
This is by far the simplest strategy.
I recommend it for typical scripts.

**Important**: you must **leave the connection open** if your script modifies persistent data in any way.
(Actually, this statement is not really true,
but you must define zodb transaction managers if you intend to use multiple connections simultaneously.
This complication is beyond the scope of this documentation.)
For example, it would be possible to create a new Leo outline from the data just read,
but the script must leave the connection open.
I do not recommend this tactic, but for the adventurous here is some sample code::

    connection = self.db.open()
    root = connection.root()
    v = root.get(fileName)
    if v:
        c2 = c.new()
        c2.openDirectory = c.openDirectory # A hack.
        c2.mFileName = fileName # Another hack.
        c2.beginUpdate()
        try:
            c2.setRootVnode(v)
            c2Root = c2.rootPosition()
            c2.atFileCommands.readAll(c2Root)
            g.es_print('zodb read: %s' % (fileName))
        finally:
            c2.endUpdate()
        # Do *not* close the connection while the new Leo window is open!
    else:
        g.es_print('zodb read: not found: %s' % (fileName))


This will work **provided** that no other zodb connection is ever opened while this connection is opened.
Unless special zodb precautions are taken (like defining zodb transaction managers)
calling get_transaction().commit() will affect **all** open connections.
You have been warned.

Convenience routines
^^^^^^^^^^^^^^^^^^^^



g.init_zodb (pathToZodbStorage,verbose=True)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


This function inits the zodb.
pathToZodbStorage is the full path to the zodb storage file.
You can call g.init_zodb as many times as you like.
Only the first call for any path actually does anything:
subsequent calls for a previously opened path simply return the same value as the first call.

v.detach()
~~~~~~~~~~


This vnode method returns v2, a copy of v that is completely detached from the outline.
v2.t is a completely new tnode.
v2.fileIndex is None initially, but is may be convenient to copy this field::

    v2 = v.detach()
    v2.t.fileIndex = v.t.fileIndex

Chapter 18: Leo and Emacs
+++++++++++++++++++++++++


@language rest

@rst html\emacs.html
***************


#######################################
Chapter 18: Leo and Emacs
#######################################

This chapter several topics relating to the Emacs editor.

.. .. contents::


.. Links
.. _elisp:              http://en.wikipedia.org/wiki/Emacs_Lisp
.. _Emacs:              http://www.xemacs.org/
.. _ZODB:               http://www.zope.org/Wikis/ZODB/guide/zodb.html
.. _`Installing ZODB`:  http://www.zope.org/Wikis/ZODB/guide/node3.html#SECTION000310000000000000000
.. _pymacs:             http://pymacs.progiciels-bpi.ca/index.html
.. _`Chapter 8: Customizing Leo`:   customizing.html

Controlling Leo from Emacs using Pymacs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Leo's leoPymacs module is a simple 'server' for the pymacs_ package.
Using pymacs and leoPymacs, elisp_ scripts in Emacs_ can open .leo files and execute *Python* scripts
as if they were executed inside Leo.
In particular, such scripts can use Leo's predefined c, g and p variables.
Thus, *Python* scripts running in Emacs can:

- Open any .leo file. 
- Access any part of the outline. 
- Change any part of the outline, including derived files, 
- Save .leo files.
- Execute *any* Leo script.

In short, you can now do from Emacs anything that you can do with Leo scripting inside Leo.

Here are step-by-step instructions for executing Python scripts in Emacs:

**Step 1. Install pymacs** 

   The pymacs installation instructions should be clear enough.
   A clarification is needed about two-way communication between Python and lisp scripts:
   in truth, Python scripts can call the Pymacs.lisp function *only* if the Python script
   was invoked from emacs.
   Otherwise, calling Pymacs.lisp will hang the process making the call.
   For example, executing the following script as an ordinary Leo script will hang Leo::

        from Pymacs import lisp
        print lisp("""2+2""") # Hangs

**Step 2. Load the leoPymacs module from Emacs, creating a hidden Leo application**

  From inside Emacs, you load Leo's leoPymacs module as follows::

    (pymacs-load "leoPymacs" "leo-")

  The call to pymacs-load is similar to ``'import leoPymacs as leo-'`` in Python.
  The side effect of pymacs-load is to define the elisp function leo-x for every top-level function x in leoPymacs.py,
  namely leo-dump, leo-get-app, leo-get-g, leo-get-script-result, leo-init, leo-open and leo-run-script.
  The first call to any of these functions creates a **hidden Leo application**
  in which .leo files may be loaded, modified and saved,
  and in which Leo scripts may be executed.
  This hidden Leo application uses Leo's nullGui class as its gui,
  so Leo commands and Leo scripts that require a fully functional gui will not work as
  expected in the hidden Leo application.
  Steps 3 and 4 tell how to use this hidden Leo application.

  pymacs-load works like a Python reload, so you can redefine leoPymacs.py while Emacs is running.
  However, calling pymacs-load destroys the old hidden Leo application and creates a new one,
  so typically you would want to call pymacs-load only once per Emacs session.
  Like this::

        (setq reload nil) ; change nil to t to force a reload.

        (if (or reload (not (boundp 'leoPymacs)))
            (setq leoPymacs (pymacs-load "leoPymacs" "leo-"))
            (message "leoPymacs already loaded")
        )

**Step 3. From Emacs, open .leo files**

   Once we have loaded the leoPymacs module
   we can open a .leo file as follows::

    (setq c (leo-open fileName))

   This binds the elisp ``c`` variable to the Leo commander created by opening fileName.
   fileName should be the full path to a .leo file.
   In the next step we will use this ``c`` variable to execute *Leo* scripts in the
   context of an open Leo outline.

   Sometimes we want to execute a Leo script before opening any Leo commanders.
   For example, we might want to compute the fileName passed to leo-open.
   leo-run-script allows the ``c`` argument to be nil,
   in which case leo-run-script creates a dummy commander in which to run the script.
   For example, the following script calls ``g.os_path_join`` and ``g.os_path_abspath``::

        (setq script "g.app.scriptResult =
            g.os_path_abspath(g.os_path_join(
                g.app.loadDir,'..','test','ut.leo'))"
        )

        (setq fileName (leo-run-script nil script))

   leo-run-script returns the value of ``g.app.scriptResult``
   As shown above, Python scripts may set ``g.app.scriptResult`` to indicate their result.
   elisp scripts can also get ``g.app.scriptResult`` using leo-script-result.
   Note that the Python script may span multiple lines.

**Step 4. From Emacs, execute Leo (Python) scripts**

   From emacs we can execute a Python script **as if** it were executed in an
   open Leo outline.
   Suppose aLeoScript is an **elisp** string containing a Leo (Python) script.
   We can execute that script in the hidden Leo application as follows::

        (leo-run-script c aLeoScript)

   For example::

        (setq c (leo-open fileName)
        (csetq script "print 'c',c,'h',c.p.h")
        (leo-run-script c script)

Putting this all together, we get::

        ; Step 1: load leoPymacs if it has not already been loaded.
        (setq reload nil)
        (if (or reload (not (boundp 'leoPymacs)))
            (setq leoPymacs (pymacs-load "leoPymacs" "leo-"))
            (message "leoPymacs already loaded")
        )

        ; Step 2: compute the path to leo/test/ut.leo using a Leo script.
        (setq script
            "g.app.scriptResult = g.os_path_abspath(
                g.os_path_join(g.app.loadDir,'..','test','ut.leo'))"
        )
        (setq fileName (leo-run-script nil script))

        ; Step 3: execute a script in ut.leo.
        (setq c (leo-open fileName))
        (setq script "print 'c',c.shortFileName() ,'current:',c.p.h")
        (leo-run-script c script)

Functions in leoPymacs.py
^^^^^^^^^^^^^^^^^^^^^^^^^


The leoPymacs module is intended to be called from Emacs using pymacs.  It contains the following top-level functions:

- get_app()

  Returns the hidden app created by the leoPymacs.init function.

- dump(anyPythonObject)

  Returns str(repr(anyPythonObject)).

- get_g()

  Returns the leoGlobals module of the hidden app created by the leoPymacs.init function.

- get_script_result()

  Returns g.app.scriptResult, where g.app is the hidden app.

- init()
  Calls leo.run(pymacs=True) to create a hidden Leo application.
  Later calls to open can open hidden Leo outlines that can be accessed via runScript.

- open(fileName)

  Opens the .leo file given by fileName.
  fileName must be the full path to a .leo file.
  Returns the commander of the open Leo outline, or None if the outline could not be opened.

- run_script(c,script,p=None)

  Executes a script in the context of a commander ``c`` returned by the leoPymacs.open.
  c may be None, in which case a dummy commander is created in which to run the script.
  In the executed script, p is set to c.p if no p argument is specified.
  Returns g.app.scriptResult, where g.app is the hidden app.

The minibuffer
^^^^^^^^^^^^^^


Leo's mini-buffer is a text area at the bottom of the body pane.
You use Leo's minibuffer 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 file names.

- **quick-command-mode**: (default shortcut: Alt-x) Like Emacs Control-C. This mode is
  defined in leoSettings.leo. It is useful for commonly-used commands.

- **universal-argument**: (default shortcut: Alt-u) Like Emacs Ctrl-u. Adds a repeat
  count for later command. Ctrl-u 999 a adds 999 a's.

- **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>.

Chapter 19: Embedding Leo with the leoBridge module
+++++++++++++++++++++++++++++++++++++++++++++++++++


@language rest

@rst html\leoBridge.html
*******************


############################################################
Chapter 19: Embedding Leo with the leoBridge module
############################################################

The leoBridge module allows complete access to all aspects of Leo from programs
running independently of Leo. Let us call such a program a **host** program.
Using the leoBridge module, host programs can get access to:

- all of Leo's source code,
- the contents of any .leo file,
- the commander of any .leo file.

.. .. contents::


.. Links

The basics
^^^^^^^^^^


Host programs use the leoBridge module as follows::

    import leo.core.leoBridge as leoBridge
    controller = leoBridge.controller(gui='nullGui')
    g = controller.globals()
    c = controller.openLeoFile(path)

Let us look at these statements in detail.  The statements::

    import leo.core.leoBridge as leoBridge
    controller = leoBridge.controller(gui='nullGui')

import the leoBridge module and create a **bridge controller**. In effect, these
statements embed an invisible copy Leo into the host program. This embedded
copy of Leo uses a null gui, which simulates all aspects of Leo's normal gui
code without creating any screen objects.

The statement::

    g = controller.globals()

provides access to Leo's leoGlobals module, and properly inits globals such as
g.app, g.app.gui, etc. *Host programs should not import leoGlobals directly*,
because doing so would not init the g.app object properly.

The statement::

    c = controller.openLeoFile(path)

invisibly opens the .leo file given by the path argument. This call returns a
completely standard Leo commander, properly inited. This is the big payoff from
the leoBridge module: the host program gets instant access to c.config.getBool,
etc. Do you see how sweet this is?

For example, the following script runs leo/test/leoBridgeTest.py outside of Leo.
leoBridgeTest.py uses the leoBridge module to run all unit tests in leo/test/unitTest.leo::

    import os,sys

    path = g.os_path_abspath(
        g.os_path_join(
            g.app.loadDir,'..','test','leoBridgeTest.py'))

    os.system('%s %s' % (sys.executable,path))

The file leo/test/test.leo contains the source code for leoBridgeTest.py.
Here it is, stripped of its sentinel lines::

    '''A program to run unit tests with the leoBridge module.'''

    import leo.core.leoBridge as leoBridge
    import leo.core.leoTest as leoTest

    def main ():
        tag = 'leoTestBridge'

        # Setting verbose=True prints messages that would be sent to the log pane.
        bridge = leoBridge.controller(gui='nullGui',verbose=False)
        if bridge.isOpen():
            g = bridge.globals()
            path = g.os_path_abspath(g.os_path_join(
                g.app.loadDir,'..','test','unitTest.leo'))
            c = bridge.openLeoFile(path)
            g.es('%s %s' % (tag,c.shortFileName()))
            runUnitTests(c,g)

        print tag,'done'

    def runUnitTests (c,g):
        nodeName = 'All unit tests' # The tests to run.
        try:
            u = leoTest.testUtils(c)
            p = u.findNodeAnywhere(nodeName)
            if p:
                g.es('running unit tests in %s...' % nodeName)
                c.selectPosition(p)
                c.debugCommands.runUnitTests()
                g.es('unit tests complete')
            else:
                g.es('node not found:' % nodeName)
        except Exception:
            g.es('unexpected exception')
            g.es_exception()
            raise

    if __name__ == '__main__':
        main()

Running leoBridge from within Leo
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


This following is adapted from Terry Brown's entry in Leo's wiki.

You can not just run leoBridge from Leo, because the leoBridge module is design
to run a separate copy of Leo. However, it is possible to run leoBridge from a
separate process. That turned out to be more, um, interesting than anticipated,
so I'm recording the results here.

The idea is that script A running in Leo (i.e. in a regular GUI Leo session)
calls script B through subprocess.Popen(), script B uses LeoBridge to do
something (parse unloaded Leo files), and returns the result to script A.
Passing the result back via the clipboard seemed like a possibility, but
XWindows / tcl/tk clipboard madness being what it is, that didn't seem to work.

First trick, calling script B from script A::

    import subprocess
    p = subprocess.Popen(('python',
        path_to_script_B,
        parameter_for_script_B,),
        stdout=subprocess.PIPE,
        env={'PYTHONPATH': g.app.loadDir,'USER': g.app.leoID},
    )
    p.wait()

Setting PYTHONPATH in the environment seemed like the easiest way to let
script B find leoBridge.py (which it needs to import).  But by setting the
env parameter you limit script B's environment to be **only** PYTHONPATH,
which causes leoBridge to fail because, in unix at least, it depends
on USER in the environment.  So you need to pass that through too.

Now, because passing stuff back on the clipboard seems unreliable, at least
in XWindows, script B passes results back to script A via stdout (print),
but there's some Leo initialization chatter you want to avoid.  So put a
sentinel, 'START_CLIPBOARD', in the output, and collect it like this::

    response = p.stdout.readlines()
    while response and 'START_CLIPBOARD' not in response[0]:
        del response[0]
    del response[0]  # delete the sentinel as well
    response = ''.join(response)

This is the basic mechanism.  What I *actually* wanted to do was have script
B generate a branch of nodes and pass that back to script A for insertion in
the tree script A is running in.  That's relatively easy if you use::

    c.setCurrentPosition(pos_of_branch_to_return)
    c.copyOutline()
    print '<!-- START_CLIPBOARD -->'
    print g.app.gui.getTextFromClipboard()
    print '<!-- END_CLIPBOARD -->'

at the end of script B, and back in script A, after you've rebuilt
`response` as shown above, just::

    g.app.gui.replaceClipboardWith(response)
    c.pasteOutline()

Chapter 20: Unit testing with Leo
+++++++++++++++++++++++++++++++++


@language rest
@tabwidth -4

@rst html\unitTesting.html
*********************


############################################################
Chapter 20: Unit testing with Leo
############################################################

This chapter describes how you can execute Python unit test from within Leo outlines.

.. .. contents::


.. Links

.. _`run Leo in a console window`:      install.html#running-leo-from-a-console-window

Overview
^^^^^^^^


Leo's **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.

Important: you must `run Leo in a console window`_ to see the output the unit tests.
Leo's 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.

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, Leo's 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 Leo's 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.
        for p in c.allNodes_iter():
            back = p.back()
            next = p.next()
            if back: assert(back.getNext() == p)
            if next: assert(next.getBack() == p)

When either of Leo's unit test commands finds this @test node the command will
run a unit test equivalent to the following::

    import leo.core.leoGlobals as g

    class aTestCase (unittest.TestCase):
        def shortDescription():
            return '@test consistency of back/next links'
        def runTest():
            c,p = g.getTestVars()
            for p in c.allNodes_iter():
                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 don't have to define a subclass of unittest.TestCase.
- Within your unit test, the c, g and p variables are predefined, 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 first 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
file leoNodes.py. @test nodes that appear outside of Python source files 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 predefines 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 predefines 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 undefined.

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.

Leo's 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 file.

Leo's test commands first 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::

    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

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
   file 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 don't matter. If you *really*
     care, see the source code for leoTests.doTests.

@button timer
^^^^^^^^^^^^^


The timit button in unitTest.leo allows you to apply Python's timeit module.
See http://docs.python.org/lib/module-timeit.html.
The contents of @button timer is::

    import leo.core.leoTest as leoTest
    leoTest.runTimerOnNode(c,p,count=100)

runTimerOnNode executes the script in the presently selected node using timit.Timer and prints the results.

@button profile
^^^^^^^^^^^^^^^


The profile button in unitTest.leo allows you to profile nodes using Python's profiler module.
See http://docs.python.org/lib/module-profile.html
The contents of @button profile is::

    import leo.core.leoTest as leoTest
    leoTest.runProfileOnNode(p,outputPath=None) # Defaults to leo\test\profileStats.txt

runProfileOnNode runs the Python profiler on the script in the selected node, then reports the stats.

Chapter 21: ILeo - the IPython bridge
+++++++++++++++++++++++++++++++++++++


@language rest

@rst html\IPythonBridge.html
***********************


############################################################
Chapter 21: IPython and Leo
############################################################

.. _`run Leo in a console window`: install.html#running-leo-from-a-console-window

Leo's 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 in a console window`_. When this plugin is
enabled, Leo's 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 IPython's _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 Leo's 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.

.. .. contents::


.. Links
.. _discussions:            http://sourceforge.net/forum/forum.php?thread_id=1911662&forum_id=10226
.. _ipython:                http://ipython.scipy.org/
.. _IPython:                http://ipython.scipy.org/
.. _`IPython Notebook`:     http://projects.scipy.org/ipython/ipython/wiki/NoteBook
.. _extensionAPI:           http://ipython.scipy.org/moin/IpythonExtensionApi
.. _`The Ipython Extension API`: extensionAPI_
.. _`Chapter 7\: Scripting Leo with Python`:    scripting.html

.. _`run Leo in a console window`:  install.html#running-leo-from-a-console-window
.. _`console window`:               install.html#running-leo-from-a-console-window

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 manipulate **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 don't 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 files (before you
really want to, of course!)

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
  (`run Leo in a console window`_, 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
  profile, or to start in 'pylab' mode), add this to your @settings:
  '@string ipython_argv = ipython -pylab' (where -pylab is the command line argument)

Accessing IPython from Leo
^^^^^^^^^^^^^^^^^^^^^^^^^^


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 definitions, 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)::

    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).


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 efficient) to execute things as
plain Python statements. Large class definitions are good candidates for P
nodes.

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!

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 definitions').

'v' attribute also has a setter, i.e. you can do::

    wb.spam.v = "mystring"

Which will result in the node 'spam' having the following text::

    'mystring'

What assignment to 'v' does can be configured 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-specific metadata. Example::

    [C:leo/core]|12> wb.spam.uA['coords'] = (12,222)
    [C:leo/core]|13> wb.spam.uA
                <13> {'coords': (12, 222)}    

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 can't use .v when you first create the node - i.e. the node needs
to be initialized by simple assignment, 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

@cl definitions
^^^^^^^^^^^^^^^


If the first 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 defined 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, let's 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> u'hello\n'
    [C:leo/core]|25> f.readline()
                <25> u'world\n'
    [C:leo/core]|26> f.readline()
                <26> u'and whatever'
    [C:leo/core]|27> f.readline()
                <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 ---"
    cd /var/tmp
    ls -l

Press alt+I on the node to run it. The output will be written to
"Command output" child node.

Special node types
^^^^^^^^^^^^^^^^^^


@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
definitions, import the modules you will be using elsewhere in the document, etc.

The contents of of the node itself will be ignored.


@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.

@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. 

@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.

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 IPython's %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 don't 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

    [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.

Declaring custom push-to-ipython handlers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Sometimes, you might want to configure 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 (first one to
try) - typically, you don't need to care about it and can usually omit the
argument altogether)

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)``)::

    def sort_node(n):
        lines = n.l
        lines.sort()
        n.l = lines

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 files or %store:d).

Startup
-------

It's 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.

Usage
-----

The simplest use case is probably pushing an existing array to Leo for editing.
Let's 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!

Magic functions
^^^^^^^^^^^^^^^


%mb
---

Execute leo minibuffer command. Tab completion works. Example::

    mb open-outline

%lee
----

Stands for "LEo Edit". Allows you to open file(s), and even objects in Leo for editing. Examples::

    lee *.txt

Opens all txt files 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.

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.

Chapter 22: Using Vim with Leo
++++++++++++++++++++++++++++++


@language rest

@rst html\vimBindings.html
*********************


############################################################
Chapter 22: Using Vim Bindings with Leo
############################################################

This chapter describes Leo's vim-like bindings, including how to install them.

.. .. contents::


.. Links

Vim bindings
^^^^^^^^^^^^



Installing vim bindings
~~~~~~~~~~~~~~~~~~~~~~~


Place a copy of the "@keys Vim bindings" node and its sub-nodes,
located in the leoSettings.leo file, under the "@settings" node
in the myLeoSettings.leo file

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 file to prevent
them from being overwritten when updating to a new version.

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:
                    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 node's body or the node's 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 node's icon box
    Alt-G       Go to specified line number (relative to derived file)
    Ctrl-:      Enter Leo's command line

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::

    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.
          Mark's are not node specific; `<label> will go to location in current node.

Select commands::

    Ctrl-v      Toggle text select mode (Vim's "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
    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 node's body text
    ?           Search backward within current node's 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 find 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.
                      Doesn't 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::

    Ctrl-b      Scroll text up by pane's height
    Ctrl-f      Scroll text down by pane's 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 node's 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

Outline commands
~~~~~~~~~~~~~~~~


The following commands are supported when in a headline's 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

    %           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 find 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.
                      Doesn't 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::

    G           Go to the outline's last node
    gg          Go to the outline's 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 pane's height supported
       Ctrl-f    Mapped to Ctrl-e until scroll down by pane's height supported

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 character's case
    .           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 n'th or up to the n'th 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, ...

Avoiding changes to 'tag' files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


If you use the open-with plugin to open node text in Vim and your Vim's "tag"
file refers to derived files then there is a risk that a derived file 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 file's original text that may later recreate the original derived file
during a Leo save operation (overwriting the changes saved from the Vim editor).

To prevent this problem, modifications to derived files can be avoided by using
Vim's "modeline" feature to disable editing of derived files.

Vim's "modeline" feature scans each loaded buffer for text at the top or bottom
of the file containing " vim:" followed by a series of Vim options. The text is
usually embedded within a comment. The following example prevents modifications
to a buffer in a Python file::

    # 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 file node (ex: @thin) then any derived file saved and
then later loaded into Vim will, by default, not be modifiable. If a derived
file does need to be edited then modifications can be re-enabled on a
file-by-file basis by issuing Vim's ":ma" command while viewing the derived
file.

The number of lines that Vim checks at the top and bottom of the buffer is
configurable. The following Vim command must be placed in the vimrc file to
allow for Leo's trailing sentinel lines::

    set modelines=8

Issue the ":help modeline" command within Vim for the more information about
modelines.

Chapter 23: Using @shadow
+++++++++++++++++++++++++


@language rest

@rst html\atShadow.html
******************


############################################################
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 benefits of @auto, @thin, @file and @nosent trees:

- The (public) files 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 files outside of Leo.

@shadow trees are often useful for studying or editing source files from projects that don't 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.

.. .. contents::


.. Links
.. _`@auto trees`:          directives.html#auto

Overview
^^^^^^^^


Using @shadow trees is the best choice when you want to have the full power of
Leo's outlines, but wish to retain the source files in their original format,
without Leo sentinels (markup) in comments in the source file. 

Leo's @file and @thin trees create derived files containing comments called sentinels.
These sentinel lines allow Leo to recreate the outlines structure of @file and @thin trees.
Alas, many people and organizations find these added sentinel lines unacceptable.
@nosent nodes create derived files without sentinels, but at a cost:
Leo can not update @nosent trees when the corresponding derived file 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** file without sentinels, and a **private** file containing sentinels.
Using Bernhard Mulder's brilliant **update algorithm**,
Leo is able to update @shadow trees in the Leo outline based *solely* on changes to public files.

Leo writes private files to a subfolder of the folder containing the public file:
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 files need not be known to source code control systems such as bzr or cvs.

That's *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.

Creating @shadow trees
^^^^^^^^^^^^^^^^^^^^^^


The first step in creating an @shadow tree is to create a node whose headline is
@shadow *<filename>*. This is always safe, even if *<filename>* already
exists: Leo writes the @shadow tree to the public and private files only if the
@shadow tree contains a **significant** amount of information. An @shadow tree
contains a significant 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 file 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 file into the @shadow tree only if
a) the public file exists and b) the private file does *not* exist.
Thus, Leo will import code into each @shadow node at most once.
After the first 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 influence of an @ignore directive.

What the update algorithm does
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Suppose our @shadow tree is @shadow a.py. When Leo writes this tree it creates a
public file, a.py, and a private file, .leo_shadow/xa.p (or just xa.p for
short). Public files might can committed to a source code control system such as
cvs or bzr. Private files 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 file, xa.p, will *not* have been changed.
(Private files should *never* change outside of Leo.

When Leo reads the *new* (and possibly updated) public file it does the
following:

1. Recreates the *old* public file by removing sentinels from the (unchanged!) *private* file.
2. Creates a set of diffs between the old and new *public* files.
3. Uses the diffs to create a new version of the *private* file.
4. Creates the @shadow tree using  the new *private* file.

**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.

Aha: boundary cases don't 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* file that results is the same.
   **The choice doesn't matter**, so the update algorithm is completely and
   absolutely safe.

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 @file 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 @file 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 file, the
   *private* file records the location of the moved line. The next time the user
   reads the @shadow file, 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 finally convinced me that @shadow could be made to work reliably.

Appendices
++++++++++


@language rest

@rst html\appendices.html
********************


############
Appendices
############

.. .. contents::


.. Relative links.
.. _`Chapter 13: Writing plugins`:   writingPlugins.html

.. References to the glossary.
.. _`sentinel lines`:             glossary.html#sentinel-lines

Bugs
^^^^


The following bugs can not be fixed:

1.  The ``Untangle`` command has no way of updating a section whose name has been changed in the derived file.

    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`` files.

Errors while tangling
^^^^^^^^^^^^^^^^^^^^^


The following error messages may be generated by the ``Tangle`` commands.

``Can not re-open temp file``
    A file error occurred while trying to reopen the temporary file used during tangling.

``Can not rename temporary file name``
    A file error occurred while trying to change the name of the temporary file 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 defined in terms of itself, either directly or indirectly.
    The trace shows the chain of section definitions that resulted in the illegal definition.

``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 defined in several parts in two ways:

    1.  Using ``<< section name >>=`` in several places with the same section name.

    2.  Using several ``@code`` directives within the same body text.

    As a precaution against mistakenly defining a section in more than one place,
    it is invalid to use @code in different nodes to define 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 file because errors were found.

``Run on comment``
    A C-language comment was not properly terminated.

``Run on file name in @root directive``
    The file 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 definition was seen in the middle of a line.

``Sections nested too deeply``
    A section was defined using more than 100 levels of section definitions (!)
    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 undefined section was encountered.

``Unexpected @directive while putting code``
    Tangle outputs 2-character WEB control code in a comment.
    This message is given if we find such comments in a code definition.

``Warning: possible duplicate definition of: <<< section name >>>``
    (The text of the duplicate definition follows.)
    The section may have been defined 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.

Errors while untangling
^^^^^^^^^^^^^^^^^^^^^^^


The following error messages may be generated by the Untangle commands.

Incompatible definitions of <<< section name >>>
    Two expansions of ``<< section name >>`` were different in the derived file.
    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 file was reached before encountering the end sentinel line for ``<< section name >>``.
    This is likely the result of adding, deleting or altering a sentinel line.

Errors while reading @file nodes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


The following are all serious errors, meaning that the data in a derived file 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 file using the ``Read Outline Only`` commands,
followed by a ``Write @file Nodes`` command

Errors while writing @file nodes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Errors while writing ``@file`` nodes are harmless.
No information is lost because all information is written to the .leo file rather than the derived file.

``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`` directive.

``Rename failed: no file created! (file may be read-only)``
    Leo's ``Save`` command writes derived files to a temporary file,
    and replaces the derived file by the temporary files only if the two files are different.
    A problem with the file system prevented the temporary file 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 definition node for *section name* exists in the descendants of *headline*.

Format of .leo files
^^^^^^^^^^^^^^^^^^^^


This technical information may be of use to those wanting to process Leo files with special-purpose filters.
Leo's uses XML for its file 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 file in another editor.

Here are the elements that may appear in Leo files.
These elements must appear in this order.

``<?xml>``
    Leo files start with the following line::

        <?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 file.
    ``</leo_file>`` ends the file.

``<leo_header>`` 
    The ``<leo_header>`` element specifies version information and other information
    that affects how Leo parses the file.  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 specifies information relating to the entire file.
    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`` specifies 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>`` element 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 specifies 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 specifies the tnode associated with this vnode.
    The ``a="xxx"`` attribute specifies 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.

    For example, ``a="EM"``  specifies 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 gnx's: global node indices.
        See ``Format of derived files (4.x)`` for the format of gnx's.

    -   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 specifies 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.

Format of derived files
^^^^^^^^^^^^^^^^^^^^^^^


This section describe the format of derived files.
Leo's `sentinel lines`_ are comments, and this section describes those comments.

The format of derived files 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 file.

- A minimum of intrusion and ugliness.

**New in Leo 4.2**:
Files derived from ``@thin`` use gnx's in ``@+node`` and ``@-node`` sentinels.
Such gnx's permanently and uniquely identify nodes.
Gnx's have the form::

    id.yyyymmddhhmmss
    id.yyyymmddhhmmss.n

The second form is used if two gnx's would otherwise be identical.

- ``id`` is a string unique to a developer, e.g., a cvs id.

- ``yyyymmddhhmmss`` is the node's 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::

      @@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,
    Leo's 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 corresponding ``@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 file.
    The new delimiter strings continue in effect until the next ``@@delims`` sentinel
    *in the derived file* or until the end of the derived file.
    Adding, deleting or changing ``@@delim`` *sentinels* will destroy Leo's ability to read the derived file.
    Mistakes in using the ``@delims`` *directives* have no effect on Leo,
    though such mistakes will thoroughly mess up a derived file as far as compilers,
    HTML renderers, etc. are concerned. 

\@+leo
    Marks the start of any derived file.
    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 file.
    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 defines the section.
    Typically no such sentinels are needed: most sections are defined 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 defines the section.

\@+node and \@-node
    Mark the start and end of a node.

    **Leo 4.2 and later**::
    ``@+node`` and ``@-node`` sentinels use gnx's 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 fields as described below::

      @+node:<child_index>:<status_fields>:<headline>
      @-node::<child_index>:<status_fields>:<headline>

    ``<child_index>`` is a number from 1 to n indicating the index of the node in the list of its parent's children.
    ``<status_field>`` is the cloneIndex field 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 continues 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 file 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.

Unicode reference
^^^^^^^^^^^^^^^^^


Leo uses unicode internally for all strings.

1.  Leo converts headline and body text to unicode when reading .leo files and derived files.
    Both .leo files and derived files may specify their encoding.  The default is ``utf-8``.
    If the encoding used in a derived file is not "utf-8" it is represented in the ``@+leo`` sentinel line.
    For example::

        #@+leo-encoding=iso-8859-1.

    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 files and derived files Leo uses the same encoding used to read the file,
    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 files and .leo files.
    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 specifies the encoding used in a derived file.
    You can't mix encodings in a single derived file.

Glossary
++++++++


@language rest

@rst html\glossary.html
******************


############
Glossary
############


.. Links used in this document.

.. ----- External links.

.. _`CWEB language`:                    http://www-cs-faculty.stanford.edu/~knuth/cweb.html
.. _`literate programming web page`:    http://www.literateprogramming.com/
.. _`noweb language`:                   http://www.eecs.harvard.edu/~nr/noweb/
.. _`rST primer`:                       http://docutils.sourceforge.net/docs/user/rst/quickstart.html

.. ----- Relative links.

.. _`Chapter 8: Customizing Leo`:   customizing.html
.. _`Writing plugins and hooks`:    writingPlugins.html

.. _`programming reference`:    directives.html
.. _`@asis`:                    directives.html#asis-and-noref
.. _`@auto`:                    directives.html#auto
.. _`@file`:                    directives.html#file-and-thin
.. _`@noref`:                   directives.html#asis-and-noref
.. _`@nosent`:                  directives.html#nosent
.. _`@root`:                    directives.html#root
.. _`@thin`:                    directives.html#file-and-thin
.. _`@unit documentation`:      directives.html#root
.. _`tangling @root trees`:     directives.html#tangling-root-trees-with-the-tangle-commands
.. _`untangling @root trees`:   directives.html#untangling-root-trees-with-the-untangle-commands

.. ----- References to the tutorial.
.. _`clones & views`:               intro.html#clones-views
.. _`leo's tutorial`:               intro.html
.. _`derived files section`:        intro.html#derived-files
.. _`directives for programming`:   intro.html#directives-for-programming
.. _`leo directives`:               intro.html#leo-directives
.. _`quick start for programmers`:  intro.html#quick-start-for-programmers
.. _`sentinels lines`:              intro.html#sentinel-lines


**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 `@file node`_ is a node whose *headline* starts with ``@file``.

.. _`@auto node`:
.. _`@file node`:
.. _`@thin node`:
.. _`@root node`:
.. _`@file nodes`:
.. _`@thin nodes`:
.. _`@root nodes`:

``@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.

.. _`@auto tree`:
.. _`@file tree`:
.. _`@thin tree`:
.. _`@root tree`:
.. _`@file trees`:
.. _`@shadow trees`:
.. _`@thin trees`:
.. _`@root trees`:

``@file tree, @others tree, @root tree, etc.``
    An @file tree_ is a tree whose root_ is an @file node, etc.

``@asis, @auto, @file, @noref, @nosent, @thin``
    Headlines_ that start with one of these create (correspond to) `derived files`_.
    The following synonyms exist::

        @asis, @file-asis
        @noref, @file-noref
        @nosent, @file-nosent

    For more information, see the documentation for `@asis`_, `@auto`_, `@file`_, `@noref`_, `@nosent`_ and `@thin`_
    in Leo's `programming reference`_ chapter.

    \@auto trees allow you to edit derived files that contain no sentinels.
    Leo will import the @auto files when reading .leo files.  Be careful when first creating the @auto node.
    *Before* saving the .leo file containing the new @auto node,
    use the read-at-auto-nodes command to do the initial import.

.. _`@all`:
.. _`@all directive`:

``@all``
    A directive_ that copies the `body text`_ of all nodes_ in an `@thin` tree to the corresponding `derived file`_.
    For more information, see `directives for programming`_ in `Leo's tutorial`_.

.. _`@others`:
.. _`@others directive`:

``@others``
    A directive_ that copies the `body text`_ of all nodes_ *except* `section definition nodes`_
    in an `@thin` tree to the corresponding `derived file`_.
    For more information, see `directives for programming`_ in `Leo's tutorial`_.

.. _`@unit`:
.. _`@unit directive`:

``@unit``
    A directive_ that expands the scope_ of definitions in `@root` trees.
    For more information, see the `@unit documentation` in Leo's `programming reference`_.

.. _`body pane`:

``Body pane``
    The pane containing the `body text`_ of the currently selected headline_ in the `outline pane`_.

.. _`body text`:

``Body text``
    The text in the `body pane`_.  Body text is always associated with a particular node_.

.. _`body text box`:

``Body text box``
    A small blue box in the `icon box`_ indicating that the node_ contains `body text`_.

.. _`child`:
.. _`children`:

``Child``
    A node_ directly contained by a node.

.. _`chunk`:
.. _`chunks`:

``Chunk``
    A section_ (noweb_ terminology).

.. _`clone`:
.. _`clones`:
.. _`cloned`:

``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`:
.. _`clone arrows`:

``Clone Arrow``
    A small red arrow in the `icon box`_ indicating that the node_ is a clone_.

.. _`code part`:
.. _`code parts`:

``Code part``
    A part of a `section definition`_ that contains code. 
    Code parts start with ``@c`` or ``@code`` directives_ and continue until the next `doc part`_

.. _contract:
.. _contracts:
.. _contracted:

``Contract``:
    To hide all descendants_ of a node_.

.. _`cweb`:

``CWEB``
    A `literate programming`_ language invented by Donald Knuth and Silvio Levy.
    The `CWEB language`_ produces derived files for the C language.

.. _`demote`:

``Demote``
    To move all siblings_ that follow a node_ so that they become children_ of the node.

.. _`derived file`:
.. _`derived files`:

``Derived file``
    The file created as the result of tangling_ a node containing an ``@root`` directive_.
    The file consists of the expansion of the text following the ``@root`` directive_.
    For more information, see the `derived files section`_ of `Leo's tutorial`_.

.. _`descendant`:
.. _`descendants`:

``Descendant``
    An offspring_ of a node_.  That is, a child_, grandchild_, etc. of a node.

.. _`directive`:
.. _`directives`:

``Directive``
    A keyword, preceded by an '@' sign, in `body text`_ that controls Leo's operation.
    The keyword is empty for the ``@`` directive.
    For more information, set the `Leo directives`_ section of `Leo's tutorial`_.

.. _`doc part`:
.. _`doc parts`:

``Doc part, @doc part, document part, etc.``
    A part_ of a `section definition`_ that contains comments.
    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`:
.. _`escape conventions`:

``Escape convention``
    A convention for representing sequences of characters that would otherwise have special 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 `noweb's`_ ``@<<`` and ``@>>`` escape conventions.
    Any line containing matched ``<<`` and ``>>`` is a `section reference`_, regardless of context.
    To use ``<<`` and ``>>`` as ordinary characters, place them on separate lines.

.. _expand:
.. _expands:
.. _expanded:

``expand``
    To make the children_ of a node_ visible.

.. _`grandchild`:
.. _`grandchildren`:

``Grandchild``
    The child_ of a child of a node_.

.. _`headline`:
.. _`headlines`:
.. _`headline text`:

``Headline``
    The headline text of a node_.  The part of the node visible in the `outline pane`_

.. _`hoist`:
.. _`hoisted`:
.. _`dehoist`:

``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.

.. _`icon box`:
.. _`icon boxes`:

.. _`LaTex`:

``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`:
.. _`Leo2`:

``Leo1 and Leo2``
    **Leo1** denotes all versions of Leo that write version 1 .leo files, 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 files.

    **Leo2** denotes all versions of Leo that write version 2 .leo files, that is,
    all versions of leo.py and all Windows versions with version number 2.0 and above.
    Only Leo2 can generate `derived files`_ from `@file trees`_.

.. _`literate programming`:

``Literate programming``
    A style of programming that aims at producing the highest quality program listings.
    Literate programming languages apply two fundamental operations to text: weaving_ and tangling_.
    Leo supports two literate programming languages, `CWEB`_ and `noweb`_.
    For more links see the `literate programming web page`_.

.. _`mark`:
.. _`marks`:

``Mark``
    A red vertical line in the `icon box`_ of a node_.

.. _node:
.. _nodes:

``Node``
    The organizational unit of an outline_. The combination of `headline text`_ and `body text`_.
    Sometimes used as a synonym for tree_.

.. _`noweb`:
.. _`noweb's`:

``noweb``
    A literate programming language invented by Norman Ramsey.
    The `noweb language`_ can produce `derived files`_ for any text-based programming language.

.. _`offspring`:

``Offspring``
    The children_, grandchildren_, etc. of a node_.

.. _`organizing node`:
.. _`organizing nodes`:
.. _`organizer node`:
.. _`organizer nodes`:

``Organizing node``, ``organizer node``
    A node_ containing no `body text`_.
    Organizing nodes may appear anywhere in an `@file tree`_; they do not affect the derived file in any way.
    In particular, organizing nodes do not affect indentation in `derived files`_.

.. _`orphan`:
.. _`orphan node`:
.. _`orphan nodes`:

``Orphan node``
    A node_ that would not be copied to a `derived file`_.
    Orphan nodes can arise because an `@thin tree`_ has no ``@others`` or ``@all`` directives_.
    Sections_ that are defined 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 file`_.
    No information is lost; Leo saves the information in the `@thin tree`_ in the .leo file.
    Leo will load the `@thin tree`_ from the .leo file the next time Leo opens the .leo file.

.. _`outline`:
.. _`outliner`:
.. _`outlines`:

``Outline``
    - A node_ and its descendants_.
    - A tree_
    - All the nodes_ of a .leo file.

.. _`outline order`:

``Outline Order``
    The order that nodes_ appear on the screen when all nodes_ are expanded.

.. _`outline pane`:

``Outline pane``
    The pane containing a visual representation of the entire outline_, or a part of the outline_ if the outline is hoisted_.

.. _parent:
.. _parents:

``Parent``
    The node_ that directly contains a node.

.. _`part`:
.. _`parts`:

``Part``
    A synonym for section_.  See also `code part`_ and `doc part`_.

.. _`pdf file`:
.. _`.pdf file`:

``pdf file``
    A file that can be read by Adobe Acrobat.

.. _`plugin`:
.. _`plugins`:

``Plugin``
    - A Python file in Leo's ``plugins`` folder.
    - A way to modify and extend Leo without changing Leo's core code.
      ``leoPlugins.leo`` contains all of Leo's official plugins.

    See `Writing plugins and hooks`.

.. _`promote`:

``Promote``
    To move all children_ of a node_ in an outline so that they become siblings_ of the node.

.. _reStructuredText:
.. _rST:

``reStructuredText (rST)``
    A simple, yet powerful markup language for creating .html, or LaTeX output files.
    See the `rST primer`_.

.. _`root`:
.. _`root node`:

``Root``
    - The first node_ of a .leo file.
    - The first node of an `@root`_ tree or `@file`_ tree.

.. _`rst3 plugin`:

``rST plugin``
    A plugin_ that supports reStructuredText_.
    Unlike previous rst plugins, the rst3 plugin supports per-node options.

.. _`scope`:

``Scope``
    The portion of the outline_ in which a `section definition`_ is known.

.. _`section`:
.. _`sections`:

``Section``
    A fragment of text that can be incorporated into `derived files`_.
    See the `Quick start for programmers`_ in `Leo's tutorial`_ for more details.

.. _`section definition`:
.. _`section definitions`:

``Section definition``:
    The `body text`_ of a `section definition node`_.
    See the `Quick start for programmers`_ in `Leo's tutorial`_ for more details.

.. _`section definition node`:
.. _`section definition nodes`:

``Section definition node``
    A node_ whose headline_ starts with a `section name`_ and whose body text defines a section_.
    See the `Quick start for programmers`_ in `Leo's tutorial`_ for more details.

.. _`section name`:
.. _`section names`:

``Section name``
    A name enclosed in ``<<`` and ``>>``.
    Section names may contain any characters except newlines and ">>".
    See the `Quick start for programmers`_ in `Leo's tutorial`_ for more details.

.. _`section reference`:
.. _`section references`:
.. _`reference`:
.. _`references`:
.. _`referenced`:

``Section reference``
    A `section name`_ appearing in a `code part`_.
    Tangling_ replaces all references by their definitions.
    See the `Quick start for programmers`_ in `Leo's tutorial`_ for more details.

.. _`sentinel`:
.. _`sentinels`:
.. _`sentinel lines`:

``Sentinels, sentinel lines``
    Comment lines in files derived from `@file nodes`_.
    Such lines start with an ``@`` following the opening comment delimiter.
    Sentinels embed outline structure into `derived files`_.
    **Do not alter sentinel lines**.  Doing so can corrupt the outline structure.
    For more information see `Sentinel lines`_ in `Leo's tutorial`_.

.. _`@settings`:
.. _`setting`:
.. _`settings`:

``Setting``:
    Plugins_ and other parts of Leo can get options from ``@settings`` trees,
    outlines_ whose headline_ is ``@settings``. When opening a .leo file, 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 Leo's core code. For a full discussion of
    @settings trees, see `Chapter 8: Customizing Leo`_.

.. _`sibling`:
.. _`siblings`:

``Sibling``
    Two nodes_ are siblings if they have the same parent_.  Siblings of the root_ have no parent.

.. _`tangle`:
.. _`tangles`:
.. _`tangling`:

``Tangling``
    The process of creating `derived files`_ from `@root trees`_ or `@file trees`_.
    Leo tangles `@file trees`_ automatically when writing a .leo file.
    You must explicitly tangle_ `@root trees`_ using the ``Tangle`` command.
    Tangling expands all `section references` in an `@root node`_ or `@file node`_.
    For more information, see `Tangling @root trees`_ in Leo's `programming reference`_.

.. _`target language`:

``Target language``
    The language used to syntax color text.
    This determines the default comment delimiters used during tangling_ and untangling_.

.. _`tree`:
.. _`trees`:

``Tree``
    An outline_.
    A node_ and its descendants_.

.. _`untangle`:
.. _`untangles`:
.. _`untangling`:

``Untangling``
    Updating an outline_ based on changes to `derived files`_.
    Untangling allows changes to be propagated from derived files back to the outline.
    Especially useful when fixing syntax errors outside Leo.
    For more information, see `Untangling @root trees`_ in Leo's `programming reference`_.

.. _`weave`:
.. _`weaves`:
.. _`weaving`:

.. _`view node`:
.. _`view nodes`:

``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 `Leo's tutorial`_ for more information.

``Weaving``
    The process of creating typeset documentation from a noweb_ or CWEB_ source file.
    Weaving creates documentation. Tangling_ creates `derived files`_.
    Leo does not support weaving directly.
    To weave a file you can create noweb_ or CWEB_ files using Leo's ``Export`` commands,
    then use the noweb_ or CWEB_ systems to weave those files.

What's New...
+++++++++++++


@language rest

What's New in Leo 4.6
*********************



@rst html\new-4-6.html
^^^^^^^^^^^^^^^^^


#######################################
What's New in Leo 4.6
#######################################

.. .. contents::


.. Links used in this document.
.. .. _`Chapter 23`:           atShadow.html

Improved unit testing
~~~~~~~~~~~~~~~~~~~~~


- leoDynamicTest.py now supports a --path argument giving the .leo file.
  This is so useful!

- leoDynamicTest.py now honors the --silent argument.

- leoTest.runUnitTestLeoFile runs all unit tests in a given .leo file
  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 fixes sometimes-misleading error messages.

- test.leo contains a 'run-test.leo-tests' button.

- leoPy.leo contains a 'run-all-core-tests' button.

Improved file handling
~~~~~~~~~~~~~~~~~~~~~~


- Leo opens a default .leo file if no other is specified, using the @string
  default_leo_file setting. The default for this setting is
  ``~/.leo/workbook.leo``

- Added escapes for underindented lines. The escape is specified 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 file that has been changed outside of
  Leo. This prevents bzr reversions.

- Leo tests syntax of .py files when saving them.

- Leo can now open any file into an @edit node. This allows Leo to be associated
  with the edit action of .py files. Like this::

    C:\Python26\python.exe "c:\leo.repo\trunk\launchLeo.py" --gui=qt %1 %2

- Leo now warns if when writing an @auto node if the the file exists and the
  node has not been read previously.  This prevents a newly-created
  @auto node from overwriting an existing file.

Improved handling of rST files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Added support for @auto-rst nodes. These import reStructuredText (rST) files
so that the files can be "round-tripped" without introducing extraneous changes.
This makes Leo a superb environment for using rST.

New code features
~~~~~~~~~~~~~~~~~


- Added autoCompleter.getExternalCompletions.
  See http://groups.google.com/group/leo-editor/browse_thread/thread/4ad91984a6d0acac

- Added g.posList.

- c.config.doEnabledPlugins sets g.app.config.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.config.getSettingSource(setting_name)
  returns the name of the file which Leo used to determine the setting:

    - D indicates default settings.
    - F indicates the file being loaded
    - L indicates leoSettings.leo
    - M indicates myLeoSettings.leo

- Predefined 'self' in @test/@suite nodes.

- Added c.getNodePath and c.getNodeFileName.
  See http://groups.google.com/group/leo-editor/browse_thread/thread/3b5f1232ecc6bba7

New command-line options
~~~~~~~~~~~~~~~~~~~~~~~~


- The --config command-line option specifies a single config (.leo) file
  to use for configuration.
  See http://groups.google.com/group/leo-editor/browse_thread/thread/f3f95d93bcd93b94

- The --file=fileName command-line option load a file.
  Only .zip and .leo extensions are allowed at present.

- The --gui=name command-line option specifies the gui to use.
  The valid values are --gui=qt, --gui=tk

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 files
  The open file dialog now shows all files by default.
  Selecting a non-.leo file will load that file 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.

- find-clone-all is a synonym for clone-find-all.

- open-quickstart-leo command opens leo/doc/quickstart.leo.

- The Alt-Right and Alt-Left keys (expand-and-go-right and contract-or-go-left
  commands) now move to the previous or next node if now left/right movement is
  possible.

New and improved directives
~~~~~~~~~~~~~~~~~~~~~~~~~~~


- Added @nocolor-node directive.

- Improved @path handling.

New settings
~~~~~~~~~~~~


- @string default_leo_file = ~/.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.

- The old bindings bound the PageUp/Down keys to back/forward page commands, and
  these commands work only for text.

  The new default bindings in leoSettings.leo: @keys EKR bindings are::

    back-page                       ! text = PageUp
    back-page-extend-selection      ! text = Shift-PageUp
    forward-page                    ! text = PageDn
    forward-page-extend-selection   ! text = Shift-PageDn

    scroll-down-half-page   ! tree = Shift-PageDn
    scroll-down-page        ! tree = PageDn
    scroll-up-half-page     ! tree = Shift-PageUp
    scroll-up-page          ! tree = PageUp    

- @bool enable_alt_ctrl_bindings.
  The default is False, needed for AltGr functionality on Windows.

Plugins
~~~~~~~


- Improved nav_buttons plugin and corresponding nodeHistory class.

- Created qtGui and tkGui plugins.

- Created leoGuiPluginsRef.leo.

- Leo issues an error message if a non-existent plugin appears
  in an @enabled-plugin node.

What's New in Leo 4.5
*********************


@language rest

@rst html\new-4-5.html
^^^^^^^^^^^^^^^^^


#######################################
What's New in Leo 4.5
#######################################

.. .. contents::


.. Links used in this document.
.. _`Chapter 23`:           atShadow.html

Major new features
~~~~~~~~~~~~~~~~~~


- Added support for @shadow files.
  This is a major breakthrough.
  See `Chapter 23`_ for full details.

- Added much improved support for vim bindings.

- Allow v.uA's in @thin and @shadow nodes.
  See http://groups.google.com/group/leo-editor/browse_thread/thread/750bb3099090f5b

Major code reorganizations
~~~~~~~~~~~~~~~~~~~~~~~~~~


- Leo now uses a sax-based parser to read .leo files.
  This makes it possible to extend Leo's file format without invalidating previous versions of Leo.

- Leo now supports the so-called 'Graph World'.
  When g.unified_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 Leo's 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.

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 function's start::

    g.startTracer()

- The find-character command now finds 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-file-into-node,
  write-file-from-node and all the import/export commands.

- Leo creates the .leo folder in the user's HOME directory, and puts several configuration files there.
  Leo looks for myLeoSettings.leo in HOME/.leo.
  Leo uses os.path.expanduser("~") if there is no home setting.

New settings
~~~~~~~~~~~~


- The default settings for @shadow files 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 fixedWindow option. Leo suppresses marks, expansion
  state, orphan bits and current position bits when writing fixed .leo files. As
  a result, all nodes will be collapsed and the root node will always be
  selected when Leo opens a fixed .leo file.

  You can optionally specify the size and position on the screen of fixed .leo
  files by putting an '@data fixedWindowPosition' node in the
  @settings tree of myLeoSettings.leo or leoSettings.leo.  You should
  **not** put such a node in the fixed .leo file itself--everyone who
  opens the file would get that fixed position.

  The body of the '@data fixedWindowPosition' 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 default is True.

What's New in Leo 4.4.8
***********************


@language rest

@rst html\new-4-4-8.html
^^^^^^^^^^^^^^^^^^^


#######################################
What's New in Leo 4.4.7 and Leo 4.4.8
#######################################

.. .. contents::


.. Links used in this document.
.. _`leoBridge chapter`:    leoBridge.html
.. _`debugging with Leo`:   debuggers.html
.. _gettext: http://docs.python.org/lib/module-gettext.html

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 Leo's log. Rather than using an '_'
  function to denote strings to be translated, Leo's g.es and g.es_print
  functions translate "odd" (first, third, fifth) arguments, leaving "even"
  arguments untranslated. Keyword arguments, color, newline, etc. are never
  translated. g.translateString does the actual translation using Python's
  `gettext`_ module.

- \@menu items may not refer to commands created by @button and @command nodes.

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.

New settings
~~~~~~~~~~~~


- Added support for @commands trees in leoSettings files.

- 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.

What's New in Leo 4.4.6
***********************



@rst html\new-4-4-6.html
^^^^^^^^^^^^^^^^^^^


##########################################
What's New in Leo 4.4.6
##########################################

Leo 4.4.6 fixes all known bugs and adds a few new features.

.. .. contents::


.. Links used in this document.
.. _`leoBridge chapter`:    leoBridge.html
.. _`debugging with Leo`:   debuggers.html

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.

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.

New settings
~~~~~~~~~~~~


- Added support for @data nodes in settings files.

- The @data import_xml_tags setting specifies the xml tags that act as organizers.
  This settings is used by @auto when importing xml files.

What's New in Leo 4.4.5
***********************



@rst html\new-4-4-5.html
^^^^^^^^^^^^^^^^^^^


##########################################
What's New in Leo 4.4.5
##########################################

Leo 4.4.5 fixes several long-delayed bug fixes 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 Leo's icon library.
- Adds support for @rst-preformat nodes to the rst3 plugin.

.. .. contents::


.. Links used in this document.
.. _`leoBridge chapter`:    leoBridge.html
.. _`debugging with Leo`:   debuggers.html

Bug fixed
~~~~~~~~~


- 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

New features
~~~~~~~~~~~~


- Leo now supports all directives in headlines.

- Moved all unit tests to unitTest.leo and reorganized the unit tests by Leo source file.

- Installed small icon set from Tango library.

- The rst3 plugin now supports @rst-preformat nodes.

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

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 significant.

- @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.

What's New in Leo 4.4.4
***********************



@rst html\new-4-4-4.html
^^^^^^^^^^^^^^^^^^^


##########################################
What's New in Leo 4.4.4
##########################################

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 doesn't 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 files Leo generates.

- **@menus trees** in settings files create all of Leo's menus.  It is now dead
  easy to make Leo's menus look the way you want.

- **@buttons trees** in settings files create common @button nodes created in all
  Leo outlines.

- A new, faster, **colorizer plugin** replaces the __jEdit_colorizer__ plugin.

- New commands for **resolving cvs conflicts**.

- Leo's core is now compatible with jython.

.. .. contents::


.. Links used in this document.
.. _`leoBridge chapter`:    leoBridge.html
.. _`debugging with Leo`:   debuggers.html

The Great Graph Aha
~~~~~~~~~~~~~~~~~~~


The Great Graph Aha is:

A Leo outline doesn't 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 Leo's 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 Leo's 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 files.
   These short, simple, self-contained, easily modifiable 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.

Added support for @auto files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



What @auto does
"""""""""""""""


@auto trees allows people to use Leo in collaborative environments without using
sentinels in the files Leo generates. In contrast to @nosent, @auto trees can
change when the corresponding file changes outside of Leo.

Leo will automatically recreate (import) all @auto trees when reading a .leo
file, and will write all dirty @auto trees when saving a .leo file. 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 influence of an @ignore directive.

2. Saving a .leo file does not save @auto nodes if a) they haven't been changed
or b) they do not contain a **significant** amount of information. An @auto tree
contains a significant 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 file. Parsers
create descendant nodes of the @auto tree: one node for each class, method and
function in the derived file.

Parsers presently exist for C, elisp, Java, Pascal, PHP and Python. Leo
determines the language using the file's extension. If no parser exists for a
language, the entire body of an @auto tree contains a significant amount of information if it has any children or if the root node contains more than 10 non-blank lines. the derived file is copied to the body of the @auto
node.

Leo does not write the contents of @auto trees to .leo files. 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.

Perfect import checks
"""""""""""""""""""""


Leo performs several checks to ensure that the result of importing an external
file will be equivalent to the file 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 file. If you @ignore directive, a later write of the
@auto tree will attempt to fix 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 significant. Before importing a file for a strict language, Leo
**regularizes** the leading whitespace of all lines of the original source file.
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 file exactly if problems are discovered while
regularizing leading whitespace.

After importing a file, Leo verifies that writing the @auto node would create
the same file as the original file. 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 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 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 files 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 file.

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.

New commands for resolving cvs conflicts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The so-called resolve-cvs-conflict project has resolved itself into small,
easily understood commands.

The **read-file-into-node** command prompts for a filename, and creates an node
whose headline is @read-file-into-node <filename> and whose body text is the
entire contents of the file.

The **write-file-from-node** command writes the body text of the selected not to a file.
If the headline of the presently selected node starts with @read-file-into-node
the command use the filename that follows in the headline. Otherwise, the
command prompts for a filename.

When a cvs conflict occurs, the user will:

- read the file into a node using the read-file-into-node command,

- fix the conflict, as with any other editor, and

- write the file with the write-file-from-node command.

Any file can be fixed in this way, including derived files and .leo files. The
only complication is that the user must not change sentinel lines. Two new
commands check the contents of a node: The **check-derived-file** and
**check-leo-file** commands tell whether a trial read of the presently selected
node can be done successfully. The check-derived-file command assumes the body
text is a derived file; the check-leo-file command assumes the body text is an
entire .leo file.

The **compare-leo-outlines** command prompts for another (presumably similar)
.leo file that will be compared with the presently selected outline file (main
window). It then creates clones of all inserted, deleted and changed nodes.

New kinds of settings trees
~~~~~~~~~~~~~~~~~~~~~~~~~~~



@buttons trees
""""""""""""""


All @buttons tree in a settings file defines global buttons that are created in
the icon area of all .leo files. You define @button nodes in the @buttons tree
as usual.

@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 define 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.

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 flash.

Leo's core is now compatible with jython
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Essentially all of Leo's startup code now runs with jython 2.2 and the (unfinished!) swing gui.

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 files 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.

Minor improvements
~~~~~~~~~~~~~~~~~~


- See the release notes for a list of bugs fixed in Leo 4.4.4.

- 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::

    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)

- 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_file_prefixes 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.

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

What's New in Leo 4.4.3
***********************



@rst html\new-4-4-3.html
^^^^^^^^^^^^^^^^^^^


##########################################
What's New in Leo 4.4.3
##########################################

The highlights of Leo 4.4.3:

- @test and @suite nodes may now be embedded directly in derived files.
- Added support for chapters in Leo's core.
- Added support for zipped .leo files.
- The new leoBridge module allows full access to all of Leo's capabilities
  from programs running outside of Leo.
- Better support for the winpdb debugger.
- Added support for @enabled-plugins and @open-with nodes in settings files.
- Removed all gui-dependent code from Leo's core.
- The__wx_gui plugin is now functional.

.. .. contents::


.. Links used in this document.
.. _`leoBridge chapter`:    leoBridge.html
.. _`debugging with Leo`:   debuggers.html

Important new features
""""""""""""""""""""""


- @test and @suite nodes may now be embedded in derived files.
- Added support for chapters to Leo's core

  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 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.

- Added support for compressed .leo files

  Leo now has save-file-as-zipped and save-file-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 Leo's Save As commands except that they
  temporarily force Leo to write the file in either zipped or unzipped format.
  Leo remembers whether a file was originally zipped. The read logic handles
  either zipped or unzipped .leo files automatically. The write logic will zip
  the file if it was originally zipped or if the save-file-as-zipped command is
  being executed. Leo writes files with .leo extension, regardless of whether
  the file is zipped or not. Zipped .leo files contain a single archive, whose
  name is the same as the .leo file itself.

  **Notes**: The new save commands suffice to compress and expand .leo files on
  a file-by-file basis. In particular, there is no need for any user settings.
  Outside of Leo you can change the extension to .leo.zip and use stuffit or
  other program to expand the .leo file contained within. I've only tested this
  on XP, but it should work everywhere...At present the code uses Python's
  zipfile module to read and write zipped files.

- Added leoBridge module.
  See the `leoBridge chapter`_ for full details.

- Removed all (or almost all) gui-independent from Leo's core.

- Improved support for the winpdb debugger.
  See the `debugging with Leo`_ chapter for full details.

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

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

Plugins
"""""""


- The __wx_gui.py plugin is now minimally functional. Alas, some problems
  remain. See the bug list in the plugin for details.

- Changed bindings in the UniversalScrolling plugin.

- Registered the write-restructured-text command in rst3 plugin.

Minor improvements
""""""""""""""""""


- See the release notes for a list of the many bugs fixed 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-first/last-sibling commands.

- Made escape in the minibuffer work like ctrl-g.

- Only do one message re writing recent files.

- Added handleUrlInUrlNode helper for OnIconDoubleClick.

- Made copied nodes valid Leo files.
  For details, see http://sourceforge.net/forum/message.php?msg_id=4014079

- changeAll now works like findAll

- Clear status line in repeat-complex-command.

What's New in Leo 4.4.2
***********************



@rst html\new-4-4-2.html
^^^^^^^^^^^^^^^^^^^


##########################################
What's New in Leo 4.4.2
##########################################

This page summarizes the changes made in Leo 4.4.2
For full details see the release notes section in LeoDocs.leo.

.. .. contents::


.. Links used in this document.
.. _Emacs:                          http://www.xemacs.org/
.. _pymacs:                         http://pymacs.progiciels-bpi.ca/index.html
.. _`Chapter 18: Leo and Emacs`:    emacs.html

A major code reorg
~~~~~~~~~~~~~~~~~~


Leo's vnode and tnode classes are now completely independent of the rest of Leo.
Some api's have been changed.  This 'big reorg' and may affect scripts and plugins.

New commands
~~~~~~~~~~~~


::

    extend-to-line
    extend-to-paragraph
    extend-to-sentence
    forward-end-word
    forward-end-word-extend-selection

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 first 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 Leo's core now use only strings.
  This is an essential precondition to supporting @menu nodes in
  leoSettings.leo.
- Leo's 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-specific 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 files in the same place Leo looks for leoSettings.leo files.
- Created three scripts (in test.leo) that help create unit tests for Leo's edit commands.
  Create Created runEditCommandTest for use by these scripts.
- Improved print-bindings command.
  The bindings are sorted by prefix: this is a big help in understanding bindings.
  For each prefix, first print items with only a single character after the prefix.
- Made writing .leo files faster.
  The new code almost exactly twice as fast as the old.
- Added p.archivedPosition.
  This is a key first 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 first letter of headlines.
- The find 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 @file, @thin, etc prefixes.
- Made outline navigation cumulative.
  When keystrokes in the outline pane are typed 'close' together Leo first tries to look
  for prefix + ch, where ch is the character just typed and prefix is the previous match.
  The term 'close together' is specified by the setting @float 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 significant. In practice everything works
  well without me thinking at all about what is happening.

New and improved plugins
~~~~~~~~~~~~~~~~~~~~~~~~


- 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, multifile, nodenavigator and shortcut_button plugins.
- The rst3 plugin now registers the rst3-process-tree command.
- The leoOPML.py plugin defines commands to read and write OPML files.
- The slideshow.py plugin allows Leo to run slideshows defined by @slideshow and @slide nodes.
- The leo_to_rtf and leo_to_html plugins create rtf and html files 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.

Settings
~~~~~~~~


- Removed .leoRecentFiles.txt from the distribution and cvs and added @bool
  write_recent_files_as_needed. The presence or absence of .leoRecentFiles.txt
  no longer controls whether Leo creates and updates .leoRecentFiles.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 files in the same place Leo looks for leoSettings.leo files.
- Added settings for all mod_scripting switches.
- Added @bool collapse_nodes_during_finds.
  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 files.
  This is slower than using Leo's 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

ZODB scripting
~~~~~~~~~~~~~~


Leo's 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.

What's New in Leo 4.4.1 and 4.4.1.1
***********************************



@rst html\new-4-4-1.html
^^^^^^^^^^^^^^^^^^^


##########################################
What's New in Leo 4.4.1
##########################################

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 Leo's body pane and
- A new colorizer plugin controlled by jEdit language description files.
- 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.

.. .. contents::


.. Links used in this document.

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

New features
~~~~~~~~~~~~


- Removed warning about changed node.
- Added scroll-outline-left/right commands.
- Leo outputs decorators correctly, assuming the decorator does not conflict with a Leo directive.
- Wrote script to convert g.es to g.et where appropriate.
  The first step in translating all Leo messages.
- Leo highlights (flashes) matching brackets when typing typing (, ), [, ], { or }.
- 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) confined 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 find command
  to the replace command.

New and improved plugins
~~~~~~~~~~~~~~~~~~~~~~~~


- 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.

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

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.
- 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.

Minor improvements
~~~~~~~~~~~~~~~~~~


- The print-bindings command now properly sorts bindings.
- The help-for-command command now works for almost all commands.
- Improved filename completion.
- Better listings for print-commands and print-bindings &amp; 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.

What's New in Leo 4.4
*********************



@rst html\new-4-4.html
^^^^^^^^^^^^^^^^^


##########################################
What's New in Leo 4.4
##########################################

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 completion.

- Many new commands, including cursor and screen movement, basic character, word
  and paragraph manipulation, 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.

.. .. contents::


.. Links used in this document.

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
    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
    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

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-find checkbox to the Find tab.
- Improved find tab.
- Improved formatting of shortcuts in print-commands and print-bindings.
- Added settings for vim plugin.
- Put up a dialog if can't 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.

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:

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)

New and improved plugins
~~~~~~~~~~~~~~~~~~~~~~~~


- 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

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.

