Merge from origin/emacs-25

[gnu-emacs] / doc / misc / url.texi

diff --git a/doc/misc/url.texi b/doc/misc/url.texi
index a1fa31fe6ce0498000523ca6ea50acda66079730..14a4c96cc47845cc2de360b96d16a62f39df3034 100644 (file)
--- a/doc/misc/url.texi
+++ b/doc/misc/url.texi
@@ -1,8 +1,7 @@
 \input texinfo
 @setfilename ../../info/url.info
 @settitle URL Programmer's Manual
-
-@documentencoding UTF-8
+@include docstyle.texi
 
 @iftex
 @c @finalout
@@ -22,7 +21,7 @@
 @copying
 This is the manual for the @code{url} Emacs Lisp library.
 
-Copyright @copyright{} 1993--1999, 2002, 2004--2015 Free Software
+Copyright @copyright{} 1993--1999, 2002, 2004--2016 Free Software
 Foundation, Inc.
 
 @quotation
@@ -374,9 +373,10 @@ for specific schemes.
 * 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
@@ -417,13 +417,19 @@ cookies, if there are any.  You can remove a cookie using the
 @kbd{C-k} (@code{url-cookie-delete}) command.
 @end defun
 
+@defun url-cookie-delete-cookies &optional regexp
+This function takes a regular expression as its parameters and deletes
+all cookies from that domain.  If @var{regexp} is @code{nil}, delete
+all cookies.
+@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
@@ -550,8 +556,8 @@ file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
 @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},
@@ -594,7 +600,7 @@ sending a message to @samp{foo@@bar.com}.  The ``retrieval method''
 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}]]}
@@ -683,7 +689,8 @@ telnet://@var{user}:@var{password}@@@var{host}:@var{port}
 @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
@@ -799,6 +806,38 @@ The @code{man} scheme is a non-standard one.  Such URLs have the form
 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
 
@@ -1116,7 +1155,7 @@ This the @samp{nslookup} program.  It is @code{"nslookup"} by default.
 @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
@@ -1297,6 +1336,14 @@ Connect directly.
 @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