* doc/rivet.xml.in: more entities to extend documentation
* doc/xml/intro.xml: introduction revised and extended
* doc/xml-2: files used to generate the manual removed or moved into doc/xml
* doc/rivet.css: changed color palette
diff --git a/ChangeLog b/ChangeLog
index d21690c..ea59804 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2017-12-29 Massimo Manghi <mxmanghi@apache.org>
+ * doc/rivet.xml.in: more entities to extend documentation
+ * doc/xml/intro.xml: introduction revised and extended
+ * doc/xml-2: files used to generate the manual removed or moved into doc/xml
+ * doc/rivet.css: changed color palette
+
2017-12-22 Massimo Manghi <mxmanghi@apache.org>
* doc/: more changes to manual pages
diff --git a/INSTALL b/INSTALL
index 8733bf5..a07a7d0 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,4 +1,4 @@
- Rivet 2.3 Installation
+ Rivet 3.0 Installation
======================
For more detailed instructions, see the docs/html/ directory.
@@ -14,7 +14,7 @@
./configure --with-tcl=/usr/lib/tcl8.6 \
--with-apache=/usr/local/apache2 \
--with-apxs=/usr/local/apache2/bin/apxs \
- --with-rivet-target-dir=/usr/local/lib/rivet2.3 \
+ --with-rivet-target-dir=/usr/local/lib/rivet3.0 \
--enable-version-display
2) if 'configure' was successful Rivet is ready for compilation
@@ -87,4 +87,4 @@
Rivet is packaged for various Linux flavours. A list is available at http://tcl.apache.org/download.html
-# RCS: @(#) $Id$
+# $Id$
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4a0101a..ea50a9f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -25,14 +25,14 @@
EXAMPLES:=$(wildcard examples/*.*)
# English, multiple files.
-$(buildir)/html/index.html: $(srcdir)/rivet.xml $(srcdir)/rivet-chunk.xsl $(srcdir)/rivet.xsl $(srcdir)/xml-2/*.xml
+$(buildir)/html/index.html: $(srcdir)/rivet.xml $(srcdir)/rivet-chunk.xsl $(srcdir)/rivet.xsl $(srcdir)/xml/*.xml
xsltproc --stringparam html.stylesheet rivet.css \
--stringparam html.ext ".html" \
--stringparam chunker.output.encoding UTF-8 \
--nonet -o $(builddir)/html/ $(srcdir)/rivet-chunk.xsl $(srcdir)/rivet.xml
# English, one big file.
-$(buildir)/html/rivet.html: $(srcdir)/rivet.xml $(srcdir)/rivet-nochunk.xsl $(srcdir)/rivet.xsl $(srcdir)/xml-2/*.xml
+$(buildir)/html/rivet.html: $(srcdir)/rivet.xml $(srcdir)/rivet-nochunk.xsl $(srcdir)/rivet.xsl $(srcdir)/xml/*.xml
xsltproc --stringparam html.stylesheet rivet.css \
--stringparam html.ext ".html" \
--stringparam chunker.output.encoding UTF-8 \
diff --git a/doc/convert_examples.tcl.in b/doc/convert_examples.tcl.in
index d6c3b16..c0aebc9 100644
--- a/doc/convert_examples.tcl.in
+++ b/doc/convert_examples.tcl.in
@@ -42,13 +42,14 @@
if {!$example_sgml_exists || \
([file mtime $example] > [file mtime $example_sgml])} {
- puts "$example needs to be escaped"
+ puts -nonewline "$example needs to be escaped..."
set example_text [string trim [::rivet::read_file $example]]
set example_sgml_fid [open $example_sgml w+]
puts $example_sgml_fid [::rivet::escape_sgml_chars $example_text]
close $example_sgml_fid
+ puts "done"
}
}
diff --git a/doc/rivet.css b/doc/rivet.css
index 69a50d5..e8566be 100644
--- a/doc/rivet.css
+++ b/doc/rivet.css
@@ -1,6 +1,7 @@
BODY
{
font-family: verdana;
+ background-color: #fbfcfc;
}
DIV.ABSTRACT
@@ -30,14 +31,14 @@
font-family: monospace;
white-space: pre;
width: 95%;
- background-color: #ffeeee;
+ background-color: #e8ecf2;
border: solid;
color: #000000;
- border-color: #990099;
- border-left: solid #990099 1px;
- border-right: solid #990099 1px;
- border-top: solid #990099 1px;
- border-bottom: solid #990099 1px;
+ border-color: #a3b1bc;
+ border-left: solid #a3b1bc 1px;
+ border-right: solid #a3b1bc 1px;
+ border-top: solid #a3b1bc 1px;
+ border-bottom: solid #a3b1bc 1px;
font-size: normal;
padding-top: 1em;
padding-left: 1em;
@@ -47,8 +48,8 @@
H1
{
color: #ffffff;
- border: solid 3px #a0a0d0;
- background-color: #606090;
+ border: solid 3px #1d252b;
+ background-color: #a3b1bc;
font-variant: small-caps;
width: 100%;
}
@@ -56,8 +57,8 @@
H1.TITLE
{
color: #ffffff;
- border: solid 3px #a0a0d0;
- background-color: #606090;
+ border: solid 3px #1d252b;
+ background-color: #a3b1bc;
font-variant: small-caps;
width: 100%;
}
@@ -81,8 +82,8 @@
{
COLOR: #ffffff ;
font-style: italic;
- BACKGROUND-color: #d0a0a0;
- BORDER: solid 3px #906060;
+ border: solid 3px #1d252b;
+ background-color: #a3b1bc;
PADDING: 0.5em;
}
@@ -121,7 +122,6 @@
font-style:italic;
font-weight: bold;
border: ridge 4px #ff0000;
-
width: 70%;
margin-left: 15%;
}
@@ -137,10 +137,10 @@
.VARLISTENTRY {
font-weight: bold;
margin-top: 10px;
- COLOR: #ffffff ;
- BACKGROUND-color: #a0a0d0;
- BORDER: solid 1px #606090;
- PADDING: 1px
+ color: #ffffff ;
+ background-color: #e8ecf2;
+ border: solid 1px #a3b1bc;
+ padding: 1px
}
/*
@@ -253,38 +253,38 @@
P.C2 {
- COLOR: #ffffff ;
- BACKGROUND-color: #a0a0d0;
- BORDER: solid 1px #606090;
- PADDING: 1px
+ COLOR: #ffffff ;
+ BACKGROUND-color: #a0a0d0;
+ BORDER: solid 1px #606090;
+ PADDING: 1px
}
DIV.NAVFOOTER {
color: #000000;
- background-color: #FFDFDF;
+ background-color: #e8ecf2;
padding: 5px;
margin-top: 10px;
width: 100%;
- border: 2px solid #d0a0a0;
+ border: 2px solid #a3b1bc;
}
DIV.NUKEFOOTER {
color: #000000;
- background-color: #B0E0E6;
+ background-color: #e8ecf2;
padding: 5px;
margin-top: 10px;
width: 100%;
- border: thin solid #a0a0d0;
+ border: thin solid #a3b1bc;
}
DIV.NAVHEADER {
color: #000000;
- background-color: #FFDFDF;
+ background-color: #e8ecf2;
padding: 5px;
margin-bottom: 10px;
width: 100%;
- border: 2px solid #d0a0a0;
+ border: 2px solid #a3b1bc;
}
DIV.SECT1,DIV.SECT2,DIV.SECT3 {
@@ -292,11 +292,11 @@
}
DIV.EXAMPLE,DIV.TOC {
- border: thin dotted #70AAE5;
+ border: thin dotted #4e5f6e;
padding-left: 10px;
padding-right: 10px;
color: #000000;
- background-color: #FFE8E8;
+ background-color: #e8ecf2;
}
DIV.EXAMPLE {
border: thin dotted #22AA22;
@@ -363,7 +363,7 @@
}
.directives tbody tr > :last-child {
- text-decoration: none;
+ text-decoration: none;
font-weight: normal;
font-size: small;
border-left: 1px solid black;
@@ -371,14 +371,14 @@
}
.directives tbody tr td {
- text-align: center;
- text-decoration: none;
- font-weight: normal;
- padding-left: 1em;
+ text-align: center;
+ text-decoration: none;
+ font-weight: normal;
+ padding-left: 1em;
padding-right: 1em;
- padding-bottom: 4px;
- padding-top: 4px;
- border-bottom: 1px solid black;
+ padding-bottom: 4px;
+ padding-top: 4px;
+ border-bottom: 1px solid black;
}
.note td {
diff --git a/doc/rivet.xml b/doc/rivet.xml
index bf0f28e..e6d6b94 100644
--- a/doc/rivet.xml
+++ b/doc/rivet.xml
@@ -11,10 +11,12 @@
<!ENTITY upload.rvt SYSTEM "examples-sgml/upload.rvt" >
<!ENTITY download.tcl SYSTEM "examples-sgml/download.tcl" >
<!ENTITY rivet_web_service.tcl SYSTEM "examples-sgml/rivet_web_service.tcl" >
- <!ENTITY request_handler.tcl SYSTEM "../rivet/default_request_handler.tcl">
+ <!ENTITY myapp_request_handler.tcl SYSTEM "examples-sgml/myapp_request_handler.tcl" >
+ <!ENTITY myrivetapp.tcl SYSTEM "examples-sgml/myrivetapp.tcl" >
+ <!ENTITY request_handler.tcl SYSTEM "../rivet/default_request_handler.tcl" >
<!ENTITY intro.xml SYSTEM "xml/intro.xml" >
<!ENTITY install.xml SYSTEM "xml/installation.xml" >
- <!ENTITY cmake.xml SYSTEM "xml/cmake.xml">
+ <!ENTITY cmake.xml SYSTEM "xml/cmake.xml" >
<!ENTITY directives.xml SYSTEM "xml/directives.xml" >
<!ENTITY commands.xml SYSTEM "xml/commands.xml" >
<!ENTITY examples.xml SYSTEM "xml/examples.xml" >
@@ -42,6 +44,9 @@
<!ENTITY apache-url "http://httpd.apache.org" >
<!ENTITY apachedoc-vhost "https://httpd.apache.org/docs/2.4/vhosts" >
<!ENTITY apachedoc-mpm "https://httpd.apache.org/docs/2.4/mpm.html" >
+ <!ENTITY apachedoc-docroot "https://httpd.apache.org/docs/2.4/mod/core.html#documentroot" >
+ <!ENTITY apachedoc-alias "https://httpd.apache.org/docs/2.4/mod/mod_alias.html" >
+ <!ENTITY apachedoc-rewrite "https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html" >
]>
<!--
diff --git a/doc/rivet.xml.in b/doc/rivet.xml.in
index 61e09a2..0c31c60 100644
--- a/doc/rivet.xml.in
+++ b/doc/rivet.xml.in
@@ -11,10 +11,12 @@
<!ENTITY upload.rvt SYSTEM "examples-sgml/upload.rvt" >
<!ENTITY download.tcl SYSTEM "examples-sgml/download.tcl" >
<!ENTITY rivet_web_service.tcl SYSTEM "examples-sgml/rivet_web_service.tcl" >
- <!ENTITY request_handler.tcl SYSTEM "../rivet/default_request_handler.tcl">
+ <!ENTITY myapp_request_handler.tcl SYSTEM "examples-sgml/myapp_request_handler.tcl" >
+ <!ENTITY myrivetapp.tcl SYSTEM "examples-sgml/myrivetapp.tcl" >
+ <!ENTITY request_handler.tcl SYSTEM "../rivet/default_request_handler.tcl" >
<!ENTITY intro.xml SYSTEM "xml/intro.xml" >
<!ENTITY install.xml SYSTEM "xml/installation.xml" >
- <!ENTITY cmake.xml SYSTEM "xml/cmake.xml">
+ <!ENTITY cmake.xml SYSTEM "xml/cmake.xml" >
<!ENTITY directives.xml SYSTEM "xml/directives.xml" >
<!ENTITY commands.xml SYSTEM "xml/commands.xml" >
<!ENTITY examples.xml SYSTEM "xml/examples.xml" >
@@ -42,6 +44,9 @@
<!ENTITY apache-url "http://httpd.apache.org" >
<!ENTITY apachedoc-vhost "https://httpd.apache.org/docs/2.4/vhosts" >
<!ENTITY apachedoc-mpm "https://httpd.apache.org/docs/2.4/mpm.html" >
+ <!ENTITY apachedoc-docroot "https://httpd.apache.org/docs/2.4/mod/core.html#documentroot" >
+ <!ENTITY apachedoc-alias "https://httpd.apache.org/docs/2.4/mod/mod_alias.html" >
+ <!ENTITY apachedoc-rewrite "https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html" >
]>
<!--
@@ -60,7 +65,7 @@
permissions and limitations under the License.
-->
-<!-- $Id: rivet.xml 1799149 2017-06-19 08:18:58Z mxmanghi $ -->
+<!-- $Id$ -->
<article>
<articleinfo>
diff --git a/doc/xml-2/directives.xml b/doc/xml-2/directives.xml
deleted file mode 100644
index 57ebdd1..0000000
--- a/doc/xml-2/directives.xml
+++ /dev/null
@@ -1,488 +0,0 @@
-<section id="directives">
- <title>Rivet Apache Directives</title>
- <section>
- <para>
- Rivet directives are used within the Apache httpd server
- configuration to set up the environment where Rivet script
- will be run. Their precedence is as follows:
- <command>RivetDirConf</command>,
- <command>RivetUserConf</command>,
- <command>RivetServerConf</command>, meaning that DirConf will
- override UserConf, which will in turn override ServerConf.
- </para>
- <para>
-
- </para>
-
- </section>
- <section>
- <variablelist>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>RivetServerConf</command>
- <group choice="req">
- <arg>CacheSize</arg>
- <arg>ServerInitScript</arg>
- <arg>GlobalInitScript</arg>
- <arg>ChildInitScript</arg>
- <arg>ChildExitScript</arg>
- <arg>BeforeScript</arg>
- <arg>AfterScript</arg>
- <arg>ErrorScript</arg>
- <arg>AbortScript</arg>
- <arg>AfterEveryScript</arg>
- <arg>UploadDirectory</arg>
- <arg>UploadMaxSize</arg>
- <arg>UploadFilesToVar</arg>
- <arg>SeparateChannels</arg>
- <arg>SeparateVirtualInterps</arg>
- <arg>HonorHeaderOnlyRequests</arg>
- </group>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- <command>RivetServerConf</command> specifies a global
- option that is valid for the whole server. If you have a
- virtual host, in some cases, the option specified in the
- virtualhost takes precedence over the 'global' version.
- </para>
- </listitem>
- <listitem>
- <variablelist>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">CacheSize</arg>
- <arg><replaceable>size</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Sets the size of the internal page cache, where
- <option><replaceable>size</replaceable></option> is
- the number of byte-compiled pages to be cached for
- future use. Default is
- <command>MaxRequestsPerChild</command> / 5, or 50,
- if <command>MaxRequestsPerChild</command> is 0.
- </para>
- <para>
- This option is completely global, even when using
- separate, per-virtual host interpreters.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">ServerInitScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Tcl script which is to run when the master interpreter is created.
- Namespaces, variables and packages loaded during this stage will
- be copied later on in the startup process, when child
- processes are created.
- </para>
- <para>
- This option is only available at the global level.
- </para>
- <para>
- The directive <command>ServerInitScript</command> plays a special
- role since the script runs within the master interpreter,
- an interpreter created before the Apache parent process spawns
- the children that actually will serve the requests coming from
- the network. During this stage Apache is still running as a
- single process, so this is the right place for doing
- initializations or loading packages. Since this
- script will be running in a single process environment (from the
- Apache point of view) <command>ServerInitScript</command>
- is also the right place for doing anything needs to avoid
- resource concurrency among processes (e.g. the creation and
- initialization of an IPC system)
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">GlobalInitScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Tcl script run as part of a child process initialization.
- If the option <option>SeparateVirtualInterp</option> is not used this is
- the right place where file handles, database connections or sockets can
- be opened.
- The argument <replaceable><option>script</option></replaceable>
- is an actual Tcl script, so to run a file, you would
- do: <programlisting>RivetServerConf GlobalInitScript "source /var/www/foobar.tcl"</programlisting>
- </para>
- <para>
- This option is ignored in virtual hosts.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">ChildInitScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Script to be evaluated when each Apache child
- process is initialized. This is the recommended
- place to load modules, create global variables, open
- connections to other facilities (such as databases)
- and so on.
- </para>
- <para>
- In virtual hosts, this script is run in addition to
- any global childinitscript.
- When <command>SeparateVirtualInterp</command>
- any <command>ChildInitScript</command> placed within a
- <option><VirtualHost ...>....</VirtualHost></option>
- will be that Virtual Host specific ininitalization
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">ChildExitScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Script to be evaluated when each Apache child
- process exits. This is the logical place to clean
- up resources created in <option>ChildInitScript</option>,
- if necessary.
- </para>
- <para>
- In virtual hosts, this script is run in addition to
- any global childexitscript.
-
- When <command>SeparateVirtualInterp</command>
- any <command>ChildExitScript</command> placed within a
- <option><VirtualHost ...>....</VirtualHost></option>
- will be that Virtual Host specific exit handler
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">BeforeScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Script to be evaluated before each server parsed
- (.rvt) page. This can be used to create a standard
- header, for instance. It could also be used to load
- code that you need for every page, if you don't want
- to put it in a <option>GlobalInitScript</option>
- <option>ChildInitScript</option> when you are first
- developing a web site.
- <note>
- This code is evaluated at the global level, not
- inside the request namespace where pages are
- evaluated.
- </note>
- </para>
- <para>
- In virtual hosts, this option takes precedence over
- the global setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">AfterScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Script to be called after each server parsed (.rvt) page.
- </para>
- <para>
- In virtual hosts, this option takes precedence over
- the global setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">ErrorScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- When Rivet encounters an error in a script, it
- constructs an HTML page with some information about
- the error, and the script that was being
- evaluated. If an <option>ErrorScript</option> is
- specified, it is possible to create custom error
- pages. This may be useful if you want to make sure
- that users never view your source code.
- </para>
- <para>
- In virtual hosts, this option takes precedence over
- the global setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">AfterEveryScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- <option>AfterEveryScript</option> is a script that is to
- be run anyway before requests processing ends. This script
- is therefore run both when the content generation script
- completes successfully and when its execution is interrupted
- by <xref linkend="abort_page" />. The code in this script
- can understand whether it's running after the page was
- interrupted by calling <xref linkend="abort_page" />
- with the argument <arg>-aborting</arg>. The command
- will return 1 if an abort_page call took place
- earlier in the request processing.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">AbortScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- The execution of a can be interrupted by
- invoking <xref linkend="abort_page" />. If
- an <option>AbortScript</option> is defined for the page
- being generated, control is passed to it. <option>AbortScript</option>
- is the right place where specific actions can be taken
- to catch resources left dangling by the sudden interruption.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">UploadDirectory</arg>
- <arg><replaceable>directory</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>Directory to place uploaded files.</para>
- <para>
- In virtual hosts, this option takes precedence over
- the global setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">UploadMaxSize</arg>
- <arg><replaceable>size</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>Maximum size for uploaded files.</para>
- <para>
- In virtual hosts, this option takes precedence over
- the global setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">UploadFilesToVar</arg>
- <group choice="req"><arg>yes</arg><arg>no</arg></group>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- This option controls whether it is possible to
- upload files to a Tcl variable. If you have a size
- limit, and don't have to deal with large files, this
- might be more convenient than sending the data to a
- file on disk.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">SeparateChannels</arg>
- <group choice="req">
- <arg>yes</arg>
- <arg>no</arg>
- </group>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Internally mod_rivet creates a new Tcl channel (Rivet channel) which is configured
- as <command>stdout</command> and registered to each existing interpreter.
- There is no need of multiple channels in a single thread as each thread can
- serve only one request at a time. But if you are deploying mod_rivet in a
- complex environment running unrelated applications developed by
- different teams, it could be the case to have <command>SeparateVirtualInterps</command>
- set. If you want to enhance the environment separation you may also
- set <command>SeparateChannels</command> to force mod_rivet to create
- a channel per each Tcl interpreter thus enabling single application
- code to change the Rivet channel parameters without affecting other
- applications (even though changing the Tcl channel parameters is a rare
- necessity). Setting this options increases the system overheads as each
- Rivet channel needs to allocate its own control structures and internal
- buffers.
- </para>
- <note>
- This option is implemented in order to have fine-grained control over mod_rivet. In
- nearly all practical cases you won't need to change Rivet Channel (stdout) settings
- for different applications by calling <command>fconfigure stdout ....</command>.
- This option is, by nature, only available at the global level and has effect only if
- also <command>SeparateVirtualInterps</command> is set
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">SeparateVirtualInterps</arg>
- <group choice="req">
- <arg>yes</arg>
- <arg>no</arg>
- </group>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- If on, Rivet will create a separate Tcl interpreter
- for each Apache virtual host. This is useful in an
- ISP type situation where it is desirable to separate
- clients into separate interpreters, so that they
- don't accidentally interfere with one another.
- </para>
- <note>
- This option is, by nature, only available at the
- global level. By enabling <command>SeparateVirtualInterps</command>
- you must rely only on <command>ChildInitScript</command> to
- initialize the interpreters. Don't expect the
- initialization done in <command>ServerInitScript</command> and
- <command>GlobalInitScript</command> to be handed down to the
- slave interpreters that are private to each configured
- virtual host.
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">HonorHeaderOnlyRequests</arg>
- <group choice="req">
- <arg>yes</arg>
- <arg>no</arg>
- </group>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- If a HEAD requests is issued by the client Rivet detects
- this case and sends back to the client a standard header
- response. If the real header has to be examined (e.g.
- for debugging) you can turn this options on.
- </para>
- <para>This option is, by nature, only available at the global level</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>RivetDirConf</command>
- <group choice="req">
- <arg>BeforeScript</arg>
- <arg>AfterScript</arg>
- <arg>ErrorScript</arg>
- <arg>UploadDirectory</arg>
- <arg>AfterEveryScript</arg>
- </group>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- These options are the same as for
- <command>RivetServerConf</command>, except that they are
- only valid for the directory where they are specified, and
- its subdirectories. It may be specified in <command>Directory</command>
- sections.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>RivetUserConf</command>
- <group choice="req">
- <arg>BeforeScript</arg>
- <arg>AfterScript</arg>
- <arg>ErrorScript</arg>
- <arg>UploadDirectory</arg>
- <arg>AfterEveryScript</arg>
- </group>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- These options are the same as for
- <command>RivetServerConf</command>, except that they are
- only valid for the directory where they are specified, and
- its subdirectories.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-</section>
diff --git a/doc/xml-2/install.xml b/doc/xml-2/install.xml
deleted file mode 100644
index ed0cf3b..0000000
--- a/doc/xml-2/install.xml
+++ /dev/null
@@ -1,253 +0,0 @@
-<section id="installation">
- <title>Apache Rivet Installation</title>
- <procedure>
- <para>
- Rivet 2.2 runs with the Apache 2.2.x and 2.4.x HTTP web server.
- It is known to build and run on various Linux distributions
- (Debian & Ubuntu, Redhat, SuSE and CentOS), FreeBSD and OpenBSD. For some
- of these Unix-like operative systems
- <ulink url="http://tcl.apache.org/rivet/static/download.html">binary packages</ulink>
- are already available for download.
- </para>
- <para>
- Currently there is no way to run Apache Rivet 2.2 on Windows© because
- Rivet currently requires the
- <ulink url="http://httpd.apache.org/docs/2.4/mod/prefork.html">prefork</ulink>, which
- is supported only on Unix/Linux systems. Efforts are under way to extend the support to the
- <ulink url="http://httpd.apache.org/docs/2.4/mod/worker.html">worker</ulink>
- and the
- <ulink url="http://httpd.apache.org/docs/2.4/mod/mpm_winnt.html">winnt</ulink> MPMs.
- Check our
- <ulink url="http://tcl.apache.org/rivet/static/about.html">development mailing list</ulink>
- for the latests updates about Rivet development
- </para>
- <para>
- If you need to compile Apache Rivet yourself this is the procedure to follow
- </para>
- <step performance="required">
- <title>Install Tcl</title>
- <para>
- Installing Rivet is about endowing the Apache HTTP webserver with the ability
- of running scripts written with the Tcl programming language.
- Therefore the
- <ulink url="http://www.tcl.tk/">Tcl</ulink>
- shell (<command>tclsh</command>), its runtime and
- development libraries (≥8.5.10) have to be installed. Building Rivet you will
- have to tell the scripts where the Tcl libraries are located via the
- <option>--with-tcl</option> option to <command>configure</command> (see below).
- </para>
- </step>
- <step>
- <title>Get Rivet</title>
- <para>
- Download the sources at <ulink url="http://tcl.apache.org/rivet/static/download.html"/>.
- </para>
- </step>
- <step performance="optional">
- <title>Get and Install Apache Sources</title>
- <para>
- Rivet needs some of the include (.h) files shipped with the webserver source code.
- The easiest way to get them is to download the Apache source.
- If can build Rivet either statically (compiled into the Apache web
- server instead of loaded dynamically) or dynamically (as a loadable shared library).
- We recommend that you build Rivet as a shared library, for maximum flexibility,
- meaning that you also build Apache to be able to load modules. Other than that,
- the default Apache install is fine. We will tell Rivet where it is located via the
- <option>--with-apxs</option> option to <command>configure</command> (see below).
- </para>
- <para>
- The source code for the Apache web server may be found by following the links here:
- <ulink url="http://httpd.apache.org/"/>.
- </para>
- </step>
- <step>
- <title>Uncompress Sources</title>
- <para>
- We will assume that you have Apache installed at this point.
- You must uncompress the Rivet sources in the directory where you
- wish to compile them.
- <programlisting>gunzip rivet-X.X.X.tar.gz
-tar -xvf rivet-X.X.X.tar.gz</programlisting>
- </para>
- </step>
- <step>
- <title>Building Rivet</title>
- <substeps>
- <step>
- <para>
- On Linux or Unix systems, Rivet uses the standard <command>./configure ; make ; make install</command>
- sequence which installs to their target directories the Apache module, the binary libraries and the
- Tcl code
- </para>
- <para>
- There are several rivet specific options to configure that might be useful (or needed):
- <variablelist>
- <varlistentry>
- <term>--with-tcl</term>
- <listitem>
- <para>
- This points to the directory where the
- <filename>tclConfig.sh</filename> file is located.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--with-tclsh</term>
- <listitem>
- <para>This points to the location of the
- <filename>tclsh</filename> executable.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--with-apxs</term>
- <listitem>
- <para>The location of the <filename>apxs</filename>
- program that provides information about the
- configuration and compilation options of Apache modules.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--with-apache-include[=DIR]</term>
- <listitem>
- <para>
- Locates the Apache include files on your computer, if they're not in standard directory.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--enable-version-display=[yes|no]</term>
- <listitem>
- <para>
- This option enables Rivet to display its version in the logfiles when Apache is started.
- The default is to keep Rivet version hidden.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--with-rivet-target-dir=DIR</term>
- <listitem>
- <para>
- This option tells the install script where Rivet's Tcl packages have to be copied.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--with-upload-dir=DIR</term>
- <listitem>
- <para>
- Configures Rivet's default upload directory
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--enable-head-requests</term>
- <listitem>
- <para>
- By default HEAD requests don't go through the usual request processing which leads
- to script execution and therefore resource consumption and Rivet returns a
- standard hardcoded HTML header to save CPU time. --enable-head-requests
- changes this default (see also <link linkend="directives">Rivet Directives</link>)
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--disable-rivet-commands-export</term>
- <listitem>
- <para>
- By default Rivet's commands are put on the export list of the <code>::rivet</code>
- namespace. With this option you may prevent it thus forcing the programmer to
- fully qualify <link linkend="commands">these commands</link>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--disable-import-rivet-commands</term>
- <listitem>
- <para>
- Likewise commands in the Rivet's namespace when exported are then by default imported
- into the global namespace for compatibility with previous version of Rivet.
- (Enabling the import of Rivet's commands overrides the switch --disable-rivet-commands-export
- and forces the export from <code>::rivet</code>). This switch overrides the default and
- prevents the import into the global namespace
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- <para>
- Example: configuring the build system to compile Rivet for an apache 2.x server, using tcl8.5 and
- specifying a custom name for the apxs program.
- </para>
- <programlisting>./configure --with-tcl=/usr/lib/tcl8.5/ --with-tclsh=/usr/bin/tclsh8.5 \
- --with-apxs=/usr/bin/apxs2 --with-apache=/usr --with-apache-version=2</programlisting>
- </step>
- <step>
- <title>Run make</title>
- <para>
- At this point, you are ready to run make, which should
- run to completion without any errors (a warning or two
- is ok, generally).
- </para>
- </step>
- <step>
- <title>Install</title>
- <para>
- Now, you are ready to run the
- </para>
- <programlisting>make install</programlisting>
- <para>
- to install the resulting files. The <code>install</code> target
- actually fires the <code>install-binaries</code> and
- <code>install-packages</code> targets which in turn
- copy the binary modules and Tcl packages to their destination
- directories. This commands create a functional Rivet environment with its
- core language.
- </para>
- </step>
- </substeps>
- </step>
- <step>
- <title>Apache Configuration Files</title>
- <para>
- Rivet is relatively easy to configure - we start off by
- adding the module itself:
- </para>
-
- <programlisting>LoadModule rivet_module <replaceable>/usr/lib/apache2/modules/mod_rivet.so</replaceable></programlisting>
-
- <para>
- This tells Apache to load the Rivet shared object, wherever
- it happens to reside on your file system. Now we have to
- tell Apache what kind of files are "Rivet" files and how to
- process them:
- </para>
-
- <programlisting>AddType application/x-httpd-rivet .rvt
-AddType application/x-rivet-tcl .tcl</programlisting>
-
- <para>
- These tell Apache to process files with the
- <filename>.rvt</filename> and <filename>.tcl</filename>
- extensions as Rivet files.
- </para>
- <para>
- The characters encoding can be changed using the <command>header type</command> command,
- but you can also change the default charset for the whole site:
- </para>
- <programlisting>AddType 'application/x-httpd-rivet;charset=utf-8' rvt</programlisting>
- <para>
- All the pages generated by Rivet on this site will be sent with a
- <command>Content-Type:'text/html;charset=utf-8'</command> header.
- </para>
- <para>You may also wish to use Rivet files as index files for
- directories. In that case, you would do the following:</para>
- <programlisting>DirectoryIndex index.html index.htm index.shtml index.cgi index.tcl index.rvt</programlisting>
- <para>
- For other directives that Rivet provides for Apache
- configuration, please see <xref linkend="directives"/>.
- </para>
- </step>
- </procedure>
-</section>
-
diff --git a/doc/xml-2/intro.xml b/doc/xml-2/intro.xml
deleted file mode 100644
index 5367491..0000000
--- a/doc/xml-2/intro.xml
+++ /dev/null
@@ -1,45 +0,0 @@
-<section id="introduction">
- <title>Introduction to Apache Rivet</title>
- <para>
- Apache Rivet is a system for creating dynamic web content via a
- programming language integrated with Apache Web Server. 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). In order to
- meet these goals, we have chosen the Tcl programming language to
- combine with the Apache Web Server.
- </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>Introduction</title>
- <para>
- Rivet 3.0 ships with a major rewriting of mod_rivet, the Apache HTTP
- Websever module at the core of Rivet. With this version of the module
- we attained full support of different MPM (Multiprocessing Modules) for
- the Apache framework, whereas previous version of mod_rivet only supported
- the prefork MPM.
- </para>
- <!-- itemizedlist>
- <listitem>
- </listitem>
- <listitem>
- </listitem>
- </itemizedlist -->
- </simplesect>
-</section>
diff --git a/doc/xml-2/upgrade.xml b/doc/xml-2/upgrade.xml
deleted file mode 100644
index 6240259..0000000
--- a/doc/xml-2/upgrade.xml
+++ /dev/null
@@ -1,50 +0,0 @@
- <section id="upgrading">
- <title>Upgrading from mod_dtcl or NeoWebScript</title>
- <para>
- Rivet is a break from the past, in that we, the authors, have
- attempted to take what we like best about our past efforts, and
- leave out or change things we no longer care for. Backwards
- compatibility was not a primary goal when creating Rivet, but we
- do provide this information which may be of use to those wishing
- to upgrade from mod_dtcl or NWS installations.
- </para>
- <section>
- <title>mod_dtcl</title>
- <para>
- Rivet was originally based on the dtcl code, but it has
- changed (improved!) quite a bit. The concepts remain the
- same, but many of the commands have changed.
- </para>
- </section>
- <section>
- <title>NeoWebScript</title>
- <para>
- NWS was a server-side scripting environment based on the Apache
- HTTP server and Safe-Tcl and it's not maintained anymore.
- </para>
- <para>
- The biggest difference between Rivet and Neowebscript is that
- Neowebscript was designed for shared hosting while Rivet is more oriented
- toward a site that owns all of its content. In the words of Karl Lehenbauer,
- NWS author and Rivet Team member:
- </para>
- <para>
- Rivet, however, is considerably more efficient, powerful, and
- evolved, though it still can support multiple independent sites on a single
- machine through its <quote>separate virtual interpreters</quote> mechanism.
- <itemizedlist>
- <listitem>By powerful, the difference is that the full power of Tcl is available
- to webpage authors, not the restricted version that NWS provides.
- For instance, you can read or write any file in the system that you
- have permission to, require any package, open sockets and pipes, etc.</listitem>
- <listitem>By efficient, the difference is that Tcl interpreters survive past
- the generation of a webpage and are reused again and again, reducing the
- overhead of generating a page.
- </listitem>
- <listitem>By evolved, all of our efforts have gone toward Rivet for many
- years and so, you know, Rivet does more out of the box than Neowebscript did.</listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
-
diff --git a/doc/xml/directives.xml b/doc/xml/directives.xml
index c5d29ee..fcd6407 100644
--- a/doc/xml/directives.xml
+++ b/doc/xml/directives.xml
@@ -19,7 +19,7 @@
globally (either to the whole Rivet installation or a single
<ulink url="&apachedoc-vhost;">virtual host</ulink>)
</listitem>
- </itemizedlist>
+ </itemizedlist>
These directives are applied so that RivetDirConf will
override RivetUserConf, which in turn overrides any
@@ -89,10 +89,9 @@
</term>
<listitem>
<para>
- The execution of a can be interrupted by
- invoking <xref linkend="abort_page" />. If
- an <option>AbortScript</option> is defined for the page
- being generated, control is passed to it. <option>AbortScript</option>
+ If an <option>AbortScript</option> is defined control is passed to it as
+ soon as the command <xref linkend="abort_page" /> is called.
+ <option>AbortScript</option>
is the right place where specific actions can be taken
to catch resources left dangling by the sudden interruption.
</para>
@@ -106,7 +105,6 @@
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
-
<listitem>
<para>
Script to be called after each parsed .rvt template or .tcl script
diff --git a/doc/xml/intro.xml b/doc/xml/intro.xml
index d8e91fc..79df424 100644
--- a/doc/xml/intro.xml
+++ b/doc/xml/intro.xml
@@ -27,22 +27,24 @@
</para>
<simplesect>
- <title>Introduction</title>
+ <!-- title>Introduction</title -->
+ <title>Rivet - MPM Bridge</title>
<para>
Rivet &version; ships with a major rewriting of mod_rivet, the Apache HTTP
- Websever module at the core of Rivet. With this version of the module
+ Websever module at the core of Rivet. Unlike in previous versions of
+ mod_rivet which only supported
+ the prefork MPM, starting with &version30;
we attained full support of different MPM (Multiprocessing Modules) for
- the Apache framework, whereas previous version of mod_rivet only supported
- the prefork MPM.
+ the Apache framework.
</para>
- <title>Rivet - MPM Bridge</title>
<para>
Threaded <ulink href="&apachedoc-mpm;">MPM</ulink>
integration was achieved by making mod_rivet multithreaded and
- modular itself, introducing the concept of MPM bridges, a set of loadable modules
- responsible to offer the running MPM the best possible integration with
+ modular itself, introducing the concept of a MPM module-bridge.
+ We developed a set of loadable modules
+ responsible to offer to the running MPM the best possible integration with
mod_rivet. 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 platform for writing more MPM bridges
+ 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 can be determined in the configuration and only
@@ -52,13 +54,17 @@
<simplesect>
<title>Request Processing</title>
<para>
- Request processing was performed in mod_rivet version 2.x by chaining together 3 scripts
+ 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 (using the defaults defined in the
- Apache webserver configuration)</listitem>
- <listitem>AfterScript, if defined in the configuration</listitem>
+ <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)
diff --git a/doc/xml/processing.xml b/doc/xml/processing.xml
index 2c16315..a96aae5 100644
--- a/doc/xml/processing.xml
+++ b/doc/xml/processing.xml
@@ -15,23 +15,27 @@
scripts can break because of coding errors (thus triggering the
ErrorScript execution) or it can deliberately interrupt
ordinary execution by calling ::rivet::abort_page (triggering
- the execution of an AbortScript. This scheme is in case
- terminated a further configurable script (AfterEveryScript).
+ the execution of a script defined by the directive AbortScript).
+ This scheme is in case
+ terminated by a further configurable script (AfterEveryScript).
In mod_rivet &version2-generic; module series
this model of request handling was coded within
- the module.
+ the module mod_rivet.so itself.
</para>
<para>
With Rivet &version30; we changed this approach and landed to
a new much simpler and flexible model where each request is
by default handled by the following Tcl procedure
</para>
+
<programlisting>&request_handler.tcl;</programlisting>
+
<para>
Note the call to new &version30; command ::rivet::url_script
that returns the body of the Tcl script or Rivet template
pointed by the URL.
</para>
+
<para>
This procedure emulates the &version2-generic; scheme
and as such works as a fully compatible request handling
@@ -42,12 +46,12 @@
<note>
Note that if you redefine the core request handler
you'll need to handle yourself any error conditions
- and any code interruption caused by calls to::rivet::abort_page.
+ and any code interruption brought about by calling
+ <command>::rivet::abort_page</command>.
The current procedure might work as a template to be
reworked and used as a template to develop your own
request handler.
</note>
-
</section>
<section>
@@ -69,43 +73,7 @@
the application class is defined and an instance of it is
created in the global namespace.
</para>
- <programlisting># myrivetapp.tcl --
-#
-# Application class definition and instance creation
-#
-
-package require Itcl
-
-::itcl::class MyRivetApp {
-
- private variable application_name
-
- public method init {}
- public method request_processing {urlencoded_args}
-
-}
-
-::itcl::body MyRivetApp::init {app_name}{
-
- # any initialization steps must go here
- # ....
-
- set application_name $app_name
-
-}
-
-::itcl::body MyRivetApp::request_processing {urlencoded_args} {
-
- # the whole application code will run from this method
- ...
-
-}
-
-set ::theApplication [MyRivetApp #auto]
-
-$::theApplication init [dict get [::rivet::inspect server] hostname]
-
-# -- myrivetapp.tcl </programlisting>
+ <programlisting>&myrivetapp.tcl;</programlisting>
<para>
which provides a very basic interface for both initialization
and request processing. Such script will be sourced into the
@@ -123,58 +91,14 @@
and how the method MyRivetApp::request_processing will
be called with appropriate arguments
</para>
- <programlisting># -- myapp_request_handler.tcl
-#
-# This script will be read by mod_rivet at the thread initialization
-# stage and its content stored in a Tcl_Obj object. This object will
-# be evaluated calling Tcl_EvalObjExe
-#
-
-::try {
-
- ::theApplication request_processing [::rivet::var_qs all]
-
-} trap {RIVET ABORTPAGE} {err opts} {
-
- switch [::rivet::abort_code] {
- code1 {
- # handling abort_page with code1
- ....
- }
- code2 {
- # handling abort_page with code2
- ....
- }
- ....
- default {
- # default abort handler
- }
- }
-
-} trap {RIVET THREAD_EXIT} {err opts} {
-
- # myApplication sudden exit handler
- ...
-
-} on error {err opts} {
-
- # myApplication error handler
- ...
-
-} finally {
-
- # request processing final elaboration
-
-}
-
-# -- myapp_request_handler.tcl</programlisting>
+ <programlisting>&myapp_request_handler.tcl;</programlisting>
</section>
<para>
Finally we have to tell mod_rivet to run this script when a
request is delivered to myApplication and we do so
using the &version30; directive <command>RequestHandler</command>
</para>
-<programlisting><IfModule rivet_module>
+ <programlisting><IfModule rivet_module>
RivetServerConf ChildInitScript "source myrivetapp.tcl"
RivetServerConf RequestHandler "myapp_request_handler.tcl"
</IfModule></programlisting>
