Improve docs for devs and high level overview

[sotte]

I was trying to implement the agenda feature (see #34) and I always got confused what document class is responsible for what and where I should store what.

The document class is in liborgmode; in document.py there are class VimBufferContent and class VimBuffer. They sound the almost the same but do different things and there is no docstring for VimBuffer. Some more docstrings would ease the development.

Also a high level overview of the architecture (I'm not talking about the diagramm), and an expanation of the debug flag would be nice too. We should put it under DEVELOPMENT in the helpfile.

[jceb]

Sorry that I didn't reply earlier. Regarding the agenda feature, I recommend the following - please feel free to correct me:
0. extend liborgmode/Heading to support dates
I'd say SCHEDULED, DEADLINE are the keywords

1. add an agenda class to liborgmode
   this class should contain all basic functionality to build an agenda
   an agenda is just a (flat) list of headings that belong to one or more documents
   this list can be sorted or filtered in various ways to allow the user to get the view port he wants
   the agenda class should not contain any highlevel UI code - all that UI stuff goes into a plugin
2. (optional, could be implemented later) add support for linked documents to liborgmode/Document.
3. implement/extend a plugin that does the job of displaying the agenda
   this includes a global variable that defines which org documents are included in the agenda
   it should do the job of allowing the user to narrow down the displayed headings

That's it.

Regarding VimBuffer and VimBufferContent, VimBuffer extends the liborgmode/Document. liborgmode/Document is just a general implementation for loading an org file. It has no interface to an actual file or vim buffer. This is the task of document.py/VimBuffer, it just interfaces with vim. The main tasks for VimBuffer are to provide read and write access to a vim buffer. (You are right, I should rename document.py to something like vimbuffer.py). VimBufferContent is a helper class for VimBuffer. Basically, it hides the details of encoding - everything read from or written to VimBufferContent is UTF-8.

I'll put it on my agenda to update the development documentation.