\input texinfo
-@setfilename url.info
+@setfilename ../info/url
@settitle URL Programmer's Manual
@iftex
@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
+Invariant Sections being
``GNU GENERAL PUBLIC LICENSE''. A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''
@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
* General Facilities:: URLs can be cached, accessed via a gateway
and tracked in a history list.
* Customization:: Variables you can alter.
-* Function Index::
-* Variable Index::
-* Concept Index::
+* Function Index::
+* Variable Index::
+* Concept Index::
@end menu
@node Getting Started
@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.
-
-The library depends on MIME support provided by the @samp{mm-}
-packages from Gnus 5.8 or later. @xref{(emacs-mime)Top, The MIME
-library}.
+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::
+* Configuration::
* Parsed URLs:: URLs are parsed into vector structures.
@end menu
@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
@menu
* http/https:: Hypertext Transfer Protocol.
-* file/ftp:: Local files and FTP archives.
+* file/ftp:: Local files and FTP archives.
* info:: Emacs `Info' pages.
* mailto:: Sending email.
* news/nntp/snews:: Usenet news.
@c * netrek::
@c * prospero::
* cid:: Content-ID.
-* about::
+* about::
* ldap:: Lightweight Directory Access Protocol
* imap:: IMAP mailboxes.
* man:: Unix man pages.
@menu
-* Cookies::
-* HTTP language/coding::
-* HTTP URL Options::
-* Dealing with HTTP documents::
+* Cookies::
+* HTTP language/coding::
+* HTTP URL Options::
+* Dealing with HTTP documents::
@end menu
@node Cookies
@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. @xref{(emacs-mime)Top, The MIME
-library}. The MIME library doesn't provide a clean function to do
-that, so the URL library does.
+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.
@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}.
+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, 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
allowed for nntp an snews.
@table @samp
-@item news:@var{newsgroup}
+@item news:@var{newsgroup}
Retrieves a list of messages in @var{newsgroup};
@item news:@var{message-id}
Retrieves the message with the given @var{message-id};
-@item news:*
+@item news:*
Retrieves a list of all available newsgroups;
@item nntp://@var{host}:@var{port}/@var{newsgroup}
@itemx nntp://@var{host}:@var{port}/@var{message-id}
@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
-@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt)
+@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}.
+session to a function named in @code{url-irc-function}.
@defopt url-irc-function
A function to actually open an IRC connection.
@samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be
omitted but the charset parameter supplied. If @samp{;base64} is
present, the @var{data} are base64-encoded.
-
+
@node nfs
@section nfs
@cindex NFS
@chapter Defining New URLs
@menu
-* Naming conventions::
-* Required functions::
-* Optional functions::
-* Asynchronous fetching::
-* Supporting file-name-handlers::
+* Naming conventions::
+* Required functions::
+* Optional functions::
+* Asynchronous fetching::
+* Supporting file-name-handlers::
@end menu
@node Naming conventions
@chapter General Facilities
@menu
-* Disk Caching::
-* Proxies::
-* Gateways in general::
-* History::
+* Disk Caching::
+* Proxies::
+* Gateways in general::
+* History::
@end menu
@node Disk Caching
@end smallexample
@end defun
-@c Fixme: never actually used currently?
+@c Fixme: never actually used currently?
@c @defopt url-standalone-mode
@c @cindex Relying on cache
@c @cindex Cache only mode
@node Proxies
@section Proxies and Gatewaying
-@c fixme: check/document url-ns stuff
+@c fixme: check/document url-ns stuff
@cindex proxy servers
@cindex proxies
@cindex environment variables
@noindent says to contact all machines in the @samp{aventail.com} and
@samp{seanet.com} domains directly, as well as the machine named
@samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY}
-and @code{no_proxy} are also tried, in that order.
+and @code{no_proxy} are also tried, in that order.
Proxies may also be specified directly in Lisp.
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
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::
+@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
only if an affirmative answer is given.
@end defopt
@defopt url-gateway-method
-@c fixme: describe gatewaying
-A symbol specifying the type of gateway support to use fro connexions
+@c fixme: describe gatewaying
+A symbol specifying the type of gateway support to use for connections
from the local machine. The supported methods are:
@table @code