Made definition of address aux-items clearer (after a discussion in

LysLysKOM), rewrote a lot of the text on mail import.

doc/Protocol-A.texi

@@ -2,7 +2,7 @@
 @c
 @c FIXME: Explain how the garb works with nice and keep-commented
 @c
-@c $Id: Protocol-A.texi,v 1.91 1999/07/23 13:12:59 ceder Exp $
+@c $Id: Protocol-A.texi,v 1.92 1999/07/25 16:06:39 kent Exp $
 @c %**start of header
 @setfilename protocol-a.info
 @settitle LysKOM Protocol A
@@ -1009,23 +1009,33 @@ restriction.
 @item mx-author [16] (text)
 
 Data is a string containing the name of the author of an imported
-e-mail. Clients should display this instead of the actual author of the
-text, which will be an importer ID.
+e-mail, extracted from the @code{From} header. Clients should display
+this instead of the actual author of the text, which will be an importer
+ID. Please note that this aux-item may be missing, if the mail adress in the
+@code{From} header consists of just the @code{addr-spec} (see the next
+aux-item).
 
+Sample contents: @code{Joe Q. Public} which may come from a @code{From}
+header containing @code{"Joe Q. Public" <john.q.public@@example.com>}.
 
 @item mx-from [17] (text)
 
-Data is the e-mail address extracted from the @code{From} header of an
-imported e-mail. This field can be used by clients to construct an
-address for personal (e-mail) replies to an imported message.
+Data is the proper e-mail address (called @code{addr-spec} in the mail
+standards) extracted from the @code{From} header of an imported
+e-mail. This field can be used by clients to construct an address for
+personal (e-mail) replies to an imported message. It can also be shown
+in addition to the @code{mx-author} aux-item.
 
+Sample contents: @code{john.q.public@@example.com} which may come from a
+@code{From} header containing @code{john.q.public@@example.com} or
+something like @code{"Joe Q. Public" <john.q.public@@example.com>}.
 
 @item mx-reply-to [18] (text)
 
-Data is the e-mail address extracted from the @code{Reply-To} header of
-an imported e-mail. Clients should use this for constructing replies to
-imported messages.
-
+Data is the proper e-mail address (called @code{addr-spec} in the mail
+standards) extracted from the @code{Reply-To} header of an imported
+e-mail. Clients should use this for constructing replies to imported
+messages.
 
 @item mx-to [19] (text)
 
@@ -1038,6 +1048,9 @@ On messages created by a LysKOM person, the @code{mx-to} items are used
 by the exporter to determine that the message is to be exported and
 where to send it.
 
+Sample contents: @code{john.q.public@@example.com} and
+@code{"Joe Q. Public" <john.q.public@@example.com>} are both valid.
+
 @item mx-cc [20] (text)
 
 Same as @code{mx-to}, but applies to the @code{CC} header rather than
@@ -4661,7 +4674,7 @@ anyway.
 
 
 @node get-map
-@section get-map [34] (1) Recommended
+@section get-map [34] (1) Obsolete (10)
 
 @findex get-map
 @example
@@ -8682,7 +8695,7 @@ to be exported. A text will have to be exported if it has an
 @code{mx-to} aux-item, if the text was not imported or if the item was
 added after the text was imported.
 
-The exportes is responsible for setting the @code{Date},
+The exporter is responsible for setting the @code{Date},
 @code{Message-ID}, @code{From}, @code{Reply-To}, @code{To}, @code{CC}
 and @code{In-Reply-To} fields in the exported message.
 
@@ -8734,18 +8747,37 @@ For the mail exporter to work, it will need special privileges.
 
 @section Importing
 
