@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
@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
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
@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
@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