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?
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 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.
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.
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.
@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:
@root trees are more flexible than @file trees:
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.