ruby-web 1.1.1

data/doc/install/win/iis.xml

@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.17 $ -->
+<sect1 id="install.windows.iis">
+ <title>Microsoft IIS</title>
+ <para>
+  This section contains notes and hints specific to IIS (Microsoft
+  Internet Information Server).
+ </para>
+
+ <sect2 id="install.windows.iis.general">
+  <title>General considerations for all installations of ruby-web with IIS</title>
+  <para>
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      First, read the <link linkend="install.windows.manual">Manual 
+      Installation Instructions</link>. Do not skip this step as it
+      provides crucial information for installing ruby-web on Windows.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      The &rubyweb; CGI is named <filename>ruby-web.exe</filename>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      The IIS user (usually IUSR_MACHINENAME) needs permission to
+      read various files and directories, including c:/ruby/bin, c:/ruby/lib, docroot, and the
+      session tmp directory.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      When defining the executable, the 'check that file exists' box may also 
+      be checked. For a small performance penalty, the IIS (or PWS) will check 
+      that the script file exists and sort out authentication before firing up 
+      ruby-web. <!--This means that the web server will provide sensible 404 style 
+      error messages instead of CGI errors complaining that ruby-web did not output 
+      any data.-->
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </sect2>
+
+ <sect2 id="install.windows.iis.iis4">
+  <title>Windows NT/200x/XP and IIS 4 or newer</title>
+
+  <simpara>
+   &rubyweb; may be installed as a CGI or Fast CGI script.
+   In either case, you need to start the Microsoft Management
+   Console (may appear as 'Internet Services Manager', either
+   in your Windows NT 4.0 Option Pack branch or the Control
+   Panel=&gt;Administrative Tools under Windows 2000/XP). Then
+   right click on your Web server node (this will most probably
+   appear as 'Default Web Server'), and select 'Properties'.
+  </simpara>
+
+  <para>
+   If you want to install &rubyweb; as a CGI, do the following:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      Under 'Home Directory', 'Virtual Directory', or 'Directory', do the 
+      following:
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Change the Execute Permissions to 'Scripts only'
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Click on the 'Configuration' button, and choose the Application Mappings 
+      tab. Click Add and set the Executable path to the
+      <filename>ruby-web.exe</filename> file.
+      An example value is: <filename>C:\ruby\bin\ruby-web.exe</filename>
+      Supply <literal>.rb</literal> or <literal>.rhtml</literal> as the extension.
+      Leave 'Method exclusions' blank, and check the 'Script engine' checkbox.
+      Now, click OK a few times.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Set up the appropriate security. (This is done in Internet
+      Service Manager), and if your NT Server uses NTFS file system,
+      add execute rights for I_USR_ to the <filename>c:\ruby\bin</filename>
+      and read rights for I_USR_ to the <filename>c:\ruby\lib</filename> directories.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   To install ruby-web.exe as a FastCGI script, do the following:
+   <itemizedlist>
+    <!--listitem>
+     <simpara>
+      If you don't want to perform HTTP Authentication using ruby-web,
+      you can (and should) skip this step. Under ISAPI Filters,
+      add a new ISAPI filter. Use RB as the filter name, and
+      supply a path to the <filename>ruby-web1isapi.dll</filename> /
+      <filename>ruby-web1isapi.dll</filename>.
+     </simpara>
+    </listitem-->
+    <listitem>
+     <simpara>
+      Under 'Home Directory', 'Virtual Directory', or 'Directory', do the 
+      following:
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Change the Execute Permissions to 'Scripts only'
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Click on the 'Configuration' button, and choose the Application Mappings 
+      tab. Click Add and set the Executable path to the isapi_fastcgi.dll.
+      The ruby-web windows installer will drop this file into:
+      <filename>C:\ruby\lib\isapi_fastcgi.dll</filename>
+      Supply <literal>.rb</literal> / <literal>.rhtml</literal> as the extension. Leave 'Method 
+      exclusions' blank, and check the 'Script engine' checkbox. Now, click 
+      OK a few times.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Stop IIS completely (NET STOP iisadmin)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Start IIS again (NET START w3svc)
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+  <!--para>
+   With IIS 6 (2003 Server), open up the IIS Manager, go to Web Service 
+   Extensions, choose "Add a new Web service extension", enter in a name such 
+   as ruby-web, choose the Add button and for the value browse to either the ISAPI 
+   file (<filename>ruby-web1isapi.dll</filename> or 
+   <filename>ruby-web1isapi.dll</filename>) or CGI (<filename>ruby-web.exe</filename>) then check "Set extension status to 
+   Allowed" and click OK.
+  </para-->
+  <para>
+   In order to use <filename>index.rhtml</filename> as a default content page, 
+   do the following: From within the Documents tab, choose Add. Type in
+   <filename>index.rhtml</filename> and click OK. Adjust the order by choosing
+   Move Up or Move Down. This is similar to setting DirectoryIndex with
+   Apache.
+  </para>
+  <!--para>
+   If you experience 100% CPU usage after some time, turn off the IIS
+   setting <literal>Cache ISAPI Application</literal>.
+  </para-->
+ </sect2>
+</sect1>

