\input texinfo
-@setfilename ../../info/url
+@setfilename ../../info/url.info
@settitle URL Programmer's Manual
-
-@documentencoding UTF-8
-@documentlanguage en
+@include docstyle.texi
@iftex
@c @finalout
@copying
This is the manual for the @code{url} Emacs Lisp library.
-Copyright @copyright{} 1993--1999, 2002, 2004--2013 Free Software
+Copyright @copyright{} 1993--1999, 2002, 2004--2016 Free Software
Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
passed through @code{url-encode-url} before using it, to ensure that
it is properly URI-encoded (@pxref{URI Encoding}).
-@defun url-retrieve-synchronously url
+@defun url-retrieve-synchronously url silent no-cookies
This function synchronously retrieves the data specified by @var{url},
and returns a buffer containing the data. The return value is
@code{nil} if there is no data associated with the URL (as is the case
for @code{dired}, @code{info}, and @code{mailto} URLs).
+
+If the optional argument @var{silent} is non-@code{nil}, progress
+messages are suppressed. If the optional argument @var{no-cookies} is
+non-@code{nil}, cookies are not stored or sent.
@end defun
@defun url-retrieve url callback &optional cbargs silent no-cookies
* rlogin/telnet/tn3270:: Remote host connectivity.
* irc:: Internet Relay Chat.
* data:: Embedded data URLs.
-* nfs:: Networked File System
-* ldap:: Lightweight Directory Access Protocol
+* nfs:: Networked File System.
+* ldap:: Lightweight Directory Access Protocol.
* man:: Unix man pages.
+* Tramp:: Schemes supported via Tramp.
@end menu
@node http/https
@node Cookies
@subsection Cookies
+@findex url-cookie-delete
+@defun url-cookie-list
+This command creates a @file{*url cookies*} buffer listing the current
+cookies, if there are any. You can remove a cookie using the
+@kbd{C-k} (@code{url-cookie-delete}) command.
+@end defun
+
@defopt url-cookie-file
The file in which cookies are stored, defaulting to @file{cookies} in
the directory specified by @code{url-configuration-directory}.
@end defopt
@defopt url-cookie-confirmation
-Specifies whether confirmation is require to accept cookies.
+Specifies whether confirmation is required to accept cookies.
@end defopt
@defopt url-cookie-multiple-line
@noindent
If the URL specifies a local file, it is retrieved by reading the file
contents in the usual way. If it specifies a remote file, it is
-retrieved using the Ange-FTP package. @xref{Remote Files,,, emacs,
-The GNU Emacs Manual}.
+retrieved using either the Tramp or the Ange-FTP package.
+@xref{Remote Files,,, emacs, The GNU Emacs Manual}.
When retrieving a compressed file, it is automatically uncompressed
if it has the file suffix @file{.z}, @file{.gz}, @file{.Z},
for such URLs is to open a mail composition buffer in which the
appropriate content (e.g., the recipient address) has been filled in.
- As defined in RFC 2368, a @code{mailto} URL has the form
+ As defined in RFC 6068, a @code{mailto} URL can have the form
@example
@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
@end example
@noindent
-but the @var{password} component is ignored.
+but the @var{password} component is ignored. By default, the
+@code{telnet} scheme is handled via Tramp (@pxref{Tramp}).
To handle rlogin, telnet and tn3270 URLs, a @code{rlogin},
@code{telnet} or @code{tn3270} (the program names and arguments are
and are retrieved by passing @var{page-spec} to the Lisp function
@code{man}.
+@node Tramp
+@section URL Types Supported via Tramp
+
+@vindex url-tramp-protocols
+Some additional URL types are supported by passing them to Tramp
+(@pxref{Top, The Tramp Manual,, tramp, The Tramp Manual}). These
+protocols are listed in the @code{url-tramp-protocols} variable, which
+you can customize. The default value includes the following
+protocols:
+
+@table @code
+@item ftp
+The file transfer protocol. @xref{file/ftp}.
+
+@item ssh
+@cindex ssh
+The secure shell protocol. @xref{Inline Methods,,, tramp, The Tramp
+Manual}.
+
+@item scp
+@cindex scp
+The secure file copy protocol. @xref{External Methods,,, tramp, The
+Tramp Manual}.
+
+@item rsync
+@cindex rsync
+The remote sync protocol.
+
+@item telnet
+The telnet protocol.
+@end table
+
@node General Facilities
@chapter General Facilities
@end defun
@defun url-cache-expired
-This function returns non-nil if a cache entry has expired (or is absent).
+This function returns non-@code{nil} if a cache entry has expired (or is absent).
The arguments are a URL and optional expiration delay in seconds
(default @var{url-cache-expire-time}).
@end defun
@cindex network connections, suppressing
@cindex suppressing network connections
@cindex bugs, HTML
-@cindex HTML `bugs'
+@cindex 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
@defopt url-debug
@cindex debugging
Specifies the types of debug messages which are logged to
-the @code{*URL-DEBUG*} buffer.
+the @file{*URL-DEBUG*} buffer.
@code{t} means log all messages.
A number means log all messages and show them with @code{message}.
It may also be a list of the types of messages to be logged.
@end table
@end defopt
+@defopt url-user-agent
+The User Agent string used for sending HTTP/HTTPS requests. The value
+should be a string or a function of no arguments that returns a
+string. The default value is @w{@samp{User-Agent: @var{package-name}
+URL/Emacs}}, where @var{package-name} is the value of
+@code{url-package-name} and its version, if they are non-@code{nil}.
+@end defopt
+
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi