[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to url.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to url.texi |
|
Date: |
Thu, 06 Sep 2007 05:02:50 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 05:02:50
Index: url.texi
===================================================================
RCS file: url.texi
diff -N url.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ url.texi 6 Sep 2007 05:02:50 -0000 1.1
@@ -0,0 +1,1202 @@
+\input texinfo
address@hidden ../info/url
address@hidden URL Programmer's Manual
+
address@hidden
address@hidden @finalout
address@hidden iftex
address@hidden @setchapternewpage odd
address@hidden @smallbook
+
address@hidden
+\overfullrule=0pt
+%\global\baselineskip 30pt % for printing in double space
address@hidden tex
address@hidden World Wide Web
address@hidden GNU Emacs Lisp
address@hidden
+* URL: (url). URL loading package.
address@hidden direntry
+
address@hidden
+This file documents the URL loading package.
+
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002,
+2004, 2005, 2006, 2007 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.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being
+``GNU GENERAL PUBLIC LICENSE''. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
address@hidden ifnottex
+
address@hidden
address@hidden
address@hidden 6
address@hidden @titlefont{URL}
address@hidden @titlefont{Programmer's Manual}
address@hidden 4
address@hidden First Edition, URL Version 2.0
address@hidden 1
address@hidden @center December 1999
address@hidden 5
address@hidden William M. Perry
address@hidden @email{wmperry@@gnu.org}
address@hidden David Love
address@hidden @email{fx@@gnu.org}
address@hidden
address@hidden 0pt plus 1filll
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002,
+2003, 2004, 2005, 2006, 2007 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.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being
+``GNU GENERAL PUBLIC LICENSE''. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
address@hidden titlepage
address@hidden
address@hidden Top
address@hidden URL
+
+
+
address@hidden
+* Getting Started:: Preparing your program to use URLs.
+* 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.
+* GNU Free Documentation License:: The license for this documentation.
+* Function Index::
+* Variable Index::
+* Concept Index::
address@hidden menu
+
address@hidden Getting Started
address@hidden Getting Started
address@hidden URLs, definition
address@hidden URIs
+
address@hidden Resource Locators} (URLs) are a specific form of
address@hidden Resource Identifiers} (URI) described in RFC 2396 which
+updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource
+agents.
+
+URIs have the form @var{scheme}:@var{scheme-specific-part}, where the
address@hidden supported by this library are described below.
address@hidden URL Types}.
+
+FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270,
+IRC and gopher URLs all have the form
+
address@hidden
address@hidden://@address@hidden@@@address@hidden@r{[}:@address@hidden@r{[}/@address@hidden
address@hidden example
address@hidden
+where @address@hidden and @address@hidden delimit optional parts.
address@hidden sometimes takes the form @var{username}:@var{password}
+but you should beware of the security risks of sending cleartext
+passwords. @var{hostname} may be a domain name or a dotted decimal
+address. If the @samp{:@var{port}} is omitted then the library will
+use the `well known' port for that service when accessing URLs. With
+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.
+
address@hidden
+* Configuration::
+* Parsed URLs:: URLs are parsed into vector structures.
address@hidden menu
+
address@hidden Configuration
address@hidden Configuration
+
address@hidden url-configuration-directory
address@hidden @file{~/.url}
address@hidden configuration files
+The directory in which URL configuration files, the cache etc.,
+reside. Default @file{~/.url}.
address@hidden defvar
+
address@hidden Parsed URLs
address@hidden Parsed URLs
address@hidden parsed URLs
+The library functions typically operate on @dfn{parsed} versions of
+URLs. These are actually vectors of the form:
+
address@hidden
address@hidden @var{user} @var{password} @var{host} @var{port} @var{file}
@var{target} @var{attributes} @var{full}]
address@hidden example
+
address@hidden where
address@hidden @var
address@hidden type
+is the type of the URL scheme, e.g., @code{http}
address@hidden user
+is the username associated with it, or @code{nil};
address@hidden password
+is the user password associated with it, or @code{nil};
address@hidden host
+is the host name associated with it, or @code{nil};
address@hidden port
+is the port number associated with it, or @code{nil};
address@hidden file
+is the `file' part of it, or @code{nil}. This doesn't necessarily
+actually refer to a file;
address@hidden target
+is the target part, or @code{nil};
address@hidden attributes
+is the attributes associated with it, or @code{nil};
address@hidden full
+is @code{t} for a fully-specified URL, with a host part indicated by
address@hidden//} after the scheme part.
address@hidden table
+
address@hidden url-type
address@hidden url-user
address@hidden url-password
address@hidden url-host
address@hidden url-port
address@hidden url-file
address@hidden url-target
address@hidden url-attributes
address@hidden url-full
address@hidden url-set-type
address@hidden url-set-user
address@hidden url-set-password
address@hidden url-set-host
address@hidden url-set-port
address@hidden url-set-file
address@hidden url-set-target
address@hidden url-set-attributes
address@hidden url-set-full
+These attributes have accessors named @address@hidden, where
address@hidden is the name of one of the elements above, e.g.,
address@hidden Similarly, there are setters of the form
address@hidden@var{part}}.
+
+There are functions for parsing and unparsing between the string and
+vector forms.
+
address@hidden url-generic-parse-url url
+Return a parsed version of the string @var{url}.
address@hidden defun
+
address@hidden url-recreate-url url
address@hidden unparsing URLs
+Recreates a URL string from the parsed @var{url}.
address@hidden defun
+
address@hidden Retrieving URLs
address@hidden Retrieving URLs
+
address@hidden 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
address@hidden if there are no data associated with it (the case for dired,
+info, or mailto URLs that need no further processing).
address@hidden defun
+
address@hidden url-retrieve url callback &optional cbargs
+Retrieve @var{url} asynchronously and call @var{callback} with args
address@hidden 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.
address@hidden defun
+
address@hidden Supported URL Types
address@hidden Supported URL Types
+
address@hidden
+* http/https:: Hypertext Transfer Protocol.
+* file/ftp:: Local files and FTP archives.
+* info:: Emacs `Info' pages.
+* mailto:: Sending email.
+* news/nntp/snews:: Usenet news.
+* rlogin/telnet/tn3270:: Remote host connectivity.
+* irc:: Internet Relay Chat.
+* data:: Embedded data URLs.
+* nfs:: Networked File System
address@hidden * finger::
address@hidden * gopher::
address@hidden * netrek::
address@hidden * prospero::
+* cid:: Content-ID.
+* about::
+* ldap:: Lightweight Directory Access Protocol
+* imap:: IMAP mailboxes.
+* man:: Unix man pages.
address@hidden menu
+
address@hidden http/https
address@hidden @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:
address@hidden
+http://@var{user}:@var{password}@@@var{host}:@var{port}/@address@hidden@var{fragment}
address@hidden example
address@hidden The @code{:@var{port}} part is optional, and @var{port} defaults
to
address@hidden 80. The @code{/@var{path}} part, if present, is a
slash-separated
address@hidden series elements. The @address@hidden, if present, is the
address@hidden query for a search or the content of a form submission. The
address@hidden @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
address@hidden library and is actually implemented by forcing the
address@hidden gateway method to be used. @xref{Gateways in general}.
+
address@hidden url-honor-refresh-requests
+This controls honouring 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 honoured,
address@hidden (the default) means they will always be honoured, and
+otherwise the user will be asked on each request.
address@hidden defopt
+
+
address@hidden
+* Cookies::
+* HTTP language/coding::
+* HTTP URL Options::
+* Dealing with HTTP documents::
address@hidden menu
+
address@hidden Cookies
address@hidden Cookies
+
address@hidden url-cookie-file
+The file in which cookies are stored, defaulting to @file{cookies} in
+the directory specified by @code{url-configuration-directory}.
address@hidden defopt
+
address@hidden url-cookie-confirmation
+Specifies whether confirmation is require to accept cookies.
address@hidden defopt
+
address@hidden url-cookie-multiple-line
+Specifies whether to put all cookies for the server on one line in the
+HTTP request to satisfy broken servers like
address@hidden://www.hotmail.com}.
address@hidden defopt
+
address@hidden url-cookie-trusted-urls
+A list of regular expressions matching URLs from which to accept
+cookies always.
address@hidden defopt
+
address@hidden url-cookie-untrusted-urls
+A list of regular expressions matching URLs from which to reject
+cookies always.
address@hidden defopt
+
address@hidden url-cookie-save-interval
+The number of seconds between automatic saves of cookies to disk.
+Default is one hour.
address@hidden defopt
+
+
address@hidden HTTP language/coding
address@hidden Language and Encoding Preferences
+
+HTTP allows clients to express preferences for the language and
+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{;address@hidden to specify its
+preference level, a decimal number from 0 to 1; e.g., for
address@hidden, @address@hidden"de, en-gb;q=0.8,
+en;q=0.7"}}. An element that has no @samp{;q} specification has
+preference level 1.
+
address@hidden url-mime-charset-string
address@hidden character sets
address@hidden coding systems
+This variable specifies a preference for character sets when documents
+can be served in more than one encoding.
+
+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}.
address@hidden defopt
+
address@hidden url-mime-language-string
address@hidden language preferences
+A string specifying the preferred language when servers can serve
+files in several languages. Use RFC 1766 abbreviations, e.g.,
address@hidden for English, @samp{de} for German.
+
+The string can be @code{"*"} to get the first available language (as
+opposed to the default).
address@hidden defopt
+
address@hidden HTTP URL Options
address@hidden HTTP URL Options
+
+HTTP supports an @samp{OPTIONS} method describing things supported by
+the address@hidden
+
address@hidden url-http-options url
+Returns a property list describing options available for URL. The
+property list members are:
+
address@hidden @code
address@hidden methods
+A list of symbols specifying what HTTP methods the resource
+supports.
+
address@hidden dav
address@hidden DAV
+A list of numbers specifying what DAV protocol/schema versions are
+supported.
+
address@hidden dasl
address@hidden DASL
+A list of supported DASL search types supported (string form).
+
address@hidden ranges
+A list of the units available for use in partial document fetches.
+
address@hidden p3p
address@hidden P3P
+The @dfn{Platform For Privacy Protection} description for the resource.
+Currently this is just the raw header contents.
address@hidden table
+
address@hidden defun
+
address@hidden Dealing with HTTP documents
address@hidden Dealing with HTTP documents
+
+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{Top,, Emacs MIME,
+emacs-mime, The Emacs MIME Manual}. The URL package provides a
+function to do this in general:
+
address@hidden url-decode-text-part handle &optional coding
+This function decodes charset-encoded text in the current buffer. In
+Emacs, the buffer is expected to be unibyte initially and is set to
+multibyte after decoding.
+HANDLE is the MIME handle of the original part. CODING is an explicit
+coding to use, overriding what the MIME headers specify.
+The coding system used for the decoding is returned.
+
+Note that this function doesn't deal with @samp{http-equiv} charset
+specifications in HTML @samp{<meta>} elements.
address@hidden defun
+
address@hidden file/ftp
address@hidden file and ftp
address@hidden files
address@hidden FTP
address@hidden File Transfer Protocol
address@hidden compressed files
address@hidden dired
+
address@hidden
+ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
+file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
address@hidden example
+
+These schemes are defined in RFC 1808.
address@hidden:} 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.
+
+Compressed files are handled, but support is hard-coded so that
address@hidden and so on have no affect.
+Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and
address@hidden
+
address@hidden url-directory-index-file
+The filename to look for when indexing a directory, default
address@hidden"index.html"}. If this file exists, and is readable, then it
+will be viewed instead of using @code{dired} to view the directory.
address@hidden defopt
+
address@hidden info
address@hidden info
address@hidden Info
address@hidden Texinfo
address@hidden Info-goto-node
+
address@hidden
+info:@address@hidden
address@hidden example
+
+Info URLs are not officially defined. They invoke
address@hidden with argument @samp{(@var{file})@var{node}}.
address@hidden@var{node}} is optional, defaulting to @samp{Top}.
+
address@hidden mailto
address@hidden mailto
+
address@hidden mailto
address@hidden 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}.
+
address@hidden url-mail-command
address@hidden 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}.
address@hidden defopt
+
+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.
+
+RFC 2368 extends the definition of mailto URLs in RFC 1738.
+The form of a mailto URL is
address@hidden
address@hidden:@address@hidden@var{contents}[&@address@hidden
address@hidden example
address@hidden where an arbitrary number of @var{header}s can be added. If the
address@hidden 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.
+
address@hidden Fixme: update
+Email messages are defined in @sc{rfc}822.
+
address@hidden news/nntp/snews
address@hidden @code{news}, @code{nntp} and @code{snews}
address@hidden news
address@hidden network news
address@hidden usenet
address@hidden NNTP
address@hidden snews
+
address@hidden 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.
+
address@hidden @samp
address@hidden news:@var{newsgroup}
+Retrieves a list of messages in @var{newsgroup};
address@hidden news:@var{message-id}
+Retrieves the message with the given @var{message-id};
address@hidden news:*
+Retrieves a list of all available newsgroups;
address@hidden nntp://@var{host}:@var{port}/@var{newsgroup}
address@hidden nntp://@var{host}:@var{port}/@var{message-id}
address@hidden nntp://@var{host}:@var{port}/*
+Similar to the @samp{news} versions.
address@hidden table
+
address@hidden:@var{port}} is optional and defaults to :119.
+
address@hidden is the same as @samp{nntp} except that the default port
+is :563.
address@hidden 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.
+
address@hidden 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.
address@hidden environment variable
address@hidden NNTPSERVER
+It may be set from the conventional environment variable
address@hidden
address@hidden defopt
+
address@hidden rlogin/telnet/tn3270
address@hidden rlogin, telnet and tn3270
address@hidden rlogin
address@hidden telnet
address@hidden tn3270
address@hidden terminal emulation
address@hidden terminal-emulator
+
+These URL schemes from RFC 1738 for logon via a terminal emulator have
+the form
address@hidden
+telnet://@var{user}:@var{password}@@@var{host}:@var{port}
address@hidden example
+but the @code{:@var{password}} component is ignored.
+
+To handle rlogin, telnet and tn3270 URLs, a @code{rlogin},
address@hidden or @code{tn3270} (the program names and arguments are
+hardcoded) session is run in a @code{terminal-emulator} buffer.
+Well-known ports are used if the URL does not specify a port.
+
address@hidden irc
address@hidden irc
address@hidden IRC
address@hidden Internet Relay Chat
address@hidden ZEN IRC
address@hidden ERC
address@hidden rcirc
address@hidden Fixme: reference (was
http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt)
address@hidden Relay Chat} (IRC) is handled by handing off the @sc{irc}
+session to a function named in @code{url-irc-function}.
+
address@hidden url-irc-function
+A function to actually open an IRC connection.
+This function
+must take five arguments, @var{host}, @var{port}, @var{channel},
address@hidden and @var{password}. The @var{channel} argument specifies the
+channel to join immediately, this can be @code{nil}. By default this is
address@hidden
address@hidden defopt
address@hidden url-irc-rcirc host port channel user password
+Processes the arguments and lets @code{rcirc} handle the session.
address@hidden defun
address@hidden url-irc-erc host port channel user password
+Processes the arguments and lets @code{ERC} handle the session.
address@hidden defun
address@hidden url-irc-zenirc host port channel user password
+Processes the arguments and lets @code{zenirc} handle the session.
address@hidden defun
+
address@hidden data
address@hidden data
address@hidden data URLs
+
address@hidden
+data:@address@hidden@address@hidden;@address@hidden,@var{data}
address@hidden example
+
+Data URLs contain MIME data in the URL itself. They are defined in
+RFC 2397.
+
address@hidden is a MIME @samp{Content-Type} string, possibly
+including parameters. It defaults to
address@hidden/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.
+
address@hidden nfs
address@hidden nfs
address@hidden NFS
address@hidden Network File System
address@hidden automounter
+
address@hidden
+nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
address@hidden example
+
+The @samp{nfs:} scheme is defined in RFC 2224. It is similar to
address@hidden:} except that it points to a file on a remote host that is
+handled by the automounter on the local host.
+
address@hidden url-nfs-automounter-directory-spec
address@hidden defvar
+A string saying how to invoke the NFS automounter. Certain @samp{%}
+sequences are recognized:
+
address@hidden @samp
address@hidden %h
+The hostname of the NFS server;
address@hidden %n
+The port number of the NFS server;
address@hidden %u
+The username to use to authenticate;
address@hidden %p
+The password to use to authenticate;
address@hidden %f
+The filename on the remote server;
address@hidden %%
+A literal @samp{%}.
address@hidden table
+
+Each can be used any number of times.
+
address@hidden cid
address@hidden cid
address@hidden Content-ID
+
+RFC 2111
+
address@hidden about
address@hidden about
+
address@hidden ldap
address@hidden ldap
address@hidden LDAP
address@hidden Lightweight Directory Access Protocol
+
+The LDAP scheme is defined in RFC 2255.
+
address@hidden imap
address@hidden imap
address@hidden IMAP
+
+RFC 2192
+
address@hidden man
address@hidden man
address@hidden @command{man}
address@hidden Unix man pages
address@hidden man
+
address@hidden
address@hidden:@var{page-spec}}
address@hidden example
+
+This is a non-standard scheme. @var{page-spec} is passed directly to
+the Lisp @code{man} function.
+
address@hidden Defining New URLs
address@hidden Defining New URLs
+
address@hidden
+* Naming conventions::
+* Required functions::
+* Optional functions::
+* Asynchronous fetching::
+* Supporting file-name-handlers::
address@hidden menu
+
address@hidden Naming conventions
address@hidden Naming conventions
+
address@hidden Required functions
address@hidden Required functions
+
address@hidden Optional functions
address@hidden Optional functions
+
address@hidden Asynchronous fetching
address@hidden Asynchronous fetching
+
address@hidden Supporting file-name-handlers
address@hidden Supporting file-name-handlers
+
address@hidden General Facilities
address@hidden General Facilities
+
address@hidden
+* Disk Caching::
+* Proxies::
+* Gateways in general::
+* History::
address@hidden menu
+
address@hidden Disk Caching
address@hidden Disk Caching
address@hidden Caching
address@hidden Persistent Cache
address@hidden Disk Cache
+
+The disk cache stores retrieved documents locally, whence they can be
+retrieved more quickly. When requesting a URL that is in the cache,
+the library checks to see if the page has changed since it was last
+retrieved from the remote machine. If not, the local copy is used,
+saving the transmission over the network.
address@hidden Cleaning the cache
address@hidden Clearing the cache
address@hidden Cache cleaning
+Currently the cache isn't cleared automatically.
address@hidden Running the @code{clean-cache} shell script
address@hidden fist is recommended, to allow for future cleaning of the cache.
This
address@hidden shell script will remove all files that have not been accessed
since it
address@hidden was last run. To keep the cache pared down, it is recommended
that this
address@hidden script be run from @i{at} or @i{cron} (see the manual pages for
address@hidden crontab(5) or at(1) for more information)
+
address@hidden url-automatic-caching
+Setting this variable address@hidden causes documents to be cached
+automatically.
address@hidden defopt
+
address@hidden url-cache-directory
+This variable specifies the
+directory to store the cache files. It defaults to sub-directory
address@hidden of @code{url-configuration-directory}.
address@hidden defopt
+
address@hidden Fixme: function v. option, but neither used.
address@hidden @findex url-cache-expired
address@hidden @defopt url-cache-expired
address@hidden This is a function to decide whether or not a cache entry has
expired.
address@hidden It takes two times as it parameters and returns address@hidden
if the
address@hidden second time is ``too old'' when compared with the first time.
address@hidden @end defopt
+
address@hidden url-cache-creation-function
+The cache relies on a scheme for mapping URLs to files in the cache.
+This variable names a function which sets the type of cache to use.
+It takes a URL as argument and returns the absolute file name of the
+corresponding cache file. The two supplied possibilities are
address@hidden and
address@hidden
address@hidden defopt
+
address@hidden url-cache-create-filename-using-md5 url
+Creates a cache file name from @var{url} using MD5 hashing.
+This is creates entries with very few cache collisions and is fast.
address@hidden MD5
address@hidden
+(url-cache-create-filename-using-md5 "http://www.example.com/foo/bar";)
+ @result{}
"/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f"
address@hidden smallexample
address@hidden defun
+
address@hidden url-cache-create-filename-human-readable url
+Creates a cache file name from @var{url} more obviously connected to
address@hidden than for @code{url-cache-create-filename-using-md5}, but
+more likely to conflict with other files.
address@hidden
+(url-cache-create-filename-human-readable "http://www.example.com/foo/bar";)
+ @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar"
address@hidden smallexample
address@hidden defun
+
address@hidden Fixme: never actually used currently?
address@hidden @defopt url-standalone-mode
address@hidden @cindex Relying on cache
address@hidden @cindex Cache only mode
address@hidden @cindex Standalone mode
address@hidden If this variable is address@hidden, the library relies solely on
the
address@hidden cache for fetching documents and avoids checking if they have
changed
address@hidden on remote servers.
address@hidden @end defopt
+
address@hidden With a large cache of documents on the local disk, it can be
very handy
address@hidden when traveling, or any other time the network connection is not
active
address@hidden (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3
can rely
address@hidden solely on its cache, and avoid checking to see if the page has
changed
address@hidden on the remote server. In the case of a dial-on-demand PPP
connection,
address@hidden this will keep the phone line free as long as possible, only
bringing up
address@hidden the PPP connection when asking for a page that is not located in
the
address@hidden cache. This is very useful for demonstrations as well.
+
address@hidden Proxies
address@hidden Proxies and Gatewaying
+
address@hidden fixme: check/document url-ns stuff
address@hidden proxy servers
address@hidden proxies
address@hidden environment variables
address@hidden HTTP_PROXY
+Proxy servers are commonly used to provide gateways through firewalls
+or as caches serving some more-or-less local network. Each protocol
+(HTTP, FTP, etc.)@: can have a different gateway server. Proxying is
+conventionally configured commonly amongst different programs through
+environment variables of the form @address@hidden, where
address@hidden is one of the supported network protocols (@code{http},
address@hidden etc.). The library recognizes such variables in either
+upper or lower case. Their values are of one of the forms:
address@hidden @bullet
address@hidden @address@hidden:@var{port}}
address@hidden A full URL;
address@hidden Simply a host name.
address@hidden itemize
+
address@hidden NO_PROXY
+The @code{NO_PROXY} environment variable specifies URLs that should be
+excluded from proxying (on servers that should be contacted directly).
+This should be a comma-separated list of hostnames, domain names, or a
+mixture of both. Asterisks can be used as wildcards, but other
+clients may not support that. Domain names may be indicated by a
+leading dot. For example:
address@hidden
+NO_PROXY="*.aventail.com,home.com,.seanet.com"
address@hidden example
address@hidden says to contact all machines in the @samp{aventail.com} and
address@hidden domains directly, as well as the machine named
address@hidden If @code{NO_PROXY} isn't defined, @code{no_PROXY}
+and @code{no_proxy} are also tried, in that order.
+
+Proxies may also be specified directly in Lisp.
+
address@hidden url-proxy-services
+This variable is an alist of URL schemes and proxy servers that
+gateway them. The items are of the form @address@hidden(@var{scheme}
+. @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is
+gatewayed through @var{portnumber} on the specified @var{host}. An
+exception is the pseudo scheme @code{"no_proxy"}, which is paired with
+a regexp matching host names not to be proxied. This variable is
+initialized from the environment as above.
+
address@hidden
+(setq url-proxy-services
+ '(("http" . "proxy.aventail.com:80")
+ ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com")))
address@hidden example
address@hidden defopt
+
address@hidden Gateways in general
address@hidden Gateways in General
address@hidden gateways
address@hidden firewalls
+
+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
+connections in some cases and pass through some sort of gateway in
address@hidden (which only operate over HTTP) are
+implemented using this.} The library's basic function responsible for
+making connections is @code{url-open-stream}.
+
address@hidden url-open-stream name buffer host service
address@hidden opening a stream
address@hidden 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
+connection if @code{url-gateway-unplugged} is address@hidden
address@hidden defun
+
address@hidden 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 connections are made
+through the gateway.
address@hidden defvar
+
address@hidden url-gateway-method
+This variable controls which gateway method is used. It may be useful
+to bind it temporarily in some applications. It has values taken from
+a list of symbols. Possible values are:
+
address@hidden @code
address@hidden telnet
address@hidden @command{telnet}
+Use this method if you must first telnet and log into a gateway host,
+and then run telnet from that host to connect to outside machines.
+
address@hidden rlogin
address@hidden @command{rlogin}
+This method is identical to @code{telnet}, but uses @command{rlogin}
+to log into the remote machine without having to send the username and
+password over the wire every time.
+
address@hidden socks
address@hidden @sc{socks}
+Use if the firewall has a @sc{socks} gateway running on it. The
address@hidden v5 protocol is defined in RFC 1928.
+
address@hidden @item ssl
address@hidden This probably shouldn't be documented
address@hidden Fixme: why not? -- fx
+
address@hidden native
+This method uses Emacs's builtin networking directly. This is the
+default. It can be used only if there is no firewall blocking access.
address@hidden table
address@hidden defvar
+
+The following variables control the gateway methods.
+
address@hidden url-gateway-telnet-host
+The gateway host to telnet to. Once logged in there, you then telnet
+out to the hosts you want to connect to.
address@hidden defopt
address@hidden url-gateway-telnet-parameters
+This should be a list of parameters to pass to the @command{telnet} program.
address@hidden defopt
address@hidden url-gateway-telnet-password-prompt
+This is a regular expression that matches the password prompt when
+logging in.
address@hidden defopt
address@hidden url-gateway-telnet-login-prompt
+This is a regular expression that matches the username prompt when
+logging in.
address@hidden defopt
address@hidden url-gateway-telnet-user-name
+The username to log in with.
address@hidden defopt
address@hidden url-gateway-telnet-password
+The password to send when logging in.
address@hidden defopt
address@hidden url-gateway-prompt-pattern
+This is a regular expression that matches the shell prompt.
address@hidden defopt
+
address@hidden url-gateway-rlogin-host
+Host to @samp{rlogin} to before telnetting out.
address@hidden defopt
address@hidden url-gateway-rlogin-parameters
+Parameters to pass to @samp{rsh}.
address@hidden defopt
address@hidden url-gateway-rlogin-user-name
+User name to use when logging in to the gateway.
address@hidden defopt
address@hidden url-gateway-prompt-pattern
+This is a regular expression that matches the shell prompt.
address@hidden defopt
+
address@hidden socks-server
+This specifies the default server, it takes the form
address@hidden@code{("Default server" @var{server} @var{port} @var{version})}}
+where @var{version} can be either 4 or 5.
address@hidden defopt
address@hidden socks-password
+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.
address@hidden defvar
address@hidden socks-username
+This is the username to use when authenticating yourself to the
address@hidden server. By default this is your login name.
address@hidden defvar
address@hidden socks-timeout
+This controls how long, in seconds, to wait for responses from the
address@hidden server; it is 5 by default.
address@hidden defvar
address@hidden fixme: these have been effectively commented-out in the code
address@hidden @defopt socks-server-aliases
address@hidden This a list of server aliases. It is a list of aliases of the
form
address@hidden @var{(alias hostname port version)}.
address@hidden @end defopt
address@hidden @defopt socks-network-aliases
address@hidden This a list of network aliases. Each entry in the list takes
the form
address@hidden @var{(alias (network))} where @var{alias} is a string that names
the
address@hidden @var{network}. The networks can contain a pair (not a dotted
pair) of
address@hidden @sc{ip} addresses which specify a range of @sc{ip} addresses, an
@sc{ip}
address@hidden address and a netmask, a domain name or a unique hostname or
@sc{ip}
address@hidden address.
address@hidden @end defopt
address@hidden @defopt socks-redirection-rules
address@hidden This a list of redirection rules. Each rule take the form
address@hidden @var{(Destination network Connection type)} where
@var{Destination
address@hidden network} is a network alias from @code{socks-network-aliases} and
address@hidden @var{Connection type} can be @code{nil} in which case a direct
address@hidden connection is used, or it can be an alias from
address@hidden @code{socks-server-aliases} in which case that server is used as
a
address@hidden proxy.
address@hidden @end defopt
address@hidden socks-nslookup-program
address@hidden @command{nslookup}
+This the @samp{nslookup} program. It is @code{"nslookup"} by default.
address@hidden defopt
+
address@hidden
+* Suppressing network connections::
address@hidden menu
address@hidden * Broken hostname resolution::
+
address@hidden Suppressing network connections
address@hidden Suppressing Network Connections
+
address@hidden network connections, suppressing
address@hidden suppressing network connections
address@hidden bugs, HTML
address@hidden HTML `bugs'
+In some circumstances it is desirable to suppress making network
+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.
+
address@hidden url-gateway-unplugged
+If this variable is address@hidden new network connections are never
+opened by the URL library.
address@hidden defvar
+
address@hidden @node Broken hostname resolution
address@hidden @subsection Broken Hostname Resolution
+
address@hidden @cindex hostname resolver
address@hidden @cindex resolver, hostname
address@hidden Some C libraries do not include the hostname resolver routines in
address@hidden their static libraries. If Emacs was linked statically, and was
not
address@hidden linked with the resolver libraries, it will not be able to get
to any
address@hidden machines off the local network. This is characterized by being
able
address@hidden to reach someplace with a raw ip number, but not its hostname
address@hidden (@url{http://129.79.254.191/} works, but
address@hidden @url{http://www.cs.indiana.edu/} doesn't). This used to happen
on
address@hidden SunOS4 and Ultrix, but is now probably now rare. If Emacs can't
be
address@hidden rebuilt linked against the resolver library, it can use the
external
address@hidden @command{nslookup} program instead.
+
address@hidden @defopt url-gateway-broken-resolution
address@hidden @cindex @code{nslookup} program
address@hidden @cindex program, @code{nslookup}
address@hidden If address@hidden, this variable says to use the program
specified by
address@hidden @code{url-gateway-nslookup-program} program to do hostname
resolution.
address@hidden @end defopt
+
address@hidden @defopt url-gateway-nslookup-program
address@hidden The name of the program to do hostname lookup if Emacs can't do
it
address@hidden directly. This program should expect a single argument on the
command
address@hidden line---the hostname to resolve---and should produce output
similar to
address@hidden the standard Unix @command{nslookup} program:
address@hidden @example
address@hidden Name: www.cs.indiana.edu
address@hidden Address: 129.79.254.191
address@hidden @end example
address@hidden @end defopt
+
address@hidden History
address@hidden History
+
address@hidden url-do-setup
+The library can maintain a global history list tracking URLs accessed.
+URL completion can be done from it. The history mechanism is set up
+automatically via @code{url-do-setup} when it is configured to be on.
+Note that the size of the history list is currently not limited.
+
address@hidden url-history-hash-table
+The history `list' is actually a hash table,
address@hidden It contains access times keyed by URL
+strings. The times are in the format returned by @code{current-time}.
+
address@hidden url-history-update-url url time
+This function updates the history table with an entry for @var{url}
+accessed at the given @var{time}.
address@hidden defun
+
address@hidden url-history-track
+If address@hidden, the library will keep track of all the URLs
+accessed. If it is @code{t}, the list is saved to disk at the end of
+each Emacs session. The default is @code{nil}.
address@hidden defopt
+
address@hidden url-history-file
+The file storing the history list between sessions. It defaults to
address@hidden in @code{url-configuration-directory}.
address@hidden defopt
+
address@hidden url-history-save-interval
address@hidden url-history-setup-save-timer
+The number of seconds between automatic saves of the history list.
+Default is one hour. Note that if you change this variable directly,
+rather than using Custom, after @code{url-do-setup} has been run, you
+need to run the function @code{url-history-setup-save-timer}.
address@hidden defopt
+
address@hidden url-history-parse-history &optional fname
+Parses the history file @var{fname} (default @code{url-history-file})
+and sets up the history list.
address@hidden defun
+
address@hidden url-history-save-history &optional fname
+Saves the current history to file @var{fname} (default
address@hidden).
address@hidden defun
+
address@hidden url-completion-function string predicate function
+You can use this function to do completion of URLs from the history.
address@hidden defun
+
address@hidden Customization
address@hidden Customization
+
address@hidden Environment Variables
+
address@hidden environment variables
+The following environment variables affect the library's operation at
+startup.
+
address@hidden @code
address@hidden TMPDIR
address@hidden TMPDIR
address@hidden url-temporary-directory
+If this is defined, @var{url-temporary-directory} is initialized from
+it.
address@hidden table
+
address@hidden General User Options
+
+The following user options, settable with Customize, affect the
+general operation of the package.
+
address@hidden url-debug
address@hidden debugging
+Specifies the types of debug messages the library which are logged to
+the @code{*URL-DEBUG*} buffer.
address@hidden means log all messages.
+A number means log all messages and show them with @code{message}.
+If may also be a list of the types of messages to be logged.
address@hidden defopt
address@hidden url-personal-mail-address
address@hidden defopt
address@hidden url-privacy-level
address@hidden defopt
address@hidden url-uncompressor-alist
address@hidden defopt
address@hidden url-passwd-entry-func
address@hidden defopt
address@hidden url-standalone-mode
address@hidden defopt
address@hidden url-bad-port-list
address@hidden defopt
address@hidden url-max-password-attempts
address@hidden defopt
address@hidden url-temporary-directory
address@hidden defopt
address@hidden url-show-status
address@hidden defopt
address@hidden url-confirmation-func
+The function to use for asking yes or no functions. This is normally
+either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another
+function taking a single argument (the prompt) and returning @code{t}
+only if an affirmative answer is given.
address@hidden defopt
address@hidden url-gateway-method
address@hidden fixme: describe gatewaying
+A symbol specifying the type of gateway support to use for connections
+from the local machine. The supported methods are:
+
address@hidden @code
address@hidden telnet
+Run telnet in a subprocess to connect;
address@hidden rlogin
+Rlogin to another machine to connect;
address@hidden socks
+Connect through a socks server;
address@hidden ssl
+Connect with SSL;
address@hidden native
+Connect directly.
address@hidden table
address@hidden defopt
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden Function Index
address@hidden Command and Function Index
address@hidden fn
+
address@hidden Variable Index
address@hidden Variable Index
address@hidden vr
+
address@hidden Concept Index
address@hidden Concept Index
address@hidden cp
+
address@hidden odd
address@hidden
address@hidden
+
address@hidden
+ arch-tag: c96be356-7e2d-4196-bcda-b13246c5c3f0
address@hidden ignore