ruby-web 1.1.1

data/TODO

@@ -0,0 +1,65 @@
+=== TODO:
+
+Top Priorities:
+
+* Installation
+ + NSIS installer
+ + Mac OS X pkg
+
+* Manual
+* More CGD and installation tests
+* FastCGIServlet: modify resin servlet to do process management
+* 'web/shim/rails'
+
+Web
+* Update Web::set_redirect() to use javascript if headers have been sent,
+  instead of throwing nasty error.
+
+Templating
+* Test tags in strange circumstances, i.e. <? Web::puts "?>" ?>
+* Replace the Foreach syntax with the following:
+  <narf:foreach item="i" in="credits">
+* Add support for RadioButtons
+* pass through all values not depended on by the tag parser.
+* Add support for links so that they correctly link to the current
+  cgi, or to a different one.
+* Support form submits, and redirects to urls of the form "?foo=bar",
+  ie no script is mentioned.
+* Provide a hook into test_unit to allow sessions to be automatically reset
+  before a setup
+* Have the tag parser report which tag was not matched
+* The following line produces an unhelpful error message:
+    <narf:foreach from"items" item="item">
+* Make VarNotFoundException report a better error message, including
+  line number and what var was not found. Print out some context from
+  the template too.
+* Add better error reporting (including line numbers and context) for
+  template parse errors. 
+* Add tests to test Web::Link
+
+Web::Testing
+* Allow clicking of links in a test.
+* Add support for submitting a form to a CGI other than the current one.
+* Have Values in textarea's and value attributes in other fields
+  correctly escaped so all escaping issues are handled. 
+* Add support for specific buttons to be submitted on a form.
+* Provide a default form submit that submits any un-named form on the
+  page. 
+* Allow a request to be made directly to a form, passing in objects
+  (objects should be serialized, unserialized before passing)
+* Add an assert that a particular template was used
+	assert_form_displayed MyTemplate
+* Add a way to find out how long an array is in a test
+* Add error reporting for when a template can not be found
+* Report errors for unrecognized parameters for do_request
+* Have assert_includes handle array fields to allow for parameters
+  with array types.
+
+Web::SimpleDispatcher
+* Support for useful data-binding might include
+  - Optionally, not having eveything written back to the form
+  - Automatic data type conversions, perhaps specified in a form tag. 
+* Submit could do with a more helpful error message. If a field is not
+  present, it could list out the fields that are present.
+* Have do request automatically encode objects
+* Make sure round trip object serialization works correctly

data/doc/additional.xml

