On Thursday, January 9, 2014 10:55:32 AM UTC-6, Edward K. Ream wrote:
> For the last week the standing joke has been that the work will take
about another two hours :-)
Yesterday was a big step forward. A few details remain to resolve. These
could be called debugging items.
This post will be pre-writing for further documentation. It contains
important insights for both users and developers.
The symptom of the bugs is that *non-bare* organizer nodes are not placed
in correct sibling order. As you recall, the value of n in the main line,
demote_helper, matters only for *bare* organizer nodes. So the proximate
cause of the problem is that pending nodes aren't entered on the global
node list before entering the organizers.
As we shall see below, the more fundamental problem is that the code does
not fully account for the outline relationships between organizer nodes.
As a result, the existing code does not always open and close organizer
nodes properly. (An organizer node is open when it may accumulated
organized nodes; an organizer node is closed when it can no longer
accumulate organized nodes without changing the order of the nodes in the
@auto file.)
Two examples will illustrate the subtleties, and will lead naturally to a
new distinction, that of an **intermediate organizer** node.
Let's start with an easy case. Suppose the organizer structure is:
- @auto x.py
- leading nodes
- organizer A
- node 1
- organizer B
- node 2
- organizer C
- node 3
- organizer D
Clearly, the children of organizer A should be: node1, organizer B,
organizer C and node 3. That is, we must *not* close organizer A just
because we have entered organizer B or organizer C. Otoh, we *must* close
organizer A when we see organizer D.
The rule is clear: we must close an organizer whenever we see another
organizer that is not a descendant organizer.
The existing code creates parent/child data for OrganizerData instances.
It will be straightforward to add descendant relationships.
Let's consider another case:
- @auto x.py
- leading nodes
- organizer A
- organizer B
- organizer C
- node 1
Here, organizer B is an **intermediate organizer** node. That is, it
occurs "between" organizers A and C.
Adding node 1 to the global node list should open organizer B, but the
present code does not. The present code opens an organizer node only when
adding a node to the organizer, but this example shows that organizer B
must be added to the global node list *before* any node is added to it.
Failure to do so results in organizer B being put in the wrong place.
===== Organizer relationships are stable!
As I was thinking about the outline relationships between organizer nodes,
I began to worry that minor changes to the imported @auto file might break
those relationships. In fact, the reverse is true: the relationships
between organizer nodes are *independent* of the @auto file!
The reason is simple: those relationships are created by the unl's in
@organizer: nodes in the .leo file. Furthermore, reorganizing the *outline*
will automatically update the unls in the @organizer nodes (in the @views
node) when the outline is saved. Thus, the *relationships* between
organizer nodes can never be broken by changes to the @auto node! This is
really important for users to know.
And there is more good news. Changing the contents of the @auto files can
indeed change the contents of organizer nodes, but the only way to totally
invalidate an organizer node is to change the *structural* relationships of
data in the @auto file. This almost never happens!
For example, if aClass is defined at the top level of the @auto file, then
the only way to invalidate the organizers that contain aClass or its
members is to move aClass so it is not a top-level node. But Leo's
importers will put aClass at the top level unless it becomes a nested class
in some other class! To repeat, this kind massive change to the context of
a class, function or method almost never happens.
In short, the links between unls (in @organizer: nodes) and imported
classes, methods and functions almost never break! This is truly great
news.
===== Summary
The following bugs will be easy to fix today:
- demote_helper must keep organizer nodes open when handling descendant
organizer nodes.
- demote_helper must open all intermediate organizer nodes when opening
descendant organizer nodes.
- The unit tests must be sure to test intermediate nodes.
The following insights are important for users (and maintainers) to know:
- Changing an @auto file does not change the relationships between its
organizer nodes in any way.
- Saving an outline automatically updates the relationships between
organizer nodes.
- Unl's are much more stable than one might suppose: the *only* way to
"break" organizer nodes is to change the fundamental relationships of
classes, methods or functions in the imported @auto file. This almost
*never* happens.
That's all for now.
Edward
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/groups/opt_out.
