[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 04:41:17 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:41:17
Index: url.texi
===================================================================
RCS file: url.texi
diff -N url.texi
--- url.texi 15 Apr 2007 20:57:15 -0000 1.23
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,1202 +0,0 @@
-\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
- [Emacs-diffs] Changes to url.texi,
Glenn Morris <=