{Proposed Architecture of Annotation Subsystem, 17 June 1998}

<em>These are Sam Rebelsky's notes on a possible architecture for
the subsystem and are intended only as a contribution to a more
general discussion of the topics.</em>

There are a number of tasks we must consider as we develop the
annotation subsystem.
* Adding "annotation points" to a document.
* Putting anotations "on" the page (once the page, permissions,
  and annotations have been determined).
* Adding an annotation to a page.
* Adding a followup to an annotation.
* Modifying or deleting an annotation.

There are also a number of more global "administrative" functions that
we will leave until later.

The "entities" we need to worry about are:
* Sites (we may want to group pages to limit access, so that groups
  and users have more local control; then again we may not).
* Users
* Groups (each user may be in multiple groups)
* Pages
* Annotation points (each page may have multiple annotation points)
* Annotation trees (one per annotation point)
* Annotations (many per annotation point, but each annotation is
  for only one part of the document).

To automatically add annotation points to the document, we'll need to 
* Identify potential annotation points (we've decided that each
  heading is an appropriate level)
* Create a listing of the annotation points with accompanying text (and
  positional information), so that we may update this list later (we may
  also need to compare those to previous ones).
* Insert appropriate HTML.

Note that this can be done separately from (in fact, prior to) the expansion
of <code>&lt;annotation&gt;</code> tags.

To insert annotation tags, we will need to
* Identify user and groups.
* Identify an annotation tree for each annotation point in the
  document.  This may require us to update the text-to-point map
  (if, for example, we have an annotation tree with no associated
  point, or vice versa).
* Using groups, build a set of the viewable annotations.
* Add them to the document appropriately.  I'd suggest a call to the
  appropriate JavaScript function, but your mileage may vary.

To add annotations, we may need an annotation server (or script), which
will
* Check privs for the adding of the annotation
* Update appropriate files to add the annotation

We'll leave modification to a later day.