@@ -0,0 +1,149 @@
+<chapter id="reference-compatibility">
+<title>Compatibility</title>
+<para>
+ruby-web ships with the cgi.rb interface, adapted to use the ruby-web infrastructure.
+</para>
+<programlisting
+>require 'web/shim/cgi'
+cgi = CGI.new
+# ...</programlisting>
+</chapter>
+  
+
+<chapter id="reference-custom_templates">
+<title>Custom Templates</title>
+  <para>You can customize how ruby-web load templates:</para>
+  
+  <programlisting
+>require 'web/phprb'
+
+Web::config['load_suffix']['rhtml'] = lambda do |scriptname|
+  PHPRB::load(scriptname)
+end
+ 
+# or, if you really really love your templating language:
+Web::config['load_suffix'].default = lambda do |scriptname|
+  PHPRB::load(scriptname)
+end
+
+Web::load('template.rhtml') # &lt;= will be processed by phprb</programlisting>
+
+  <para>phprb is an experimental template parser derived from erb, but not as inspired
+  by the systems invented by Sun and Microsoft.  It has the following rules:</para>
+
+  <variablelist>
+  <varlistentry>
+  <term>&lt;? ... ?&gt;</term>
+    <listitem>
+			Evaluate ruby code.
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+		<term>&lt;?= ... ?&gt;</term>
+    <listitem>
+			Evaluate the enclosed ruby code and print the output.
+    </listitem>
+    </varlistentry>
+    
+		<varlistentry>
+		<term>&lt;!--- ... ---&gt;</term>
+    <listitem>
+			Comment out the enclosed code.
+    </listitem>
+    </varlistentry>
+    
+		<varlistentry>
+		<term>&lt;??, ??&gt;</term>
+    <listitem>
+			Print out literal &lt;?? or ??&gt;.
+    </listitem>
+    </varlistentry>
+    </variablelist>
+</chapter>
+
+<chapter id="reference-testing">
+  <title>Testing Functions</title>
+
+  <para>To access these functions, include Web::Testing in your testcase</para>
+  
+  <programlisting
+>require 'web/testing'
+require 'web/unit/testcase'
+class MyWebTest &lt;&lt; Test::Unit::TestCase
+  include Web::Testing
+  #...
+end</programlisting>
+  
+  <variablelist>
+  <varlistentry>
+  <term>do_request( scriptname, params={} )</term>
+  <listitem>
+    <para>Do a mock request to scriptname, passing in params.</para>
+
+    <para>
+    <emphasis>scriptname</emphasis> can be /absolute/scriptname.rb if you use set
+    the docroot using Web::docroot = "...".
+    Otherwise, use a relative path from the current directory.
+    </para>
+
+    <para>
+    <emphasis>params</emphasis> is a hash of request parameters.  You can mock
+    enviroment parameters on an :env key.
+    </para>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>do_submit( formname, params={} )</term>
+  <listitem>
+    Once you've done a request, you can submit forms on the page.
+    You can "fill out" fields by passing in params.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>assert_content(expected, message="")</term>
+  <listitem>
+    fails if content is not set to the provided string.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>assert_form_includes(formname, vars)</term>
+  <listitem>
+    Assert output content contains a form that includes the given hash of values. ### this could sure use some more docs.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::get_content()</term>
+  <listitem>
+    the body content of the response (sans headers)
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>assert_header( name, values, message="" )</term>
+  <listitem>
+    Fails if the header has not been set to the provided value(s).
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>assert_cookie( name, values, message="" )</term>
+  <listitem>
+    Fails if cookie values are not present.
+  </listitem>
+  </varlistentry>
+
+  </variablelist>
+
+</chapter>
+
+<!--para>
+ruby-web also ships with a rails driver:
+</para>
+<programlisting>
+require 'web/shim/rails'
+...</programlisting-->

data/doc/core.xml

