More updates for the URL library manual.

* url.texi (Introduction): Move url-configuration-directory to
Customization node.
(Parsed URIs): Split into its own node.
(URI Encoding): New node.
(Defining New URLs): Remove empty chapter.
(Retrieving URLs): Add an introduction.  Doc fix for url-retrieve.
Improve docs for url-queue-*.
(Supported URL Types): Copyedits.  Delete empty subnodes.

2 files changed, 315 insertions, 222 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index d7af0d79c68..80d19f3adaa 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,14 @@
+2012-11-09  Chong Yidong  <cyd@gnu.org>
+
+        * url.texi (Introduction): Move url-configuration-directory to
+        Customization node.
+        (Parsed URIs): Split into its own node.
+        (URI Encoding): New node.
+        (Defining New URLs): Remove empty chapter.
+        (Retrieving URLs): Add an introduction.  Doc fix for url-retrieve.
+        Improve docs for url-queue-*.
+        (Supported URL Types): Copyedits.  Delete empty subnodes.
+
 2012-11-08  Chong Yidong  <cyd@gnu.org>
 
         * url.texi (Introduction): Rename from Getting Started.  Rewrite
diff --git a/doc/misc/url.texi b/doc/misc/url.texi
index 9124edfcf73..fdb3ab452f2 100644
--- a/doc/misc/url.texi
+++ b/doc/misc/url.texi
@@ -18,7 +18,7 @@
 @end direntry
 
 @copying
-This file documents @code{url} Emacs Lisp library.
+This is the manual for the @code{url} Emacs Lisp library.
 
 Copyright @copyright{} 1993-1999, 2002, 2004-2012 Free Software Foundation, Inc.
 
@@ -61,7 +61,6 @@ developing GNU and promoting software freedom.''
 * URI Parsing::                 Parsing (and unparsing) URIs.
 * Retrieving URLs::             How to use this package to retrieve a URL.
 * Supported URL Types::         Descriptions of URL types currently supported.
-* Defining New URLs::           How to define a URL loader for a new protocol.
 * General Facilities::          URLs can be cached, accessed via a gateway
                                 and tracked in a history list.
 * Customization::               Variables you can alter.
@@ -79,12 +78,12 @@ developing GNU and promoting software freedom.''
 @cindex uniform resource locator
 
 A @dfn{Uniform Resource Identifier} (URI) is a specially-formatted
-name, such as an Internet address, which identifies some name or
+name, such as an Internet address, that identifies some name or
 resource.  The format of URIs is described in RFC 3986, which updates
 and replaces the earlier RFCs 2732, 2396, 1808, and 1738.  A
 @dfn{Uniform Resource Locator} (URL) is an older but still-common
-term, which basically refers to a URI corresponding to a resource
-which can be accessed over a network.
+term, which basically refers to a URI corresponding to a resource that
+can be accessed (usually over a network) in a specific way.
 
   Here are some examples of URIs (taken from RFC 3986):
 
@@ -101,22 +100,9 @@ urn:oasis:names:specification:docbook:dtd:xml:4.1.2
 
   This manual describes the @code{url} library, an Emacs Lisp library
 for parsing URIs and retrieving the resources to which they refer.
-(The library is so-named due to historical reasons; nowadays, the
-``URI'' terminology is regarded as the more general one, and ``URL''
-is technically obsolete despite its widespread vernacular usage.)
-
-@defvar url-configuration-directory
-@cindex configuration files
-The value of this variable specifies the name of the directory in
-which the @code{url} library stores its various configuration files,
-cache files, etc.
-
-The default value specifies a subdirectory named @file{url/} in the
-standard Emacs user data directory specified by the variable
-@code{user-emacs-directory} (normally @file{~/.emacs.d}).  However,
-the old default was @file{~/.url}, and this directory is used instead
-if it exists.
-@end defvar
+(The library is so-named for historical reasons; nowadays, the ``URI''
+terminology is regarded as the more general one, and ``URL'' is
+technically obsolete despite its widespread vernacular usage.)
 
 @node URI Parsing
 @chapter URI Parsing
@@ -133,28 +119,38 @@ specifies the scheme component @samp{http}, the hostname component
 @samp{www.gnu.org}, and the path component @samp{/software/emacs/}.
 
 @cindex parsed URIs
