doc: Document email data types.

* doc/guile-email.texi (Data Types): New chapter.

1 files changed, 262 insertions, 0 deletions

diff --git a/doc/guile-email.texi b/doc/guile-email.texi
index 16f9f72..d4c3504 100644
--- a/doc/guile-email.texi
+++ b/doc/guile-email.texi
@@ -94,6 +94,268 @@ this variant of @code{parse-email} and @code{parse-email-body} will be
 deprecated in the future. This variant is only provided in the interest
 of backward compatibility.
 
+@node Data Types
+@chapter Data Types
+
+guile-email provides data types for representing emails and MIME
+entities.
+
+@section email data type
+
+@deftp {Data Type} <email> headers body
+This is the data type representing emails.
+@end deftp
+
+@deffn {Scheme Procedure} email? object
+@deffnx {Scheme Procedure} email-headers email
+@deffnx {Scheme Procedure} email-body email
+Predicate and field accessors for the @code{<email>} data type.
+@end deffn
+
+@deffn {Scheme Procedure} make-email headers body
+Construct an @code{<email>} object.  @var{headers} is an association
+list of email headers.  @var{body} is either a string or a list of
+@code{<mime-entity>} objects.
+@end deffn
+
+@section mime-entity data type
+
+@deftp {Data Type} <mime-entity> headers body
+This is the data type representing MIME entities.
+@end deftp
+
+@deffn {Scheme Procedure} mime-entity? object
+@deffnx {Scheme Procedure} mime-entity-headers mime-entity
+@deffnx {Scheme Procedure} mime-entity-body mime-entity
+Predicate and field accessors for the @code{<mime-entity>} data type.
+@end deffn
+
+@deffn {Scheme Procedure} make-mime-entity headers body
+Construct a mime-entity object.  @var{headers} is an association list of
+MIME entity headers.  @var{body} is either a string or a list of
+@code{<mime-entity>} objects.
+@end deffn
+
+@section email headers
+
+The following descriptions of email headers are only a summary.  Please
+see the relevant RFCs for more details.
+
+@subsection email header types
+
+@deftp {Email Header Type} AssociationList
+An association list of key-value pairs (@pxref{Association Lists,,,
+guile}).  Keys are the name of the email header, downcased and converted
+to symbols.  Values are specific to the header and explained below.
+@end deftp
+
+@deftp {Email Header Type} Date
+An SRFI-19 date.  @xref{SRFI-19 Date,,, guile}.
+@end deftp
+
+@deftp {Email Header Type} Address
+An association list of atmost two keys - 'name' and 'address'.  The
+values corresponding to these keys are explained below.
+
+@table @code
+@item name
+Display name of the email address.  When the email address
+does not specifiy a display name, this key will be absent.
+@item address
+Actual email address.
+@end table
+@end deftp
+
+@deftp {Email Header Type} AddressList
+A list of addresses, each of type 'Address'.
+@end deftp
+
+@deftp {Email Header Type} MessageID
+A string containing an email message ID with the surrounding angle
+brackets (@samp{<} and @samp{>}) removed.  Email message IDs uniquely
+identify the email.
+@end deftp
+
+@deftp {Email Header Type} MessageIDList
+A list of message IDs, each of type @code{MessageID}.
+@end deftp
+
+@subsection email headers
+
+@deftypevr {Email Header} Date date
+The date the email was sent on, as specified in the @dfn{Date} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList from
+The list of authors of the email, as specified in the @dfn{From} header.
+@end deftypevr
+
+@deftypevr {Email Header} Address sender
+The sender of the email, as specified in the @dfn{Sender} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList reply-to
+The list of addresses the author of the email suggests replies be sent
+to, as specified in the @dfn{Reply-To} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList to
+The list of primary recipients of the email, as specified in the
+@dfn{To} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList cc
+The list of other recipients of the email at whom the content of the
+email may not be directed, as specified in the @dfn{Cc} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList bcc
+THe list of recipients whose address is not to be revealed to other
+recipients of the email, as specified in the @dfn{Bcc} header.
+@end deftypevr
+
+@deftypevr {Email Header} MessageID message-id
+The message ID of the email, as specified in the @dfn{Message-ID}
+header.
+@end deftypevr
+
+@deftypevr {Email Header} MessageIDList in-reply-to
+The list of message IDs of emails to which this email is a reply, as
+specified in the @dfn{In-Reply-To} header.
+@end deftypevr
+
+@deftypevr {Email Header} MessageIDList references
+The list of message IDs specified in the @dfn{References} header.
+@end deftypevr
+
+@deftypevr {Email Header} String subject
+A string identifying the topic of the email, as specified in the
+@dfn{Subject} header.
+@end deftypevr
+
+@deftypevr {Email Header} String comments
+A string containing additional comments on the body of the email, as
+specified in the @dfn{Comments} header.
+@end deftypevr
+
+@deftypevr {Email Header} StringList keywords
+A list of strings each an important word or phrase, as specified in the
+@dfn{Keywords} header.
+@end deftypevr
+
+@deftypevr {Email Header} Date resent-date
+The date at which the resent message was dispatched by the resender, as
+specified in the @dfn{Resent-Date} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList resent-from
+The list of addresses specified in the @dfn{Resent-From} header.
+@end deftypevr
+
+@deftypevr {Email Header} Address resent-sender
+The address specified in the @dfn{Resent-Sender} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList resent-to
+The list of addresses specified in the @dfn{Resent-To} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList resent-cc
+The list of addresses specified in the @dfn{Resent-Cc} header.
+@end deftypevr
+
+@deftypevr {Email Header} AddressList resent-bcc
+The list of addresses specified in the @dfn{Resent-Bcc} header.
+@end deftypevr
+
+@deftypevr {Email Header} MessageID resent-message-id
+The message ID specified in the @dfn{Resent-Message-ID} header.
+@end deftypevr
+
+@c TODO: Document trace fields
+
+@deftypevr {Email Header} String mime-version
+The MIME version specified in the @dfn{MIME-Version} header.
+@end deftypevr
+
+@deftypevr {Email Header} AssociationList content-type
+The MIME type of the body, as specified in the @dfn{Content-Type}
+header, as an association list.  The following keys always exist in the
+association list.  Any additional parameters will also be listed as
+key-value pairs.  Keys are names of the parameters, downcased and
+converted to symbols.
+
+@table @code
+@item type
+The primary type
+@item subtype
+The secondary type
+@item charset
+The charset
+@end table
+@end deftypevr
+
+If no Content-Type header is present, a type of @code{text}, a subtype
+of @code{plain} and a charset of ``utf-8'' is assumed as the default.
+That is, the following:
+
+@example
+((type . text)
+ (subtype . plain)
+ (charset . "utf-8"))
+@end example
+
+@deftypevr {Email Header} AssociationList content-disposition
+The content disposition type, as specified in the
+@dfn{Content-Disposition} header, as an association list.  The following
+keys always exist in the association list.
+
+@table @code
+@item type
+@table @code
+@item inline
+@item attachment
+@end table
+@end table
+
+Other optional keys include
+
+@table @code
+@item filename
+@item creation-date
+@item modification-date
+@item read-date
+@item size
+@end table
+
+Any additional parameters will also be listed as key-value pairs.
+Keys are names of the parameters, downcased and converted to
+symbols.
+@end deftypevr
+
+@deftypevr {Email Header} Symbol content-transfer-encoding
+The encoding of the body of the email as specified in the
+@dfn{Content-Transfer-Encoding} header.  This can be one of the
+following symbols.
+
+@table @code
+@item 7bit
+The message is 7-bit encoded.  This is the default if no
+Content-Transfer-Encoding header is present.
+@item 8bit
+The message is 8-bit encoded.
+@item quoted-printable
+The message is encoded using Quoted-Printable encoding.
+@item base64
+The message is encoded using Base64 encoding.
+@end table
+
+Note that guile-email automatically decodes the email.  The user need
+not read the @code{content-transfer-encoding} and invoke the appropriate
+decoding procedure.  The @code{content-transfer-encoding} header is only
+provided for the sake of completion.
+@end deftypevr
+
 @node Encoding and Decoding
 @chapter Encoding and Decoding