@@ -0,0 +1,652 @@
+  <chapter id="reference-basics">
+  <title>Basics</title>
+  
+  <para>
+  Templates are loaded using Web::load.  ruby-web loads .rb files as ruby, and assumes everything else is an erb template.  Below is a short guide to erb templating:</para>
+  <variablelist>
+  <varlistentry>
+  <term>&lt;% ... %&gt;</term>
+    <listitem>
+			Evaluate ruby code.
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+		<term>&lt;%= ... %&gt;</term>
+    <listitem>
+			Evaluate the enclosed ruby code and print the output.
+    </listitem>
+    </varlistentry>
+    
+		<!--varlistentry>
+		<term>&lt;!- - - ... - - -&gt;</term>
+    <listitem>
+			Comment out the enclosed code.
+    </listitem>
+    </varlistentry-->
+    
+		<varlistentry>
+		<term>&lt;%%, %%&gt;</term>
+    <listitem>
+			Print out literal &lt;%% or %%&gt;.
+    </listitem>
+    </varlistentry>
+    </variablelist>
+
+
+  <para>
+  The ruby-web interpreter will open a connection to the webserver and load the first
+  command-line argument using Web::load.  In a script, one can include additional files using Web::load.
+  </para>
+  
+  <para>
+  In a ruby script, one can also open a Web::Connection using Web::open.  This is not
+  recommended, but is documented here for use in unsupported server environments.
+  </para>
+
+  <variablelist>
+  <varlistentry>
+  <term>Web::load( filename )</term>
+  <listitem>
+	Given 'filename.ext' as filename, load using the handler Web::config[:load_suffix][:ext].
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::connection</term>
+  <listitem>
+    Return current Web::Connection.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::open(options)</term>
+  <listitem>
+    Handle a web request.  Use this method when running the ruby-web libraries
+    outside of the ruby-web interpreter and outside of Web::load.
+    <programlisting>
+#!/usr/bin/ruby
+require 'web'
+Web::open do |connection|
+  Web::write "Hello"
+  cgi.write  "World"
+end</programlisting>
+
+    <para>Guide to options <emphasis>(defaults are in parenthesis)</emphasis>:</para>
+
+    <variablelist>
+    <varlistentry>
+    <term>:unbuffered</term>
+    <listitem>
+      flag whether output should(n't) be buffered. <emphasis>(false)</emphasis>
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:cgd</term>
+    <listitem>
+      pass in a CGD driver
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:out</term>
+    <listitem>
+      set the output stream to the given IO <emphasis>($stdout)</emphasis>.
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:raw_post_data</term>
+    <listitem>
+      set the raw_post_data to the given IO <emphasis>($stdin)</emphasis>.
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:request</term>
+    <listitem>
+      pass in the request hash
+    </listitem>
+    </varlistentry>
+
+	<varlistentry>
+    <term>:session</term>
+    <listitem>
+      set the session to the given hash <emphasis>(Web::Session)</emphasis>.
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:env</term>
+    <listitem>
+      pass in the ENV variables
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:path_info</term>
+    <listitem>
+      path_info is the part of the query that is after the script,
+      i.e. the path_info.html in /script_name.rb/path_info.html <emphasis>(Web::env[:path_info])</emphasis>
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:document_root</term>
+    <listitem>
+      Document root of website.  <emphasis>(Web::env[:document_root])</emphasis>
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>:script_name</term>
+    <listitem>
+      Script name, ie /script_name.rb in /script_name.rb/path_info.html <emphasis>(Web::env[:script_name])</emphasis>
+    </listitem>
+    </varlistentry>
+    </variablelist>
+  </listitem>
+  </varlistentry>
+  </variablelist>
+
+  </chapter>
+  
+  <chapter id="reference-variables">
+  <title>Web Variables</title>
+  <variablelist>
+  <varlistentry>
+  <term>Web[key]</term>
+  <listitem>
+		Convenience method to access values within Web::request.
+    If the key is array-style, aka 'param[]',	the value is
+    returned as an array. Otherwise, value is joined with ","
+    and returned as a string.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web[key] = value</term>
+  <listitem>
+    Convenience method to set values within Web::request.
+    If value is not an array, sets key to [value].
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::cookie</term>
+  <listitem>
+    Access cookies sent by the client.
+  </listitem>
+  </varlistentry>
+
+	<varlistentry>
+	<term>Web::env</term>
+  <listitem>
+    ENV variables, scoped to the request, returned in a case-insensitive hash
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::get</term>
+  <listitem>
+    Access parameters passed on the url.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::info</term>
+  <listitem>
+    Display information about the execution enviroment to the client.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::key?(key)</term>
+  <listitem>
+		Test whether Web::cookie, Web::get, or Web::post contain the given key.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::keys</term>
+  <listitem>
+    Return set of the keys of Web::cookie, Web::get, and Web::post.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+	<term>Web::local</term>
+  <listitem>
+    A hash scoped to the current web connection.
+    Similar to Request scope in the Java Servlet API.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::post</term>
+  <listitem>
+    Access parameters submitted via a form posting.
+  </listitem>
+  </varlistentry>
+		
+  <varlistentry>
+  <term>Web::request</term>
+  <listitem>
+    Convenience array.  Combines Web::get, Web::post, and Web::cookie into one hash.  If the same key is passed in Web::get and Web::post, Web::env['request_method'] is used to choose which takes priority.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::raw_post_data</term>
+  <listitem>
+    An IO object containing the raw post data from the request.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::session</term>
+  <listitem>
+    Session values.
+  </listitem>
+  </varlistentry>
+
+  </variablelist>
+  </chapter>
+
+  <chapter id="reference-output">
+  <title>Output Functions</title>
+  <variablelist>
+  <varlistentry>
+  <term>Web &lt;&lt; output</term>
+  <listitem>
+    Write output to the browser.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::clear</term>
+  <listitem>
+    Reset output buffer. Fails if headers have been sent.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::close</term>
+  <listitem>
+    Flushes the output and, if applicable, saves the session.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::flush</term>
+  <listitem>
+    Send header to the client, and flush any buffered output
+  </listitem>
+  </varlistentry>
+  
+	<varlistentry>
+  <term>Web::puts(output)</term>
+  <listitem>
+    Write output to the browser with line breaks.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::write(output)</term>
+  <listitem>
+    Write output to the browser.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::send_file( filename )</term>
+  <listitem>
+    This method will replace the contents of the output buffer
+  	with the content read from the given filename.
+	  If the Content-Type header has not already been set,
+	  it will guess an appropriate mime-type from the extension of the file.
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::send_lib_file( relative_filename )</term>
+  <listitem>
+    Using Web::send_file(filename), sends the contents of a file
+    from the ruby lib to the client.  Filename is relative to the file of Kernel::caller.
+    This method is intended to help the distribution of web applications as normal ruby libraries.
+    <programlisting>
+# sends ".../ruby/site_lib/1.8/web/resources/logo.gif" to the client
+Web::send_lib_file( 'resources/logo.gif' )</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::unbuffered?</term>
+  <listitem>
+    Returns whether output buffering is being used.  By default, output is buffered.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::filter</term>
+  <listitem>
+  Start an output buffer.  aka Web::ob_start.  Yields content for filtering before being written out:
+  <programlisting>
+Web::filter do |content|
+  # ... filter  content   
+end</programlisting>
+    
+   </listitem>
+   </varlistentry>
+
+    <varlistentry>
+    <term>Web::ob_flush</term>
+    <listitem>
+    Flush (send) the output buffer
+    </listitem>
+    </varlistentry>
+
+   <varlistentry>
+   <term>Web::ob_clean</term>
+   <listitem>
+   Erase and discard contents of the output buffer
+   </listitem>
+   </varlistentry>
+
+   <varlistentry>
+   <term>Web::ob_end_clean</term>
+   <listitem>
+   Erase contents of output buffer, and discard the buffer itself
+   </listitem>
+   </varlistentry>
+
+   <varlistentry>
+   <term>Web::ob_end_flush</term>
+   <listitem>
+    Flush (send) the output buffer and discard the buffer itself
+    </listitem>
+    </varlistentry>
+
+     <varlistentry>
+    <term>Web::ob_get_clean</term>
+     <listitem>
+      Get current buffer contents and delete current output buffer
+     </listitem>
+     </varlistentry>
+
+     <varlistentry>
+    <term>Web::ob_get_contents</term>
+    <listitem>
+     Return the contents of the output buffer
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>Web::ob_get_flush</term>
+    <listitem>
+    Flush the output buffer, return it as a string and turn off output buffering
+    </listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>Web::ob_get_length</term>
+    <listitem>Return the length of the output buffer</listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>Web::ob_get_level</term>
+    <listitem>Return the nesting level of the output buffering mechanism</listitem>
+    </varlistentry>
+
+    <varlistentry>
+    <term>Web::ob_list_handlers</term>
+    <listitem>List all output handlers in use</listitem>
+    </varlistentry>
+
+    <!--#  ob_get_contents  Return the contents of the output buffer-->
+  
+  </variablelist>
+  </chapter>
+
+  <chapter id="reference-header">
+  <title>Header Functions</title>
+  <varlistentry>
+  <term>Web::charset / Web::charset=(new_charset)</term>
+  <listitem>
+    Get / set charset.
+  </listitem>
+  </varlistentry>
+  
+  <variablelist>
+  <varlistentry>
+  <term>Web::cookies_sent</term>
+  <listitem>
+    Returns a hash of all the cookie name/value pairs that have been set on the server.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::content_type() / Web::content_type=(new_content_type)</term>
+  <listitem>
+    Get / set content type.  The default content-type is "text/html".
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::encoding / Web::encoding=( new_encoding )</term>
+  <listitem>
+    Get / set character encoding.a
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::get_cookie(key)</term>
+  <listitem>
+    Returns an array of cookie values that have been set. Path / Expires / etc. info is currently not returned.  Note that this is different from the cookies that the browser submitted to the server.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::status / Web::status=(new_status)</term>
+  <listitem>
+    Get / Set new status, as in:
+	<programlisting>Web::status = 200</programlisting>
+  </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Web::set_cookie( name, value, options={} )</term>
+  <listitem>
+    <para>Sends client a cookie with the given name and a value, and these optional keyword arguments:</para>
+
+    <variablelist>
+	<varlistentry>
+	<term>:path</term>
+	<listitem>
+	  Path string
+	</listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>:domain</term>
+	<listitem>
+	  Domain string
+	</listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>:expires</term>
+	<listitem>
+      Date this cookie should expire
+	</listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>:secure</term>
+    <listitem>
+	    Whether this cookie should be tagged as secure or not.
+    </listitem>
+	  </varlistentry>
+  	</variablelist>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::set_redirect( new_location )</term>
+  <listitem>
+    Sets the status and the location appropriately.
+  </listitem>
+  </varlistentry>
+  
+  </variablelist>
+
+  </chapter>
+
+  <chapter id="reference-utility">
+  <title>Utility Functions</title>
+  <variablelist>
+  <varlistentry>
+  <term>Web::escape(string)</term>
+  <listitem>
+    URL-encode a string. (from cgi.rb)
+    <programlisting>
+url_encoded_string = Web::escape("'Stop!' said Fred")
+  # => "%27Stop%21%27+said+Fred"</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::escape_element(string, *elements)</term>
+  <listitem>
+    Escape only the tags of certain HTML elements in string. Takes an element or elements or array of elements. Each element is specified by the name of the element, without angle brackets. This matches both the start and the end tag of that element. The attribute list of the open tag will also be escaped (for instance, the double-quotes surrounding attribute values).  (from cgi.rb)
+    <programlisting>
+print Web::escape_element('&lt;BR&gt;&lt;A HREF="url"&gt;&lt;/A&gt;', "A", "IMG")
+  # "&lt;BR&gt;&amp;lt;A HREF=&amp;quot;url&amp;quot;&amp;gt;&amp;lt;/A&amp;gt;"
+    
+print Web::escape_element('&lt;BR&gt;&lt;A HREF="url"&gt;&lt;/A&gt;', ["A", "IMG"])
+  # "&lt;BR&gt;&amp;lt;A HREF=&amp;quot;url&amp;quot;&amp;gt;&amp;lt;/A&amp;gt;"</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::escape_html(string)</term>
+  <listitem>
+    Escape special characters in HTML, namely &amp;\"&lt;&gt; (from cgi.rb)
+	<programlisting>
+Web::escape_html('Usage: foo "bar" &lt;baz&gt;')
+  # => "Usage: foo &amp;quot;bar&amp;quot; &amp;lt;baz&amp;gt;"</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::get_mime_type(filename)</term>
+  <listitem>
+    Guess the mimetype for the filename from the file extension.
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::lib_file_contents( filename )</term>
+  <listitem>
+    Get the contents of a file in the ruby libraries.  Filename is relative to Kernel::caller
+    <programlisting>
+template = Web::lib_file_contents('resources/template.html')</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::lib_filename( resource )</term>
+  <listitem>
+    This function is for apps that want to store resources with the source files in the ruby lib directories. Filename is relative to Kernel::caller
+	<programlisting>
+Web::lib_filename('resources/logo.gif')
+  # =&gt; ".../ruby/site_lib/1.8/web/resources/logo.gif"</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::rfc1123_date(time)</term>
+  <listitem>
+    Make RFC1123 date string
+	<programlisting>Web::rfc1123_date(Time.now) # =&gt; Sat, 01 Jan 2000 00:00:00 GMT</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::unescape(string)</term>
+  <listitem>
+    URL-decode a string. (from cgi.rb)
+    <programlisting>
+string = Web::unescape("%27Stop%21%27+said+Fred")
+       # => "'Stop!' said Fred"</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::unescape_element(string, *elements)</term>
+  <listitem>
+    Undo escaping such as that done by Web::escape_element.  (from cgi.rb)
+    <programlisting>
+print Web::unescape_element(
+         Web::escapeHTML('&lt;BR&gt;&lt;A HREF="url"&gt;&lt;/A&gt;'), "A", "IMG")
+  # "&amp;lt;BR&amp;gt;&lt;A HREF="url"&gt;&lt;/A&gt;"
+
+print Web::unescape_element(
+        Web::escapeHTML('&lt;BR&gt;&lt;A HREF="url"&gt;&lt;/A&gt;'), ["A", "IMG"])
+  # "&amp;lt;BR&amp;gt;&lt;A HREF="url"&gt;&lt;/A&gt;"</programlisting>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>Web::unescape_html(string)</term>
+  <listitem>
+    Unescape a string that has been HTML-escaped (from cgi.rb)
+    <programlisting>
+Web::unescape_html("Usage: foo &amp;quot;bar&amp;quot; &amp;lt;baz&amp;gt;")
+  # => "Usage: foo \"bar\" &lt;baz&gt;"</programlisting>
+  </listitem>
+  </varlistentry>
+
+  </variablelist>
+</chapter>
+
+<chapter id="reference-configuration">
+  <title>Configuration</title>
+  <para>Config directives are set using Web::config[:directive] = value.  If desired, config directives can be set within 'site_lib/x.x/web/site-config.rb'.</para>
+  <para>Below is a list of available config directives:</para>
+  <variablelist>
+  <varlistentry>
+  <term>:load_suffix</term>
+  <listitem>
+    <para>:load_suffix contains a hash of handlers for different file extensions.  You can then control the behavior of Web::load:</para>
+    <programlisting
+>Web::config[:load_suffix][:amrita] = lambda do |scriptname|
+  #...handle amrita templates...
+end</programlisting>
+	  <para>
+	  :load_suffix by default will load .rb and .erb files appropriately.
+    Everything else is loaded using ruby-web's default templating.
+	  </para>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
+  <term>:load_path</term>
+  <listitem>
+    :load_path is an array of directories, searched by Web::load when it has been given a relative path to load.
+  </listitem>
+  </varlistentry>
+    
+  <varlistentry>
+  <term>:error_style</term>
+  <listitem>
+    Controls how exceptions are handled.  Valid values include :development, :production, or :custom.  :development prints a full stacktrace, :production prints a more abbreviated message.  :custom allows one to defined their own handler using Web::config[:error_handler]
+  </listitem>
+  </varlistentry>
+    
+  <varlistentry>
+  <term>:multipart_progress_hook</term>
+  <listitem>
+    Allows one to pass a lambda that will be called as a multipart upload is read.  The lambda is called with 2 arguments: the total number of bytes, and the number of bytes read so far.  Probably only useful to AJAX implementations.
+  </listitem>
+  </varlistentry>
+  </variablelist>
+  </chapter>