ruby-web 1.1.1

data/doc/install/index.xml

@@ -0,0 +1,136 @@
+  <chapter id="install.general">
+   <title>General Installation Considerations</title>
+   <para>
+    To install ruby-web, you need a few things:
+    Ruby, ruby-web itself, a web server and a web browser. You
+    probably already have a web browser, and depending on
+    your operating system setup, you may also have a web
+    server (e.g. Apache on Linux and MacOS X; IIS on Windows).
+   </para>
+	
+    <para>
+    There are two ways to use ruby-web: as a library, and as an extension
+    to the Ruby interpreter.  Installing ruby-web as a library is simple,
+	  and gives one access to the useful functions of ruby-web.  There are
+    a few additional features which can be provided at a higher level:
+	  </para>
+	
+	  <itemizedlist>
+    <listitem>
+      The big one: Web friendly reporting of all errors, including syntax errors
+	  </listitem>
+    <listitem>
+      Dynamic web scripting with .rhtml documents, like php or coldfusion
+	  </listitem>
+    <listitem>
+      I'm working on this one: consistent scope for interpreter state between requests
+      across different server environments
+ 	  </listitem>
+  	</itemizedlist>
+
+    <para>It's up to you, both options have been tested.</para>
+    
+
+   <para>
+    While setting up the server and Ruby on your own, you can
+    generally choose between configuring ruby-web in a CGI or FastCGI processor.
+    This means you set up your server to use the CGI executable of
+    ruby-web to process all .rhtml and .rb file requests on the server.
+   </para>
+
+   <para>
+    ruby-web source code and binary distributions can be
+    found at
+    <ulink url="&url.ruby-web.downloads;">&url.ruby-web.downloads;</ulink>.
+   </para>
+
+    <para>
+    Finally, please note that these install instructions are a work in progress.  Please report any problems at <ulink url="http://rubyforge.org/tracker/?group_id=873">http://rubyforge.org/tracker/?group_id=873</ulink>, so that we can solve your problem, and improve.
+    </para>
+  </chapter>
+
+  &install.windows;
+
+  &install.macos;
+
+  &install.unix;
+
+  <chapter>
+  <title>Webrick</title>
+  
+  <para>ruby-web provides a Web::RubyWebHandler, based on the CGIHandler, to run ruby-web scripts. You will need to add the Web::RubyWebHandler to webrick with a startup script like this, replacing :DocumentRoot with the appropriate value:</para>
+
+  <programlisting>
+    #!/usr/local/bin/ruby
+    $: &lt;&lt; File.dirname($0)
+    require 'webrick'
+    require 'web/sapi/webrick'
+
+    include WEBrick
+
+    dir = Dir::pwd
+
+    HTTPServlet::FileHandler.add_handler("rb", Web::RubyWebHandler)
+    HTTPServlet::FileHandler.add_handler("rhtml", Web::RubyWebHandler)
+
+    s = HTTPServer.new(:Port            => 4476,
+                       :DocumentRoot    => "/.../htdocs/" )
+    trap("INT"){ s.shutdown }
+    s.start
+  </programlisting>
+  </chapter>
+
+  <chapter id="install.problems">
+   <title>Problems?</title>
+
+   <!--sect1 id="install.problems.faq">
+    <title>Read the FAQ</title>
+    <simpara>
+     Some problems are more common than others. The most
+     common ones are listed in the <link linkend="faq">PHP
+     FAQ</link>, part of this manual.
+    </simpara>
+   </sect1-->
+
+   <sect1 id="install.problems.support">
+    <title>Other problems</title>
+
+    <simpara>
+     If you are still stuck, someone on the ruby-web mailing list may be
+     able to help you. <!--You should check out the archive first, in case
+     someone already answered someone else who had the same problem as
+     you. The archives are available from the support page on <ulink
+      url="&url.ruby-web.support;">&url.ruby-web.support;</ulink>.--> To subscribe to the ruby-web installation
+     mailing list, submit the form at<ulink
+     url="mailto:&url.ruby-web.subscribe;">&url.ruby-web.subscribe;</ulink>.
+     The mailing list address is <ulink
+     url="mailto:&email.ruby-web;">&email.ruby-web;</ulink>.
+    </simpara>
+    <simpara>
+     If you want to get help on the mailing list, please try to be
+     precise and give the necessary details about your environment
+     (which operating system, what ruby-web version, what web server, if
+     you are running ruby-web as CGI or a server module, &safemode;, etc...), and
+     preferably enough code to make others able to reproduce and test
+     your problem.
+    </simpara>
+   </sect1>
+
+   <sect1 id="install.problems.bugs">
+    <title>Bug reports</title>
+    <simpara>
+     If you think you have found a bug in ruby-web, please report it.  The
+     ruby-web developers probably don't know about it, and unless you
+     report it, chances are it won't be fixed. You can report bugs
+     using the bug-tracking system at <ulink
+     url="&url.ruby-web.bugs;">&url.ruby-web.bugs;</ulink>. Please do not
+     send bug reports in mailing list or personal letters. The
+     bug system is also suitable to submit feature requests.
+    </simpara>
+    <!--simpara>
+     Read the <ulink 
+     url="&url.ruby-web.bugs.howtoreport;">How to report a bug</ulink> 
+     document before submitting any bug reports!
+    </simpara-->
+   </sect1>
+  </chapter>

