[Guile-commits] 01/02: Document support for URI references.

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit d64146f2101ba4e3afacd5e724d038f20f42e26e
Author: Andy Wingo <address@hidden>
Date:   Sun Feb 8 13:12:27 2015 +0100

    Document support for URI references.
    
    * doc/ref/web.texi (URIs): Update for URI reference changes.
---
 doc/ref/web.texi |   40 +++++++++++++++++++++++++++++++---------
 1 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index c59f958..300b456 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 2010, 2011, 2012, 2013 Free Software Foundation, 
Inc.
address@hidden Copyright (C) 2010, 2011, 2012, 2013, 2015 Free Software 
Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node Web
@@ -184,6 +184,13 @@ URIs have a scheme and a path (though the path might be 
empty).  Some
 URIs have a host, and some of those have ports and userinfo.  Any URI
 might have a query part or a fragment.
 
+There is also a ``URI-reference'' data type, which is the same as a URI
+but where the scheme is optional.  In this case, the scheme is taken to
+be relative to some other related URI.  A common use of URI references
+is when you want to be vague regarding the choice of HTTP or HTTPS --
+serving a web page referring to @code{/foo.css} will use HTTPS if loaded
+over HTTPS, or HTTP otherwise.
+
 Userinfo is something of an abstraction, as some legacy URI schemes
 allowed userinfo of the form @address@hidden:@var{passwd}}.  But
 since passwords do not belong in URIs, the RFC does not want to condone
@@ -217,6 +224,16 @@ also run some consistency checks to make sure that the 
constructed URI
 is valid.
 @end deffn
 
address@hidden {Scheme Procedure} build-uri-reference [#:address@hidden@
+       [#:address@hidden [#:address@hidden [#:address@hidden @
+       [#:address@hidden""}] [#:address@hidden [#:address@hidden @
+       [#:address@hidden
+Like @code{build-uri}, but with an optional scheme.
address@hidden deffn
+
+In Guile, both URI and URI reference data types are represented in the
+same way, as URI objects.
+
 @deffn {Scheme Procedure} uri? obj
 @deffnx {Scheme Procedure} uri-scheme uri
 @deffnx {Scheme Procedure} uri-userinfo uri
@@ -226,8 +243,10 @@ is valid.
 @deffnx {Scheme Procedure} uri-query uri
 @deffnx {Scheme Procedure} uri-fragment uri
 A predicate and field accessors for the URI record type.  The URI scheme
-will be a symbol, the port either a positive, exact integer or @code{#f},
-and the rest either strings or @code{#f} if not present.
+will be a symbol, or @code{#f} if the object is a URI reference but not
+a URI.  The port will be either a positive, exact integer or @code{#f},
+and the rest of the fields will be either strings or @code{#f} if not
+present.
 @end deffn
 
 @deffn {Scheme Procedure} string->uri string
@@ -235,6 +254,11 @@ Parse @var{string} into a URI object.  Return @code{#f} if 
the string
 could not be parsed.
 @end deffn
 
address@hidden {Scheme Procedure} string->uri-reference string
+Parse @var{string} into a URI object, while not requiring a scheme.
+Return @code{#f} if the string could not be parsed.
address@hidden deffn
+
 @deffn {Scheme Procedure} uri->string uri
 Serialize @var{uri} to a string.  If the URI has a port that is the
 default port for its scheme, the port is not included in the
@@ -266,9 +290,6 @@ Returns a string of the decoded characters, or a bytevector 
if
 @var{encoding} was @code{#f}.
 @end deffn
 
-Fixme: clarify return type. indicate default values. type of
-unescaped-chars.
-
 @deffn {Scheme Procedure} uri-encode str [#:address@hidden"utf-8"}] 
[#:unescaped-chars]
 Percent-encode any character not in the character set,
 @var{unescaped-chars}.
@@ -975,9 +996,10 @@ The entity-tag of the resource.
 @end example
 @end deftypevr
 
address@hidden {HTTP Header} URI location
-A URI on which a request may be completed.  Used in combination with a
-redirecting status code to perform client-side redirection.
address@hidden {HTTP Header} URI-reference location
+A URI reference on which a request may be completed.  Used in
+combination with a redirecting status code to perform client-side
+redirection.
 @example
 (parse-header 'location "http://example.com/other";)
 @result{} #<uri ...>