diff options
Diffstat (limited to 'devel-docs')
| -rw-r--r-- | devel-docs/.cvsignore | 3 | ||||
| -rw-r--r-- | devel-docs/Makefile.am | 3 | ||||
| -rw-r--r-- | devel-docs/camel/.cvsignore | 12 | ||||
| -rw-r--r-- | devel-docs/camel/Makefile.am | 101 | ||||
| -rw-r--r-- | devel-docs/camel/README_AND_TODO.txt | 43 | ||||
| -rw-r--r-- | devel-docs/camel/camel-docs.sgml | 28 | ||||
| -rw-r--r-- | devel-docs/camel/camel-sections.txt | 154 | ||||
| -rw-r--r-- | devel-docs/camel/camel.types | 9 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/.cvsignore | 2 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-data-wrapper.sgml | 26 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-folder.sgml | 96 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-mime-message.sgml | 171 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-mime-part.sgml | 151 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-recipient.sgml | 88 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-service.sgml | 72 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-store.sgml | 45 | ||||
| -rw-r--r-- | devel-docs/camel/tmpl/camel-stream.sgml | 101 | ||||
| -rw-r--r-- | devel-docs/misc/ref_and_id_proposition.txt | 237 | ||||
| -rw-r--r-- | devel-docs/query/virtual-folder-in-depth.sgml | 407 | ||||
| -rw-r--r-- | devel-docs/query/virtual-folder-in-depth.txt | 309 |
20 files changed, 0 insertions, 2058 deletions
diff --git a/devel-docs/.cvsignore b/devel-docs/.cvsignore deleted file mode 100644 index d436efd0f7..0000000000 --- a/devel-docs/.cvsignore +++ /dev/null @@ -1,3 +0,0 @@ -Makefile.in -Makefile - diff --git a/devel-docs/Makefile.am b/devel-docs/Makefile.am deleted file mode 100644 index 74a5ff5b60..0000000000 --- a/devel-docs/Makefile.am +++ /dev/null @@ -1,3 +0,0 @@ -## Process this file with automake to produce Makefile.in - -SUBDIRS=camel diff --git a/devel-docs/camel/.cvsignore b/devel-docs/camel/.cvsignore deleted file mode 100644 index 56d9506207..0000000000 --- a/devel-docs/camel/.cvsignore +++ /dev/null @@ -1,12 +0,0 @@ -sgml -html -Makefile.in -Makefile -camel.signals -camel.hierarchy -camel.args -camel-decl.txt -camel-unused.txt -camel.html -camel-decl-list.txt - diff --git a/devel-docs/camel/Makefile.am b/devel-docs/camel/Makefile.am deleted file mode 100644 index 276059cf88..0000000000 --- a/devel-docs/camel/Makefile.am +++ /dev/null @@ -1,101 +0,0 @@ -## Process this file with automake to produce Makefile.in - -# The name of the module. -DOC_MODULE=camel - -# The top-level SGML file. -DOC_MAIN_SGML_FILE=camel-docs.sgml - -# The directory containing the source code (if it contains documentation). -DOC_SOURCE_DIR=$(top_srcdir)/camel - -CFLAGS=`gtk-config --cflags gtk` -LDFLAGS="-lcamel `gtk-config --libs gtk` " - - -HTML_DIR=$(datadir)/gnome/html - - - -TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) - -tmpl_sources = \ - tmpl/camel-data-wrapper.sgml \ - tmpl/camel-folder.sgml \ - tmpl/camel-mime-message.sgml \ - tmpl/camel-mime-part.sgml \ - tmpl/camel-recipient.sgml \ - tmpl/camel-service.sgml \ - tmpl/camel-store.sgml \ - tmpl/camel-stream.sgml - - -camel_docdir = $(HTML_DIR) -camel_doc_DATA = \ - camel.html \ - camel.hierarchy \ - camel.types \ - camel-scan.c \ - camel-decl.txt \ - camel-sections.txt - -EXTRA_DIST = $(camel_doc_DATA) - -camel.html: html/book1.html - -cd $(srcdir) && cp html/book1.html camel.html - -html/book1.html: sgml/camel-doc.bottom - $(MAKE) html - -sgml/camel-doc.bottom: $(tmpl_sources) - $(MAKE) sgml - -camel-scan.c: - -scan: camel-scan.c - CFLAGS=$(CFLAGS) LDFLAGS=$(LDFLAGS) gtkdoc-scanobj --module=$(DOC_MODULE) - gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) - -templates: scan - gtkdoc-mktmpl --module=$(DOC_MODULE) - -sgml: - gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) - -html: - if ! test -d html ; then mkdir html ; fi - -cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) - -clean-local: - rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt camel.html - -maintainer-clean-local: clean - rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt Makefile.in - -install-data-local: - $(mkinstalldirs) $(TARGET_DIR) - (installfiles=`echo $(srcdir)/html/*.html`; \ - if test "$$installfiles" = '$(srcdir)/html/*.html'; \ - then echo '-- Nothing to install' ; \ - else \ - for i in $$installfiles; do \ - echo '-- Installing '$$i ; \ - $(INSTALL_DATA) $$i $(TARGET_DIR); \ - done; \ - echo '-- Installing $(srcdir)/html/index.sgml' ; \ - $(INSTALL_DATA) $(srcdir)/html/index.sgml $(TARGET_DIR); \ - echo '-- Fixing Crossreferences' ; \ - gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR)|| true; \ - fi) - -dist-hook: - mkdir $(distdir)/html - mkdir $(distdir)/sgml - mkdir $(distdir)/tmpl - -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html - -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl - -cp $(srcdir)/sgml/*.sgml $(distdir)/sgml - -cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml - - -.PHONY : html sgml templates scan diff --git a/devel-docs/camel/README_AND_TODO.txt b/devel-docs/camel/README_AND_TODO.txt deleted file mode 100644 index 5feeb1e4e9..0000000000 --- a/devel-docs/camel/README_AND_TODO.txt +++ /dev/null @@ -1,43 +0,0 @@ -Camel is currently (conceptualy) separated in four parts: - -* the session handling -* the storage mechanism. -* the (mime) message handling. -* some general utilities class/functions. - - - -* Session handling ------------------- - -(This is not gnome session managing related) -CamelSession is an object used to store some parameters on a user -basis. This can be a permanent (fs based) or volatile -(ram only) storage depending on user preferences. -The session object is, for example, responsible for -remembering authentication datas during application lifetime. -It is also responsible for selecting and loading providers -corresponding to protocols. In the case where only one -provider exists for a given protocol, the task is trivial, -but when multiple providers exist for a given protocol, the -user can choose their prefered one. Given its relationship -with providers, the session object is also used to instanciate -a store given an URL. - -Associated Classes: - CamelSession - implementation: 5% - -Associated Files: - camel-provider.[ch] - implementation: 2.5% (a struct in camel-provider.h) - - -* the storage mechanism. ------------------------- - -The storage mechanism is mainly represented by -the Store class and the Folder class. -* the (mime) message handling. -* some general utilities class/functions. - diff --git a/devel-docs/camel/camel-docs.sgml b/devel-docs/camel/camel-docs.sgml deleted file mode 100644 index 33c6623731..0000000000 --- a/devel-docs/camel/camel-docs.sgml +++ /dev/null @@ -1,28 +0,0 @@ -<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ -<!entity CamelDataWrapper SYSTEM "sgml/camel-data-wrapper.sgml"> -<!entity CamelFolder SYSTEM "sgml/camel-folder.sgml"> -<!entity CamelMimeMessage SYSTEM "sgml/camel-mime-message.sgml"> -<!entity CamelMimePart SYSTEM "sgml/camel-mime-part.sgml"> -<!entity CamelRecipient SYSTEM "sgml/camel-recipient.sgml"> -<!entity CamelService SYSTEM "sgml/camel-service.sgml"> -<!entity CamelStore SYSTEM "sgml/camel-store.sgml"> -<!entity CamelStream SYSTEM "sgml/camel-stream.sgml"> -]> - -<book> - <bookinfo> - <title>Camel Messaging Library Reference Manual</title> - </bookinfo> - - <chapter id="camel-objects"> - <title>Camel Objects</title> - &CamelMimeMessage; - &CamelService; - &CamelStore; - &CamelFolder; - &CamelMimePart; - &CamelDataWrapper; - &CamelRecipient; - - </chapter> -</book> diff --git a/devel-docs/camel/camel-sections.txt b/devel-docs/camel/camel-sections.txt deleted file mode 100644 index 1f6d45c03c..0000000000 --- a/devel-docs/camel/camel-sections.txt +++ /dev/null @@ -1,154 +0,0 @@ - -<INCLUDE>gnome.h</INCLUDE> -<INCLUDE>camel-data-wrapper.h</INCLUDE> - - -<SECTION> -<FILE>camel-data-wrapper</FILE> -CamelDataWrapper -<TITLE>CamelDataWrapper</TITLE> -camel_data_wrapper_write_to_stream -<SUBSECTION Standard> -CAMEL_DATA_WRAPPER -camel_data_wrapper_get_type -CAMEL_DATA_WRAPPER_CLASS -</SECTION> - -<SECTION> -<FILE>camel-recipient</FILE> -CamelRecipientTable -<TITLE>CamelRecipientTable</TITLE> -camel_recipient_table_new -camel_recipient_table_get -camel_recipient_table_add -camel_recipient_table_add_list -camel_recipient_table_remove -camel_recipient_table_ref -camel_recipient_table_unref -</SECTION> - -<SECTION> -<FILE>camel-mime-part</FILE> -CamelMimePart -<TITLE>CamelMimePart</TITLE> -camel_mime_part_add_header -camel_mime_part_set_content_object -camel_mime_part_set_filename -camel_mime_part_get_disposition -camel_mime_part_get_content_MD5 -camel_mime_part_get_encoding -camel_mime_part_set_header_lines -camel_mime_part_get_content_object -camel_mime_part_get_content_id -camel_mime_part_set_description -camel_mime_part_set_text -camel_mime_part_set_encoding -camel_mime_part_set_disposition -camel_mime_part_remove_header -camel_mime_part_get_filename -camel_mime_part_get_content_languages -camel_mime_part_set_content_languages -camel_mime_part_get_header_lines -camel_mime_part_get_description -camel_mime_part_get_header -<SUBSECTION Standard> -CAMEL_MIME_PART -camel_mime_part_get_type -CAMEL_MIME_PART_CLASS -</SECTION> - - - -<SECTION> -<FILE>camel-mime-message</FILE> -CamelMimeMessage -<TITLE>CamelMimeMessage</TITLE> -camel_mime_message_remove_recipient -camel_mime_message_get_recipients -camel_mime_message_set_flag -camel_mime_message_set_subject -camel_mime_message_get_reply_to -camel_mime_message_get_from -camel_mime_message_set_reply_to -camel_mime_message_get_sent_date -camel_mime_message_new_with_session -camel_mime_message_add_recipient -camel_mime_message_get_subject -camel_mime_message_set_from -camel_mime_message_get_flag -camel_mime_message_get_message_number -camel_mime_message_get_received_date -camel_mime_message_set_received_date -<SUBSECTION Standard> -CAMEL_MIME_MESSAGE -camel_mime_message_get_type -CAMEL_MIME_MESSAGE_CLASS -</SECTION> - - -<SECTION> -<FILE>camel-folder</FILE> -CamelFolder -<TITLE>CamelFolder</TITLE> -camel_folder_get_folder -camel_folder_create -camel_folder_delete -camel_folder_delete_messages -camel_folder_get_parent_folder -camel_folder_get_parent_store -camel_folder_get_mode -camel_folder_list_subfolders -<SUBSECTION Standard> -CAMEL_FOLDER -camel_folder_get_type -CAMEL_FOLDER_CLASS -</SECTION> - -<SECTION> -<FILE>camel-service</FILE> -CamelService -<TITLE>CamelService</TITLE> -camel_service_connect -camel_service_is_connected -camel_service_connect_to_with_login_passwd -camel_service_connect_to_with_login_passwd_port -camel_service_get_url -<SUBSECTION Standard> -CAMEL_SERVICE -camel_service_get_type -CAMEL_SERVICE_CLASS -</SECTION> - -<SECTION> -<FILE>camel-store</FILE> -CamelStore -<TITLE>CamelStore</TITLE> -camel_store_get_separator -camel_store_get_folder -<SUBSECTION Standard> -CAMEL_STORE -camel_store_get_type -CAMEL_STORE_CLASS -</SECTION> - - -<SECTION> -<FILE>camel-stream</FILE> -CamelStream -<TITLE>CamelStream</TITLE> -camel_stream_seek -camel_stream_write -camel_stream_flush -camel_stream_eos -camel_stream_write_string -camel_stream_close -camel_stream_write_strings -camel_stream_read -camel_stream_available -<SUBSECTION Standard> -CAMEL_STREAM -camel_stream_get_type -CAMEL_STREAM_CLASS -</SECTION> - - diff --git a/devel-docs/camel/camel.types b/devel-docs/camel/camel.types deleted file mode 100644 index 93142d8692..0000000000 --- a/devel-docs/camel/camel.types +++ /dev/null @@ -1,9 +0,0 @@ -#include <gtk/gtk.h> -#include <camel/camel-data-wrapper.h> -camel_data_wrapper_get_type -camel_folder_get_type -camel_mime_message_get_type -camel_mime_part_get_type -camel_service_get_type -camel_store_get_type -camel_stream_get_type diff --git a/devel-docs/camel/tmpl/.cvsignore b/devel-docs/camel/tmpl/.cvsignore deleted file mode 100644 index 29db8d052d..0000000000 --- a/devel-docs/camel/tmpl/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -camel-unused.sgml - diff --git a/devel-docs/camel/tmpl/camel-data-wrapper.sgml b/devel-docs/camel/tmpl/camel-data-wrapper.sgml deleted file mode 100644 index 6fce9eb128..0000000000 --- a/devel-docs/camel/tmpl/camel-data-wrapper.sgml +++ /dev/null @@ -1,26 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelDataWrapper - -<!-- ##### SECTION Short_Description ##### --> -data container with streaming methods - -<!-- ##### SECTION Long_Description ##### --> -<para> -A CamelDataWrapper is wrapper around data which can save them to a stream -and restore them from a stream. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### FUNCTION camel_data_wrapper_write_to_stream ##### --> -<para> - -</para> - -@data_wrapper: -@stream: - - diff --git a/devel-docs/camel/tmpl/camel-folder.sgml b/devel-docs/camel/tmpl/camel-folder.sgml deleted file mode 100644 index 882d63499c..0000000000 --- a/devel-docs/camel/tmpl/camel-folder.sgml +++ /dev/null @@ -1,96 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelFolder - -<!-- ##### SECTION Short_Description ##### --> -Represents a folder of messages on a store. - -<!-- ##### SECTION Long_Description ##### --> -<para> -CamelFolder represents a folder in a message store. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### STRUCT CamelFolder ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION camel_folder_get_folder ##### --> -<para> - -</para> - -@folder: -@folder_name: -@Returns: - - -<!-- ##### FUNCTION camel_folder_create ##### --> -<para> - -</para> - -@folder: -@Returns: - - -<!-- ##### FUNCTION camel_folder_delete ##### --> -<para> - -</para> - -@folder: -@recurse: -@Returns: - - -<!-- ##### FUNCTION camel_folder_delete_messages ##### --> -<para> - -</para> - -@folder: -@Returns: - - -<!-- ##### FUNCTION camel_folder_get_parent_folder ##### --> -<para> - -</para> - -@folder: -@Returns: - - -<!-- ##### FUNCTION camel_folder_get_parent_store ##### --> -<para> - -</para> - -@folder: -@Returns: - - -<!-- ##### FUNCTION camel_folder_get_mode ##### --> -<para> - -</para> - -@folder: -@Returns: - - -<!-- ##### FUNCTION camel_folder_list_subfolders ##### --> -<para> - -</para> - -@folder: -@Returns: - - diff --git a/devel-docs/camel/tmpl/camel-mime-message.sgml b/devel-docs/camel/tmpl/camel-mime-message.sgml deleted file mode 100644 index 704f3d3572..0000000000 --- a/devel-docs/camel/tmpl/camel-mime-message.sgml +++ /dev/null @@ -1,171 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelMimeMessage - -<!-- ##### SECTION Short_Description ##### --> - - -<!-- ##### SECTION Long_Description ##### --> -<para> - -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### STRUCT CamelMimeMessage ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION camel_mime_message_remove_recipient ##### --> -<para> - -</para> - -@mime_message: -@recipient_type: -@recipient: - - -<!-- ##### FUNCTION camel_mime_message_get_recipients ##### --> -<para> - -</para> - -@mime_message: -@recipient_type: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_set_flag ##### --> -<para> - -</para> - -@mime_message: -@flag: -@value: - - -<!-- ##### FUNCTION camel_mime_message_set_subject ##### --> -<para> - -</para> - -@mime_message: -@subject: - - -<!-- ##### FUNCTION camel_mime_message_get_reply_to ##### --> -<para> - -</para> - -@mime_message: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_get_from ##### --> -<para> - -</para> - -@mime_message: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_set_reply_to ##### --> -<para> - -</para> - -@mime_message: -@reply_to: - - -<!-- ##### FUNCTION camel_mime_message_get_sent_date ##### --> -<para> - -</para> - -@mime_message: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_new_with_session ##### --> -<para> - -</para> - -@session: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_add_recipient ##### --> -<para> - -</para> - -@mime_message: -@recipient_type: -@recipient: - - -<!-- ##### FUNCTION camel_mime_message_get_subject ##### --> -<para> - -</para> - -@mime_message: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_set_from ##### --> -<para> - -</para> - -@mime_message: -@from: - - -<!-- ##### FUNCTION camel_mime_message_get_flag ##### --> -<para> - -</para> - -@mime_message: -@flag: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_get_message_number ##### --> -<para> - -</para> - -@mime_message: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_get_received_date ##### --> -<para> - -</para> - -@mime_message: -@Returns: - - -<!-- ##### FUNCTION camel_mime_message_set_received_date ##### --> -<para> - -</para> - -@mime_message: -@received_date: - - diff --git a/devel-docs/camel/tmpl/camel-mime-part.sgml b/devel-docs/camel/tmpl/camel-mime-part.sgml deleted file mode 100644 index 2db158b25f..0000000000 --- a/devel-docs/camel/tmpl/camel-mime-part.sgml +++ /dev/null @@ -1,151 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelMimePart - -<!-- ##### SECTION Short_Description ##### --> - - -<!-- ##### SECTION Long_Description ##### --> -<para> - -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### FUNCTION camel_mime_part_set_filename ##### --> -<para> - -</para> - -@mime_part: -@filename: - - -<!-- ##### FUNCTION camel_mime_part_get_disposition ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - -<!-- ##### FUNCTION camel_mime_part_get_content_MD5 ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - -<!-- ##### FUNCTION camel_mime_part_get_encoding ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - -<!-- ##### FUNCTION camel_mime_part_set_header_lines ##### --> -<para> - -</para> - -@mime_part: -@header_lines: - - -<!-- ##### FUNCTION camel_mime_part_get_content_id ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - -<!-- ##### FUNCTION camel_mime_part_set_description ##### --> -<para> - -</para> - -@mime_part: -@description: - - -<!-- ##### FUNCTION camel_mime_part_set_text ##### --> -<para> - -</para> - -@camel_mime_part: -@text: - - -<!-- ##### FUNCTION camel_mime_part_set_encoding ##### --> -<para> - -</para> - -@mime_part: -@encoding: - - -<!-- ##### FUNCTION camel_mime_part_set_disposition ##### --> -<para> - -</para> - -@mime_part: -@disposition: - - -<!-- ##### FUNCTION camel_mime_part_get_filename ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - -<!-- ##### FUNCTION camel_mime_part_get_content_languages ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - -<!-- ##### FUNCTION camel_mime_part_set_content_languages ##### --> -<para> - -</para> - -@mime_part: -@content_languages: - - -<!-- ##### FUNCTION camel_mime_part_get_header_lines ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - -<!-- ##### FUNCTION camel_mime_part_get_description ##### --> -<para> - -</para> - -@mime_part: -@Returns: - - diff --git a/devel-docs/camel/tmpl/camel-recipient.sgml b/devel-docs/camel/tmpl/camel-recipient.sgml deleted file mode 100644 index 4af84cf58e..0000000000 --- a/devel-docs/camel/tmpl/camel-recipient.sgml +++ /dev/null @@ -1,88 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelRecipientTable - -<!-- ##### SECTION Short_Description ##### --> - - -<!-- ##### SECTION Long_Description ##### --> -<para> - -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### STRUCT CamelRecipientTable ##### --> -<para> - -</para> - -@recipient_hash_table: -@ref_count: - -<!-- ##### FUNCTION camel_recipient_table_new ##### --> -<para> - -</para> - -@Returns: - - -<!-- ##### FUNCTION camel_recipient_table_unref ##### --> -<para> - -</para> - -@recipient_table: - - -<!-- ##### FUNCTION camel_recipient_table_get ##### --> -<para> - -</para> - -@recipient_table: -@recipient_type: -@Returns: - - -<!-- ##### FUNCTION camel_recipient_table_add ##### --> -<para> - -</para> - -@recipient_table: -@recipient_type: -@recipient: - - -<!-- ##### FUNCTION camel_recipient_table_remove ##### --> -<para> - -</para> - -@recipient_table: -@recipient_type: -@recipient: - - -<!-- ##### FUNCTION camel_recipient_table_add_list ##### --> -<para> - -</para> - -@recipient_table: -@recipient_type: -@recipient_list: - - -<!-- ##### FUNCTION camel_recipient_table_ref ##### --> -<para> - -</para> - -@recipient_table: - - diff --git a/devel-docs/camel/tmpl/camel-service.sgml b/devel-docs/camel/tmpl/camel-service.sgml deleted file mode 100644 index 5b51ea902e..0000000000 --- a/devel-docs/camel/tmpl/camel-service.sgml +++ /dev/null @@ -1,72 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelService - -<!-- ##### SECTION Short_Description ##### --> - - -<!-- ##### SECTION Long_Description ##### --> -<para> - -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### STRUCT CamelService ##### --> -<para> - -</para> - -@e: - -<!-- ##### FUNCTION camel_service_connect ##### --> -<para> - -</para> - -@service: - - -<!-- ##### FUNCTION camel_service_is_connected ##### --> -<para> - -</para> - -@service: -@Returns: - - -<!-- ##### FUNCTION camel_service_connect_to_with_login_passwd ##### --> -<para> - -</para> - -@service: -@host: -@login: -@passwd: - - -<!-- ##### FUNCTION camel_service_connect_to_with_login_passwd_port ##### --> -<para> - -</para> - -@service: -@host: -@login: -@passwd: -@port: - - -<!-- ##### FUNCTION camel_service_get_url ##### --> -<para> - -</para> - -@service: -@Returns: - - diff --git a/devel-docs/camel/tmpl/camel-store.sgml b/devel-docs/camel/tmpl/camel-store.sgml deleted file mode 100644 index 2882c09986..0000000000 --- a/devel-docs/camel/tmpl/camel-store.sgml +++ /dev/null @@ -1,45 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelStore - -<!-- ##### SECTION Short_Description ##### --> - -A class representing a message (local or distant) repository - -<!-- ##### SECTION Long_Description ##### --> -<para> -The store class models a place where messages can be stored and retreived. It can be a local -store (for example an mbox-style store) or a distant server (for example an POP3 server). Messages are -not retreived or stored directly with a CamelStore object. Instead, a CamelFolder object must be -obtained from the store first. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### STRUCT CamelStore ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION camel_store_get_separator ##### --> -<para> - -</para> - -@store: -@Returns: - - -<!-- ##### FUNCTION camel_store_get_folder ##### --> -<para> - -</para> - -@store: -@folder_name: -@Returns: - - diff --git a/devel-docs/camel/tmpl/camel-stream.sgml b/devel-docs/camel/tmpl/camel-stream.sgml deleted file mode 100644 index e965db2e45..0000000000 --- a/devel-docs/camel/tmpl/camel-stream.sgml +++ /dev/null @@ -1,101 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CamelStream - -<!-- ##### SECTION Short_Description ##### --> - - -<!-- ##### SECTION Long_Description ##### --> -<para> - -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### FUNCTION camel_stream_seek ##### --> -<para> - -</para> - -@stream: -@offset: -@policy: -@Returns: - - -<!-- ##### FUNCTION camel_stream_write ##### --> -<para> - -</para> - -@stream: -@buffer: -@n: -@Returns: - - -<!-- ##### FUNCTION camel_stream_flush ##### --> -<para> - -</para> - -@stream: - - -<!-- ##### FUNCTION camel_stream_eos ##### --> -<para> - -</para> - -@stream: -@Returns: - - -<!-- ##### MACRO camel_stream_write_string ##### --> -<para> - -</para> - -@stream: -@string: - - -<!-- ##### FUNCTION camel_stream_close ##### --> -<para> - -</para> - -@stream: - - -<!-- ##### FUNCTION camel_stream_write_strings ##### --> -<para> - -</para> - -@stream: -@Varargs: - - -<!-- ##### FUNCTION camel_stream_read ##### --> -<para> - -</para> - -@stream: -@buffer: -@n: -@Returns: - - -<!-- ##### FUNCTION camel_stream_available ##### --> -<para> - -</para> - -@stream: -@Returns: - - diff --git a/devel-docs/misc/ref_and_id_proposition.txt b/devel-docs/misc/ref_and_id_proposition.txt deleted file mode 100644 index 2127b45a57..0000000000 --- a/devel-docs/misc/ref_and_id_proposition.txt +++ /dev/null @@ -1,237 +0,0 @@ -Author: Bertrand Guiheneuf <Bertrand.Guiheneuf@aful.org> -Date: August 9th 1999 -Last revision date : September 3rd 1999 -Version: 0.2 - -The last version of this document is always available in gnome CVS in -the gnome-mailer module: devel-docs/misc/ref_and_id_proposition.txt - - - -A) Identifying messages within folders --------------------------------------- - -Currently, in Camel there is only one way to retrieve a message from a -mail store: - CamelMimeMessage * - get_message (CamelFolder *folder, gint number) - -where number is an integer representing the message rank within its -parent folder. - -This is a traditional method (JavaMail, MAPI) and it is very useful -because this is often the only way to get a message in from a -classical store (pop3 for example). - -Moreover, various documents ([1], [2]) proposed to generalize the URL -scheme used in Camel ([3]) to access mail stores in order to identify -messages. Such an URL would be, for instance: - -pop3://po.myisp.com:1 - -Meaning: "Access message 1 on Pop3 server po.myisp.com" - - -However, referencing a message with its number within a folder is a -very unreliable method: - -1) Message order in a folder can change during a session: - - The user can move or remove messages from the folder, thus - completely changing message numbers. We could however imagine to - follow message operations in order to keep camel in a coherent - state at each time instant. This could be quite complex but may - be feasible using gtk signal system. - -2) Message order can change between sessions: - - Gnome-mailer was designed from the begining to allow messages to be - stored in classical mailboxes (mbox, maildir, MH, IMAP ...), in - order to allow users to run other MUA on their mailboxes if - necessary. These other MUA can change message order within folders - without any chance for Camel to trace the operations. - -These two scenarii show that it is quite impossible to use reliable -folder caching or message referencing if messages are referenced only -by their position within their parent folder. - - -We thus have to find a general way to identify and retreive a message -within its folder. One thing is sure, however: all folders -implementation won't allow this method. Pop3 stores will always access -messages using their rank on the server. MUA using Camel will thus -have to be prepared to access some stores providing only the old -fashionned message number access method. - -Basically, we have two choices: - -1) Accessing messages using (mailbox) Unique ID (UID) - - A UID is a string identifier associated to a message, which is - guaranteed to be unique within its parent folder and which will not - change between sessions. - -2) Accessing messages using Message ID - - A Message ID is a string identifier associated to a messages which - is guaranteed to be unique in the world, that is, no other message - can have the same Message ID. The message ID is defined in RFC 822, - and is stored as the message header "Message-id" - -Method (1) already exists in IMAP. -It is quite simple to define on local stores (MH, mbox, ....) but it -may not resist to message modification by other MUA. -Methods based on Message-id matching or message content checksum seem -to be the best one. Using an "X-" header is another possibility for -non read-only folders. A combination of these three methods may be the -most reliable solution. -The UID is impossible to implement in a POP3 store provider. - -(2) Can be used with IMAP, but would be very ineficient. -The main issue with this method is its dependancy upon other MUAs and -MTAs. Message-id is set before or during message transport. Moreover, -some rfc822 compliant messages may not even have any Message-id -header. -These are major issues when accessing read-only stores. -The M-ID is also impossible to implement in a POP3 store provider. - - -We may not rely on external MUA and MTA to guarentee the uniqueness of -the identifier . We may loose messages by never being able to read them -if two had the same uid. It would be possible to find workarounds, but -it could make Camel use a bit tricky. - -Given that most users will use IMAP or a database based store as their -main mail store, and given that this stores allow UID very -easily, I suggest that we use method (1). Discussion is still open, -though. - -Here are the public methods I propose to add to CamelFolder: - -gboolean camel_folder_supports_uid (CamelFolder *folder) - returns true if the folder can get messages - by their uid. - -gchar * camel_folder_get_uid_by_number (CamelFolder *folder, gint message_number) - return the uid of message which number in the folder - is %message_number. - -gchar * camel_folder_get_message_uid (CamelFolder *folder, CamelMimeMessage *message) - return the uid of the message within the folder. - -CamelMimeMessage *camel_folder_get_message_by_uid (CamelFolder *folder, gchar *uid) - return the message which uid is %uid - -In addition, the CamelMessage Class will have a new public method - -gchar * camel_mime_message_get_uid (CamelMimeMessage *message) - return the uid associated to the message in its physical parent - folder. - - - -B) Handling message references in (v)folders. ---------------------------------------------- - - -We want the future Gnome mailer to be able to build (virtual) folders -holding references to messages physically located in other -folders. More generally, we would like folders to be able to hold: - -1) messages -2) subfolders -3) references to messages - -(1) and (2) are already implemented in Camel because most mail stores -can hold messages and/or subfolders. - -(3) is a different issue, because no existing mail store can currently -hold, within folders, references to messages in other folders. -It will thus be a specific gnome-mailer extension. - - -One of the main issue is to determine what kind of behaviour we expect -from folders holding references. Here is a possible API. - -( the world (v)folder is used to distinguish between the physical -parent folder and the folder holding a reference to the message, when -a confusion may arise) - -Addition to CamelFolder: - -gboolean camel_folder_can_hold_references (CamelFolder *folder) - return true if the folder can contain references - -void camel_folder_add_reference_by_uid (CamelFolder *folder, gchar *folder_url, gchar *message_uid) - add a reference into a folder. %folder_url is the url of - the folder, %message_uid is the uid of the message within - its physical parent folder. - -void camel_folder_add_reference_by_message (CamelFolder *folder, CamelMessage *message) - add a reference. The place where the reference points - to is found using CamelMessage methods - -void camel_folder_remove_reference_by_uid (CamelFolder *folder, gchar *uid) - remove a message reference form a folder. Reference - is identified using its uid within the folder. - -gboolean camel_folder_uid_is_reference (CamelFolder *folder, gchar *uid) - return true if the message corresponding to the uid is a reference. - -Then all usual operations on the folder act if the message was -actually physically stored in this folder. For example, when the mailer -uses camel_folder_get_message_by_uid onto the (v)folder, the actual -message is retreived from its physical store. - -As you can see, the uid of the message within its physical parent -folder is different than its uid within the (v)folder. This is because -there is no way to guarantee that the uids of two messages in two -different folders would be different. Using references on this two -message in the same vfolder would break uniqueness of the uid in the -(v)folder. - -A couple of other methods could be defined but all the basics are -described here. - -This draft API is far from complete nor perfect, and is described here -only to stimulate discussions before the actual implementation. - - -The question now is to know how we store references. There are basically -two ways: - -1) references are stored using the URL of the physical folder - and the uid of the message within the folder - -2) a list of reference is kept, and in this list, reference are stored -as in (1). Folders would refer to the actual message using index in -the list - - - -The main problem with (1) is that references get lost as soon -as the actual message is moved. There is no way to find in which -folders references to the message exist. - -(2) is a way to solve this issue. When messages are used, Camel looks -in the list to see if the message is refered somewhere, and actualize -the URL and the uid with their new values. - -The problem with (2) is that we need to keep this information in a file -and libraries writing automatically to files are generally a bad idea. - -As in additional remark, it is clear that Camel will only be able to -hold references to messages on stores supporting UIDs. - - -Thanks in advance for your comments and ideas, - - - Bertrand <Bertrand.Guiheneuf@aful.org> - - --- - -[1] : http://www.selequa.com/%7epurp/gnomail/mail2db.html -[2] : http://www.selequa.com/%7epurp/gnomail/dbRecFmt.html -[3] : http://www.gnome.org/mailing-lists/archives/gnome-mailer-list/1999-April/0248.shtml diff --git a/devel-docs/query/virtual-folder-in-depth.sgml b/devel-docs/query/virtual-folder-in-depth.sgml deleted file mode 100644 index d3e3e0504b..0000000000 --- a/devel-docs/query/virtual-folder-in-depth.sgml +++ /dev/null @@ -1,407 +0,0 @@ -<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" []> - -<!-- SGMLized by Bertrand <Bertrand.Guiheneuf@aful.org> --> - -<article id="index"> - <artheader> - <authorgroup> - <author> - <firstname>Giao</firstname> - <surname>Nguyen</surname> - </author> - </authorgroup> - - <title>An in-depth look at the virtual folder mechanism</title> - <abstract> - <para> - This document describes a different way of approaching mail - organization and how all things are possible in this brave new - world. This document does not describe physical storage issues - nor interface issues. - </para> - <para> - Historically mail has been organized into folders. These - folders usually mapped to a single storage medium. The - relationship between mail organization and storage medium was - one to one. There was one mail organization for every storage - medium. This scheme had its limitations. - </para> - <para> - Efforts at categorizations are only meaningful at the instance that - one categorized. To find any piece of data, regardless of how well - it was categorized, required some amount of searching. Therefore, any - attempts to nullify searching is doomed to fail. It's time to embrace - searching as a way of life. - </para> - <para> - These are the terms and their definitions. The example rules used are - based on the syntax for VM (http://www.wonderworks.com/vm/) by Kyle - Jones whose ideas form the basis for this. I'm only adding the - existence of summary files to aid in scaling. I currently use VM and - it's virtual-folder rules for my daily mail purposes. To date, my only - complaints are speed (it has no caches) and for the unitiated, it's - not very user-friendly. - </para> - <para> - Comments, questions, rants, etc. should be directed at Giao Nguyen - (grail@cafebabe.org) who will try to address issues in a timely - manner. - </para> - </abstract> - </artheader> - - <!-- Definitions --> - <sect1 id="definitions"> - <title>Definitions</title> - <sect2> - <title>Store</title> - <para> - A location where mail can be found. This may be a file (Berkeley - mbox), directory (MH), IMAP server, POP3 server, Exchange server, - Lotus Notes server, a stack of Post-Its by your monitor fed through - some OCR system. - </para> - </sect2> - - <sect2> - <title>Message</title> - <para> - An individual mail message. - </para> - </sect2> - <sect2> - <title>Vfolder</title> - <para> - A group of messages sharing some commonality. This is the result of a - query. The vfolder maybe contained in a store, but it is not necessary - that a store holds only one vfolder. There is always an implicit - vfolder rule which matches all messages. A store contains the vfolder - which is the result of the query (any). It's short for virtual folder - or maybe view folder. I dunno. - </para> - </sect2> - <sect2> - <title>Default-vfolder</title> - <para> - The vfolder defined by (any) applied to the store. This is not the - inbox. The inbox could easily be defined by a query. A default rule - for the inbox could be (new) but it doesn't have to be. Mine happens - to be (or (unread) (new)). - </para> - </sect2> - <sect2> - <title>Folder</title> - <para> - The classical mail folder approach: one message organization per - store. - </para> - </sect2> - <sect2> - <title>Query</title> - <para> - A search for messages. The result of this is a vfolder. There are two - kinds of queries: named queries and lambda queries. More on this - later. - </para> - </sect2> - <sect2> - <title>Summary file </title> - <para> - An external file that contains pointers to messages which are matches - for a named query. In addition to pointers, the summary file should - also contain signatures of the store for sanity checks. When the term - "index" is used as a verb, it means to build a summary file for a - given name-value pair. - </para> - </sect2> - </sect1> - - <!-- Queries --> - <sect1> - <title>Queries</title> - <para> - Named queries are analogous to classical mail folders. Because named - queries maybe reused, summary files are kept as caches to reduce - the overall cost of viewing a vfolder. Summary files are superior to - folders in that they allow for the same messages to appear in multiple - vfolders without message duplications. Duplications of messages - defeats attempts at tagging a message with additional user information - like annotations. Named queries will define folders. - </para> - <para> - Lambda queries are similar to named queries except that they have no - name. These are created on the fly by the user to filter out or - include certain messages. - </para> - <para> - All queries can be layered on top of each other. A lambda query can be - layered on a named query and a named query can be layered on a lambda - query. The possibilities are endless. - </para> - <para> - The layerings can be done as boolean operations (and, or, not). Short - circuiting should be used. - </para> - <para> - Examples: - <programlisting> -(and (author "Giao") - (unread)) - </programlisting> - The (unread) query should only be evaluated on the results of (author - "Giao"). - <programlisting> -(or (author "Giao") - (unread)) - </programlisting> - Both of these queries should be evaluated. Any matches are added to the - resulting vfolder. - </para> - </sect1> - - <!-- Summary files --> - <sect1> - <title>Summary files</title> - <para> - Summary files are only meaningful when applied to the context of the - default-vfolder of a store. - </para> - <para> - Summary files should be generated for queries of the form: - <programlisting> -(function "constant value") - </programlisting> - Summary files should never be generated for queries of the form: - <programlisting> - (function (function1)) - - (and (function "value") - (another-function "another value")) - </programlisting> - Given a query of the form: - <programlisting> - (and (function "value") - (another-function "another value")) - </programlisting> - The system should use one summary file for (function "value") and - another summary file for (another-function "another value"). I will - call the prior form the "plain form". - </para> - <para> - It should be noted that the signature of the store should be based on - the assumption that new data may have been added to the store since - the application generated the summary file. Signatures generated on - the entirety of the store will most likely be meaningless for things - like POP/IMAP servers. - </para> - </sect1> - - <!-- Incremental Indexing --> - <sect1> - <title>Incremental indexing</title> - <para> - When new messages are detected, all known queries should be evaluated - on the new messages. vfolders should be notified of new messages that - are positive matches for their queries. The indexes generated by this - process should be merged into the current indexes for the vfolder. - </para> - </sect1> - - <!-- Can I have multiple stores --> - <sect1> - <title>Can I have multiple stores?</title> - <para> - I don't see why not. Again, the inbox is a vfolder so you can get a - unified inbox consisting of all new mail sent to all your stores or - your can get inboxes for each store or any combination your heart - desire. You get your cake, eat it, and someone else cleans the dishes! - </para> - </sect1> - - <!-- Why all this? --> - <sect1> - <title>Why all this?</title> - <para> - Consider the dynamic nature of the following query: - <programlisting> -(and (author "Giao") - (sent-after (today-midnight))) - </programlisting> - today-midnight would be a function that is evaluated at run-time to - calculate the appropriate object. - </para> - </sect1> - - <!-- Scenarios of usage and their solutions --> - <sect1> - <title>Scenarios of usage and their solutions</title> - <sect2> - <title>Mesage alterations</title> - <para> - This is a fuzzy area that should be left to the UI to handle. Messages - are altered. Read status are altered when a new message is read for - example. How do we handle this if our query is for unread messages? - Upon viewing the state would change. - </para> - <para> - One idea is to not evaluate the queries unless we're changing between - vfolder views. This assumes that one can only view a particular - vfolder at a time. For multi-vfolder viewing, a message change should - propagate through the vfolder system. Certain effects (as in our - example) would not be intuitive. - </para> - <para> - It would not be a clean solution to make special cases but they may be - necessary where certain defined fields are ignored when they are - changed. Some combination of the above rules can be used. I don't - think it's an easy solution. - </para> - </sect2> - <sect2> - <title>Message inclusion and exclusion</title> - <para> - Messages are included and excluded also with queries. The final query - will have the form of: - <programlisting> - (and (author "Giao") - (criteria value) - (not (criteria other-value))) - </programlisting> - Userland criterias may be a label of some sort. These may be userland - labels or Message-IDs. What are the performance issues involved in - this? With short circuiting, it's not a major problem. - </para> - <para> - The criterias and values are determined by the UI. The vfolder - mechanism isn't concerned with such issues. - </para> - <para> - Messages can be included and excluded at will. The idea is often - called "arbitrary inclusion/exclusion". This can be done by - Message-IDs or other fields. It's been noted that Message-IDs are not - unique. - </para> - <para> - I propose that any given vfolder is allocated an inclusion label and an - exclusion label. These should be randomly generated. This should be - part of the vfolder description. It should be noted that the vfolder - description has not been drafted yet. - </para> - <para> - The result is such that the rules for a given named query is: - <programlisting> - (and (user-query) - (label inclusion-label) - (not exclusion-label)) - </programlisting> - </para> - </sect2> - <sect2> - <title>Query scheduling</title> - <para> - Consider the following extremely dynamic queries: - <programlisting> - A: - (and (author "Giao") - (sent-after (today-midnight))) - - B: - (and (sent-after (today-midnight)) - (author "Giao")) - - C: - (or (author "Giao") - (sent-after (today-midnight))) - </programlisting> - Query A would be significantly faster because (author "Giao") is not - dynamic. A summary file could be generated for this query. Query B is - slow and can be optimized if there was a query compiler of some - sort. Query C demonstrates a query in which there is no good - optimization which can be applied. These come with a certain amount of - baggage. - </para> - <para> - It seems then that for boolean 'and' operations, plain forms should be - moved forward and other queries should be moved such that they are - evaluated later. I would expect that the majority of queries would be - of the plain form. - </para> - <para> - First is that the summary file is tied to the query and the store - where the query originates from. Second, a hashing function for - strings needs to be calculated for the query so that the query and the - summary file can be associated. This hashing function could be similar - to the hashing function described in Rob Pike's "The Practice of - Programming". (FIXME: Stick page number here) - </para> - </sect2> - <sect2> - <title>Archives</title> - <para> - Many people are concerned that archives won't be preserved, archives - aren't supported, and many other archive related issues. This is the - short version. - </para> - <para> - Archives are just that, archives. Archives are stores. Take your - vfolder, export it to a store. You are done. If you load up the store - again, then the default-vfolder of that store is the view of the - vfolder, except the query is different. - </para> - <para> - The point to vfolder is not to do away with classical folder - representation but to move the queries to the front where it would - make data management easier for people who don't think in terms of - files but in terms of queries because ordinary people don't think in - terms of files. - </para> - </sect2> - </sect1> - - <!-- Miscellany --> - <sect1> - <title>Miscellany</title> - <sect2> - <title>Annotations</title> - <para> - There should be a scheme to add annotations to messages. Common mail - user agents have used a tag in the message header to mark messages as - read/unread for example. Extending on this we have the ability to add - our own data to a message to add meaning to it. If we have a good - scheme for doing this, new possibilities are opened. - </para> - <sect3> - <title>Keywords</title> - <para> - When sending a message, a message could have certain keywords attached - to it. While this can be done with the subject line, the subject line - has a tendency to be munged by other mail applications. One popular - example is the "[rR]e:" prefix. Using the subject line also breaks the - "contract" with other mail user agents. Using keywords in another - field in the message header allows the sender to assist the recipient - in organizing data automatically. Note that the sender can only - provide hints as the sender is unlikely to know the organization - schemes of the recipient. - </para> - </sect3> - </sect2> - <sect2> - <title>Scope</title> - <para> - Let us assume that we have multiple stores. Does a query work on a - given store? Or does it work on all stores? Or is it configurable such - that a query can work on a user-selected list of stores? - </para> - </sect2> - </sect1> - - <!-- Alternatives to the above --> - <sect1> - <title>Alternatives to the above</title> - <para> - Jim Meyer (purp@selequa.com) is putting some notes on where - annotations needs to be located. They'll be located here as well as - any contributions I may have to them. - </para> - </sect1> -</article> diff --git a/devel-docs/query/virtual-folder-in-depth.txt b/devel-docs/query/virtual-folder-in-depth.txt deleted file mode 100644 index 01718a5f05..0000000000 --- a/devel-docs/query/virtual-folder-in-depth.txt +++ /dev/null @@ -1,309 +0,0 @@ -TITLE: An in-depth look at the virtual folder mechanism -AUTHOR: Giao Nguyen <grail@cafebabe.org> - -* introduction - -This document describes a different way of approaching mail -organization and how all things are possible in this brave new -world. This document does not describe physical storage issues nor -interface issues. - -Historically mail has been organized into folders. These folders -usually mapped to a single storage medium. The relationship between -mail organization and storage medium was one to one. There was one -mail organization for every storage medium. This scheme had its -limitations. - -Efforts at categorizations are only meaningful at the instance that -one categorized. To find any piece of data, regardless of how well -it was categorized, required some amount of searching. Therefore, any -attempts to nullify searching is doomed to fail. It's time to embrace -searching as a way of life. - -These are the terms and their definitions. The example rules used are -based on the syntax for VM (http://www.wonderworks.com/vm/) by Kyle -Jones whose ideas form the basis for this. I'm only adding the -existence of summary files to aid in scaling. I currently use VM and -it's virtual-folder rules for my daily mail purposes. To date, my only -complaints are speed (it has no caches) and for the unitiated, it's -not very user-friendly. - -Comments, questions, rants, etc. should be directed at Giao Nguyen -<grail@cafebabe.org> who will try to address issues in a timely -manner. - -* Definitions - -** store - -A location where mail can be found. This may be a file (Berkeley -mbox), directory (MH), IMAP server, POP3 server, Exchange server, -Lotus Notes server, a stack of Post-Its by your monitor fed through -some OCR system. - -** message - -An individual mail message. - -** vfolder - -A group of messages sharing some commonality. This is the result of a -query. The vfolder maybe contained in a store, but it is not necessary -that a store holds only one vfolder. There is always an implicit -vfolder rule which matches all messages. A store contains the vfolder -which is the result of the query (any). It's short for virtual folder -or maybe view folder. I dunno. - -** default-vfolder - -The vfolder defined by (any) applied to the store. This is not the -inbox. The inbox could easily be defined by a query. A default rule -for the inbox could be (new) but it doesn't have to be. Mine happens -to be (or (unread) (new)). - -** folder - -The classical mail folder approach: one message organization per -store. - -** query - -A search for messages. The result of this is a vfolder. There are two -kinds of queries: named queries and lambda queries. More on this -later. - -** summary file - -An external file that contains pointers to messages which are matches -for a named query. In addition to pointers, the summary file should -also contain signatures of the store for sanity checks. When the term -"index" is used as a verb, it means to build a summary file for a -given name-value pair. - -* Queries - -Named queries are analogous to classical mail folders. Because named -queries maybe reused, summary files are kept as caches to reduce -the overall cost of viewing a vfolder. Summary files are superior to -folders in that they allow for the same messages to appear in multiple -vfolders without message duplications. Duplications of messages -defeats attempts at tagging a message with additional user information -like annotations. Named queries will define folders. - -Lambda queries are similar to named queries except that they have no -name. These are created on the fly by the user to filter out or -include certain messages. - -All queries can be layered on top of each other. A lambda query can be -layered on a named query and a named query can be layered on a lambda -query. The possibilities are endless. - -The layerings can be done as boolean operations (and, or, not). Short -circuiting should be used. - -Examples: - -(and (author "Giao") - (unread)) - -The (unread) query should only be evaluated on the results of (author -"Giao"). - -(or (author "Giao") - (unread)) - -Both of these queries should be evaluated. Any matches are added to the -resulting vfolder. - -* Summary files - -Summary files are only meaningful when applied to the context of the -default-vfolder of a store. - -Summary files should be generated for queries of the form: - -(function "constant value") - -Summary files should never be generated for queries of the form: - -(function (function1)) - -(and (function "value") - (another-function "another value")) - -Given a query of the form: - -(and (function "value") - (another-function "another value")) - -The system should use one summary file for (function "value") and -another summary file for (another-function "another value"). I will -call the prior form the "plain form". - -It should be noted that the signature of the store should be based on -the assumption that new data may have been added to the store since -the application generated the summary file. Signatures generated on -the entirety of the store will most likely be meaningless for things -like POP/IMAP servers. - -* Incremental indexing - -When new messages are detected, all known queries should be evaluated -on the new messages. vfolders should be notified of new messages that -are positive matches for their queries. The indexes generated by this -process should be merged into the current indexes for the vfolder. - -* Can I have multiple stores? - -I don't see why not. Again, the inbox is a vfolder so you can get a -unified inbox consisting of all new mail sent to all your stores or -your can get inboxes for each store or any combination your heart -desire. You get your cake, eat it, and someone else cleans the dishes! - -* Why all this? - -Consider the dynamic nature of the following query: - -(and (author "Giao") - (sent-after (today-midnight))) - -today-midnight would be a function that is evaluated at run-time to -calculate the appropriate object. - -* Scenarios of usage and their solutions - -** Mesage alterations - -This is a fuzzy area that should be left to the UI to handle. Messages -are altered. Read status are altered when a new message is read for -example. How do we handle this if our query is for unread messages? -Upon viewing the state would change. - -One idea is to not evaluate the queries unless we're changing between -vfolder views. This assumes that one can only view a particular -vfolder at a time. For multi-vfolder viewing, a message change should -propagate through the vfolder system. Certain effects (as in our -example) would not be intuitive. - -It would not be a clean solution to make special cases but they may be -necessary where certain defined fields are ignored when they are -changed. Some combination of the above rules can be used. I don't -think it's an easy solution. - -** Message inclusion and exclusion - -Messages are included and excluded also with queries. The final query -will have the form of: - -(and (author "Giao") - (criteria value) - (not (criteria other-value))) - -Userland criterias may be a label of some sort. These may be userland -labels or Message-IDs. What are the performance issues involved in -this? With short circuiting, it's not a major problem. - -The criterias and values are determined by the UI. The vfolder -mechanism isn't concerned with such issues. - -Messages can be included and excluded at will. The idea is often -called "arbitrary inclusion/exclusion". This can be done by -Message-IDs or other fields. It's been noted that Message-IDs are not -unique. - -I propose that any given vfolder is allocated an inclusion label and an -exclusion label. These should be randomly generated. This should be -part of the vfolder description. It should be noted that the vfolder -description has not been drafted yet. - -The result is such that the rules for a given named query is: - -(and (user-query) - (label inclusion-label) - (not exclusion-label)) - -** Query scheduling - -Consider the following extremely dynamic queries: - -A: -(and (author "Giao") - (sent-after (today-midnight))) - -B: -(and (sent-after (today-midnight)) - (author "Giao")) - -C: -(or (author "Giao") - (sent-after (today-midnight))) - -Query A would be significantly faster because (author "Giao") is not -dynamic. A summary file could be generated for this query. Query B is -slow and can be optimized if there was a query compiler of some -sort. Query C demonstrates a query in which there is no good -optimization which can be applied. These come with a certain amount of -baggage. - -It seems then that for boolean 'and' operations, plain forms should be -moved forward and other queries should be moved such that they are -evaluated later. I would expect that the majority of queries would be -of the plain form. - -First is that the summary file is tied to the query and the store -where the query originates from. Second, a hashing function for -strings needs to be calculated for the query so that the query and the -summary file can be associated. This hashing function could be similar -to the hashing function described in Rob Pike's "The Practice of -Programming". (FIXME: Stick page number here) - -** Archives - -Many people are concerned that archives won't be preserved, archives -aren't supported, and many other archive related issues. This is the -short version. - -Archives are just that, archives. Archives are stores. Take your -vfolder, export it to a store. You are done. If you load up the store -again, then the default-vfolder of that store is the view of the -vfolder, except the query is different. - -The point to vfolder is not to do away with classical folder -representation but to move the queries to the front where it would -make data management easier for people who don't think in terms of -files but in terms of queries because ordinary people don't think in -terms of files. - -* Miscellany - -** Annotations - -There should be a scheme to add annotations to messages. Common mail -user agents have used a tag in the message header to mark messages as -read/unread for example. Extending on this we have the ability to add -our own data to a message to add meaning to it. If we have a good -scheme for doing this, new possibilities are opened. - -*** Keywords - -When sending a message, a message could have certain keywords attached -to it. While this can be done with the subject line, the subject line -has a tendency to be munged by other mail applications. One popular -example is the "[rR]e:" prefix. Using the subject line also breaks the -"contract" with other mail user agents. Using keywords in another -field in the message header allows the sender to assist the recipient -in organizing data automatically. Note that the sender can only -provide hints as the sender is unlikely to know the organization -schemes of the recipient. - -** Scope - -Let us assume that we have multiple stores. Does a query work on a -given store? Or does it work on all stores? Or is it configurable such -that a query can work on a user-selected list of stores? - -* Alternatives to the above - -Jim Meyer <purp@selequa.com> is putting some notes on where -annotations needs to be located. They'll be located here as well as -any contributions I may have to them. |