Updated and corrected URL documentation.

@@ -15,6 +15,7 @@ EXTRA_DIST = \
  encoding.texi \
  envelope.texi \
  ex-address.texi \
+ ex-url.texi \
  framework.texi \
  folder.texi \
  headers.texi \
@@ -45,6 +46,8 @@ EXTRA_DIST = \
 #	sed -es/{/@{/g -e s/}/@}/g < $< > $@
 #sfrom.texi: ${top_srcdir}/doc/examples/sfrom.c
 #	sed -es/{/@{/g -e s/}/@}/g < $< > $@
+#ex-url.texi: ${top_srcdir}/doc/examples/url-parse.c
+#	sed -es/{/@{/g -e s/}/@}/g < $< > $@
 
 #mailutils.info: mailutils.texi version.texi ex-address.texi
 #mailutils.dvi: mailutils.texi version.texi ex-address.texi

@@ -12,7 +12,7 @@
 * Authenticator::               Authenticator.
 * Address::                     Address.
 * Locker::                      Locker.
-* URL::                         Unified Ressource Locator.
+* URL::                         Uniform Resource Locators.
 
 @end menu
 

 
 @comment See rfc2368, rfc2369, rfc2384
-A mailbox and mailer can be described in a URL, the string will contain the
+A mailbox or a mailer can be described in a URL, the string will contain the
 necessary information to initialize @code{mailbox_t}, or @code{mailer_t}
 properly.
 