-The main job of the mail importer is to figure out where to deliver mail 
-and how to deal with threading. The importer can find the recipients in
-the @code{To} and @code{CC} headers of the message. The current (very
-simple) importer uses addresses like ``p@i{person}@@@i{server}´´, where 
-@i{person} is the number of the recipient and @i{server} is the LysKOM
-server.
-
-The importer should add recipients in the @code{CC} header as
-carbon-copy-recipients, and recipients in the @code{To} header as
-regular recipients. The importer needs to be careful not to deliver
-messages to conferences that do not allow messages, even though the
-server might not complain.
+The main job of the mail importer is to figure out where to deliver mail,
+how to handle MIME appendices and how to deal with threading.
+
+Although a mail message contains @code{To} and @code{CC} headers, they
+are not really useful when importing as it is the envelope recipients,
+not the header recipients, that should be used. To understand this,
+consider a mail where the @code{To} header contains a personal mail
+address. The mail is received using a tool like @code{procmail} and
+forwarded to the LysKOM importer. The envelope address will be correct,
+but the @code{To} header will still contain the personal address.
+
+The current (very simple) importer uses addresses like
+``p@i{person}@@@i{server}´´, where @i{person} is the number of the
+recipient and @i{server} is the LysKOM server.
+
+Care should be taken when a mail is received more than once. This can
+happen if a mail is addressed to more than one address. For example,
+assume that a mail is sent to @code{john.q.public@@example.com} and
+@code{sven.svensson@@exempel.se}. Two different mail servers handle the
+two recipients, but both eventually decide to forward the mail to the
+LysKOM importer (but for different conferences). The LysKOM importer
+will receive the mail twice, with different envelope recipients.
+
+A solution is to keep a database containing a mapping from
+@code{Message-ID} to LysKOM text number for imported messages.  If a
+message is seen more than once, the message is not imported. Instead,
+recipients are added to the existing text.
+
+The importer needs to be careful not to deliver messages to conferences
+that do not allow messages, even though the server might not complain.
+@c FIXME: Please elaborate on that...
 
 For mail delivery to work, the importer has to run as a privileged user, 
 or it would be unable to deliver mail to secret conferences. A potential 
@@ -8755,6 +8787,9 @@ whether it accepts imported e-mail. This is currently not possible, but
 can easily be implemented, should the implementor of the first good
 importer want it.
 
+@c FIXME: What privileges are needed? Couldn't the importer run
+@c as an unprivileged user and be added as a member to secret conferences
+@c that should be able to import mail?
 
 @subsection Threading
 
@@ -8767,43 +8802,29 @@ be made a comment to the replied-to text.
 This means that the importer will probably have to maintain its own
 database of imported texts that maps the message ID to the text number
 in the LysKOM database. There is no other way to find the text number
-for a particular imported text.
+for a particular imported text. The same database can be used to solve
+the multiple reception problem described above.
+
+@c FIXME: remove import algorithm; it was too broken.
 
+@subsection MIME issues
 
-@section An Algorithm, Sort Of
+An importer should try to handle e-mail messages containing MIME
+appendices as smart as possible. As the current LysKOM model lacks
+hierarchical structuring inside articles, appendices should probably be
+imported as comments or footnotes to the main message. Appendices
+encoded with Base64 or Quoted-Printable should be decoded.
 
-Here's an outline for algorithms for import and export of messages.
-They're hardly complete, and may not even quite work, but they should
+When creating aux-items like @code{mx-author}, text coded using the
+method in RFC 2047 should be decoded.
+
+@section An Export Algorithm, Sort Of
+
+Here's an outline for a message export algorithm.
+It is hardly complete, and may not even quite work, but it should
 give the general idea of how things can work.
 
 @example
-function import-message (message)
-@{
-    recipient_list = To header of message
-    cc_list = CC header of message 
-    
-    
-    delete recipients from recipient_list that do not want imported mail
-    delete recipients from cc_list that do not want imported mail
-
-    for each element el in In-Reply-To header of message
-        if el is a LysKOM message ID
-            text_no = text number of el
-        if el is in the imported database
-            text_no = text number from database
-
-        if text_no is set
-            add text_no to comm_to
-
-    result = create_text with
-            recipients = recipient_list
-            cc-recipients = cc_list
-            comment-to = comm_to
-            aux-items extracted from header
-
-    if result is a failure, construct and send a bounce
-    put Message-ID and result into the imported database
-@}
 
 function exporter ()
 @{