data/doc/install/mac/index.xml

@@ -0,0 +1,21 @@
+  <chapter id="install_macosx">
+  <title>Mac OS X</title>
+  <para>
+  The simplest way to install ruby-web is to use the installer
+  found in the ruby-web.x.x.x-powerpc-darwin.dmg.  This will install ruby-web
+  and configure the default Apache with mod_ruby.
+  </para>
+
+  <para>
+  The installer has been tested on Mac OS X Tiger (10.4).
+  Please let me know (install.help@hexane.org)
+  if you have success or failure on other versions of Mac OS X.
+  </para>
+
+  <para>
+  If the installer does not work on your version of Mac OS X,
+  use the unix instructions to install and configure ruby-web
+  by hand.
+  </para>
+</chapter>
+

data/doc/install/ruby-web.install.rb.instructions.xml

@@ -0,0 +1,7 @@
+  <para>Extract the archive with Winzip / Stuffit / "tar -xvzf ruby-web-x.x.x.tgz".  From the command line, execute these commands:</para>
+
+  <programlisting>
+  ruby install.rb config
+  ruby install.rb setup
+  ruby install.rb install
+  </programlisting>

data/doc/install/unix/index.xml

@@ -0,0 +1,46 @@
+<chapter  id="install_unix">
+<title>Unix / Other</title>
+
+ <sect1>
+ <title>Ruby-Web</title>
+
+ <para>ruby-web depends on Ruby 1.8.x.  After installing ruby, download the latest ruby-web_x.x.x.tar.gz from <ulink url="http://rubyforge.org/frs/?group_id=873">Rubyforge.org</ulink>.</para>
+
+  
+ <para>This will compile and install the ruby-web interpreter.  You will have to configure the web servers separately.</para>
+  </sect1>
+  
+  <sect1>
+  <title>Mod Ruby</title>
+  
+  <para>First, configure and install the mod_ruby<ulink url="http://modruby.net/en/index.rbx/mod_ruby/install.html">mod_ruby</ulink></para>
+
+  <para>In http.conf setup apache to use the ruby-web runner, instead of the default mod_ruby runner:</para>
+
+  <programlisting>
+  &lt;IfModule mod_ruby.c&gt;
+  RubySafeLevel 0
+  # for Apache::RubyRun
+  RubyRequire web/sapi/apache
+
+  &lt;Location / &gt;
+      Options Indexes FollowSymLinks ExecCGI
+      AddHandler ruby-object cgi rb rhtml
+      RubyHandler Web::ModNarf.instance
+  &lt;/Location&gt;
+  &lt;/IfModule&gt;
+  </programlisting>
+  
+  </sect1>
+  
+  <sect1>
+  <title>FastCGI</title>
+  <para>To run fastcgi on unix, ruby-web depends on the 'fcgi' libary:</para>
+  <para>http://raa.ruby-lang.org/list.rhtml?name=fcgi</para>
+
+  <para>You will also need FastCGI running on your webserver.  You can find a links to extensions for Apache and other web servers at the this website:</para>
+
+  <para>http://www.fastcgi.com</para>
+  </sect1>
+</chapter>
+  

data/doc/install/win/apache1.xml

