diff options
| -rw-r--r-- | doc/misc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/misc/url.texi | 198 | ||||
| -rw-r--r-- | etc/NEWS | 9 |
3 files changed, 126 insertions, 87 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 700d432ef44..d7af0d79c68 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,9 @@ +2012-11-08 Chong Yidong <cyd@gnu.org> + + * url.texi (Introduction): Rename from Getting Started. Rewrite + the introduction. + (URI Parsing): Rewrite. Omit the obsolete attributes slot. + 2012-11-07 Glenn Morris <rgm@gnu.org> * cl.texi (Obsolete Setf Customization): diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 898a9994a86..9124edfcf73 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -18,7 +18,7 @@ @end direntry @copying -This file documents the Emacs Lisp URL loading package. +This file documents @code{url} Emacs Lisp library. Copyright @copyright{} 1993-1999, 2002, 2004-2012 Free Software Foundation, Inc. @@ -57,7 +57,8 @@ developing GNU and promoting software freedom.'' @end ifnottex @menu -* Getting Started:: Preparing your program to use URLs. +* Introduction:: About the @code{url} library. +* URI Parsing:: Parsing (and unparsing) URIs. * 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. @@ -70,93 +71,132 @@ developing GNU and promoting software freedom.'' * Concept Index:: @end menu -@node Getting Started -@chapter Getting Started -@cindex URLs, definition -@cindex URIs +@node Introduction +@chapter Introduction +@cindex URL +@cindex URI +@cindex uniform resource identifier +@cindex uniform resource locator -@dfn{Uniform Resource Locators} (URLs) are a specific form of -@dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which -updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource -agents. +A @dfn{Uniform Resource Identifier} (URI) is a specially-formatted +name, such as an Internet address, which identifies some name or +resource. The format of URIs is described in RFC 3986, which updates +and replaces the earlier RFCs 2732, 2396, 1808, and 1738. A +@dfn{Uniform Resource Locator} (URL) is an older but still-common +term, which basically refers to a URI corresponding to a resource +which can be accessed over a network. -URIs have the form @var{scheme}:@var{scheme-specific-part}, where the -@var{scheme}s supported by this library are described below. -@xref{Supported URL Types}. - -FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270, -IRC and gopher URLs all have the form + Here are some examples of URIs (taken from RFC 3986): @example -@var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]} +ftp://ftp.is.co.za/rfc/rfc1808.txt +http://www.ietf.org/rfc/rfc2396.txt +ldap://[2001:db8::7]/c=GB?objectClass?one +mailto:John.Doe@@example.com +news:comp.infosystems.www.servers.unix +tel:+1-816-555-1212 +telnet://192.0.2.16:80/ +urn:oasis:names:specification:docbook:dtd:xml:4.1.2 @end example -@noindent -where @samp{@r{[}} and @samp{@r{]}} delimit optional parts. -@var{userinfo} 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. - -@menu -* Configuration:: -* Parsed URLs:: URLs are parsed into vector structures. -@end menu -@node Configuration -@section Configuration + This manual describes the @code{url} library, an Emacs Lisp library +for parsing URIs and retrieving the resources to which they refer. +(The library is so-named due to historical reasons; nowadays, the +``URI'' terminology is regarded as the more general one, and ``URL'' +is technically obsolete despite its widespread vernacular usage.) @defvar url-configuration-directory -@cindex @file{~/.url} @cindex configuration files -The directory in which URL configuration files, the cache etc., -reside. The old default was @file{~/.url}, and this directory -is still used if it exists. The new default is a @file{url/} -directory in @code{user-emacs-directory}, which is normally -@file{~/.emacs.d}. +The value of this variable specifies the name of the directory in +which the @code{url} library stores its various configuration files, +cache files, etc. + +The default value specifies a subdirectory named @file{url/} in the +standard Emacs user data directory specified by the variable +@code{user-emacs-directory} (normally @file{~/.emacs.d}). However, +the old default was @file{~/.url}, and this directory is used instead +if it exists. @end defvar -@node Parsed URLs -@section Parsed URLs -@cindex parsed URLs -The library functions typically operate on @dfn{parsed} versions of -URLs. These are actually CL structures (vectors) of the form: +@node URI Parsing +@chapter URI Parsing + + A URI consists of several @dfn{components}, each having a different +meaning. For example, the URI @example -[cl-struct-url @var{type} @var{user} @var{password} @var{host} @var{port} @var{filename} @var{target} @var{attributes} @var{fullness} @var{use-cookies}] +http://www.gnu.org/software/emacs/ @end example -@noindent where -@table @var +@noindent +specifies the scheme component @samp{http}, the hostname component +@samp{www.gnu.org}, and the path component @samp{/software/emacs/}. + +@cindex parsed URIs + The URI format is specified by RFC 3986. The @code{url} library +provides the Lisp function @code{url-generic-parse-url}, a +standard-compliant URI parser, as well as the unparser +@code{url-recreate-url}: + +@defun url-generic-parse-url url +This function returns a parsed version of the string @var{url}. +@end defun + +@defun url-recreate-url uri +@cindex unparsing URLs +Given a parsed URI, this function returns a corresponding URI string. +@end defun + +@cindex parsed URI + The return value of @code{url-generic-parse-url}, and the argument +expected by @code{url-recreate-url}, is a @dfn{parsed URI}, in the +form of a CL structure whose slots hold the various components of the +URI. @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. Each parsed URI structure +contains the following slots: + +@table @code @item type -is the type of the URL scheme, e.g., @code{http} +The URI scheme (a string, e.g.@: @code{http}). @xref{Supported URL +Types}, for a list of schemes that the @code{url} library knows how to +process. This slot can also be @code{nil}, if the URI is not fully +specified. + @item user -is the username associated with it, or @code{nil}; +The user name (a string), or @code{nil}. + @item password -is the user password associated with it, or @code{nil}; +The user password (a string), or @code{nil}. The use of this URI +component is strongly discouraged; nowadays, passwords are transmitted +by other means, not as part of a URI. + @item host -is the host name associated with it, or @code{nil}; +The host name (a string), or @code{nil}. If present, this is +typically a domain name or IP address. + @item port -is the port number associated with it, or @code{nil}; +The port number (an integer), or @code{nil}. Omitting this component +usually means to use the ``standard'' port associated with the URI +scheme. + @item filename -is the ``file'' part of it, or @code{nil}. This doesn't necessarily -actually refer to a file; +The combination of the ``path'' and ``query'' components of the URI (a +string), or @code{nil}. If the query component is present, it is the +substring following the first @samp{?} character, and the path +component is the substring before the @samp{?}. The meaning of these +components depends on the service; they do not necessarily refer to a +file on a disk. + @item target -is the target part, or @code{nil}; -@item attributes -is the attributes associated with it, or @code{nil}; +The fragment component (a string), or @code{nil}. The fragment +component specifies a ``secondary resource'', such as a section of a +webpage. + @item fullness -is @code{t} for a fully-specified URL, with a host part indicated by -@samp{//} after the scheme part. -@item use-cookies -is @code{nil} to neither send or store cookies to the server, @code{t} -otherwise. +This is @code{t} if the URI is fully specified, i.e.@: the +hierarchical components of the URI (the hostname and/or username +and/or password) are preceded by @samp{//}. @end table @findex url-type @@ -168,30 +208,18 @@ otherwise. @findex url-target @findex url-attributes @findex url-fullness -These attributes have accessors named @code{url-@var{part}}, where -@var{part} is the name of one of the elements above, e.g., -@code{url-host}. These attributes can be set with the same accessors -using @code{setf}: +The above slots have accessors named @code{url-@var{part}}, where +@var{part} is the slot name. For example, the accessor for the +@code{host} slot is the function @code{url-host}. The @code{url-port} +accessor returns the default port for the URI scheme if the parsed +URI's @var{port} slot is @code{nil}. + + The slots can be set using @code{setf}. For example: @example (setf (url-port url) 80) @end example -If @var{port} is @var{nil}, @code{url-port} returns the default port -of the protocol. - -There are functions for parsing and unparsing between the string and -vector forms. - -@defun url-generic-parse-url url -Return a parsed version of the string @var{url}. -@end defun - -@defun url-recreate-url url -@cindex unparsing URLs -Recreates a URL string from the parsed @var{url}. -@end defun - @node Retrieving URLs @chapter Retrieving URLs @@ -454,7 +454,9 @@ specifying URL types which should be converted to remote file names at the FFAP prompt. The default is now '("ftp"). ** Generic-x -`javascript-generic-mode' is now an obsolete alias for `js-mode'. + +--- +*** `javascript-generic-mode' is now an obsolete alias for `js-mode'. ** Ibuffer @@ -531,6 +533,7 @@ python-send-string | python-shell-send-string python-switch-to-python | python-shell-switch-to-shell python-describe-symbol | python-eldoc-at-point +--- ** reStructuredText mode *** Rebind nearly all keys making room for more keys and complying @@ -561,6 +564,7 @@ the experience for Sphinx users. *** Support `imenu' and `which-func'. +--- ** SH Script mode *** Pairing of parens/quotes uses electric-pair-mode instead of skeleton-pair. @@ -575,6 +579,7 @@ the experience for Sphinx users. for a new asynchronous shell command when the default output buffer `*Async Shell Command*' is already taken by another running command. +--- ** SQL Mode *** DB2 added `sql-db2-escape-newlines' @@ -605,7 +610,7 @@ definitions. See the manual for details. *** Remote processes are now supported also on remote Windows host. ** URL - ++++ *** Structs made by `url-generic-parse-url' have nil `attributes' slot. Previously, this slot stored semicolon-separated attribute-value pairs appended to some imap URLs, but this is not compatible with RFC 3986. |