Here is a first draft of a slideshow explaining @file, @auto and
@edit. All comments welcome.
I have found that it's useful to see all the text together during the
initial drafts. ===== indicates a slide. The title is **not** likely
to be show in the final show. The ((.. )) notation indicates what
will be shown in the accompanying screenshot.
===== Intro
Trees whose root headline starts with \...@file, \...@auto or \...@edit create
**external
files** on your file system. Here are some examples::
@file myClass.py
@auto ../graphics/circles.cpp
@edit ~/.leo/.leoID.txt
As you can see, these nodes specify file names, which can be an
absolute
path or a path relative to the directory containing the Leo outline.
Collectively, nodes that create external files are known as **@<file>
nodes.**
Leo defines several other kinds of @<file> nodes, but this slideshow
will not
discuss them.
===== Automatic load/store make Leo an IDE
Leo automatically loads all @<file> trees when you open a Leo outline,
and Leo
writes any modified @<file> tree when you save an outline. Reading
external
files is very fast because of an efficient file-caching scheme.
A single Leo outline may be connected to dozens of external files:
this makes
Leo work like an IDE (Integrated Development Environment). Leo
outlines act like
project files. For example, a Leo outline, leoPyRef.leo, contains
\...@file trees
for all of Leo's core source files. Another Leo outline,
leoPluginsRef.leo,
creates the external files for all of Leo's plugins, and LeoDocs.leo
contains
all of Leo's documentation.
===== Using sentinel lines, or not
When using \...@file, Leo stores outline structure in external files
using comment
lines called **sentinel lines**. These sentinel lines are important:
they allow
Leo to keep track of outlines structure, including clone
relationships. Using
\...@file is **highly recommended** whenever possible. In particular,
using \...@file
allows you to **share outline structure** with others merely by
sharing external
files.
Alas, in some situations it is not appropriate to use sentinel
comments in
external files. In that case you use \...@auto and \...@edit trees to
connect Leo
outlines to existing external files without creating sentinel files.
Not all of
Leo's features can be used with \...@auto and \...@edit trees, but that
can't be
helped. In particular, Leo can not preserve outline structure exactly.
Leo's
"degraded" operation for such trees is similar to that found in all
other
editors and IDE's.
The rest of this slide show will discuss \...@file trees and their
capabilities. We
will then discuss \...@auto and \...@edit.
===== Using @file trees.
To repeat, it's best to use \...@file to create external files if at all
possible.
The next series of slides will show you how to create external files
with \...@file
trees.
To create a new external file, create an \...@file node giving the path
to the
external file. This path can be a full, absolute path, but it is
usually much
more convenient to use a relative paths. All relative paths in @<file>
nodes are
relative to Leo's **load directory**, the directory containing
the .leo file for
the present outline. In most cases, we can ignore the path prefix
entirely. For
example::
@file myFile.py
===== The top-level body text: section references & @others
Here is the body text for a typical @file node that defines a single
Python class::
<< imports >>
class MyDemoClass:
@others
Let's look at this line by line.
===== << imports >>
The << imports >> lines is a **section reference**.
"Imports" is the **section name**.
This line tells Leo to insert the **section definition**
into the output file at the place where section reference occurs.
===== Section definitions
**Section definition nodes** create section definitions.
Section definition node contains a section reference in the
headline.
The body text contains the section definition.
Therefore, the definition of << imports >> are the lines::
import os
import sys
Each section definition node must be a descendant of the node
containing the section reference.
===== @others definitions
The \...@others directive is similar to a section reference;
\...@others tells Leo to insert text into the output file.
However, instead of inserting the body text of one particular
node,
as in a section reference, \...@others tells Leo to insert the
body text of all node that **aren't** section definition nodes.
That's where the name comes from: it inserts all the **other**
nodes.
===== Simple expansion of @others.
Here we have added two children of the root node, named, as usual
in Python examples, spam and eggs. The expansion of the \...@others
directive
will be the body text of those two nodes. Each line of the
expansion is
indented with the leading whitespace that occurs before the
\...@others directive.
===== Expansion
Let us use the term **reference** to mean either a section
reference or an
\...@others directive. The **expansion** of a reference is the set of
all lines
that Leo writes to the output file as the result of that
reference.
In our example, the expansions are straightforward. However,
things are not
always so simple: any node may contain one or more section
references, and
any node may also contain a single \...@others directive.
Every line of an expansion is written as the result of exactly one
reference. In particular, \...@others always expands to the set of
all descendant
nodes that have not been included in a reference in a descendant
node.
===== Indentation
The indentation of section references and the \...@others is
important.
When Leo writes the expansion of the a section reference or
\...@others directive,
Leo indents each line of the expansion by the leading whitespace
that appears
before the section reference or \...@others directive.
In our example, there is no leading whitespace before the
reference to
<< imports >>, but there are four spaces before the \...@others
directives.
This means that Leo writes the import statements without
additional indentation,
but Leo adds 4 spaces before all nodes written as the result of
the @other directive.
As noted above, expansions may contain many section references and
\
\...@others directives.
Leo keeps track of the indentation in effect at any point in the
expansion
and outputs leading whitespace accordingly when writing external
files.
This allows Leo handle languages like Python in which indentation
is especially important.
**Important**: Indentation is controlled **only** by the
indentation of section
references and \...@others directives. The outline level of nodes in
expansions
does not affect indentation in any way.
This **decoupling** of outline structure from indentation is very
important:
it allows you to create **organizer nodes** without affecting the
external
file in any significant way (other than sentinel comments).
===== Multiple @others nodes: top-level node
((
<< imports >>
@others
))
An example will clarify matters. Here is a common pattern for a
file that
defines two classes, SpamClass and EggsClass. The top-level node
includes imports,
and then uses \...@others to include the expansion of the rest of the
outline.
===== Multiple @others nodes: SpamClass
((
class SpamClass:
@others
))
The first child node creates the expansion of SpamClass.
The line::
class SpamClass:
has no extra indentation, because the \...@others in the top-level
node has no leading whitespace.
However, all the methods of the class will have 4 spaces of
indentation
because the \...@others directive in *this* node is indented by 4
spaces.
===== Multiple @others nodes: EggsClass
((
class EggsClass:
@others
))
The second child node creates the expansion of EggsClass in a
similar manner.
It's always perfectly clear what nodes are included in \...@others
directives.
Here, \...@others refers to all descendant nodes of *this* node.
===== Multiple @others nodes: @if 0:
((
if 0:
@others
))
You can use @others to "comment out" all descendant nodes as
shown. This
works in Python because the indentation of the \...@others directive
cause the
expansion of all descendant nodes to have 4 extra spaces.
===== Using @auto nodes.
When Leo reads an *...@auto node**, Leo will automatically create an
outline
that shows the class, functions or other units of the external
file.
Leo can only do this if Leo has an **importer** for the external
file. At
present, Leo has importers for C, elisp, HTML, .ini files, Java,
Javascript,
Pascal, PHP, Python and xml. Leo determines the language using the
file's
extension. If no parser exists for a language, Leo copies the
entire body of
the external file into the \...@auto node.
===== Using @edit nodes
When Leo reads and *...@edit node**, Leo reads the entire contents
of the
external file into the body text of the \...@edit node.
Edward
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/leo-editor?hl=en.
