Hal Fulton wrote:
> In short: Tycho is a tool for managing random information
> in the form of "notes" arranged in a hierarchy of "topics."

Ok Hal, I've had a read of your API. I created an ORM model of it
in fact, using VisioModeler. That's ORM as in Object Role Model.
The reason I've taken an interest in this is because I believe that
such a tool can benefit strongly from an aspect-oriented data model,
more on that later.

> 1. Start with the API, test it heavily, worry about GUI later

Good move not starting on the GUI, but you need to start even further
back, with a conceptual data model. The API is then a simple consequence
of the data model.

>    NOTE: My latest scribblings on the API are really
>    where I'd like feedback at the moment.

You have a few bits of mixed terminology or terms used only once.
For example:
* I assume that "name" and "title" are the same thing?
* You also use the word "key" - again, is this "title" or
   is it a path in the data store?
* What's the significance of the "current" topic - is that just a
   presentation thing or does it affect searching? No other function
   seems to indicate that the current topic is relevant.
* What's the effect of "load"ing a topic of note?

Functionality questions:
* When you change the root topic of an app, what happens to all the
   now unreachable topics and notes? Is the change persistent? Perhaps
   you could replace this problematic operation with a simple "flip
   parent and child" operation?
* It isn't clear whether find_topic searches content or just titles.
* It seems that topics and notes differ only in that notes have content,
   which requires a different presentation, and in whether the metadata
   inherits (BTW, this isn't inheritance I believe, but propagation down
   the tree - is that right?).
   Why bother with the two things - instead you could simply load all
   items having no content as your tree.

Aspect orientation suggestion:
Your model has a number of different kinds of data value associated
with each note or topic. For example, you have info on date/time and
number of times accessed, modified, etc. You have GUI variables. You
have sorting and searching (keywords).

If you regard each item (topic/note) as having values for variables,
you can model the variables as pertaining to a relevant (meta-)topic.
So for example, you could have a Presentation topic, which contains a
Note sub-topic. The variables whose values define the presentation of
a note "belong" to the Note class, but "pertain" to the
Presentation/Note subtopic. I also allow Items to pertain to other
items.

In this way you provide for an arbitrary number of kinds of metadata,
while the model actually has very little actual *meta*data. The only
metadata you need is the "Item" class(es) and the Variable class(es).

Item has a title string, a parent Item, a superclass Item (e.g. Topic,
Note), an Item to which it "pertains" (which will often be its parent),
subitems, optional Variables, and optional values (for its variables
and for inherited ones).

Variable is also an item (each has the same), but its subclasses define
sub-Variables, for example "max-length" for a string, etc.

The API should allow fetching all values (including inherited and
propagated) of an item which *pertain to* the aspect of interest. So
for example the GUI will fetch values of all variables of items which
pertain to the Presentation topic. The searcher will fetch values of
different variables, and the object manager will access and update
values pertaining to access and modification times and counts. You can
also store user information (values for an item, and subitems) into
multiple aspects in the same way. It creates some interesting search
algorithms, but is a very powerful way to separate different kinds of
data and metadata.

Let me know if I haven't explained this adequately.

Clifford Heath.