X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/872faefb07a9196a583fc8cbe146ab6a2ebc9c2b..d38d2a8:/doc/misc/url.texi diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 49f8f3f095..a3c6b88ea0 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -1,6 +1,7 @@ \input texinfo -@setfilename ../../info/url +@setfilename ../../info/url.info @settitle URL Programmer's Manual +@include docstyle.texi @iftex @c @finalout @@ -20,14 +21,14 @@ @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''. @@ -138,7 +139,7 @@ Given a parsed URI, this function returns the corresponding URI string. The return value of @code{url-generic-parse-url}, and the argument expected by @code{url-recreate-url}, is a @dfn{parsed URI}: a CL structure whose slots hold the various components of the URI@. -@xref{top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for +@xref{Top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for details about CL structures. Most of the other functions in the @code{url} library act on parsed URIs. @@ -288,11 +289,15 @@ string or a parsed URL structure. If it is a string, that string is 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 @@ -372,9 +377,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 @@ -408,13 +414,20 @@ ignored; any other value means to ask the user on each request. @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 @@ -541,8 +554,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}, @@ -585,7 +598,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}]]} @@ -674,7 +687,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 @@ -790,6 +804,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 @@ -863,7 +909,7 @@ more likely to conflict with other files. @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 @@ -1107,7 +1153,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 @@ -1240,7 +1286,7 @@ if it exists. @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. @@ -1288,6 +1334,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