data/doc/install/win/index.xml

@@ -0,0 +1,24 @@
+  <chapter id="install.windows">
+   <title>Installation on Windows systems</title>
+   <para>
+    There are two main ways to install ruby-web for Windows: either
+    <link linkend="install.windows.manual">manually</link>
+    or by using the <link linkend="install.windows.installer">installer</link>.
+   </para>
+   <!--para>
+    If you have Microsoft Visual Studio, you can also 
+    <link linkend="install.windows.building">build</link>
+    ruby-web from the original source code.
+   </para-->
+
+   &install.windows.installer;
+   &install.windows.manual;
+   &install.windows.iis;
+  <!--
+   &install.windows.apache1;
+   &install.windows.apache2;
+  -->  
+ 
+   <!--&install.windows.building; -->
+  
+  </chapter>

data/doc/install/win/installer.xml

@@ -0,0 +1,31 @@
+   <sect1 id="install.windows.installer">
+    <title>Windows Installer</title>
+    
+    <para>
+     The Windows ruby-web installer is available from the downloads page at
+     <ulink url="&url.ruby-web.downloads;">&url.ruby-web.downloads;</ulink>. This
+     installs ruby-web and for IIS, Apache 1.x,
+     and Apache 2.x, it also configures the web server to run .rb and .rhtml
+    scripts using the CGI version of ruby-web.
+    </para>
+    
+    <simpara>
+     First, install your selected <acronym>HTTP</acronym> (web) server on your 
+     system, and make sure that it works.
+    </simpara>
+    
+    <simpara>
+     The installation wizard gathers enough information to set up the ruby-web,
+     and configure certain web servers to use ruby-web.
+    </simpara>
+
+    <simpara>
+     Once the installation has completed, the installer will restart the server,
+     and you should be ready to just start using ruby-web.
+    </simpara>
+
+    <!--simpara>
+     Once the installation has completed, the installer will inform you if you
+     need to restart your system, restart the server, or just start using ruby-web.
+    </simpara-->
+    </sect1>

data/doc/install/win/manual.xml

