Leo 4.1 rc1 released

[Edward K. Ream]

> Where's the Leo file format documented? (say, with a DTD
> but a semantic description would be possibly better)  Have I missed this
> somewhere?

Good question.

See Users Guide:Appendices:XML file format in LeoDocs.leo for a discussion
of Leo's file format.  This is out-of-date, though it is a start.  This also
contains a DTD, which a) is _way_ out-of-date and b) has never been checked
and so almost certainly has syntactic and/or semantic "bugs".

With these caveats, Leo's file format has remained pretty stable.  The heart
of the format is the <vnodes> element containing possibly nested <v>
elements, and the <tnodes> element containing a list of (non-nested) <t>
elements.  <v> elements refer to <t> elements using "t" attributes in <v>
elements corresponding to "tx" attributes in <t> elements.

The last time I looked (a long time ago) xml spy could properly associate
<t> elements with <v> elements.

N.B. <v> and <t> elements in .leo files correspond directly to vnodes and
tnodes in memory when Leo is running.  For full information about these see
@file leoNodes.py in LeoPy.leo.  For full information about exactly what Leo
is doing when reading and writing files, see @file leoFileCommands.py in
LeoPy.leo.

Oh yes, there is one more piece of the puzzle.  <v> elements corresponding
to @file nodes now contain tnodeList attributes that are a list of gnx's.
The tnodeList attribute allows the read code in @file leoAtFile.py 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 the
nodeIndices class in leoNodes.py for details.  A gnx has the form
id.timestamp.n where .n is elided unless two nodes would have the same
id.timestamp field.

The following sections of LeoDocs.leo Users Guide:Customizing Leo contain
new conventions that allow plugins to extend this format by adding
attributes to <v> and <t> elements:

- Extending the format of .leo files
- Attaching temporary attributes to vnodes and tnodes
- Recommended conventions for plugins

HTH.  I should probably review the existing documentation.  I would be glad
to answer any more questions you have here, or even better on Leo's
SourceForge forums.

Edward
--------------------------------------------------------------------
Edward K. Ream   email:  edreamleo at charter.net
Leo: Literate Editor with Outlines
Leo: http://webpages.charter.net/edreamleo/front.html
--------------------------------------------------------------------