@ifnottex
This file documents the URL loading package.
-Copyright (C) 1996, 1997, 1998, 1999, 2002, 2004 Free Software Foundation
-Copyright (C) 1993, 1994, 1995, 1996 William M. Perry
+Copyright @copyright{} 1996, 1997, 1998, 1999, 2002, 2004,
+2005, 2006 Free Software Foundation, Inc.@*
+Copyright @copyright{} 1993, 1994, 1995, 1996 William M. Perry
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being
``GNU GENERAL PUBLIC LICENSE''. A copy of the
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993, 1994, 1995, 1996 William M. Perry@*
-Copyright @copyright{} 1996, 1997, 1998, 1999, 2002 Free Software Foundation
+Copyright @copyright{} 1996, 1997, 1998, 1999, 2002, 2003, 2004,
+2005, 2006 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being
``GNU GENERAL PUBLIC LICENSE''. A copy of the
@var{scheme}s supported by this library are described below.
@xref{Supported URL Types}.
-FTP NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270,
+FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270,
IRC and gopher URLs all have the form
@example
the possible exception of @code{telnet}, it is rare for ports to be
specified, and it is possible using a non-standard port may have
undesired consequences if a different service is listening on that
-port (e.g.@: an HTTP URL specifying the SMTP port can cause mail to be
-sent).@c , but @xref{Other Variables, url-bad-port-list}.
-The meaning of
-the @var{path} component depends on the service.
+port (e.g., an HTTP URL specifying the SMTP port can cause mail to be
+sent). @c , but @xref{Other Variables, url-bad-port-list}.
+The meaning of the @var{path} component depends on the service.
@menu
* Configuration::
@noindent where
@table @var
@item type
-is the type of the URL scheme, e.g.@: @code{http}
+is the type of the URL scheme, e.g., @code{http}
@item user
is the username associated with it, or @code{nil};
@item password
@findex url-set-attributes
@findex url-set-full
These attributes have accessors named @code{url-@var{part}}, where
-@var{part} is the name of one of the elements above, e.g.@:
+@var{part} is the name of one of the elements above, e.g.,
@code{url-host}. Similarly, there are setters of the form
@code{url-set-@var{part}}.
@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
-@var{nil} if there are no data associated with it (the case for dired,
+@code{nil} if there are no data associated with it (the case for dired,
info, or mailto URLs that need no further processing).
@end defun
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 @var{nil} if the process has already completed.
+load into, or @code{nil} if the process has already completed.
@end defun
@node Supported URL Types
@subsection Language and Encoding Preferences
HTTP allows clients to express preferences for the language and
-encoding of documents which servers may honour.
+encoding of documents which servers may honour. For each of these
+variables, the value is a string; it can specify a single choice, or
+it can be a comma-separated list.
+
+Normally this list ordered by descending preference. However, each
+element can be followed by @samp{;q=@var{priority}} to specify its
+preference level, a decimal number from 0 to 1; e.g., for
+@code{url-mime-language-string}, @w{@code{"de, en-gb;q=0.8,
+en;q=0.7"}}. An element that has no @samp{;q} specification has
+preference level 1.
@defopt url-mime-charset-string
@cindex character sets
This variable specifies a preference for character sets when documents
can be served in more than one encoding.
-HTTP allows specifying a list of MIME charsets which indicate your
-preferred character set encodings, e.g.@: Latin-9 or Big5, and these
-can be weighted. In Emacs 21 this list is generated automatically
-from the list of defined coding systems which have associated MIME
-types. These are sorted by coding priority. @xref{Recognize Coding,
-, Recognizing Coding Systems, emacs, GNU Emacs Manual}.
+HTTP allows specifying a series of MIME charsets which indicate your
+preferred character set encodings, e.g., Latin-9 or Big5, and these
+can be weighted. The default series is generated automatically from
+the associated MIME types of all defined coding systems, sorted by the
+coding system priority specified in Emacs. @xref{Recognize Coding, ,
+Recognizing Coding Systems, emacs, The GNU Emacs Manual}.
@end defopt
@defopt url-mime-language-string
@cindex language preferences
A string specifying the preferred language when servers can serve
-files in several languages. Use RFC 1766 abbreviations, e.g.@:
-@samp{en} for English, @samp{de} for German. It can be a
-comma-separated list in descending order of preference. The ordering
-can be made explicit using `q' factors defined by HTTP, e.g.@:
-@w{@samp{de, en-gb;q=0.8, en;q=0.7}}. It can be @samp{*} to get the
-first available language (as opposed to the default).
+files in several languages. Use RFC 1766 abbreviations, e.g.,
+@samp{en} for English, @samp{de} for German.
+
+The string can be @code{"*"} to get the first available language (as
+opposed to the default).
@end defopt
@node HTTP URL Options
HTTP URLs are retrieved into a buffer containing the HTTP headers
followed by the body. Since the headers are quasi-MIME, they may be
-processed using the MIME library. @inforef{Top, The MIME library,
-emacs-mime}. The URL package provides a function to do this in
-general:
+processed using the MIME library. @xref{Top,, Emacs MIME,
+emacs-mime, The Emacs MIME Manual}. The URL package provides a
+function to do this in general:
@defun url-decode-text-part handle &optional coding
This function decodes charset-encoded text in the current buffer. In
@end example
These schemes are defined in RFC 1808.
-@samp{ftp:} and @samp{file:} are synonomous in this library. They
-allow reading arbitary files from hosts. Either @samp{ange-ftp}
+@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.
@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, GNU Emacs Manual}.
+Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}.
@end defopt
An @samp{X-Url-From} header field containing the URL of the document
@example
@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
@end example
-@noindent where an arbitary number of @var{header}s can be added. If the
+@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
@samp{snews} is the same as @samp{nntp} except that the default port
is :563.
@cindex SSL
-(It is tunnelled through SSL.)
+(It is tunneled through SSL.)
An @samp{nntp} URL is the same as a news URL, except that the URL may
specify an article by its number.
@cindex IRC
@cindex Internet Relay Chat
@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}.
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-zenirc}.
+@code{url-irc-rcirc}.
@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
The library provides a general gateway layer through which all
networking passes. It can both control access to the network and
provide access through gateways in firewalls. This may make direct
-connexions in some cases and pass through some sort of gateway in
+connections in some cases and pass through some sort of gateway in
others.@footnote{Proxies (which only operate over HTTP) are
implemented using this.} The library's basic function responsible for
-making connexions is @code{url-open-stream}.
+making connections is @code{url-open-stream}.
@defun url-open-stream name buffer host service
@cindex opening a stream
@cindex stream, opening
Open a stream to @var{host}, possibly via a gateway. The other
arguments are as for @code{open-network-stream}. This will not make a
-connexion if @code{url-gateway-unplugged} is non-@code{nil}.
+connection if @code{url-gateway-unplugged} is non-@code{nil}.
@end defun
@defvar url-gateway-local-host-regexp
This is a regular expression that matches local hosts that do not
-require the use of a gateway. If @code{nil}, all connexions are made
+require the use of a gateway. If @code{nil}, all connections are made
through the gateway.
@end defvar
Host to @samp{rlogin} to before telnetting out.
@end defopt
@defopt url-gateway-rlogin-parameters
-Parametres to pass to @samp{rsh}.
+Parameters to pass to @samp{rsh}.
@end defopt
@defopt url-gateway-rlogin-user-name
User name to use when logging in to the gateway.
where @var{version} can be either 4 or 5.
@end defopt
@defvar socks-password
-If this is @code{nil} then you will be asked for the passward,
+If this is @code{nil} then you will be asked for the password,
otherwise it will be used as the password for authenticating you to
the @sc{socks} server.
@end defvar
@end defopt
@menu
-* Suppressing network connexions::
+* Suppressing network connections::
@end menu
@c * Broken hostname resolution::
-@node Suppressing network connexions
-@subsection Suppressing Network Connexions
+@node Suppressing network connections
+@subsection Suppressing Network Connections
-@cindex network connexions, suppressing
-@cindex suppressing network connexions
+@cindex network connections, suppressing
+@cindex suppressing network connections
@cindex bugs, HTML
@cindex HTML `bugs'
In some circumstances it is desirable to suppress making network
-connexions. A typical case is when rendering HTML in a mail user
+connections. A typical case is when rendering HTML in a mail user
agent, when external URLs should not be activated, particularly to
avoid `bugs' which `call home' by fetch single-pixel images and the
like. To arrange this, bind the following variable for the duration
of such processing.
@defvar url-gateway-unplugged
-If this variable is non-@code{nil} new network connexions are never
+If this variable is non-@code{nil} new network connections are never
opened by the URL library.
@end defvar
@c @cindex resolver, hostname
@c Some C libraries do not include the hostname resolver routines in
@c their static libraries. If Emacs was linked statically, and was not
-@c linked with the resolver libraries, it wil not be able to get to any
+@c linked with the resolver libraries, it will not be able to get to any
@c machines off the local network. This is characterized by being able
@c to reach someplace with a raw ip number, but not its hostname
@c (@url{http://129.79.254.191/} works, but
strings. The times are in the format returned by @code{current-time}.
@defun url-history-update-url url time
-This function updates the hsitory table with an entry for @var{url}
-accessed at the gievn @var{time}.
+This function updates the history table with an entry for @var{url}
+accessed at the given @var{time}.
@end defun
@defopt url-history-track
If non-@code{nil}, the library will keep track of all the URLs
-accessed. If is is @code{t}, the list is saved to disk at the end of
+accessed. If it is @code{t}, the list is saved to disk at the end of
each Emacs session. The default is @code{nil}.
@end defopt
@end defopt
@defopt url-gateway-method
@c fixme: describe gatewaying
-A symbol specifying the type of gateway support to use fro connexions
+A symbol specifying the type of gateway support to use for connections
from the local machine. The supported methods are:
@table @code