@@ -0,0 +1,43 @@
+    <sect1 id="install.windows.manual">
+    <title>Manual Installation Steps</title>
+    
+    <para>
+     This install guide will help you manually install and configure ruby-web with
+     a web server on Microsoft Windows.   Although we distribute a ruby-web
+    installer for Microsoft Windows, you might want to take to setup ruby-web
+    yourself as this will provide you with a better understanding of the system.
+    </para>
+ 
+   <para>
+    To get started you'll need to download 
+     the tar.gz distribution from the downloads page at
+     <ulink url="&url.ruby-web.downloads;">&url.ruby-web.downloads;</ulink>.
+     If you have not already done so, you will need to install the
+     <ulink url="&url.ruby.windows.installer;">Ruby One Click installer</ulink>
+     in the directory of your choice.  You may choose
+     a different location but do not have spaces in the
+     path (like <filename class="directory">C:\Program Files\Ruby</filename>)
+     as some web servers will crash properly if you do.
+    </para>
+    
+    <para>Extract the archive (using a program like Winzip) .  From the command line, execute these commands:</para>
+
+  <programlisting>
+  ruby.exe install.rb config
+  ruby.exe install.rb setup
+  ruby.exe install.rb install
+  </programlisting>
+
+    <para>
+      If you're using NTFS on Windows NT, 2000, XP or 2003, make sure that the
+      user running the web server has read permissions to your ruby lib directories (e.g.
+      make c:/ruby/bin and c:/ruby/lib readable by Everyone).
+    </para>
+    
+    <para>
+     Ruby-web is now setup on your system.  The next step is to choose a web
+     server, and enable it to run Ruby-web.   FastCGI will provide significantly
+     better performance compared to CGI.  However, CGI can be easier to setup.
+     Choose a webserver from the table of contents.
+    </para>
+   </sect1>

data/doc/manual.xml

@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                      "http://www.docbook.org/xml/4.3/docbookx.dtd"
+  [ 
+  <!ENTITY rubyweb "<emphasis>ruby-web</emphasis>">
+  <!ENTITY url.ruby.windows.installer "http://rubyforge.org/frs/?group_id=167">
+  <!ENTITY url.ruby-web.downloads "http://rubyforge.org/frs/?group_id=873">
+	<!ENTITY url.ruby-web.subscribe "http://lists.sourceforge.net/lists/listinfo/narf-lib-devel">
+	<!ENTITY httpd.conf "httpd.conf">
+  <!ENTITY email.ruby-web "narf-devel@sourceforge.net">
+  <!ENTITY url.ruby-web.bugs "http://rubyforge.org/tracker/?group_id=873">
+	<!ENTITY url.apache2.docs "url.apache2.docs">
+	<!ENTITY url.apache2.windows "url.apache2.windows">
+	<!ENTITY url.apache "url.apache">
+  <!ENTITY install SYSTEM "install/index.xml">
+	<!ENTITY install.windows SYSTEM "install/win/index.xml">
+	<!ENTITY install.windows.installer SYSTEM "install/win/installer.xml">
+	<!ENTITY install.windows.manual SYSTEM "install/win/manual.xml">
+	<!ENTITY install.windows.iis SYSTEM "install/win/iis.xml">
+	<!ENTITY install.windows.apache1 SYSTEM "install/win/apache1.xml">
+	<!ENTITY install.windows.apache2 SYSTEM "install/win/apache2.xml">
+
+  <!ENTITY install.macos SYSTEM "install/mac/index.xml">
+
+  <!ENTITY install.unix SYSTEM "install/unix/index.xml">
+
+
+	<!ENTITY core.reference             SYSTEM "core.xml">
+	<!ENTITY additional.reference    SYSTEM "additional.xml">
+					
+
+   <!ENTITY % php.snippets SYSTEM "credits/php.language-snippets.ent">
+   %php.snippets;
+   <!ENTITY php.credits SYSTEM "credits/php.contributors.xml">
+   <!ENTITY credits SYSTEM "credits/index.xml">  ] >
+
+<book>
+<bookinfo>
+  <title><emphasis>ruby-web</emphasis></title>
+</bookinfo>
+
+<part id="install">
+<title>Installation</title>
+&install;
+</part>
+
+<!--
+<part id="tutorial">
+<title>Tutorial</title>
+&tutorial;
+</part>
+-->
+
+<part id="core">
+<title>Core Reference</title>
+&core.reference;
+</part>
+
+<part id="additional">
+<title>Additional Libraries</title>
+&additional.reference;
+</part>
+
+<part id="credits">
+<title>Credits</title>
+&credits;
+</part>
+
+</book>

data/doc/old/apache_cgi.txt

