Changes propose by Sam Roberts, They look valid and interesting.

+@code{#include <mailutils/mailbox.h>}
+@deftp {Data Type} address_t
+The @code{address_t} object is used to hold information about a parsed
+RFC822 address list, and is an opaque
+data structure to the user. Functions are provided to retrieve information
+about the address list. An address list is a sequence of addresses, each
+of which has four components: an optional phrase describing the address, the
+local-part of the address, the domain of the address, and an optional
+comment field.
+
+If the phrase is present it is probably the personal name
+associated with the the address, if not, the comment may contain some
+identifying information.
+
+Since the address-list may contain multiple addresses, they are accessed
+by a @strong{one-based index number}, @var{no}.
+
+Comment: Why is this one-based? nobody
+familiar with C would ever expect that!
+
+The size of a particular component
+may be queried by providing @code{0} for the @var{len} of the buffer,
+in which case the buffer is optional and if @var{n} is provided
+*@var{n} is assigned the length of the component string.
+
+If @var{len}
+is greater than @code{0} it is the length of the buffer @var{buf}, and
+as much of the component as possible will be copied into the buffer.
+
+Comments:
+
+The API isn't complete, there are useful things you can't do.
+
+There needs to be a way of accessing the local-part and the
+domain of an email address seperately, the syntax of local-part is too complex
+to expect somebody to parse it, in particular strchring for '@@'
+will fail if there is an '@@' in the local-part, which is valid if
+its quoted or escaped.
+
+You can't create an address or an address list.
+
+Creating one should apropriately quote unsafe characters in the local
+part and phrase/personal name, not allow a comment (its deprecated), etc.
+
+What about groups? They are easy to parse, but a pain from an api point
+of view. _address, instead of being a pure linked list, could
+be more tree-like, so each _address also contained and _address* group
+member. If there was a group, then email would be the name of the group,
+something like "my special group: ;", and group would be the (possibly
+empty) list of addresses in the group, and each of those addresses
+could in turn be a group, etc.
+
+This data structure reflects the structure of an address ok, but doesn't
+address (;-)) what happens if you had a program that just wanted to print
+out all the recipients email addresses. The @var{no} could still be
+a linear index into the tree, so those not wanting to know could not
+know, and the group nodes could silently dissappear.
+
+But what if you wanted to iterate the whole tree?
+  address_is_group(addr, no)? address_get_group_name(addr, no)?
+  address_get_group(addr, &addr)?
+
+For creating, maybe the easy way is to splice an address list.
+
+address_create(&addr, NULL)
+
+address_insert(addr, -1, "Big John", "bluesman", "yahoo.com");
+
+// -1 is the end, anything else is position to be inserted at, for ex.
+
+address_create(&group, NULL)
+
+address_insert(group, -1, "Sam", "sroberts", "uniserve.com");
+
+address_insert(group, -1, "Joe @ \"home\"", "joe", "uniserve.com");
+
+address_insert_group(addr, group, "the uniserve boys");
+
+This would be:
+@example
+  Big John <bluesman@@yahoo.com>, the uniserve boys: Sam
+  <sroberts@@uniserve.com>, "Joe @@ \"home\"" <joe@@uniserve.com> ;
+@end example
+
+This is just a sketch of what I think should be conceptually possible
+in a complete address parser class. Basically the goals are to be
+able to see the structure of an RFC822 address exactly (except for
+comments... they get munged together if present, but what the hell,
+they're comments!) and to build as complex an address as is
+possible. Simple things should still be simple.
+
+Two problems are domain literals, and non-ascii characters. I
+think domain literals should be parsed from [127.0.0.1] into
+the more commonly groked 127.0.0.1 when somebody does a get_domain()
+on one, and that if somebody wants to provide one as a domain, they
+can.
+
+Non ascii chars are uglier, perhaps a warning? Perhaps a non-strict
+switch that makes it an error, and otherwise if they want umlauts
+and utf-8 in the strings, just allow it? The machinery to encode
+and decode header fields according to the MIME spec doesn't really
+belong here, it's a layer on top of rfc822.
+
+@end deftp
+
+@deftypefun int address_create (address_t *@var{addr}, const char *@var{string})
+This function allocates and initializes @var{addr} by parsing the
+RFC822 address-list @var{string}.
+
+The return value is @code{0} on success and a code number on error conditions:
+@table @code
+@item ENOMEM
+Not enough memory to allocate resources.
+@end table
+@end deftypefun
+
+@deftypefun  void address_destroy (address_t *@var{addr})
+The @var{addr} is destroyed.
+@end deftypefun
+
+@deftypefun  int address_get_email (address_t *@var{addr},
+	size_t no, char* buf, size_t len, size_t* n)
+Acesses the @var{no}th email address component.
+
+The return value is @code{0} on success and a code number on error conditions:
+@table @code
+@item EINVAL
+@var{addr} is NULL.
+@end table
+@end deftypefun
+

@@ -110,6 +110,7 @@ This document was produced for version @value{VERSION} of @sc{gnu}
 * Attribute::                   Attribute.
 * Attribute::                   Attribute.
 * Stream::                      Stream API.
 * Stream::                      Stream API.
 * Authenticator::               Authenticator.
 * Authenticator::               Authenticator.
+* Address::                     Address.
 * Locker::                      Locker.
 * Locker::                      Locker.
 * Encoding::                    Encoding API.
 * Encoding::                    Encoding API.
 * URL::                         Unified Ressource Locator.
 * URL::                         Unified Ressource Locator.
@@ -210,14 +211,21 @@ For example writing a simple @command{from} command that will list the
 
 
 @include stream.texi
 @include stream.texi
 
 
-@node Authenticator, Locker, Stream, Top
+@node Authenticator, Address, Stream, Top
 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up
 @chapter Authenticator
 @chapter Authenticator
 @cindex Authenticator
 @cindex Authenticator
 
 
 @include auth.texi
 @include auth.texi
 
 
-@node Locker , Encoding, Authenticator, Top
+@node Address, Locker, Authenticator, Top
+@comment  node-name,  next,  previous,  up
+@chapter Address
+@cindex Address
+
+@include address.texi
+
+@node Locker, Encoding, Address, Top
 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up
 @chapter Locker
 @chapter Locker
 @cindex Locker
 @cindex Locker