FAQ: Frequently Asked Questions about Leo

What is the best way to learn to use Leo?
Where are the simple examples about how to use Leo?
How can I create JavaScript comments in derived files?
How can I make a derived file start with a shebang line?
What are the differences between @root and @file trees?
Why should I use clones?

What is the best way to learn to use Leo?

First, read the introduction to Leo. After that, I suggest studying LeoPy.leo, the source code for leo.py. The best way to learn about Leo is to spend 15 or 20 minutes just browsing through the outline, not worrying about details but just seeing how most nodes are organized and how directives and section references are typically used. Then they could read Chapter 4 to learn the details. When studying leo.py, I would suggest paying particular attention to the following:

The (Projects) tree shows how to use clones to represent tasks.
The @file leoNodes.py tree shows how to define more than one class in a single file using several @others directives. Note that the @others directives must be in separate nodes.
Most other files show how to use a single @others directive to define one class.
Note in particular that the vast majority of methods are defined in unnamed nodes.

Where are the simple examples about how to use Leo?

The file LeoDocs.leo contains two "Hello World" programs, one using @file trees and the other using @root trees. The file LeoPy.leo contains a large number of other examples, some small, some large and complex.

How can I create JavaScript comments in derived files?

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 setting the language to html, but how can I get the tangling comments inside the CDATA section to be java-style comments rather than html ones?

In @file trees you use the @delims directive to change comment delimiters. For example:

@delims /* */ 
Javascript stuff 
@delims <-- --> 
HTML stuff

Warning: Leo2 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 make a derived file start with a shebang line?

Use the @first directive in @file trees. Use the @silent directive in @root trees.

The @first directive allows you to place lines at the very start of files derived from @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 nodes. No text may precede @first directives. More than one @first directive may exist, like this:

@first #! /usr/bin/env python
@first # more comments.

What are the differences between @root and @file trees?

@file trees and @root trees represent derived files within an outline. Leo outlines may contain both @root and @file trees. I recommend using @file trees whenever possible.

@file trees are much easier to use than @root trees:

@file trees require less markup than @root trees; all sections in @root trees must have names, but @file trees usually contain many unnamed sections. Within @file trees, the @others directive acts like a reference to all unnamed sections.
The user must explicitly tangle and untangle @root trees using the Tangle and Untangle commands. Leo tangles and untangles @file trees automatically, tangling all changed @file trees when writing an outline and untangling all @file trees when reading an outline.

@root trees are more flexible than @file trees:

Within @file trees, sections must be defined in descendents of the node that contains the section reference.
Within @root trees a section may be defined anywhere within the @root tree, regardless of where the section is referenced. 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.

Why should I use clones?

In general, Leo's clones provide an excellent way of solving any organizational problem. The fundamental principle is this: Clones create multiple views of data.

For example, whenever I have a task to do, say a new feature to implement, or a non-trivial bug to fix, I create a new headline to represent that task. Let's call such a headline a task headline. By convention, I enclose the headline in parentheses and put an @ignore in the body text of the headline, but that's just a convention I use.

I clone all nodes that relate to that task and move the clones under the headline. Voila. I now have a new view of Leo's source code, containing all and only those nodes that relate to the task. It is now trivial to find the parts of code relating to the task. Note that I can change the cloned nodes under the headline task in any way, and the clones under the @file tree also change and the @file node itself is marked dirty so that when I save the .leo file all affected @file trees are also saved. The task headline is a perfect place to place notes about the task: why some approaches didn't work, to-do lists, test data, whatever. You could even create @file nodes to create test files if you want.

There are situations where you need to use @root trees. However, those situations are rare. Most of the time you can use clones to great effect. For extended examples, look at the (Projects) section in LeoPy.leo. That section contains a large number of views of Leo itself.