You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-cvs@tcl.apache.org by mx...@apache.org on 2017/06/19 08:18:58 UTC
svn commit: r1799149 - in /tcl/rivet/trunk: ChangeLog
doc/convert_examples.tcl.in doc/examples-sgml/color-table.tcl
doc/examples/color-table.tcl doc/images/color-table.png doc/rivet.css
doc/rivet.xml doc/style.css doc/xml/directives.xml doc/xml/intro.xml
Author: mxmanghi
Date: Mon Jun 19 08:18:58 2017
New Revision: 1799149
URL: http://svn.apache.org/viewvc?rev=1799149&view=rev
Log:
* doc/xml/directives.xml: first rewriting into a new page.
Still more directives to be documented
* doc/convert_examples.tcl.in: changed message
* doc/rivet.css: add directives for styling the
directives page
Modified:
tcl/rivet/trunk/ChangeLog
tcl/rivet/trunk/doc/convert_examples.tcl.in
tcl/rivet/trunk/doc/examples-sgml/color-table.tcl
tcl/rivet/trunk/doc/examples/color-table.tcl
tcl/rivet/trunk/doc/images/color-table.png
tcl/rivet/trunk/doc/rivet.css
tcl/rivet/trunk/doc/rivet.xml
tcl/rivet/trunk/doc/style.css
tcl/rivet/trunk/doc/xml/directives.xml
tcl/rivet/trunk/doc/xml/intro.xml
Modified: tcl/rivet/trunk/ChangeLog
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/ChangeLog?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/ChangeLog (original)
+++ tcl/rivet/trunk/ChangeLog Mon Jun 19 08:18:58 2017
@@ -1,3 +1,10 @@
+2017-06-19 Massimo Manghi <mx...@apache.org>
+ * doc/xml/directives.xml: first rewriting into a new page.
+ Still more directives to be documented
+ * doc/convert_examples.tcl.in: changed message
+ * doc/rivet.css: add directives for styling the
+ directives page
+
2017-06-09 Massimo Manghi <mx...@apache.org>
* doc/xml/: manual rewriting started
Modified: tcl/rivet/trunk/doc/convert_examples.tcl.in
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/convert_examples.tcl.in?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/convert_examples.tcl.in (original)
+++ tcl/rivet/trunk/doc/convert_examples.tcl.in Mon Jun 19 08:18:58 2017
@@ -42,7 +42,7 @@ foreach example $source_examples {
if {!$example_sgml_exists || \
([file mtime $example] > [file mtime $example_sgml])} {
- puts "$example needs rebuild"
+ puts "$example needs to be escaped"
set example_text [string trim [::rivet::read_file $example]]
Modified: tcl/rivet/trunk/doc/examples-sgml/color-table.tcl
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/examples-sgml/color-table.tcl?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/examples-sgml/color-table.tcl (original)
+++ tcl/rivet/trunk/doc/examples-sgml/color-table.tcl Mon Jun 19 08:18:58 2017
@@ -1,9 +1,10 @@
puts "<html><head>"
-puts "<style>\n td { font-size: 12px; }\n td.bright { color: #eee; }\n td.dark { color: #222; }\n</style>"
+puts "<style>\n td { font-size: 12px; text-align: center; padding-left: 3px; padding-right: 3px}"
+puts " td.bright { color: #eee; }\n td.dark { color: #222; }\n</style>"
puts "</head><body>"
puts "<table>"
-# we create a 8x8 table selecting a different background for each cell
+# we create a 9x9 table selecting a different background for each cell
for {set i 0} { $i < 9 } {incr i} {
puts "<tr>"
@@ -16,7 +17,7 @@ for {set i 0} { $i < 9 } {incr i} {
# determining the background luminosity (YIQ space of NTSC) and choosing
# the foreground color accordingly in order maintain maximum contrast
- if { [expr ($r*0.29894)+($g*0.58704)+($b*0.11402)] > 128} {
+ if { [expr ($r*0.29894)+($g*0.58704)+($b*0.11402)] > 128.0} {
set cssclass "dark"
} else {
set cssclass "bright"
Modified: tcl/rivet/trunk/doc/examples/color-table.tcl
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/examples/color-table.tcl?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/examples/color-table.tcl (original)
+++ tcl/rivet/trunk/doc/examples/color-table.tcl Mon Jun 19 08:18:58 2017
@@ -1,9 +1,10 @@
puts "<html><head>"
-puts "<style>\n td { font-size: 12px; }\n td.bright { color: #eee; }\n td.dark { color: #222; }\n</style>"
+puts "<style>\n td { font-size: 12px; text-align: center; padding-left: 3px; padding-right: 3px}"
+puts " td.bright { color: #eee; }\n td.dark { color: #222; }\n</style>"
puts "</head><body>"
puts "<table>"
-# we create a 8x8 table selecting a different background for each cell
+# we create a 9x9 table selecting a different background for each cell
for {set i 0} { $i < 9 } {incr i} {
puts "<tr>"
@@ -16,7 +17,7 @@ for {set i 0} { $i < 9 } {incr i} {
# determining the background luminosity (YIQ space of NTSC) and choosing
# the foreground color accordingly in order maintain maximum contrast
- if { [expr ($r*0.29894)+($g*0.58704)+($b*0.11402)] > 128} {
+ if { [expr ($r*0.29894)+($g*0.58704)+($b*0.11402)] > 128.0} {
set cssclass "dark"
} else {
set cssclass "bright"
Modified: tcl/rivet/trunk/doc/images/color-table.png
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/images/color-table.png?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/rivet.css
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/rivet.css?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/rivet.css (original)
+++ tcl/rivet/trunk/doc/rivet.css Mon Jun 19 08:18:58 2017
@@ -342,10 +342,49 @@ UL {
background-color: #eee;
}
+table.directives {
+ border-collapse: collapse;
+}
+.directives thead {
+ background-color: #bbf;
+ font-size: 1em;
+ text-decoration: none;
+}
+
+.directives thead td {
+ padding: 8px;
+}
+
+.directives tbody tr > :first-child {
+ background-color: #eee;
+ padding-left: 2em;
+ padding-right: 2em;
+ text-align: left;
+}
+
+.directives tbody tr > :last-child {
+ text-decoration: none;
+ font-weight: normal;
+ font-size: small;
+ border-left: 1px solid black;
+ text-align: left;
+}
+
+.directives tbody tr td {
+ 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;
+}
+
.note td {
- font-size: small;
+ font-size: small;
}
li.listitem {
- font-size: small;
+ font-size: small;
}
Modified: tcl/rivet/trunk/doc/rivet.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/rivet.xml?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/rivet.xml (original)
+++ tcl/rivet/trunk/doc/rivet.xml Mon Jun 19 08:18:58 2017
@@ -30,11 +30,14 @@
<!ENTITY asciiglyphs.xml SYSTEM "xml-2/asciiglyphs.xml" >
<!ENTITY lazybridge.xml SYSTEM "xml/lazybridge.xml" >
<!ENTITY formbroker.xml SYSTEM "xml/formbroker.xml" >
- <!ENTITY version "3.0" >
- <!ENTITY fullversion "3.0.0" >
- <!ENTITY version2-series "2.0,2.1,2.2,2.3" >
- <!ENTITY version2-generic "2.x" >
-
+ <!ENTITY version "3.0" >
+ <!ENTITY fullversion "3.0.0" >
+ <!ENTITY version2-series "2.0,2.1,2.2,2.3" >
+ <!ENTITY version2-generic "2.x" >
+ <!ENTITY tcltk-url "http://www.tcl.tk/" >
+ <!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" >
]>
<!--
Modified: tcl/rivet/trunk/doc/style.css
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/style.css?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/style.css (original)
+++ tcl/rivet/trunk/doc/style.css Mon Jun 19 08:18:58 2017
@@ -40,10 +40,10 @@ code {
}
div.box {
- border-width: medium;
- padding: 0.25em;
+ border-width: medium;
+ padding: 0.25em;
background-color: #dddddd;
}
li {
-}
\ No newline at end of file
+}
Modified: tcl/rivet/trunk/doc/xml/directives.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/xml/directives.xml?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/xml/directives.xml (original)
+++ tcl/rivet/trunk/doc/xml/directives.xml Mon Jun 19 08:18:58 2017
@@ -4,59 +4,181 @@
<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.
+ will be run.
+ </para>
+ <title>Apache Rivet Configuration lines</title>
+ <para>
+ Rivet has 3 general <quote>scope</quote> directives
+
+ <itemizedlist>
+ <listitem>RivetDirConf: for configuration directives meant to
+ apply to a directory tree</listitem>
+ <listitem>RivetUserConf: for directives specific to
+ a user private space</listitem>
+ <listitem>RivetServerConf: for any directive meant to apply
+ globally (either to the whole Rivet installation or a single
+ <ulink url="&apachedoc-vhost;">virtual host</ulink>)
+ </listitem>
+ </itemizedlist>
+
+ These directives are applied so that RivetDirConf will
+ override RivetUserConf, which in turn overrides any
+ RivetServerConf directives. Not every configuration directory
+ is meaningful to a scope directive, as shown in the table below. The scope
+ of application of a configuration line is matched also with the context where
+ it appears. Virtual hosts definitions are contexts where rivet configuration
+ lines can appear in many adding further customization to a given virtual
+ host server.
</para>
+ <para>
+ Example of configuration of a web server having independent
+ interpreters for each virtual host, a larger default cache and a specific
+ script to be executed before any templates/scripts located in /var/www/myrivetapp
+ </para>
+ <programlisting><IfModule rivet_module>
+ AddType application/x-httpd-rivet .rvt
+ AddType application/x-rivet-tcl .tcl
+
+ RivetServerConf CacheSize 100
+ RivetServerConf SeparateVirtualInterps On
+</IfModule>
+
+<Directory /var/www/myrivetapp>
+ RivetDirConf BeforeScript "source /var/www/myrivetapp/before_script.tcl"
+</Directory></programlisting>
- </section>
+ </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>
+ <title>Configuration Directives</title>
+ <table align="center" title="Configuration Directives application scopes" class="directives">
+ <thead>
+ <td>Configuration Directives</td><td>DirConf</td><td>UserConf</td><td>ServerConf</td><td>Virtual Host</td><td>Notes</td>
+ </thead>
+ <tbody>
+ <tr><td>AbortScript</td><td>X</td><td>X</td><td>X</td><td>X</td><td></td></tr>
+ <tr><td>AfterScript</td><td>X</td><td>X</td><td>X</td><td>X</td><td></td></tr>
+ <tr><td>AfterEveryScript</td><td>X</td><td>X</td><td>X</td><td>X</td><td></td></tr>
+ <tr><td>BeforeScript</td><td>X</td><td>X</td><td>X</td><td>X</td><td></td></tr>
+ <tr><td>CacheSize</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>ChildExitScript</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>ChildInitScript</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>ErrorScript</td><td>X</td><td>X</td><td>X</td><td>X</td><td></td></tr>
+ <tr><td>ExportRivetNS</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>GlobalInitScript</td><td></td><td></td><td>X</td><td></td><td>effective only when SeparateVirtualInterps is Off (default)</td></tr>
+ <tr><td>ImportRivetNS</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>HonorHeaderOnlyRequests</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>MpmBridge</td><td></td><td></td><td>X</td><td></td><td>global setting</td></tr>
+ <tr><td>SeparateChannels</td><td></td><td></td><td>X</td><td></td><td>global setting</td></tr>
+ <tr><td>SeparateVirtualInterps</td><td></td><td></td><td>X</td><td></td><td>global setting</td></tr>
+ <tr><td>ServerInitScript</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>UploadDirectory</td><td></td><td>X</td><td>X</td><td>X</td><td></td></tr>
+ <tr><td>UploadFilesToVar</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+ <tr><td>UploadMaxSize</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
+ </tbody>
+ </table>
+
+ <variablelist>
+ <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">AfterScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+
+ <listitem>
+ <para>
+ Script to be called after each parsed .rvt template or .tcl script
+ is executed
+ </para>
+ <para>
+ In virtual hosts, this option overrides any AfterScript
+ definitions at the global level.
+ </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">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">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
@@ -66,67 +188,38 @@
</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>
+ separate per-virtual host interpreters.
</para>
- <para>
- This option is ignored in virtual hosts.
- </para>
- </listitem>
- </varlistentry>
+ </listitem>
+ </varlistentry>
- <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">ChildInitScript</arg>
@@ -150,333 +243,230 @@
will be that Virtual Host specific ininitalization
</para>
</listitem>
- </varlistentry>
+ </varlistentry>
- <varlistentry>
+ <varlistentry>
<term>
<cmdsynopsis>
- <arg choice="plain">ChildExitScript</arg>
+ <arg choice="plain">ErrorScript</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.
+ 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 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
+ In virtual hosts, this option takes precedence over
+ the global setting.
</para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">ExportRivetNS</arg>
+ <group choice="req">
+ <arg>yes</arg>
+ <arg>no</arg>
+ </group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Rivet commands are created within the ::rivet namespace. Setting
+ this option you tell mod_rivet to place the whole command set on
+ the export list of namespace, enabling your scripts to import
+ them in a different namespace.
+ </para>
+ <para>This option is, by nature, only available at the global level</para>
+ </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>
+
+ <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">ServerInitScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ The directive <command>ServerInitScript</command> plays a special
+ role since the script runs within the master interpreter,
+ an interpreter created when the Apache web server is setting up
+ for answering requests and before worker processes/threads are
+ started. During this stage Apache is still running as a
+ single process, so this is the right place for doing
+ initialization of systems such as any IPC systems.
+ </para>
+ <para>
+ On systems with the capability of forking child processes
+ the Apache web server can run the prefork MPM. By default
+ rivet selects the prefork brigde which makes mod_rivet work
+ the way mod_rivet &version2-generic; work.
+ In a web server with this set up child processes inherit a copy of the
+ address space from the parent processes and therefore
+ Tcl interpreters too are replicated into the child address space.
+ If SeparateVirtualInteprs is Off child processes run with a
+ copy of the Tcl master interpreter and ServerInitScipt
+ thus provides a way to initialize only once
+ any subsequent Tcl interpreters created by fork calls as each
+ of them are clones of the master interpreter.
+ </para>
+
+ </listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry>
<term>
<cmdsynopsis>
- <arg choice="plain">BeforeScript</arg>
- <arg><replaceable>script</replaceable></arg>
+ <arg choice="plain">UploadDirectory</arg>
+ <arg><replaceable>directory</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
+ <para>Directory to place uploaded files.</para>
<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>
+ 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>
- In virtual hosts, this option takes precedence over
- the global setting.
+ 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">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>
+ </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">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">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>
Modified: tcl/rivet/trunk/doc/xml/intro.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/xml/intro.xml?rev=1799149&r1=1799148&r2=1799149&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/xml/intro.xml (original)
+++ tcl/rivet/trunk/doc/xml/intro.xml Mon Jun 19 08:18:58 2017
@@ -3,8 +3,8 @@
<para>
Apache Rivet is a system for creating dynamic web content by
integrating the
- <ulink url="http://www.tcl.tk/">Tcl programming language</ulink> within the
- <ulink url="http://httpd.apache.org">Apache Web Server</ulink>.
+ <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
@@ -37,7 +37,7 @@
</para>
<title>Rivet - MPM Bridge</title>
<para>
- Threaded <ulink href="https://httpd.apache.org/docs/2.4/mpm.html">MPM</ulink>
+ 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
---------------------------------------------------------------------
To unsubscribe, e-mail: site-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: site-cvs-help@tcl.apache.org