doc: Document encoding and decoding procedures.

* doc/guile-email.texi (Encoding and Decoding): New chapter.

1 files changed, 77 insertions, 0 deletions

diff --git a/doc/guile-email.texi b/doc/guile-email.texi
index 9fed64e..900d070 100644
--- a/doc/guile-email.texi
+++ b/doc/guile-email.texi
@@ -21,6 +21,8 @@ Documentation License''.
 @menu
 * Introduction:: What is guile-email?
 * Parsing e-mail:: Parsing e-mail
+* Encoding and Decoding:: Encoding and decoding Base64, Quoted-Printable
+  and Q-encoding
 * Contributing:: Contributing
 
 Indices
@@ -66,6 +68,81 @@ list of header keys and values as returned by
 @code{parse-email-headers}. Return a list of <mime-entity> records if
 the body is a multipart message. Else, return a single <mime-entity>
 record.
+
+@node Encoding and Decoding
+@chapter Encoding and Decoding
+
+guile-email supports encoding and decoding using Base64 encoding,
+Quoted-Printable encoding and Q-encoding.  Note that guile-email
+automatically invokes the necessary decoding procedures while parsing
+email.  The following procedures are only provided in case you need to
+use them in a context not automatically handled by guile-email.
+
+Character encoding schemes such as UTF-8 encode characters as bytes.
+Encoding schemes such as Quoted-Printable encoding, Base64 encoding and
+Q-encoding re-encode these bytes as 7-bit text suitable for transmission
+over a medium such as email that is not 8-bit clean.  Therefore, the
+input to the following encoding procedures and the output from the
+following decoding procedures is a bytevector.  Encoding characters to
+bytes or decoding bytes to characters is not within the scope of these
+procedures.  @xref{Representing Strings as Bytes,,, guile} for more
+information on how to do this.
+
+@section Base64 encoding
+
+@deffn {Scheme Procedure} base64-encode bv
+Encode bytevector @var{bv} using Base64 encoding and return the encoded
+string.
+@end deffn
+
+@deffn {Scheme Procedure} base64-decode str
+Decode Base64 encoded string @var{str} and return the decoded
+bytevector.
+@end deffn
+
+@section Quoted-Printable encoding
+
+The Quoted-Printable encoding and decoding procedures in this section
+are typed functions in that they behave differently based on the types
+of their arguments.
+
+@deftypefn {Scheme Procedure} {} quoted-printable-encode (bytevector @var{bv})
+@deftypefnx {Scheme Procedure} {} quoted-printable-encode (port @var{in})
+@deftypefnx {Scheme Procedure} {} quoted-printable-encode (port @var{in}) (port @var{out})
+Encode bytevector @var{bv} using Quoted-Printable encoding and return
+the encoded string.
+
+Read bytes from the bytevector input port @var{in} and return the
+Quoted-Printable encoded string.
+
+Read bytes from the bytevector input port @var{in} and write the
+Quoted-Printable encoded string to output port @var{out}.
+@end deftypefn
+
+@deftypefn {Scheme Procedure} {} quoted-printable-decode (string @var{str})
+@deftypefnx {Scheme Procedure} {} quoted-printable-decode (port @var{in})
+@deftypefnx {Scheme Procedure} {} quoted-printable-decode (port @var{in}) (port @var{out})
+Decode Quoted-Printable encoded string @var{str} and return the decoded
+bytevector.
+
+Read Quoted-Printable encoded characters from input port @var{in} and
+return the decoded bytevector.
+
+Read Quoted-Printable encoded characters from port @var{in} and write
+the decoded bytevector to bytevector output port @var{out}.
+@end deftypefn
+
+@section Q-encoding
+
+@deffn {Scheme Procedure} q-encoding-encode bv
+Encode bytevector @var{bv} using Q-encoding and return the encoded
+string.
+@end deffn
+
+@deffn {Scheme Procedure} q-encoding-decode str
+Decode Q-encoding encoded string @var{str} and return the decoded
+bytevector.
+@end deffn
 @end deffn
 
 @node Contributing