back leo next

FAQ

This is Leo's Frequently Asked Questions document.

Contents

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

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 @file trees?

Use @file trees (including @thin trees) unless you are sure you must have the extra flexibility of @root trees. Indeed, @file trees are much easier to use than @root trees:

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.

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

Using @thin trees can eliminate most problems with using Leo in cvs environments:

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

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

    Important: Leo's cvs 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.

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

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

  • Use the mod_shadow plugin.

    A third possibility is to use the mod_shadow plugin. This plugin maintains two copies of the file: one with sentinels in a subdirectory, and one without sentinels. The plugin picks up external changes when Leo is started.

    This currently works only for Python file (until I figure out how access the information what the sentinels are for a file in Leo).

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 @file 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 unsuppoorted 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 @file trees or @nosent trees. Use the @silent directive in @root trees.

The @first directive puts lines at the very start of files derived from @file. 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

Leo recognizes the @first directive only at the start of the body text of @file 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. @file 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 @file trees must be part of the derived file: orphan and @ignore nodes are invalid in @file 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 @file trees and stuff you don't want in the @file 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.

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@charter.net. 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)

Tips and techniques

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

Trouble shooting

I can't run Leo from a cvs sandbox. What's going on?

Leo's extensions folder contains Pmw in official distributions, but not in the Cvs repository, so you won't be able to use a Leo in a sandbox unless you copy Pmw to the extensions folder or have Pmw otherwise availble on Python's path.

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

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.

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). Important: once a .leo file is created the <?xml..."> line can only be changed by hand. This may cause unicode errors the next time the .leo file is loaded, so you should change the <?xml..."> line by hand only when first creating a .leo file.

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:

  1. using the tk_encoding setting if it exists,
  2. using locale.getpreferredencoding if it exists, or the equivalent code in pre-python 2.3 versions,
  3. using sys.getdefaultencoding
  4. defaulting to "utf-8"

Neither b nor c are guaranteed to give a valid encoding in all systems, and Leo will ignore invalid encodings returned from b or c. Therefore, setting the tk_encoding setting may be needed.

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.

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 @file or @root as desired, then remove the @ignore directive. Saving the outline will then create the derived file.

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

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.

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 from a console window.

However, in some cases, docutils crashes instead of properly reporting the problem. There are several workarounds:

  1. The crashes I have seen arise from the following bug in docutils. Hyperlinks in image:: markup must be lower case. This will work:

    .. |back| image:: arrow_lt.gif
        :target: faq_
    

    This will crash:

    .. |back| image:: arrow_lt.gif
        :target: FAQ_
    

    So avoid this crash by making sure to use lower case targets in :target: markup.

  2. You can change the docutils source slightly so that it prints a traceback when it crashes. (The rst3 plugin should be able to do this, but I 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 from 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.

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

I left cap locks on and found the node copy/paste shortcuts stopped working

This is a bug in Tk that has no workaround. Some keyboards, e.g. the Microsoft ergonomic keyboard allow you to disable the caps lock key. OTOH, the same keyboard has a brain-dead F-lock key that disables the F-keys when pressed by mistake and that can't be disabled. Oh well...


back leo next