Discussions
===========

All Discussions objects are basically the same.  You get a set of
options which are inherited from the parent or provided.

Discussions (version 1) is a strict hierarchy with views on this object.
Email messages (as per the python ``email`` module) are used as the
basis of all message object:  that is, each object should be
expressable as a set of headers and body.  Since email messages are
hierarchal, the organization makes sense

Discussion version 2 is planned to be a directed graph.

Core concepts:
 * events
 * people
 * moderation
 * policy


Events
------

The add_message event: this is the portal event for all messages going
through discussions.  This may be via 

 * email
 * web
 * command line

This could provide a front for twitter, RSS, or other discussions instances.


Roles and Permissions
---------------------

A member can be in one of three states with respect to a resource:  

 * administrator: has all rights over a resource except as set by
   above resources;  Administrators of the root ('/') resource are
   site administrators and have all rights.

 * members:  has permissions of a resource as dictated by the
   administrator (view, post, etc).  [different types of members?
   groups?  probably not]

 * non-members: if an agent isn't a member of a resource, they
   generally have lowest level priveleges.

Options and Configuration
-------------------------

Configuration options can be in one of three states:  unset, set, and locked (and
set + locked).  In
the case where the option is locked, all children inherit the setting
as well:

archive.lock = false

Locking an option prohibits any but a higher-level admin from
unlocking it.  The higher-level admin is free to change the setting:

archive.lock = false
archive = true

This locks the archive of subchildren into the false state, but sets
the archive for this discussion in the current discussion.

This prevents archiving on any sublist.  Messages to a list inherit
the list settings.

If an option is unset, it will use the settings of its parent, the
site defaults, or the application default, based on its type
(Forum or Discussion).


Members
-------

Preferences:

Member preferences can also be set from the site level.


Digest
------

Different templates can be used to display different digest methods.
For instance, you could display a brief form of the message with just
the links:

{{{
Example of .ini configuration:

[digest:daily]
template = /path/to/templates/daily-digest.txt

}}}

This can be used to facilitate a moderated digest.  Roundup emails can
be sent about a discussion written and editted by the moderator.


Hierarchy Example
-----------------

Both Forum and Conversation objects are MessageContainers.

/foo
 bar/--message 1
     |       |
     |       +-reply to message 1
     |       |      |
     |       |      \-"..."
     |       |
     |       \-"..."
     |
     +-message 2
     |
     \-message 3

URL for reply posting: /foo/<message id>/reply
(posts to /foo/<message id> )


Message Objects
---------------

{ 'headers': {},
  'messages': [ list, of, children ],
  'next':
  'previous':
  'parent': } 


Discussions -> Collaborative Documents
--------------------------------------

discussions presents a strict hierachal document that can only append
leaf nodes.  Collaborative documents (e.g. a wiki) may also be
hierachal, but additional functionality is implied:

 * the ability to edit nodes
 * the ability to merge nodes
 * the keeping of history (including all implied functionality of an VCS)