@@ -10,17 +10,21 @@ and the authentication mechanism.  The general form is
 
 @example
 @url{pop://[<user>[;AUTH=<auth>]@@]<host>[:<port>]}
+ or
+@url{pop://[<user>[:<passwd>]@@]<host>[:<port>]}
 @end example
 
 If @emph{:port} is omitted the default value is 110. Different forms of
 authentication can be specified with @emph{;AUTH=type}.
 The special string @emph{;AUTH=*} indicates that the client will use
 a default scheme base on the capability of the server.
+
 @example
 @url{pop://obelix@@gaulois.org}
 @url{pop://asterix;AUTH=*@@france.com}
 @url{pop://falbala;AUTH=+APOP@@france.com}
 @url{pop://obelix;AUTH=+APOP@@village.gaulois.org:2000}
+@url{pop://obelix:menhir@@village.gaulois.org:2000}
 @end example
 
 For more complete information see @cite{rfc2368}.
@@ -30,16 +34,20 @@ The IMAP URL scheme contains an IMAP server, optional port number
 and the authentication mechanism.  The general form is
 
 @example
-@url{imap://[user[;AUTH=type]]@@hostname[:port][/mailbox]}
+@url{imap://[<user>[;AUTH=<type>]]@@<host>[:port][/<mailbox>]}
+ or
+@url{imap://[<user>[:<passwd>]]@@<host>[:port][/<mailbox>]}
 @end example
 
 If @emph{:port} is omitted the default value is 220. Different forms of
 authentication can be specified with @emph{;AUTH=type}.
 The special string @emph{;AUTH=*} indicates that the client will use
 a default scheme base on the capability of the server.
+
 @example
-@url{pop://obelix@@imap.gaulois.org}
-@url{pop://asterix;AUTH=*@@france.com}
+@url{imap://obelix@@imap.gaulois.org}
+@url{imap://asterix;AUTH=*@@imap.france.com}
+@url{imap://asterix:potion@@imap.france.com}
 @end example
 
 For more complete information see @cite{rfc2192}.
@@ -68,12 +76,14 @@ use @url{file://path} and let the library figure out which one.
 
 After setting a mailer, @url{mailto:} is used to tell the mailer where
 and to whom the message is for.
+
 @example
 @url{mailto://hostname}
 @end example
 
 Mailto can be used to generate short messages, for example to subscribe
 to mailing lists.
+
 @example
 @url{mailto://bug-mailutils@@gnu.org?body=subscribe}
 @url{mailto://bug-mailutils@@gnu.org?Subject=hello&body=subscribe}
@@ -85,90 +95,38 @@ For more complete information see @cite{rfc2368}.
 
 Helper functions are provided to retrieve and set the @emph{URL} fields.
 
-@deftypefun int  url_init (url_t *@var{url}, const char *name)
-Initialize and parse the @var{url}
+@deftypefun int  url_create (url_t *@var{url}, const char *@var{name})
+Create and the @var{url} data structure, but do not parse it.
 @end deftypefun
 
 @deftypefun void url_destroy (url_t *)
+Destroy the url and free it's resources.
 @end deftypefun
 
-@deftp {Data type} struct url_type
+@deftypefun int  url_parse (url_t @var{url})
+Parses the url, after calling this the get functions can be called.
+
+The syntax, condensed from RFC 1738, and extended with the ;auth=
+of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:
+
 @example
-@{
-  char *scheme;
-  size_t  len;
-  char *description;
-  int  id;
-  int  (*_init) (url_t *, const char * name);
-  void (*_destroy) (url_t *);
-@};
-@end example
-@end deftp
+url =
+    scheme ":" = "//"
 
-@subsection URL registration
+    [ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ]
 
-@deftypefun int url_list_type (struct url_type @var{list}[], size_t @var{len}, size_t *@var{n})
-@end deftypefun
+    host [ ":" port ]
 
-@deftypefun int url_add_type (struct url_type *@var{utype})
-@end deftypefun
+    [ ( "/" urlpath ) | ( "?" query ) ]
+@end example
 
-@deftypefun int url_remove_type (const struct url_type *@var{utype})
-@end deftypefun
+This is a generalized URL syntax, and may not be exactly appropriate
+for any particular scheme.
 
-@deftypefun int url_get_id (const url_t @var{url}, int *@var{id})
 @end deftypefun
 
-@subsection Helper functions
-
-@example
-#include <mailutils/url.h>
-#include <stdio.h>
-#include <string.h>
-
-int main ()
-@{
-    char str[1024];
-    char buffer[1024];
-    long port = -1;
-    url_t u;
-
-    while (fgets (str, sizeof (str), stdin) != NULL)
-      @{
-         str[strlen (str) - 1] = '\0'; /* chop newline */
-         if (url_init (&u, str) != 0)
-           @{
-              printf ("%s --> FAILED\n", str);
-              continue;
-           @}
-         printf ("%s --> SUCCESS\n", str);
-
-         url_get_scheme (u, buffer, len, NULL);
-         printf ("\tscheme <%s>\n", buffer);
-
-         url_get_user (u, buffer, len, NULL);
-         printf ("\tuser <%s>\n", buffer);
-
-         url_get_passwd (u, buffer, len, NULL);
-         printf ("\tpasswd <%s>\n", buffer);
-
-         url_get_host (u, buffer, len, NULL);
-         printf ("\thost <%s>\n", buffer);
-
-         url_get_port (u, &port);
-         printf ("\tport %ld\n", port);
-
-         url_get_path (u, buffer, len, NULL);
-         printf ("\tpath <%s>\n", buffer);
-
-         url_get_query (u, buffer, len, NULL);
-         printf ("\tquery <%s>\n", buffer);
-
-         url_destroy (&u);
-     @}
-   return 0;
-@}
-@end example
+@deftypefun const char* url_to_string (const url_t @var{url})
+@end deftypefun
 
 @deftypefun int url_get_scheme (const url_t @var{url}, char *@var{schem}, size_t @var{len}, size_t *@var{n})
 @end deftypefun
@@ -190,3 +148,15 @@ int main ()
 
 @deftypefun int url_get_query (const url_t @var{url}, char *@var{query}, size_t{len}, size_t *@var{n})
 @end deftypefun
+
+@deftypefun char* url_decode (const char* s)
+Decodes an RFC 1738 % encoded string, returning the decoded string in
+allocated memory. If the string is not encoded, this degenerates to
+a strdup().
+@end deftypefun
+
+@section Example
+@example
+@include ex-url.texi
+@end example
+