diff options
author | Daniel Hartwig <mandyke@gmail.com> | 2013-03-16 17:53:53 +0800 |
---|---|---|
committer | Daniel Hartwig <mandyke@gmail.com> | 2013-03-16 17:53:53 +0800 |
commit | dc8712611597c6d5be918a69b0ce719e0675f6fe (patch) | |
tree | 72e3e7a6cf3538e12a322ee56960215f2c320f81 /module/web | |
parent | 01b83dbd1a11735519b7d6ca7b02006b45861c9c (diff) | |
download | guile-dc8712611597c6d5be918a69b0ce719e0675f6fe.tar.gz |
minor tweaks to web documentation
* doc/ref/web.texi: Say `World Wide Web'; the hyphenated form is almost
never used (c.f. w3.org).
General predicate arguments are named `obj'. Fill in arguments
omitted from some procedure definitions (e.g. `request-method').
Minor tweaks, such as using en-dash and missing markup as appropriate.
Wrap very long deffn lines.
* module/web/*.scm: Expand texinfo markup in doc strings. Synchronize
with changes in web.texi.
Diffstat (limited to 'module/web')
-rw-r--r-- | module/web/client.scm | 6 | ||||
-rw-r--r-- | module/web/http.scm | 6 | ||||
-rw-r--r-- | module/web/response.scm | 6 | ||||
-rw-r--r-- | module/web/uri.scm | 28 |
4 files changed, 22 insertions, 24 deletions
diff --git a/module/web/client.scm b/module/web/client.scm index 9fbb25bba..7d5ea4989 100644 --- a/module/web/client.scm +++ b/module/web/client.scm @@ -248,10 +248,10 @@ pass it as PORT. The port will be closed at the end of the request unless KEEP-ALIVE? is true. Any extra headers in the alist HEADERS will be added to the request. -If BODY is not #f, a message body will also be sent with the HTTP +If BODY is not ‘#f’, a message body will also be sent with the HTTP request. If BODY is a string, it is encoded according to the content-type in HEADERS, defaulting to UTF-8. Otherwise BODY should be -a bytevector, or #f for no body. Although it's allowed to send a +a bytevector, or ‘#f’ for no body. Although it's allowed to send a message body along with any request, usually only POST and PUT requests have bodies. See ‘http-put’ and ‘http-post’ documentation, for more. @@ -317,7 +317,7 @@ This function is similar to ‘http-get’, except it uses the \"HEAD\" method. See ‘http-get’ for full documentation on the various keyword arguments that are accepted by this function. -Returns two values: the resulting response, and #f. Responses to HEAD +Returns two values: the resulting response, and ‘#f’. Responses to HEAD requests do not have a body. The second value is only returned so that other procedures can treat all of the http-foo verbs identically.") diff --git a/module/web/http.scm b/module/web/http.scm index c79d57d78..712208b69 100644 --- a/module/web/http.scm +++ b/module/web/http.scm @@ -167,7 +167,7 @@ The default writer is ‘display’." (define *eof* (call-with-input-string "" read)) (define (read-header port) - "Reads one HTTP header from PORT. Returns two values: the header + "Read one HTTP header from PORT. Return two values: the header name and the parsed Scheme value. May raise an exception if the header was known but the value was invalid. @@ -220,7 +220,7 @@ as an ordered alist." (define (write-headers headers port) "Write the given header alist to PORT. Doesn't write the final -@samp{\\r\\n}, as the user might want to add another header." +‘\\r\\n’, as the user might want to add another header." (let lp ((headers headers)) (if (pair? headers) (begin @@ -971,7 +971,7 @@ as an ordered alist." (define *known-versions* '()) (define* (parse-http-version str #:optional (start 0) (end (string-length str))) - "Parse an HTTP version from STR, returning it as a major-minor + "Parse an HTTP version from STR, returning it as a major–minor pair. For example, ‘HTTP/1.1’ parses as the pair of integers, ‘(1 . 1)’." (or (let lp ((known *known-versions*)) diff --git a/module/web/response.scm b/module/web/response.scm index 3f97dffa5..570a2d7d2 100644 --- a/module/web/response.scm +++ b/module/web/response.scm @@ -267,10 +267,10 @@ closes PORT, unless KEEP-ALIVE? is true." (define* (response-body-port r #:key (decode? #t) (keep-alive? #t)) "Return an input port from which the body of R can be read. The encoding of the returned port is set according to R's ‘content-type’ -header, when it's textual, except if DECODE? is #f. Return #f when no -body is available. +header, when it's textual, except if DECODE? is ‘#f’. Return #f when +no body is available. -When KEEP-ALIVE? is #f, closing the returned port also closes R's +When KEEP-ALIVE? is ‘#f’, closing the returned port also closes R's response port." (define port (cond diff --git a/module/web/uri.scm b/module/web/uri.scm index 25406b368..7fe010096 100644 --- a/module/web/uri.scm +++ b/module/web/uri.scm @@ -53,8 +53,8 @@ (query uri-query) (fragment uri-fragment)) -(define (absolute-uri? x) - (and (uri? x) (uri-scheme x) #t)) +(define (absolute-uri? obj) + (and (uri? obj) (uri-scheme obj) #t)) (define (uri-error message . args) (throw 'uri-error message args)) @@ -309,17 +309,16 @@ serialization." which should be the name of a character encoding. Note that this function should not generally be applied to a full URI -string. For paths, use split-and-decode-uri-path instead. For query +string. For paths, use ‘split-and-decode-uri-path’ instead. For query strings, split the query on ‘&’ and ‘=’ boundaries, and decode the components separately. -Note also that percent-encoded strings encode @emph{bytes}, not -characters. There is no guarantee that a given byte sequence is a valid -string encoding. Therefore this routine may signal an error if the -decoded bytes are not valid for the given encoding. Pass ‘#f’ for -ENCODING if you want decoded bytes as a bytevector directly. -@xref{Ports, ‘set-port-encoding!’}, for more information on -character encodings. +Note also that percent-encoded strings encode _bytes_, not characters. +There is no guarantee that a given byte sequence is a valid string +encoding. Therefore this routine may signal an error if the decoded +bytes are not valid for the given encoding. Pass ‘#f’ for ENCODING if +you want decoded bytes as a bytevector directly. ‘set-port-encoding!’, +for more information on character encodings. Returns a string of the decoded characters, or a bytevector if ENCODING was ‘#f’." @@ -380,11 +379,10 @@ ENCODING was ‘#f’." UNESCAPED-CHARS. The default character set includes alphanumerics from ASCII, as well as -the special characters @samp{-}, @samp{.}, @samp{_}, and @samp{~}. Any -other character will be percent-encoded, by writing out the character to -a bytevector within the given ENCODING, then encoding each byte as -‘%HH’, where HH is the hexadecimal representation of -the byte." +the special characters ‘-’, ‘.’, ‘_’, and ‘~’. Any other character will +be percent-encoded, by writing out the character to a bytevector within +the given ENCODING, then encoding each byte as ‘%HH’, where HH is the +hexadecimal representation of the byte." (define (needs-escaped? ch) (not (char-set-contains? unescaped-chars ch))) (if (string-index str needs-escaped?) |