@@ -0,0 +1,23 @@
+The narf executable is quite useful.  It can parse .narf files:
+
+    <? puts "hello world" ?>
+
+Also, it will print syntax errors to the screen.  To compile, run this from the project root (./narf):
+
+    ruby build.rb compile
+
+The compiled binary will be in
+
+    ./narf/bin/narf
+
+Copy this file where ever you like, make it executable, and tell apache to run it with a shebang:
+
+    #!/usr/local/bin/narf
+
+Mac OS X Note: If you get this message with compiling:
+
+    ld: Undefined symbols:
+
+You may need to re-compile ruby with --enable-shared:
+
+    http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/47248

data/doc/old/fastcgi.txt

@@ -0,0 +1,23 @@
+== FastCGI
+
+FastCGI support for narf requires the 'fcgi' libary:
+
+    http://raa.ruby-lang.org/list.rhtml?name=fcgi
+
+You can find a list of FastCGI servers here:
+
+    http://www.fastcgi.com
+
+After installing and configuring the appropriate fastcgi libraries for your server, run .narf files with the Narf runner:
+
+    #!/usr/local/bin/narf
+
+    <? Web::puts "Hello World" ?>
+
+or, run .rb files:
+
+    #!/usr/local/bin/narf
+
+    Web::puts "Hello World"
+
+Please note that fcgi.rb does not run on windows, thus the narf runner will not run with isapi_fastcgi.dll.

data/doc/old/mod_ruby.txt

@@ -0,0 +1,21 @@
+== mod_ruby
+
+Configure mod_ruby:
+
+  http://modruby.net/en/index.rbx/mod_ruby/install.html
+
+But use the narf runner, instead of the default apache runner:
+
+  <IfModule mod_ruby.c>
+  RubySafeLevel 0
+  # for Apache::RubyRun
+  RubyRequire web/sapi/apache
+
+  <Location / >
+      Options Indexes FollowSymLinks ExecCGI
+      AddHandler ruby-object cgi rb narf
+      RubyHandler Web::ModNarf.instance
+  </Location>
+  </IfModule>
+
+Narf will detect that mod_ruby is running and use the proper apis.

data/doc/old/snippets.rdoc