@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.16 $ -->
+   <sect1 id="install.windows.apache1">
+    <title>Apache 1.3.x on Microsoft Windows</title>
+    <para>
+     This section contains notes and hints specific to Apache 1.3.x installs
+     of PHP on Microsoft Windows systems. There are also
+     <link linkend="install.windows.apache2">instructions and notes
+     for Apache 2</link> on a separate page.
+    </para>
+    <note>
+     <para>
+      Please read the <link linkend="install.windows.manual">manual
+      installation steps</link> first!
+     </para>
+    </note>
+    
+    <simpara>
+     There are two ways to set up PHP to work with Apache 1.3.x
+     on Windows. One is to use the CGI binary (<filename>php.exe</filename>
+     for PHP 4 and <filename>php-cgi.exe</filename> for PHP 5),
+     the other is to use the Apache Module DLL. In either case
+     you need to edit your &httpd.conf; to configure Apache to
+     work with PHP, and then restart the server.
+    </simpara>
+    
+    <simpara>
+     It is worth noting here that now the SAPI module has been 
+     made more stable under Windows, we recommend it's use above
+     the CGI binary, since it is more transparent and secure.
+    </simpara>
+    
+    <simpara>
+     Although there can be a few variations of configuring PHP
+     under Apache, these are simple enough to be used by the
+     newcomer. Please consult the Apache Documentation for further
+     configuration directives.
+    </simpara>
+  
+    <simpara>
+     After changing the configuration file, remember to restart the server, for
+     example, <command>NET STOP APACHE</command> followed by
+     <command>NET START APACHE</command>, if you run Apache as a Windows
+     Service, or use your regular shortcuts.
+    </simpara>
+    
+    &note.apache.slashes;
+
+    <sect2 id="install.windows.apache1.module">
+     <title>Installing as an Apache module</title>
+     <para>
+      You should add the following lines to your Apache &httpd.conf; file:
+     </para>
+     <para>
+      <example>
+       <title>PHP as an Apache 1.3.x module</title>
+        <para>
+         This assumes PHP is installed to <filename>c:\php</filename>. Adjust the
+         path if this is not the case.
+        </para>
+        <para>
+         For PHP 4:
+        </para>
+        <programlisting role="apache-conf">
+<![CDATA[
+# Add to the end of the LoadModule section
+# Don't forget to copy this file from the sapi directory!
+LoadModule php4_module "C:/php/php4apache.dll"
+
+# Add to the end of the AddModule section
+AddModule mod_php4.c
+]]>
+       </programlisting>
+       <para>
+        For PHP 5:
+       </para>
+       <programlisting role="apache-conf">
+<![CDATA[
+# Add to the end of the LoadModule section
+LoadModule php5_module "C:/php/php5apache.dll"
+
+# Add to the end of the AddModule section
+AddModule mod_php5.c
+]]>
+       </programlisting>
+       <para>
+        For both:
+       </para>
+       <programlisting role="apache-conf">
+<![CDATA[
+# Add this line inside the <IfModule mod_mime.c> conditional brace
+AddType application/x-httpd-php .php
+
+# For syntax highlighted .phps files, also add
+AddType application/x-httpd-php-source .phps
+]]>
+       </programlisting>
+      </example>
+     </para>
+    </sect2>
+
+    <sect2 id="install.windows.apache1.cgi">
+     <title>Installing as a CGI binary</title>
+    
+     <para>
+      If you unzipped the PHP package to <filename>C:\php\</filename> as described
+      in the <link linkend="install.windows.manual">Manual
+      Installation Steps</link> section, you need to insert
+      these lines to your Apache configuration file to set
+      up the CGI binary:
+      <example>
+       <title>PHP and Apache 1.3.x as CGI</title>
+        <programlisting role="apache-conf">
+<![CDATA[
+ScriptAlias /php/ "c:/php/"
+AddType application/x-httpd-php .php
+
+# For PHP 4
+Action application/x-httpd-php "/php/php.exe"
+
+# For PHP 5
+Action application/x-httpd-php "/php/php-cgi.exe"
+
+# specify the directory where php.ini is
+SetEnv PHPRC C:/php
+]]>
+       </programlisting>
+      </example>
+      Note that the second line in the list above can be found
+      in the actual versions of &httpd.conf;, but it is commented out. Remember
+      also to substitute the <filename>c:/php/</filename> for your actual path to
+      PHP.
+     </para>
+     &warn.install.cgi;
+     <simpara>
+      If you would like to present PHP source files syntax highlighted, there
+      is no such convenient option as with the module version of PHP.
+      If you chose to configure Apache to use PHP as a CGI binary, you
+      will need to use the <function>highlight_file</function> function. To
+      do this simply create a PHP script file and add this code: 
+      <literal>&lt;?php highlight_file('some_php_script.php'); ?&gt;</literal>.
+     </simpara>
+    </sect2>
+
+   </sect1>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

data/doc/install/win/apache2.xml