-  The URI format is specified by RFC 3986.  The @code{url} library
-provides the Lisp function @code{url-generic-parse-url}, a
-standard-compliant URI parser, as well as the unparser
-@code{url-recreate-url}:
-
-@defun url-generic-parse-url url
-This function returns a parsed version of the string @var{url}.
+  The format of URIs is specified by RFC 3986.  The @code{url} library
+provides the Lisp function @code{url-generic-parse-url}, a (mostly)
+standard-compliant URI parser, as well as function
+@code{url-recreate-url}, which converts a parsed URI back into a URI
+string.
+
+@defun url-generic-parse-url uri-string
+This function returns a parsed version of the string @var{uri-string}.
 @end defun
 
-@defun url-recreate-url uri
+@defun url-recreate-url uri-obj
 @cindex unparsing URLs
-Given a parsed URI, this function returns a corresponding URI string.
+Given a parsed URI, this function returns the corresponding URI string.
 @end defun
 
 @cindex parsed URI
   The return value of @code{url-generic-parse-url}, and the argument
-expected by @code{url-recreate-url}, is a @dfn{parsed URI}, in the
-form of a CL structure whose slots hold the various components of the
-URI.  @xref{top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation},
-for details about CL structures.  Most of the other functions in the
-@code{url} library act on parsed URIs.  Each parsed URI structure
-contains the following slots:
+expected by @code{url-recreate-url}, is a @dfn{parsed URI}: a CL
+structure whose slots hold the various components of the URI.
+@xref{top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for
+details about CL structures.  Most of the other functions in the
+@code{url} library act on parsed URIs.
+
+@menu
+* Parsed URIs::           Format of parsed URI structures.
+* URI Encoding::          Non-@acronym{ASCII} characters in URIs.
+@end menu
+
+@node Parsed URIs
+@section Parsed URI structures
+
+  Each parsed URI structure contains the following slots:
 
 @table @code
 @item type
@@ -185,7 +181,7 @@ The combination of the ``path'' and ``query'' components of the URI (a
 string), or @code{nil}.  If the query component is present, it is the
 substring following the first @samp{?} character, and the path
 component is the substring before the @samp{?}.  The meaning of these
-components depends on the service; they do not necessarily refer to a
+components is scheme-dependent; they do not necessarily refer to a
 file on a disk.
 
 @item target
@@ -208,7 +204,7 @@ and/or password) are preceded by @samp{//}.
 @findex url-target
 @findex url-attributes
 @findex url-fullness
-The above slots have accessors named @code{url-@var{part}}, where
+These slots have accessors named @code{url-@var{part}}, where
 @var{part} is the slot name.  For example, the accessor for the
 @code{host} slot is the function @code{url-host}.  The @code{url-port}
 accessor returns the default port for the URI scheme if the parsed
@@ -220,40 +216,153 @@ URI's @var{port} slot is @code{nil}.
 (setf (url-port url) 80)
 @end example
 
+@node URI Encoding
+@section URI Encoding
+
+@cindex percent encoding
+  The @code{url-generic-parse-url} parser does not obey RFC 3986 in
+one respect: it allows non-@acronym{ASCII} characters in URI strings.
+
+  Strictly speaking, RFC 3986 compatible URIs may only consist of
+@acronym{ASCII} characters; non-@acronym{ASCII} characters are
+represented by converting them to UTF-8 byte sequences, and performing
+@dfn{percent encoding} on the bytes.  For example, the o-umlaut
+character is converted to the UTF-8 byte sequence @samp{\xD3\xA7},
+then percent encoded to @samp{%D3%A7}.  (Certain ``reserved''
+@acronym{ASCII} characters must also be percent encoded when they
+appear in URI components.)
+
+  The function @code{url-encode-url} can be used to convert a URI
+string containing arbitrary characters to one that is properly
+percent-encoded in accordance with RFC 3986.
+
+@defun url-encode-url url-string
+This function return a properly URI-encoded version of
+@var{url-string}.  It also performs @dfn{URI normalization},
+e.g.@: converting the scheme component to lowercase if it was
+previously uppercase.
+@end defun
+
+  To convert between a string containing arbitrary characters and a
+percent-encoded all-@acronym{ASCII} string, use the functions
+@code{url-hexify-string} and @code{url-unhex-string}:
+
+@defun url-hexify-string string &optional allowed-chars
+This function performs percent-encoding on @var{string}, and returns
+the result.
+
+If @var{string} is multibyte, it is first converted to a UTF-8 byte
+string.  Each byte corresponding to an allowed character is left
+as-is, while all other bytes are converted to a three-character
+sequence: @samp{%} followed by two upper-case hex digits.
+
+@vindex url-unreserved-chars
+@cindex unreserved characters
+The allowed characters are specified by @var{allowed-chars}.  If this
+argument is @code{nil}, the allowed characters are those specified as
+@dfn{unreserved characters} by RFC 3986 (see the variable
+@code{url-unreserved-chars}).  Otherwise, @var{allowed-chars} should
+be a vector whose @var{n}-th element is non-@code{nil} if character
+@var{n} is allowed.
+@end defun
+
+@defun url-unhex-string string &optional allow-newlines
+This function replaces percent-encoding sequences in @var{string} with
+their character equivalents, and returns the resulting string.
+
+If @var{allow-newlines} is non-@code{nil}, it allows the decoding of
+carriage returns and line feeds, which are normally forbidden in URIs.
+@end defun
+
 @node Retrieving URLs
 @chapter Retrieving URLs
 
+  The @code{url} library defines the following three functions for
+retrieving the data specified by a URL.  The actual retrieval protocol
+depends on the URL's URI scheme, and is performed by lower-level
+scheme-specific functions.  (Those lower-level functions are not
+documented here, and generally should not be called directly.)
+
+  In each of these functions, the @var{url} argument can be either a
+string or a parsed URL structure.  If it is a string, that string is
+passed through @code{url-encode-url} before using it, to ensure that
+it is properly URI-encoded (@pxref{URI Encoding}).
+
 @defun url-retrieve-synchronously url
-Retrieve @var{url} synchronously and return a buffer containing the
-data.  @var{url} is either a string or a parsed URL structure.  Return
-@code{nil} if there are no data associated with it (the case for dired,
-info, or mailto URLs that need no further processing).
+This function synchronously retrieves the data specified by @var{url},
+and returns a buffer containing the data.  The return value is
+@code{nil} if there is no data associated with the URL (as is the case
+for @code{dired}, @code{info}, and @code{mailto} URLs).
 @end defun
 
 @defun url-retrieve url callback &optional cbargs silent no-cookies
-Retrieve @var{url} asynchronously and call @var{callback} with args
-@var{cbargs} when finished.  The callback is called when the object
-has been completely retrieved, with the current buffer containing the
-object and any MIME headers associated with it.  @var{url} is either a
-string or a parsed URL structure.  Returns the buffer @var{url} will
-load into, or @code{nil} if the process has already completed.
-If the optional argument @var{silent} is non-@code{nil}, suppress
-progress messages.  If the optional argument @var{no-cookies} is
-non-@code{nil}, do not store or send cookies.
+This function retrieves @var{url} asynchronously, calling the function
+@var{callback} when the object has been completely retrieved.  The
+return value is the buffer into which the data will be inserted, or
+@code{nil} if the process has already completed.
+
+The callback function is called this way:
+
+@example
+(apply @var{callback} @var{status} @var{cbargs})
+@end example
+
+@noindent
+where @var{status} is a plist representing what happened during the
+retrieval, with most recent events first, or an empty list if no
+events have occurred.  Each pair in the plist is one of:
+
+@table @code
+@item (:redirect @var{redirected-to})
+This means that the request was redirected to the URL
+@var{redirected-to}.
+
+@item (:error (@var{error-symbol} . @var{data}))
+This means that an error occurred.  If so desired, the error can be
+signaled with @code{(signal @var{error-symbol} @var{data})}.
+@end table
+
+When the callback function is called, the current buffer is the one
+containing the retrieved data (if any).  The buffer also contains any
+MIME headers associated with the data retrieval.
+
+If the optional argument @var{silent} is non-@code{nil}, progress
+messages are suppressed.  If the optional argument @var{no-cookies} is
+non-@code{nil}, cookies are not stored or sent.
 @end defun
 
-@vindex url-queue-parallel-processes
-@vindex url-queue-timeout
 @defun url-queue-retrieve url callback &optional cbargs silent no-cookies
-This acts like the @code{url-retrieve} function, but with limits on
-the degree of parallelism.  The option @code{url-queue-parallel-processes}
-controls the number of concurrent processes, and the option
-@code{url-queue-timeout} sets a timeout in seconds.
+This function acts like @code{url-retrieve}, but with limits on the
+number of concurrently-running network processes.  The option
+@code{url-queue-parallel-processes} controls the number of concurrent
+processes, and the option @code{url-queue-timeout} sets a timeout in
+seconds.
+
+To use this function, you must @code{(require 'url-queue)}.
 @end defun
 
+@vindex url-queue-parallel-processes
+@defopt url-queue-parallel-processes
+The value of this option is an integer specifying the maximum number
+of concurrent @code{url-queue-retrieve} network processes.  If the
+number of @code{url-queue-retrieve} calls is larger than this number,
+later ones are queued until ealier ones are finished.
+@end defopt
+
+@vindex url-queue-timeout
+@defopt url-queue-timeout
+The value of this option is a number specifying the maximum lifetime
+of a @code{url-queue-retrieve} network process, once it is started.
+If a process is not finished by then, it is killed and removed from
+the queue.
+@end defopt
+
 @node Supported URL Types
 @chapter Supported URL Types
 
+This chapter describes functions and variables affecting URL retrieval
+for specific schemes.
+
 @menu
 * http/https::                  Hypertext Transfer Protocol.
 * file/ftp::                    Local files and FTP archives.
@@ -264,48 +373,31 @@ controls the number of concurrent processes, and the option
 * irc::                         Internet Relay Chat.
 * data::                        Embedded data URLs.
 * nfs::                         Networked File System
-@c * finger::
-@c * gopher::
-@c * netrek::
-@c * prospero::
-* cid::                         Content-ID.
-* about::
 * ldap::                        Lightweight Directory Access Protocol
-* imap::                        IMAP mailboxes.
 * man::                         Unix man pages.
 @end menu
 
 @node http/https
 @section @code{http} and @code{https}
 
-The scheme @code{http} is Hypertext Transfer Protocol.  The library
-supports version 1.1, specified in RFC 2616.  (This supersedes 1.0,
-defined in RFC 1945) HTTP URLs have the following form, where most of
-the parts are optional:
-@example
-http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment}
-@end example
-@c The @code{:@var{port}} part is optional, and @var{port} defaults to
-@c 80.  The @code{/@var{path}} part, if present, is a slash-separated
-@c series elements.  The @code{?@var{searchpart}}, if present, is the
-@c query for a search or the content of a form submission.  The
-@c @code{#fragment} part, if present, is a location in the document.
-
-The scheme @code{https} is a secure version of @code{http}, with
-transmission via SSL.  It is defined in RFC 2069.  Its default port is
-443.  This scheme depends on SSL support in Emacs via the
-@file{ssl.el} library and is actually implemented by forcing the
-@code{ssl} gateway method to be used.  @xref{Gateways in general}.
+The @code{http} scheme refers to the Hypertext Transfer Protocol.  The
+@code{url} library supports HTTP version 1.1, specified in RFC 2616.
+Its default port is 80.
+
+  The @code{https} scheme is a secure version of @code{http}, with
+transmission via SSL.  It is defined in RFC 2069, and its default port
+is 443.  When using @code{https}, the @code{url} library performs SSL
+encryption via the @code{ssl} library, by forcing the @code{ssl}
+gateway method to be used.  @xref{Gateways in general}.
 
 @defopt url-honor-refresh-requests
-This controls honoring of HTTP @samp{Refresh} headers by which
-servers can direct clients to reload documents from the same URL or a
-or different one.  @code{nil} means they will not be honored,
-@code{t} (the default) means they will always be honored, and
-otherwise the user will be asked on each request.
+If this option is non-@code{nil} (the default), the @code{url} library
+honors the HTTP @samp{Refresh} header, which is used by servers to
+direct clients to reload documents from the same URL or a or different
+one.  If the value is @code{nil}, the @samp{Refresh} header is
+ignored; any other value means to ask the user on each request.
 @end defopt
 
-
 @menu
 * Cookies::
 * HTTP language/coding::
@@ -437,26 +529,32 @@ emacs-mime, The Emacs MIME Manual}.
 @cindex compressed files
 @cindex dired
 
+The @code{ftp} and @code{file} schemes are defined in RFC 1808.  The
+@code{url} library treats @samp{ftp:} and @samp{file:} as synonymous.
+Such URLs have the form
+
 @example
 ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
 file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
 @end example
 
-These schemes are defined in RFC 1808.
-@samp{ftp:} and @samp{file:} are synonymous in this library.  They
-allow reading arbitrary files from hosts.  Either @samp{ange-ftp}
-(Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote
-hosts.  Local files are accessed directly.
+@noindent
+If the URL specifies a local file, it is retrieved by reading the file
+contents in the usual way.  If it specifies a remote file, it is
+retrieved using the Ange-FTP package.  @xref{Remote Files,,, emacs,
+The GNU Emacs Manual}.
 
-Compressed files are handled, but support is hard-coded so that
-@code{jka-compr-compression-info-list} and so on have no affect.
-Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and
-@samp{.bz2}.
+  When retrieving a compressed file, it is automatically uncompressed
+if it has the file suffix @file{.z}, @file{.gz}, @file{.Z},
+@file{.bz2}, or @file{.xz}.  (The list of supported suffixes is
+hard-coded, and cannot be altered by customizing
+@code{jka-compr-compression-info-list}.)
 
 @defopt url-directory-index-file
-The filename to look for when indexing a directory, default
-@samp{"index.html"}.  If this file exists, and is readable, then it
-will be viewed instead of using @code{dired} to view the directory.
+This option specifies the filename to look for when a @code{file} or
+@code{ftp} URL specifies a directory.  The default is
+@file{index.html}.  If this file exists and is readable, it is viewed.
+Otherwise, Emacs visits the directory using Dired.
 @end defopt
 
 @node info
@@ -465,47 +563,53 @@ will be viewed instead of using @code{dired} to view the directory.
 @cindex Texinfo
 @findex Info-goto-node
 
+The @code{info} scheme is non-standard.  Such URLs have the form
+
 @example
 info:@var{file}#@var{node}
 @end example
 
-Info URLs are not officially defined.  They invoke
-@code{Info-goto-node} with argument @samp{(@var{file})@var{node}}.
-@samp{#@var{node}} is optional, defaulting to @samp{Top}.
+@noindent
+and are retrieved by invoking @code{Info-goto-node} with argument
+@samp{(@var{file})@var{node}}.  If @samp{#@var{node}} is omitted, the
+@samp{Top} node is opened.
 
 @node mailto
 @section mailto
 
 @cindex mailto
 @cindex email
-A mailto URL will send an email message to the address in the
-URL, for example @samp{mailto:foo@@bar.com} would compose a
-message to @samp{foo@@bar.com}.
-
-@defopt url-mail-command
-@vindex mail-user-agent
-The function called whenever url needs to send mail.  This should
-normally be left to default from @var{mail-user-agent}.  @xref{Mail
-Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}.
-@end defopt
+A @code{mailto} URL specifies an email message to be sent to a given
+email address.  For example, @samp{mailto:foo@@bar.com} specifies
+sending a message to @samp{foo@@bar.com}.  The ``retrieval method''
+for such URLs is to open a mail composition buffer in which the
+appropriate content (e.g.@: the recipient address) has been filled in.
 
-An @samp{X-Url-From} header field containing the URL of the document
-that contained the mailto URL is added if that URL is known.
+  As defined in RFC 2368, a @code{mailto} URL has the form
 
-RFC 2368 extends the definition of mailto URLs in RFC 1738.
-The form of a mailto URL is
 @example
 @samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
 @end example
-@noindent where an arbitrary number of @var{header}s can be added.  If the
-@var{header} is @samp{body}, then @var{contents} is put in the body
-otherwise a @var{header} header field is created with @var{contents}
-as its contents.  Note that the URL library does not consider any
-headers ``dangerous'' so you should check them before sending the
-message.
 
-@c Fixme: update
-Email messages are defined in @sc{rfc}822.
+@noindent
+where an arbitrary number of @var{header}s can be added.  If the
+@var{header} is @samp{body}, then @var{contents} is put in the message
+body; otherwise, a @var{header} header field is created with
+@var{contents} as its contents.  Note that the @code{url} library does
+not perform any checking of @var{header} or @var{contents}, so you
+should check them before sending the message.
+
+@defopt url-mail-command
+@vindex mail-user-agent
+The value of this variable is the function called whenever url needs
+to send mail.  This should normally be left its default, which is the
+standard mail-composition command @code{compose-mail}.  @xref{Sending
+Mail,,, emacs, The GNU Emacs Manual}.
+@end defopt
+
+  If the document containing the @code{mailto} URL itself possessed a
+known URL, Emacs automatically inserts an @samp{X-Url-From} header
+field into the mail buffer, specifying that URL.
 
 @node news/nntp/snews
 @section @code{news}, @code{nntp} and @code{snews}
@@ -515,11 +619,13 @@ Email messages are defined in @sc{rfc}822.
 @cindex NNTP
 @cindex snews
 
-@c draft-gilman-news-url-01
-The network news URL scheme take the following forms following RFC
-1738 except that for compatibility with other clients, host and port
-fields may be included in news URLs though they are properly only
-allowed for nntp an snews.
+The @code{news}, @code{nntp}, and @code{snews} schemes, defined in RFC
+1738, are used for reading Usenet newsgroups.  For compatibility with
+non-standard-compliant news clients, the @code{url} library allows
+host and port fields to be included in @code{news} URLs, even though
+they are properly only allowed for @code{nntp} and @code{snews}.
+
+  @code{news} and @code{nntp} URLs have the following form:
 
 @table @samp
 @item news:@var{newsgroup}
@@ -534,24 +640,22 @@ Retrieves a list of all available newsgroups;
 Similar to the @samp{news} versions.
 @end table
 
-@samp{:@var{port}} is optional and defaults to :119.
-
-@samp{snews} is the same as @samp{nntp} except that the default port
-is :563.
-@cindex SSL
-(It is tunneled through SSL.)
+  The default port for @code{nntp} (and @code{news}) is 119.  The
+difference between an @code{nntp} URL and a @code{news} URL is that an
+@code{nttp} URL may specify an article by its number.  The
+@samp{snews} scheme is the same as @samp{nntp}, except that it is
+tunneled through SSL and has default port 563.
 
-An @samp{nntp} URL is the same as a news URL, except that the URL may
-specify an article by its number.
+  These URLs are retrieved via the Gnus package.
 
-@defopt url-news-server
-This variable can be used to override the default news server.
-Usually this will be set by the Gnus package, which is used to fetch
-news.
 @cindex environment variable
 @vindex NNTPSERVER
-It may be set from the conventional environment variable
-@code{NNTPSERVER}.
+@defopt url-news-server
+This variable specifies the default news server from which to fetch
+news, if no server was specified in the URL.  The default value,
+@code{nil}, means to use the server specified by the standard
+environment variable @samp{NNTPSERVER}, or @samp{news} if that
+environment variable is unset.
 @end defopt
 
 @node rlogin/telnet/tn3270
@@ -562,12 +666,15 @@ It may be set from the conventional environment variable
 @cindex terminal emulation
 @findex terminal-emulator
 
-These URL schemes from RFC 1738 for logon via a terminal emulator have
-the form
+These URL schemes are defined in RFC 1738, and are used for logging in
+via a terminal emulator.  They have the form
+
 @example
 telnet://@var{user}:@var{password}@@@var{host}:@var{port}
 @end example
-but the @code{:@var{password}} component is ignored.
+
+@noindent
+but the @var{password} component is ignored.
 
 To handle rlogin, telnet and tn3270 URLs, a @code{rlogin},
 @code{telnet} or @code{tn3270} (the program names and arguments are
@@ -581,39 +688,43 @@ Well-known ports are used if the URL does not specify a port.
 @cindex ZEN IRC
 @cindex ERC
 @cindex rcirc
-@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt)
-@dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc}
-session to a function named in @code{url-irc-function}.
+
+  The @code{irc} scheme is defined in the Internet Draft at
+@url{http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt} (which
+was never approved as an RFC).  Such URLs have the form
+
+@example
+irc://@var{host}:@var{port}/@var{target},@var{needpass}
+@end example
+
+@noindent
+and are retrieved by opening an @acronym{IRC} session using the
+function specified by @code{url-irc-function}.
 
 @defopt url-irc-function
-A function to actually open an IRC connection.
-This function
-must take five arguments, @var{host}, @var{port}, @var{channel},
-@var{user} and @var{password}.  The @var{channel} argument specifies the
-channel to join immediately, this can be @code{nil}.  By default this is
-@code{url-irc-rcirc}.
+The value of this option is a function, which is called to open an IRC
+connection for @code{irc} URLs.  This function must take five
+arguments, @var{host}, @var{port}, @var{channel}, @var{user} and
+@var{password}.  The @var{channel} argument specifies the channel to
+join immediately, and may be @code{nil}.
+
+The default is @code{url-irc-rcirc}, which uses the Rcirc package.
+Other options are @code{url-irc-erc} (which uses ERC) and
+@code{url-irc-zenirc} (which uses ZenIRC).
 @end defopt
-@defun url-irc-rcirc host port channel user password
-Processes the arguments and lets @code{rcirc} handle the session.
-@end defun
-@defun url-irc-erc host port channel user password
-Processes the arguments and lets @code{ERC} handle the session.
-@end defun
-@defun url-irc-zenirc host port channel user password
-Processes the arguments and lets @code{zenirc} handle the session.
-@end defun
 
 @node data
 @section data
 @cindex data URLs
 
+  The @code{data} scheme, defined in RFC 2397, contains MIME data in
+the URL itself.  Such URLs have the form
+
 @example
 data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data}
 @end example
 
-Data URLs contain MIME data in the URL itself.  They are defined in
-RFC 2397.
-
+@noindent
 @var{media-type} is a MIME @samp{Content-Type} string, possibly
 including parameters.  It defaults to
 @samp{text/plain;charset=US-ASCII}.  The @samp{text/plain} can be
@@ -626,14 +737,14 @@ present, the @var{data} are base64-encoded.
 @cindex Network File System
 @cindex automounter
 
+The @code{nfs} scheme, defined in RFC 2224, is similar to @code{ftp}
+except that it points to a file on a remote host that is handled by an
+NFS automounter on the local host.  Such URLs have the form
+
 @example
 nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
 @end example
 
-The @samp{nfs:} scheme is defined in RFC 2224.  It is similar to
-@samp{ftp:} except that it points to a file on a remote host that is
-handled by the automounter on the local host.
-
 @defvar url-nfs-automounter-directory-spec
 @end defvar
 A string saying how to invoke the NFS automounter.  Certain @samp{%}
@@ -656,15 +767,6 @@ A literal @samp{%}.
 
 Each can be used any number of times.
 
-@node cid
-@section cid
-@cindex Content-ID
-
-RFC 2111
-
-@node about
-@section about
-
 @node ldap
 @section ldap
 @cindex LDAP
@@ -672,50 +774,21 @@ RFC 2111
 
 The LDAP scheme is defined in RFC 2255.
 
-@node imap
-@section imap
-@cindex IMAP
-
-RFC 2192
-
 @node man
 @section man
 @cindex @command{man}
 @cindex Unix man pages
 @findex man
 
+The @code{man} scheme is a non-standard one.  Such URLs have the form
+
 @example
 @samp{man:@var{page-spec}}
 @end example
 
-This is a non-standard scheme.  @var{page-spec} is passed directly to
-the Lisp @code{man} function.
-
-@node Defining New URLs
-@chapter Defining New URLs
-
-@menu
-* Naming conventions::
-* Required functions::
-* Optional functions::
-* Asynchronous fetching::
-* Supporting file-name-handlers::
-@end menu
-
-@node Naming conventions
-@section Naming conventions
-
-@node Required functions
-@section Required functions
-
-@node Optional functions
-@section Optional functions
-
-@node Asynchronous fetching
-@section Asynchronous fetching
-
-@node Supporting file-name-handlers
-@section Supporting file-name-handlers
+@noindent
+and are retrieved by passing @var{page-spec} to the Lisp function
+@code{man}.
 
 @node General Facilities
 @chapter General Facilities
@@ -1136,11 +1209,9 @@ You can use this function to do completion of URLs from the history.
 @node Customization
 @chapter Customization
 
-@section Environment Variables
-
 @cindex environment variables
-The following environment variables affect the library's operation at
-startup.
+  The following environment variables affect the @code{url} library's
+operation at startup.
 
 @table @code
 @item TMPDIR
@@ -1150,10 +1221,21 @@ If this is defined, @var{url-temporary-directory} is initialized from
 it.
 @end table
 
-@section General User Options
+  The following user options affect the general operation of
+@code{url} library.
+
+@defopt url-configuration-directory
+@cindex configuration files
+The value of this variable specifies the name of the directory where
+the @code{url} library stores its various configuration files, cache
+files, etc.
 
-The following user options, settable with Customize, affect the
-general operation of the package.
+The default value specifies a subdirectory named @file{url/} in the
+standard Emacs user data directory specified by the variable
+@code{user-emacs-directory} (normally @file{~/.emacs.d}).  However,
+the old default was @file{~/.url}, and this directory is used instead
+if it exists.
+@end defopt
 
 @defopt url-debug
 @cindex debugging