doc/xml/intro.xml

<section id="introduction">
    <title>Introduction to Apache Rivet version &version;</title>
    <para>
      Apache Rivet is a system for creating dynamic web content by
      integrating the 
		<ulink url="&tcltk-url;">Tcl programming language</ulink> within the 
      <ulink url="&apache-url;">Apache Web Server</ulink>.
      It is designed to be fast, powerful and extensible, consume 
      few system resources, be easy to learn, and to provide the user with a
      platform that can also be used for other programming tasks
      outside the web (GUI's, system administration tasks, text
      processing, database manipulation, XML, and so on).
    </para>
    <para>
      In this manual, we aim to help get you started, and then
      writing productive code as quickly as possible, as well as
      giving you ideas on how to best take advantage of Rivet's
      architecture to create different styles of web site.
    </para>
    <para>
      This documentation is focused on the current version of Rivet, but
      still a work in progress, and, like everything
      else about Apache Rivet, it is Free Software. If you see
      something that needs improving, and have ideas or suggestions,
      don't hesitate to let us know.  If you want to contribute
      directly, better yet!
    </para>
    <simplesect>
        <title>Apache MPM and Rivet Bridge Modules</title>
        <para>
				Rivet &version; is a successor to Rivet &version30;, a major rewriting of mod_rivet,
				the Apache HTTP Websever module at the core of Rivet. Unlike in &version2-generic; of
				mod_rivet, which only supported the
				<ulink url="&apachedoc-prefork;">prefork MPM</ulink>
				(<ulink url="&apachedoc-mpm;">Multiprocessing Module</ulink>),
				starting with &version30; we attained full support of different MPM for
				the Apache framework.
        </para>
        <para>
        		Threaded <ulink url="&apachedoc-mpm;">MPM</ulink>
        		integration was achieved by making mod_rivet multithreaded and
        		modular itself, introducing the MPM-module bridge concept.
				We developed a set of loadable modules which are supposed not only to overcome 
            the issues related to threading but also to offer the best possible MPM mod_rivet 
            integration.
        		As a side effect of this modular design mod_rivet is not only able to integrate
        		with its environment but also to work as a framework for writing more MPM bridges
        		designed along different multi-threading schemes and workload management models. 
        		See the <link linkend="internals">internals</link> section of this manual for
        		further reading. MPM bridges are loaded accordingly to a heuristics of rules based
        		on the Apache introspection calls but they can be determined in the configuration. 
        		Only a bridge can be loaded at a time.
        </para>
    </simplesect>
    <simplesect>
    	<title>Request Processing</title>
    	<para>
    			Request processing was performed in mod_rivet version &version2-generic; by chaining together 3 scripts
    	</para>
    	<itemizedlist>
    		<listitem>BeforeScript, if defined in the configuration</listitem>
 			<listitem>The URI referenced Tcl script or rvt template dermined with
 				respect to the <ulink url="&apachedoc-docroot;">DocumentRoot</ulink> and following 
 				other resource determination methods such the ones offered by 
 				<ulink url="&apachedoc-alias;">mod_alias</ulink> and by
 				<ulink url="&apachedoc-rewrite;">mod_rewrite</ulink>.
 			</listitem>
 			<listitem>AfterScript, if defined in the configuration</listitem> 
		</itemizedlist>
		<para>
			Errors and exceptions (raised by the <link linkend="abort_page">::rivet::abort_page</link> command)
			are handled by the ErrorScript and AbortScript (ErrorScript has a default implementation
			if undefined in the configuration)
		</para>
		
		<para>
			Rivet &version; implements a new <link linkend="request">request processing scheme</link> 
			entirely based on Tcl. By default rivet &version; provides compatiblity with the 
			version &version2-generic; scheme to handle a request but this can be entirely overridden by
			the developer replacing the central request handling procedure. See the 
			<link linkend="request">request processing</link> page.
		</para>
    </simplesect>
    <simplesect>
    	<title>Acknowledgements</title>
    	<para>This version of Rivet received substantial contributions from George Petasis who solved
    	several problems with the threaded code, improved the code in several ways and made the CMake
    	based build scripts</para>
    </simplesect>
</section>