@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.13 $ -->
+   <sect1 id="install.windows.apache2">
+    <title>Apache 2.0.x on Microsoft Windows</title>
+    <para>
+     This section contains notes and hints specific to Apache 2.0.x installs
+     of ruby-web on Microsoft Windows systems. We also
+     have <link linkend="install.windows.apache1">instructions and notes
+     for Apache 1.3.x users on a separate page</link>.
+    </para>
+    <note>
+     <para>
+      You should read the <link linkend="install.windows.manual">manual
+       installation steps</link> first!
+     </para>
+    </note>
+    
+    <para>
+     You are highly encouraged to take a look at the
+     <ulink url="&url.apache2.docs;">Apache Documentation</ulink> to get
+     a basic understanding of the Apache 2.0.x Server. Also consider to
+     read the <ulink url="&url.apache2.windows;">Windows specific
+     notes</ulink> for Apache 2.0.x before reading on here.
+    </para>
+    
+    <warning>
+     <para>
+      Apache 2.0.x is designed to run on Windows NT 4.0, Windows 2000 or
+      Windows XP. At this time, support for Windows 9x is incomplete.
+      Apache 2.0.x is not expected to work on those platforms at this time.
+     </para>
+    </warning>
+    <para>
+     Download the most recent version of <ulink url= "&url.apache;">
+     Apache 2.0.x</ulink> and a fitting ruby-web version.
+     Follow the <link linkend="install.windows.manual">Manual Installation
+     Steps</link> and come back to go on with the integration of ruby-web and Apache.
+    </para>
+    <para>
+     There are two ways to set up ruby-web to work with Apache 2.0.x on Windows.
+     One is to use the CGI binary the other is to use the Apache module DLL.
+     In either case you need to edit your &httpd.conf; to configure Apache
+     to work with ruby-web and then restart the server.
+    </para>
+    
+    &note.apache.slashes;
+    
+    <sect2 id="install.windows.apache2.cgi">
+     <title>Installing as a CGI binary</title>
+    
+     <para>
+      You need to insert these three lines to your Apache &httpd.conf;
+      configuration file to set up the CGI binary:
+      <example>
+       <title>ruby-web and Apache 2.0 as CGI</title>
+        <programlisting role="apache-conf">
+<![CDATA[
+ScriptAlias /ruby-web/ "c:/ruby/bin"
+AddType application/x-httpd-ruby .rb
+
+Action application/x-httpd-rb "/ruby-web/ruby-web.exe"
+
+]]>
+       </programlisting>
+      </example>
+     </para>
+     &warn.install.cgi;
+    </sect2>
+    
+    <sect2 id="install.windows.apache2.module">
+     <title>Installing as an Apache module</title>
+     <para>
+      You need to insert these two lines to your
+      Apache &httpd.conf; configuration file to set up the
+      ruby-web module for Apache 2.0:
+      <example>
+       <title>ruby-web and Apache 2.0 as Module</title>
+        <programlisting role="apache-conf">
+<![CDATA[
+# For PHP 4 do something like this:
+LoadModule php4_module "c:/php/php4apache2.dll"
+# Don't forget to copy the php4apache2.dll file from the sapi directory!
+AddType application/x-httpd-php .php
+
+# For PHP 5 do something like this:
+LoadModule php5_module "c:/php/php5apache2.dll"
+AddType application/x-httpd-php .php
+
+# configure the path to php.ini
+PHPIniDir "C:/php"
+]]>
+       </programlisting>
+      </example>
+     </para>
+     <note>
+      <simpara>
+       Remember to substitute your actual path to PHP for the
+       <filename>c:/php/</filename> in the above examples. Take care to use
+       either <filename>php4apache2.dll</filename> or 
+       <filename>php5apache2.dll</filename> in your LoadModule directive and
+       <emphasis>not</emphasis> <filename>php4apache.dll</filename> or 
+       <filename>php5apache.dll</filename> as the latter ones are designed to
+       run with <link linkend="install.windows.apache1">Apache 1.3.x</link>.
+      </simpara>
+     </note>
+     <note>
+      <para>
+       If you want to use content negotiation, read
+       <link linkend="faq.installation.apache.multiviews">related FAQ</link>.
+      </para>
+     </note>
+     <warning>
+      <simpara>
+       Don't mix up your installation with DLL files from
+       <emphasis>different PHP versions</emphasis>. You have the only choice
+       to use the DLL's and extensions that ship with your downloaded PHP version.
+      </simpara>
+     </warning>
+    </sect2>
+   </sect1>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->