add section on format of parsed http headers

* doc/ref/web.texi (HTTP Headers): New section. Needs some examples,
  though.

doc/ref/web.texi

@@ -33,6 +33,7 @@ the thing?  Read on!
 @menu
 * URIs::                        Universal Resource Identifiers.
 * HTTP::                        The Hyper-Text Transfer Protocol.
+* HTTP Headers::                How Guile represents specific header values.
 * Requests::                    HTTP requests.
 * Responses::                   HTTP responses.
 * Web Handlers::                A simple web application interface.
@@ -298,6 +299,248 @@ Write the first line of an HTTP response to @var{port}.
 @end defun
 
 
+@node HTTP Headers
+@subsection HTTP Headers
+
+The @code{(web http)} module defines parsers and unparsers for all
+headers defined in the HTTP/1.1 standard.  This section describes the
+parsed format of the various headers.
+
+We cannot describe the function of all of these headers, however, in
+sufficient detail.  The interested reader would do well to download a
+copy of RFC 2616 and have it on hand.
+
+To begin with, we should make a few definitions:
+
+@table @dfn
+@item key-value list
+A key-value list is a list of values.  Each value may be a string,
+a symbol, or a pair.  Known keys are parsed to symbols; otherwise keys
+are left as strings.  Keys with values are parsed to pairs, the car of
+which is the symbol or string key, and the cdr is the parsed value.
+Parsed values for known keys have key-dependent formats.  Parsed values
+for unknown keys are strings.
+
+@item param list
+A param list is a list of key-value lists.  When serialized to a string,
+items in the inner lists are separated by semicolons.  Again, known keys
+are parsed to symbols.
+
+@item quality
+A number of headers have quality values in them, which are decimal
+fractions between zero and one indicating a preference for various kinds
+of responses, which the server may choose to heed.  Given that only
+three digits are allowed in the fractional part, Guile parses quality
+values to integers between 0 and 1000 instead of inexact numbers between
+0.0 and 1.0.
+
+@item quality list
+A list of pairs, the car of which is a quality value.
+
+@item entity tag
+A pair, the car of which is an opaque string, and the cdr of which is
+true iff the entity tag is a ``strong'' entity tag.
+@end table
+
+
+@subsubsection General Headers
+
+@table @code
+@item cache-control
+A key-value list of cache-control directives. Known keys are
+@code{max-age}, @code{max-stale}, @code{min-fresh},
+@code{must-revalidate}, @code{no-cache}, @code{no-store},
+@code{no-transform}, @code{only-if-cached}, @code{private},
+@code{proxy-revalidate}, @code{public}, and @code{s-maxage}.
+
+If present, parameters to @code{max-age}, @code{max-stale},
+@code{min-fresh}, and @code{s-maxage} are all parsed as non-negative
+integers.
+
+If present, parameters to @code{private} and @code{no-cache} are parsed
+as lists of header names, represented as symbols if they are known
+headers or strings otherwise.
+
+@item connection
+A list of connection tokens.  A connection token is a string.
+
+@item date
+A SRFI-19 date record.
+
+@item pragma
+A key-value list of pragma directives.  @code{no-cache} is the only
+known key.
+
+@item trailer
+A list of header names.  Known header names are parsed to symbols,
+otherwise they are left as strings.
+
+@item transfer-encoding
+A param list of transfer codings.  @code{chunked} is the only known key.
+
+@item upgrade
+A list of strings.
+
+@item via
+A list of strings.  There may be multiple @code{via} headers in ne
+message.
+
+@item warning
+A list of warnings.  Each warning is a itself a list of four elements: a
+code, as an exact integer between 0 and 1000, a host as a string, the
+warning text as a string, and either @code{#f} or a SRFI-19 date.
+
+There may be multiple @code{warning} headers in one message.
+@end table
+
+
+@subsubsection Entity Headers
+
+@table @code
+@item allow
+A list of methods, as strings.  Methods are parsed as strings instead of
+@code{parse-http-method} so as to allow for new methods.
+
+@item content-encoding
+A list of content codings, as strings.
+
+@item content-language
+A list of language tags, as strings.
+
+@item content-length
+An exact, non-negative integer.
+
+@item content-location
+A URI record.
+
+@item content-md5
+A string.
+
+@item content-range
+A list of three elements: the symbol @code{bytes}, either the symbol
+@code{*} or a pair of integers, indicating the byte rage, and either
+@code{*} or an integer, for the instance length.
+
+@item content-type
+A pair, the car of which is the media type as a string, and the cdr is
+an alist of parameters, with strings as keys and values.
+
+For example, @code{"text/plain"} parses as @code{("text/plain")}, and
+@code{"text/plain;charset=utf-8"} parses as @code{("text/plain"
+("charset" . "utf-8"))}.
+
+@item expires
+A SRFI-19 date.
+
+@item last-modified
+A SRFI-19 date.
+
+@end table
+
+
+@subsubsection Request Headers
+
+@table @code
+@item accept
+A param list.  Each element in the list indicates one media-range
+with accept-params.  They only known key is @code{q}, whose value is
+parsed as a quality value.
+
+@item accept-charset
+A quality-list of charsets, as strings.
+
+@item accept-encoding
+A quality-list of content codings, as strings.
+
+@item accept-language
+A quality-list of languages, as strings.
+
+@item authorization
+A string.
+
+@item expect
+A param list of expectations.  The only known key is
+@code{100-continue}.
+
+@item from
+A string.
+
+@item host
+A pair of the host, as a string, and the port, as an integer. If no port
+is given, port is @code{#f}.
+
+@item if-match
+Either the symbol @code{*}, or a list of entity tags (see above).
+
+@item if-modified-since
+A SRFI-19 date.
+
+@item if-none-match
+Either the symbol @code{*}, or a list of entity tags (see above).
+
+@item if-range
+Either an entity tag, or a SRFI-19 date.
+
+@item if-unmodified-since
+A SRFI-19 date.
+
+@item max-forwards
+An exact non-negative integer.
+
+@item proxy-authorization
+A string.
+
+@item range
+A pair whose car is the symbol @code{bytes}, and whose cdr is a list of
+pairs. Each element of the cdr indicates a range; the car is the first
+byte position and the cdr is the last byte position, as integers, or
+@code{#f} if not given.
+
+@item referer
+A URI.
+
+@item te
+A param list of transfer-codings.  The only known key is
+@code{trailers}.
+
+@item user-agent
+A string.
+@end table
+
+
+@subsubsection Response Headers
+
+@table @code
+@item accept-ranges
+A list of strings.
+
+@item age
+An exact, non-negative integer.
+
+@item etag
+An entity tag.
+
+@item location
+A URI.
+
+@item proxy-authenticate
+A string.
+
+@item retry-after
+Either an exact, non-negative integer, or a SRFI-19 date.
+
+@item server
+A string.
+
+@item vary
+Either the symbol @code{*}, or a list of headers, with known headers
+parsed to symbols.
+
+@item www-authenticate
+A string.
+@end table
+
+
 @node Requests
 @subsection HTTP Requests