@@ -0,0 +1,183 @@
+# == Purpose
+# Web provides an infrastructure for building and testing
+# web applications.
+#
+# == Usage
+# Use the Web module to interact with the client.  The module
+# delegates to a Web::CGI object, which does the actual work.
+#
+#     #!/usr/bin/ruby
+#     require 'web'
+#     Web::process do
+#       Web["field"]                      # access parameters
+#       Web.cookies["muppet"]             # access cookies
+#       Web.session["key"] ||= "value"    # get and set session values
+#       Web.set_cookie( "muppet", "cookie monster" ) # set cookies
+#       Web.puts "something"              # print 'something' out
+#     end
+#
+# If the request contained multipart/form-data, uploaded files are returned as
+# Web::Upload objects.  Other parameters are treated as strings.
+#
+# == Output
+#
+# You write output as if it were an IO:
+#     Web << "<h1>Hello World!</h1>"
+#     Web.print "<p>We have lots of tricks for you.<br>"
+#     Web.write "From kungfu to jiujitsu<br>"
+#     Web.puts  "anything and everything works</p>."
+# or even:
+#     puts "hello world"
+#
+# Narf buffers output by default.  Buffered output allows you to set headers
+# (cookies, redirects, status, etc.) at any point before the cgi is flushed.
+# You can force this by calling:
+#     Web.flush
+#
+# Once the headers are sent to the client, you cannot set any more headers.
+#
+# == Error Handling
+#
+# For cgi-scripts under Apache, one can use the 'bin/narf'
+# script instead of using the ruby executable.  This little c program
+# doesn't do much fancy, but it can trap syntax errors and send them
+# back to the browser.  <i>I would especially appreciate security-related
+# feedback; narf.c is contributed and I am not a c programmer.</i>
+#
+# == Sessions:
+#
+# Sessions provide a way of storing data between Web
+# requests. Anything that can be marshalled can be stored in the
+# session. 
+#
+# === Getting and Setting values in a session
+#
+#      Web.session["key"] = "value"
+#      Web.session["key"]             # => "value"
+#
+# === Deleting session values
+#
+#      Web.session["key"] = "value"
+#      Web.session["key"].delete      # => "value"
+#      Web.session["key"]             # => "nil"
+#
+# === Iterating through session keys
+#
+#      Web.session.each do |key, val|
+#          Web.puts "#{key} => #{val}<br>"
+#      end
+#
+# === Resetting the Session
+#
+# Reseting the session to an empty hash is simple:
+#     Web.session.reset
+#
+# === Testing
+#
+# See Web::Testing for more details.
+#
+
+
+  # When testing, this is a useful method to tell
+  # NARF where to find your scripts
+
+
+    # Web delegates to the current
+    # cgi object.  This is the recommended
+    # way to use narf:
+    #
+    #    Web["param"]
+    #    Web << "hello world"
+    #    Web.set_redirect( "http://www.narf-lib.org" )
+    #    ...
+    # 
+    # The documentation for these methods is on the Web::CGI object.
+
+    # set the singleton connection object for Web
+
+
+    # get the singleton cgi object for Web
+
+
+  # this function should be useful for web apps that
+  # want to store resources with the source files
+  # in the ruby lib directories. For example:
+  #     Web::lib_filename('resources/logo.gif' )
+  # Uses Kernel::caller to determine base directory,
+  # use optional dirname parameter to change base directory
+
+
+  # Get the contents of a lib file, aka
+  #    template = Web::lib_file_contents('resources/template.html' )
+  # Uses Kernel::caller to determine base directory,
+  # use optional dirname parameter to change base directory
+
+
+  # To send a resource gif to the client:
+  #     Web::send_lib_file( 'resources/logo.gif' )
+  # Uses Kernel::caller to determine base directory,
+  # use optional dirname parameter to change base directory
+
+
+
+  # URL-encode a string.
+  #   url_encoded_string = Web::escape("'Stop!' said Fred")
+  #      # => "%27Stop%21%27+said+Fred"
+  # (from cgi.rb)
+
+
+
+  # URL-decode a string.
+  #   string = Web::unescape("%27Stop%21%27+said+Fred")
+  #      # => "'Stop!' said Fred"
+  # (from cgi.rb)
+
+
+  # Escape special characters in HTML, namely &\"<>
+  #   Web::escape_html('Usage: foo "bar" <baz>')
+  #      # => "Usage: foo &quot;bar&quot; &lt;baz&gt;"
+  # (from cgi.rb)
+
+  # Append output to client with line endings
+
+  # Unescape a string that has been HTML-escaped
+  #   Web::unescape_html("Usage: foo &quot;bar&quot; &lt;baz&gt;")
+  #      # => "Usage: foo \"bar\" <baz>"
+  # (from cgi.rb)
+
+
+  # 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).
+  #
+  #   print Web::escape_element('<BR><A HREF="url"></A>', "A", "IMG")
+  #     # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
+  #
+  #   print Web::escape_element('<BR><A HREF="url"></A>', ["A", "IMG"])
+  #     # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
+  #
+  # (from cgi.rb)
+
+
+
+  # Undo escaping such as that done by Web::escape_element()
+  #
+  #   print Web::unescape_element(
+  #           Web::escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG")
+  #     # "&lt;BR&gt;<A HREF="url"></A>"
+  # 
+  #   print Web::unescape_element(
+  #           Web::escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"])
+  #     # "&lt;BR&gt;<A HREF="url"></A>"
+  # (from cgi.rb)
+
+
+  # Make RFC1123 date string
+  #     Web::rfc1123_date(Time.now) # => Sat, 01 Jan 2000 00:00:00 GMT
+
+
+  # wrapper for web errors