A good start on docs, WTD

1 files changed, 673 insertions, 157 deletions

diff --git a/project2/docs/docbook.xml b/project2/docs/docbook.xml
index e8b7028..868088d 100644
--- a/project2/docs/docbook.xml
+++ b/project2/docs/docbook.xml
@@ -1,107 +1,75 @@
 <?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5CR3/docbookx.dtd">
 <book>
 	<bookinfo>
 		<title>Project2 - Platform Guide</title>
 		<author>
 			<firstname>Dan</firstname>
 			<surname>Goodliffe</surname>
-			<affiliation>
-				<address>
-					<email>dan@randomdan.homeip.net</email>
-				</address>
-			</affiliation>
-			<personblurb>foo</personblurb>
+			<email>dan@randomdan.homeip.net</email>
+			<personblurb><para>Original author</para></personblurb>
 		</author>
 		<copyright>
 			<year>2011</year>
 			<holder role="mailto:dan@randomdan.homeip.net">Dan Goodliffe</holder>
 		</copyright>
 		<abstract>
-			<para>The complete guide to everything Project2</para>
+			<para>The complete guide to everything Project2.</para>
 		</abstract>
-	</bookinfo>
-	<info>
 		<productname>Project2</productname>
-	</info>
-	<chapter>
-		<title>Introduction</title>
-	</chapter>
-	<chapter>
-		<title>Requirements</title>
-	</chapter>
-	<chapter>
-		<title>Compilation</title>
-	</chapter>
-	<chapter>
-		<title>Installation</title>
-	</chapter>
-	<chapter>
-		<title>Deployment</title>
-	</chapter>
+	</bookinfo>
 	<chapter>
-		<title>Runtime configuration</title>
-		<refentry id="p2config">
-			<refmeta>
-				<refentrytitle>p2config</refentrytitle>
-				<manvolnum>5</manvolnum>
-			</refmeta>
-			<refnamediv>
-				<refname>p2config</refname>
-				<refname>.p2config</refname>
-				<refpurpose>Configure runtime behaviour of Project2 application engines.</refpurpose>
-			</refnamediv>
-			<variablelist>
-				<varlistentry>
-					<term><envar>sysloglevel=<replaceable>&lt;-1...7&gt;</replaceable></envar></term>
-					<listitem>
-						<para>The level of logging written via <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
-					</listitem>
-				</varlistentry>
-				<varlistentry>
-					<term><envar>consoleloglevel=<replaceable>&lt;-1...7&gt;</replaceable></envar></term>
-					<listitem>
-						<para>The level of logging written to <literal>stderr</literal>.</para>
-					</listitem>
-				</varlistentry>
-				<varlistentry>
-					<term><envar>dumpdatadoc=<replaceable>/path/to/file.xml</replaceable></envar></term>
-					<listitem>
-						<para>Write a copy of the data document produced by <application>p2cgi</application> before sending it to the web server.</para>
-						<tip>This option is available only when compiled with debugging support.</tip>
-					</listitem>
-				</varlistentry>
-				<varlistentry>
-					<term>errorcontenttype</term>
-					<listitem>
-						<para>The HTTP <literal>Content-Type</literal> header producted by <application>p2cgi</application> for an unhandled error document.</para>
-					</listitem>
-				</varlistentry>
-				<varlistentry>
-					<term>errortransformstyle</term>
-					<listitem>
-						<para>The <literal>href</literal> of the <literal>xml-stylesheet</literal> <application>p2cgi</application> will write into the processing instruction for an unhandled error document.</para>
-					</listitem>
-				</varlistentry>
-			</variablelist>
-		</refentry>
+		<title>Preparation</title>
 		<section>
-			<title>Platform</title>
+			<title>Introduction</title>
+			<para>todo</para>
+		</section>
+		<section>
+			<title>Requirements</title>
+			<para>todo</para>
 		</section>
-	</chapter>
-	<chapter>
-		<title>Execution stages</title>
 		<section>
-			<title>Check</title>
+			<title>Compilation</title>
+			<para>todo</para>
 		</section>
 		<section>
-			<title>Request</title>
+			<title>Installation</title>
+			<para>todo</para>
 		</section>
 		<section>
-			<title>Present</title>
+			<title>Deployment</title>
+			<para>todo</para>
 		</section>
 	</chapter>
 	<chapter>
+		<title>Overview and deployment</title>
+		<refentry>
+			<refmeta>
+				<refentrytitle>Project2</refentrytitle>
+				<manvolnum>7</manvolnum>
+			</refmeta>
+			<refnamediv>
+				<refname>project2</refname>
+				<refpurpose>The Project2 application engine.</refpurpose>
+			</refnamediv>
+			<refsection>
+				<title>Script life cycle</title>
+				<refsection>
+					<title>Check</title>
+					<para>todo</para>
+				</refsection>
+				<refsection>
+					<title>Request</title>
+					<para>todo</para>
+				</refsection>
+				<refsection>
+					<title>Present</title>
+					<para>todo</para>
+				</refsection>
+			</refsection>
+		</refentry>
+	</chapter>
+	<chapter>
 		<title>Engines</title>
 		<refentry>
 			<refmeta>
@@ -110,7 +78,7 @@
 			</refmeta>
 			<refnamediv>
 				<refname>p2console</refname>
-				<refpurpose>Run one or more Project2 script from the console.</refpurpose>
+				<refpurpose>Execute one or more Project2 scripts from the console.</refpurpose>
 			</refnamediv>
 			<refsynopsisdiv>
 				<cmdsynopsis>
@@ -118,6 +86,15 @@
 					<arg choice="req" rep="repeat"><replaceable>file</replaceable></arg>
 				</cmdsynopsis>
 			</refsynopsisdiv>
+			<refsection>
+				<title>Description</title>
+				<para>Execute one or more Project2 scripts from the console or from some other process launcher, such as cron.</para>
+				<para>All stages of execution are supported.</para>
+			</refsection>
+			<refsection>
+				<title>Notes</title>
+				<para>Data source transactions are considered on a script by script basis; a transaction is open when required and always committed or rolled back at the end of a script, before another script is started.</para>
+			</refsection>
 		</refentry>
 		<refentry>
 			<refmeta>
@@ -128,6 +105,13 @@
 				<refname>p2cgi</refname>
 				<refpurpose>Generate webpages and/or run Project2 scripts from a CGI capable web server.</refpurpose>
 			</refnamediv>
+			<refsection>
+				<title>Description</title>
+				<para>The ultimate aim of a p2cgi instance is to generate a document that can be transformed into a webpage. Processing takes part in one of two ways depending on how the instance was requested by the client.</para>
+				<para>A GET request is the simplest form of request. The request URL is mapped onto a single Project2 script file, and that file is executed to produce a document that is sent to the host web server for transformation. This method supports checks and views; all checks must be passed before any views are executed. A check failure will result in a different (named) Project2 script being executed. No transactions are ever opened on any data source.</para>
+				<para>A POST request however, provides support for checks and tasks. Again the request URL is mapped to a script and that script is executed. All checks must be passed and then all tasks will be executed. Transactions will be opened as required on data sources and will be committed automatically on successful completion of the script, rolled back otherwise, after which a (named) Project2 script will be presented (see GET request).</para>
+				<para>Tasks <emphasis>cannot</emphasis> be executed from a GET request and views cannot be (directly) presented from a POST request. The use of transactional data sources is highly recommended, Project2 will tightly integrate its behaviour with them.</para>
+			</refsection>
 		</refentry>
 		<refentry>
 			<refmeta>
@@ -138,9 +122,80 @@
 				<refname>p2fcgi</refname>
 				<refpurpose><application>FastCGI</application> implementation of <application>p2cgi</application>.</refpurpose>
 			</refnamediv>
-			<para>For all intents and purposes, <application>p2fcgi</application> is a drop in replacement for <application>p2cgi</application> and should be used whenever possible. See your web server configuration documentation for details on running fast CGI applications.</para>
-			<para>Unless otherwise specified, <literal>p2cgi</literal> refers to both <application>p2cgi</application> and/or <application>p2fcgi</application>.</para>
-			<para><application>p2fcgi</application> has numerous significant benefits over <application>p2cgi</application>. Most notably a near zero startup time, presistent connections to RDBMS datasources and high performance in memory caching of row sets.</para>
+			<refsection>
+				<title>Description</title>
+				<para>For all intents and purposes, <application>p2fcgi</application> is a drop in replacement for <application>p2cgi</application>, with exactly the same application engine internals, and should be used whenever possible. See your web server configuration documentation for details on running fast CGI applications.</para>
+				<para>Unless otherwise specified, <literal>p2cgi</literal> refers to both <application>p2cgi</application> and/or <application>p2fcgi</application>.</para>
+				<para><application>p2fcgi</application> has numerous significant benefits over <application>p2cgi</application>. Most notably a near zero startup time, presistent connections to RDBMS datasources and high performance in memory caching of row sets.</para>
+			</refsection>
+		</refentry>
+	</chapter>
+	<chapter>
+		<title>Runtime configuration</title>
+		<refentry>
+			<refmeta>
+				<refentrytitle>p2config</refentrytitle>
+				<manvolnum>5</manvolnum>
+			</refmeta>
+			<refnamediv>
+				<refname>p2config</refname>
+				<refname>.p2config</refname>
+				<refpurpose>Configure runtime behaviour of Project2 application engines.</refpurpose>
+			</refnamediv>
+			<refsynopsisdiv>
+				<variablelist>
+					<varlistentry>
+						<term><envar>sysloglevel=<replaceable>&lt;-1...7&gt;</replaceable></envar></term>
+						<listitem>
+							<para>The level of logging written via <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+						</listitem>
+					</varlistentry>
+					<varlistentry>
+						<term><envar>consoleloglevel=<replaceable>&lt;-1...7&gt;</replaceable></envar></term>
+						<listitem>
+							<para>The level of logging written to <literal>stderr</literal>.</para>
+						</listitem>
+					</varlistentry>
+					<varlistentry>
+						<term><envar>dumpdatadoc=<replaceable>/path/to/file.xml</replaceable></envar></term>
+						<listitem>
+							<para>Write a copy of the data document produced by <application>p2cgi</application> before sending it to the web server.</para>
+							<tip><para>This option is available only when compiled with debugging support.</para></tip>
+							<warning><para>The dumped document may contain sensitive information (such as passwords); it is your responsibility to delete the file when you're done with it!</para></warning>
+						</listitem>
+					</varlistentry>
+					<varlistentry>
+						<term><envar>errorcontenttype=<replaceable>Some/MimeType; charset=foo</replaceable></envar></term>
+						<listitem>
+							<para>The HTTP <literal>Content-Type</literal> header producted by <application>p2cgi</application> for an unhandled error document.</para>
+						</listitem>
+					</varlistentry>
+					<varlistentry>
+						<term><envar>errortransformstyle=<replaceable>transform.xslt</replaceable></envar></term>
+						<listitem>
+							<para>The <literal>href</literal> of the <literal>xml-stylesheet</literal> <application>p2cgi</application> will write into the processing instruction for an unhandled error document.</para>
+						</listitem>
+					</varlistentry>
+				</variablelist>
+			</refsynopsisdiv>
+			<refsection>
+				<title>Descripton</title>
+				<para><filename>.p2config</filename> should placed in the web root of a web page and/or the current working directory of a script run from the console.</para>
+			</refsection>
+		</refentry>
+		<refentry>
+			<refmeta>
+				<refentrytitle>config.xml</refentrytitle>
+				<manvolnum>5</manvolnum>
+			</refmeta>
+			<refnamediv>
+				<refname>config.xml</refname>
+				<refpurpose>Configure platform specific runtime variables.</refpurpose>
+			</refnamediv>
+			<refsection>
+				<title>Descripton</title>
+				<para><filename>config.xml</filename> should placed in the web root of a web page and/or the current working directory of a script run from the console.</para>
+			</refsection>
 		</refentry>
 	</chapter>
 	<chapter>
@@ -149,11 +204,11 @@
 			<title>Common</title>
 			<refentry>
 				<refmeta>
-					<refentrytitle>project2:iterate</refentrytitle>
+					<refentrytitle>iterate</refentrytitle>
 					<manvolnum>7</manvolnum>
 				</refmeta>
 				<refnamediv>
-					<refname>project2:iterate</refname>
+					<refname>project2-iterate</refname>
 					<refpurpose>Execute tasks for every record in a row source.</refpurpose>
 				</refnamediv>
 				<refsynopsisdiv>
@@ -163,15 +218,56 @@
 						<arg choice="req">source=&quot;<replaceable>row source</replaceable>&quot;</arg>
 						<arg choice="opt">filter=&quot;<replaceable>row source filter name</replaceable>&quot;</arg>
 					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:iterate/parameters/param</command>
+						<arg choice="req">name=&quot;<replaceable>parameter name</replaceable>&quot;</arg>
+						<arg choice="req">value=&quot;<replaceable>parameter value</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:iterate/project2:iterate (as above)</command>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:iterate/project2:if</command>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:iterate/project2:<replaceable>task</replaceable></command>
+					</cmdsynopsis>
 				</refsynopsisdiv>
+				<refsection>
+					<title>Description</title>
+					<para>Take the records in the named row source and for each one, execute the child tasks specified.</para>
+					<para>The tasks that can be executed are outside the scope of this document [section] and therefore you should see the documention for the task[s] you wish to execute for more information.</para>
+					<para>For details on the use of <function>parameter</function>s and <function>filter</function>s, see <citerefentry><refentrytitle>project2-view</refentrytitle><manvolnum>7</manvolnum></citerefentry> as an <function>iterate</function> has exactly the same behaviour in this regard.</para>
+					<para>An <function>iterate</function> passes nothing to the presentation layer.</para>
+					<para>Iterations specified as children of an iteration are executed once per parent row.</para>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>The error handling features are completed undocumented!</para>
+				</refsection>
+				<refsection>
+					<title>See Also</title>
+					<para>
+						<citerefentry><refentrytitle>project2-if</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-view</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+					</para>
+					<para>
+						<citerefentry><refentrytitle>project2-sessionset</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sessionclear</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sqlmergetask</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sqltask</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sendmail</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						...
+					</para>
+				</refsection>
 			</refentry>
 			<refentry>
 				<refmeta>
-					<refentrytitle>project2:view</refentrytitle>
+					<refentrytitle>view</refentrytitle>
 					<manvolnum>7</manvolnum>
 				</refmeta>
 				<refnamediv>
-					<refname>project2:view</refname>
+					<refname>project2-view</refname>
 					<refpurpose>Present data from a row source.</refpurpose>
 				</refnamediv>
 				<refsynopsisdiv>
@@ -183,15 +279,44 @@
 						<arg choice="req">recordname=&quot;<replaceable>record xml node name</replaceable>&quot;</arg>
 						<arg choice="opt">filter=&quot;<replaceable>row source filter name</replaceable>&quot;</arg>
 					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:view/columns/column = </command><arg choice="req"><replaceable>column name</replaceable></arg>
+						<arg choice="req">name=&quot;<replaceable>column name</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:view/parameters/param</command>
+						<arg choice="req">name=&quot;<replaceable>parameter name</replaceable>&quot;</arg>
+						<arg choice="req">value=&quot;<replaceable>parameter value</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:view/project2:view (as above)</command>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:view/project2:if</command>
+					</cmdsynopsis>
 				</refsynopsisdiv>
+				<refsection>
+					<title>Description</title>
+					<para>Take rows for the named row source (<function>sqlrows</function>, <function>filerows</function>, etc) and pass their data onto the presentation layer, marked up according to <function>rootname</function> and <function>recordname</function>. <function>filter</function> allows you to specify an optional filter name to the underlying row source, see the row source documentation for details on this. <function>params</function> allow you to pass parameters to the underlying row source.</para>
+					<para><function>columns</function> allow you only pass on a subset of columns from the row source, or specify extra columns that would not normally be included. You can also use this to effectively rename columns before passing them on.</para>
+					<para>The inclusion of more <function>view</function> elements with a <function>view</function> allow use of values in the current row set to be used in generation of child row sets. Note that this will execute the child row source once for every row returned by the current row source and therefore might not be especially efficient. When used with row sources that all the needed flexibility, it might be worth using it to avoid this situation (e.g. consider using <function>filter</function> in conjunction with joins when using <function>project2:sqlrows</function>. The use of <function>columns</function> does NOT effective the availability of values used by child <function>view</function>s.</para>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>I can't remember which way round to specify columns. One specifies the name of the row source column name, one specifies the name that is passed to the presentation layer. Nor can I remember how you access row source attributes such as <function>rownum</function>.</para>
+				</refsection>
+				<refsection>
+					<title>See Also</title>
+					<para><citerefentry><refentrytitle>project2-if</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
+				</refsection>
 			</refentry>
 			<refentry>
 				<refmeta>
-					<refentrytitle>project2:if</refentrytitle>
+					<refentrytitle>if</refentrytitle>
 					<manvolnum>7</manvolnum>
 				</refmeta>
 				<refnamediv>
-					<refname>project2:if</refname>
+					<refname>project2-if</refname>
 					<refpurpose>Conditionally execute and/or present data.</refpurpose>
 				</refnamediv>
 				<refsynopsisdiv>
@@ -200,95 +325,486 @@
 						<arg choice="req">name=&quot;<replaceable>if name</replaceable>&quot;</arg>
 						<arg choice="req">mode=&quot;<replaceable>and | or</replaceable>&quot;</arg>
 					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:if//if</command>
+						<arg choice="req">mode=&quot;<replaceable>and | or</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:if//if/<replaceable>check</replaceable></command>
+						<arg choice="req">mode=&quot;<replaceable>and | or</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:if//<replaceable>view | task | iterate</replaceable></command>
+					</cmdsynopsis>
 				</refsynopsisdiv>
+				<refsection>
+					<title>Description</title>
+					<para><function>if</function> evaluates its child <function>check</function> and <function>if</function> elements until either a true or false result is determined. Execution takes place in the order specified in the script and halts when the results of further check execution is unimportant to the result (short cutting.)</para>
+					<para>If, and only if, the checks are evaulated are being true then child <function>view</function> and/or <function>iterate</function> and tasks are executed.</para>
+				</refsection>
+				<refsection>
+					<title>See Also</title>
+					<para>
+						<citerefentry><refentrytitle>project2-sqlcheck</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-regexcheck</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+					</para>
+					<para>
+						<citerefentry><refentrytitle>project2-if</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-iterate</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-view</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+					</para>
+					<para>
+						<citerefentry><refentrytitle>project2-sessionset</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sessionclear</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sqlmergetask</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sqltask</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						<citerefentry><refentrytitle>project2-sendmail</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+						...
+					</para>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>The error handling features are completed undocumented!</para>
+				</refsection>
 			</refentry>
 		</section>
 		<section>
 			<title>Data Sources</title>
-			<section>
-				<title>rdbmsdatasource</title>
-				<section>
+			<refentry>
+				<refmeta>
+					<refentrytitle>rdbmsdatasource</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-rdbmsdatasource</refname>
+					<refpurpose>Define a datasource for connecting to an RDBMS database.</refpurpose>
+				</refnamediv>
+				<refsynopsisdiv>
+					<cmdsynopsis>
+						<command>project2:rdbmsdatasource</command>
+						<arg choice="req">name=&quot;<replaceable>datasource name</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:rdbmsdatasource/masterdsn/<replaceable>connector</replaceable> = </command><arg choice="req"><replaceable>connector specific connection string</replaceable></arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:rdbmsdatasource/readonly</command>
+						<arg choice="req">preferlocal=&quot;<replaceable>true | false</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:rdbmsdatasource/readonly/dsn/<replaceable>connector</replaceable> = </command><arg choice="req"><replaceable>connector specific connection string</replaceable></arg>
+						<arg choice="req">host=&quot;<replaceable>source hostname</replaceable>&quot;</arg>
+					</cmdsynopsis>
+				</refsynopsisdiv>
+				<refsection>
+					<title>Description</title>
+					<para>Defines a named data source for use with a transaction RDBMS database. Readonly actions will be performed against one of the readonly DSNs until such a time that changes are made to the content. The changes will be made on the master DSN, which will be then used for the duration of the current application engine run. Note that an error leading to a rollback will cause the application engine to revert to using a readonly DSN until another change is made.</para>
+					<para>A readonly datasource is chosen according to the <literal>preferlocal</literal> and <literal>host</literal> value of the <literal>readonly/dsn</literal>s. When <literal>preferlocal</literal> is true, <literal>host</literal> is matched against the hostname of the local machine (see <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If not matching <literal>reaodnly/dsn/host</literal> is found, <literal>masterdsn</literal> is used. This mode suits the situation where you might have several web servers, each with a local instance of the database. When <literal>perferlocal</literal> is false, however, readonly connections are attempted in alphabetical readonly by the <literal>host</literal>. This would suit have a primary and secondary/failover database.</para>
+					<para><emphasis>ANY</emphasis> connection established from any <function>rdbmsdatasource</function> may be used and reused to fulfill another connection. This allows for minimising the overheads in establishing connections. Matching is performed according to connector type and connection string. For this reason, it is advisable to not specify a readonly attribute in a connection string that might match that of master. Doing so would cause two connections to be established when one would otherwise suffice.</para>
+					<para>Note that the value of <literal>dsn/host</literal> has NO effect on how a connection is established or where to, only in choosing which connection to use.</para>
+				</refsection>
+				<refsection>
 					<title>Connectors</title>
-					<section>
+					<refsection>
 						<title>ODBC</title>
-					</section>
-					<section>
+						<cmdsynopsis>
+							<command>odbc = <replaceable>odbc connection string</replaceable></command>
+						</cmdsynopsis>
+						<para>Connect using unixODBC driver.</para>
+					</refsection>
+					<refsection>
 						<title>PostgreSQL</title>
-					</section>
-				</section>
-			</section>
+						<cmdsynopsis>
+							<command>postgresql = <replaceable>libpq connection string</replaceable></command>
+						</cmdsynopsis>
+						<para>Connect using the native PostgreSQL driver.</para>
+					</refsection>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>Despite the amount of textual duplication required in a simple configuration with failover, the actual amount of control you get is still quite poor. For example, there is no way to specify any form of round robin DB pool or use any sort of load balancing of a DB cluster. As such, expect changes to this component.</para>
+				</refsection>
+			</refentry>
+		</section>
+		<section>
+			<title>Helpers</title>
+			<refentry>
+				<refmeta>
+					<refentrytitle>curlhelper</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-curlhelper</refname>
+					<refpurpose>Provide support for retrieving data with <citerefentry><refentrytitle>libcurl</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</refpurpose>
+				</refnamediv>
+				<refsynopsisdiv>
+					<cmdsynopsis>
+						<command>project2:curlhelper</command>
+						<arg choice="req">url=&quot;<replaceable>resource url</replaceable>&quot;</arg>
+						<arg choice="opt">useragent=&quot;<replaceable>user agent string</replaceable>&quot;</arg>
+						<arg choice="opt">cookiejar=&quot;<replaceable>cookie jar file path</replaceable>&quot;</arg>
+						<arg choice="opt">proxy=&quot;<replaceable>proxy address</replaceable>&quot;</arg>
+						<arg choice="opt">method=&quot;<replaceable>request method</replaceable>&quot;</arg>
+						<arg choice="opt">username=&quot;<replaceable>request username</replaceable>&quot;</arg>
+						<arg choice="opt">password=&quot;<replaceable>request password</replaceable>&quot;</arg>
+						<arg choice="opt">timeout=&quot;<replaceable>timeout (ms)</replaceable>&quot;</arg>
+					</cmdsynopsis>
+				</refsynopsisdiv>
+				<refsection>
+					<title>Notes</title>
+					<para>All values are passed verbatim (after suitable type coercion) to <citerefentry><refentrytitle>libcurl</refentrytitle><manvolnum>3</manvolnum></citerefentry>, see <citerefentry><refentrytitle>curl_easy_setopt</refentrytitle><manvolnum>3</manvolnum></citerefentry> for details. Note also, that the mapping between <application>Project2</application> variables and <application>libcurl</application> settings may not be one to one and that some settings are only useful with some protocols.</para>
+					<para>An instance of <function>curlhelper</function> can't exist on its own, only as part of something else.</para>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>Not all <application>libcurl</application> settings are supported.</para>
+				</refsection>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>streamrows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-streamrows</refname>
+					<refpurpose>Provide common functionality for processing a byte stream into record and field data.</refpurpose>
+				</refnamediv>
+				<refsynopsisdiv>
+					<cmdsynopsis>
+						<command>project2:streamrows</command>
+					</cmdsynopsis>
+				</refsynopsisdiv>
+				<refsection>
+					<title>Notes</title>
+					<para>An instance of <function>streamrows</function> can't exist on its own, only as part of something else.</para>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>Many features are missing from stream rows, which still make it difficult or impossible to support some common file formats, <function>procrows</function> can sometimes fill this gap, but it starts getting messy.</para>
+				</refsection>
+			</refentry>
 		</section>
 		<section>
 			<title>Row sources</title>
-			<section>
-				<title>xslrows</title>
-			</section>
-			<section>
-				<title>xmlrows</title>
-			</section>
-			<section>
-				<title>sqlrows</title>
-			</section>
-			<section>
-				<title>filerows</title>
-			</section>
-			<section>
-				<title>fsrows</title>
-			</section>
-			<section>
-				<title>urlrows</title>
-			</section>
-			<section>
-				<title>procrows</title>
-			</section>
+			<refentry>
+				<refmeta>
+					<refentrytitle>xslrows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-xslrows</refname>
+					<refpurpose>Create a row set from an XML or HTML document and a set of XPaths.</refpurpose>
+				</refnamediv>
+				<refsynopsisdiv>
+					<cmdsynopsis>
+						<command>project2:xslrows</command>
+						<arg choice="req">name=&quot;<replaceable>row set name</replaceable>&quot;</arg>
+						<arg choice="req">url=&quot;<replaceable>document URL</replaceable>&quot;</arg>
+						<arg choice="opt">html=&quot;<replaceable>true | false</replaceable>&quot;</arg>
+						<arg choice="opt">warnings=&quot;<replaceable>true | false</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:xslrows/namespace</command>
+						<arg choice="req">prefix=&quot;<replaceable>namespace prefix</replaceable>&quot;</arg>
+						<arg choice="req">url=&quot;<replaceable>namespace url</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:xslrows/filterview</command>
+						<arg choice="req">name=&quot;<replaceable>filter name</replaceable>&quot;</arg>
+						<arg choice="req">root=&quot;<replaceable>xpath of record root</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:xslrows/filterview/field</command>
+						<arg choice="req">name=&quot;<replaceable>field name</replaceable>&quot;</arg>
+						<arg choice="req">xpath=&quot;<replaceable>xpath of field value</replaceable>&quot;</arg>
+					</cmdsynopsis>
+				</refsynopsisdiv>
+				<refsection>
+					<title>Description</title>
+					<para>Creates a row set from an XML or HTML document based on evaluations of XPaths against that tree.</para>
+					<para>Each <literal>filterview</literal> defines an extractable row set. The <literal>root</literal> specifies what constitutes a record such as <literal>/html//h1</literal> would create a record in the row set for all level 1 headings in a HTML document. You could then create fields in that record based on XPaths such as <literal>@class</literal> and <literal>.//text()</literal> to extract the heading's CSS style and wording.</para>
+					<para>Any number of named <literal>filterview</literal>s can be created, with any number of named <literal>field</literal>s with them. A user of this row set <emphasis>must</emphasis> specify a <literal>filter</literal>.</para>
+				</refsection>
+				<refsection>
+					<title>Notes</title>
+					<para><function>xslrows</function> use <citerefentry><refentrytitle>project2-curlhelper</refentrytitle><manvolnum>7</manvolnum></citerefentry> and thus support all its attributes for accessing the document resource.</para>
+					<para>Large documents may consume a lot of memory and may be held in memory until the end of the application engine iteration. See <citerefentry><refentrytitle>project2-xmlrows</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a less fully featured alternative that does not have this issue.</para>
+				</refsection>
+				<refsection>
+					<title>Example</title>
+					<example>
+						<title>Extract headings and heading styles from an HTML document</title>
+						<programlisting>
+&lt;project2:xslrows name=&quot;example&quot; url=&quot;file:///tmp/doc.html&quot; html=&quot;true&quot;&gt;
+	&lt;filterview name=&quot;heading1s&quot; root=&quot;/html//h1&quot;&gt;
+		&lt;field name=&quot;text&quot; xpath=&quot;.//text()&quot;&gt;
+		&lt;field name=&quot;style&quot; xpath=&quot;@class&quot;&gt;
+	&lt;/filterview&gt;
+&lt;/project2:xslrows&gt;
+						</programlisting>
+					</example>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>This component is badly named and should be renamed to <function>xpathrows</function>.</para>
+				</refsection>
+				<refsection>
+					<title>See Also</title>
+					<para><citerefentry><refentrytitle>project2-curlhelper</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
+				</refsection>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>xmlrows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-xmlrows</refname>
+					<refpurpose>Create a row set while reading through an XML resource.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>sqlrows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-sqlrows</refname>
+					<refpurpose>Create a row set from an SQL select.</refpurpose>
+				</refnamediv>
+				<refsynopsisdiv>
+					<cmdsynopsis>
+						<command>project2:sqlrows</command>
+						<arg choice="req">name=&quot;<replaceable>row set name</replaceable>&quot;</arg>
+						<arg choice="req">datasource=&quot;<replaceable>the name of an rdbmsdatasource</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:sqlrows/sql = </command><arg choice="req" rep="repeat"><replaceable>SQL text</replaceable> | <replaceable>&lt;filter&gt;</replaceable> | <replaceable>&lt;param&gt;</replaceable></arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:sqlrows/sql/filter = </command><arg choice="req" rep="repeat"><replaceable>SQL text</replaceable> | <replaceable>&lt;param&gt;</replaceable></arg>
+						<arg choice="req">name=&quot;<replaceable>filter name</replaceable>&quot;</arg>
+					</cmdsynopsis>
+					<cmdsynopsis>
+						<command>project2:sqlrows/sql//param</command>
+						<arg choice="req">name=&quot;<replaceable>parameter name</replaceable>&quot;</arg>
+					</cmdsynopsis>
+				</refsynopsisdiv>
+				<refsection>
+					<title>Description</title>
+					<para>This component constructs an SQL statement for execution against an RDBMS data source.</para>
+					<para>SQL text within a <function>filter</function> element is condition upon that filter being specified by a row set user. Many <function>filter</function> elements can have the same name and upon its use, all elements will be included in the result SQL. Parameters specified with the <function>param</function> may also shared the same name, in which case the same value will be bound to all positions in the query.</para>
+					<para>Any part of the query can be part of the <function>filter</function> element and can therefore include extra columns (for example, returning a match accuracy only when a free text search filter is used) or an order by clause which might be different depending on which filter is used. You can also join extra tables or sub-selects if you need to.</para>
+					<para><function>param</function> elements will be automatically translated into SQL text suitable for using bound parameters with your chosen RBDMS data source driver. No other changes to the SQL are made. For the purpose, it is assume that ' (single quote) is used to mark the beginning and end of a string literal, and '' (two single quotes) are used to escape a single quote within a string literal.</para>
+				</refsection>
+				<refsection>
+					<title>Example</title>
+					<example>
+						<title>Select all or some employees from an SQL database</title>
+						<programlisting>
+&lt;project2:sqlrows name=&quot;example&quot; datasource=&quot;staffdb&quot;&gt;
+	&lt;sql&gt;
+		SELECT empno, firstname, lastname, deptno
+		FROM employees
+		&lt;filter name=&quot;bydept&quot;&gt;
+			WHERE deptno = &lt;param name=&quot;deptno&quot; /&gt;
+		&lt;/filter&gt;
+	&lt;/sql&gt;
+&lt;/project2:sqlrows&gt;
+						</programlisting>
+					</example>
+					<para>When no filter is specified by a row set user, returns all employees in the employees table. When the bydept filter is specified along with a department number parameter, only employees in that department are returned.</para>
+					<para>This example assumes the existance of the employees table with suitable columns.</para>
+				</refsection>
+				<refsection>
+					<title>Bugs</title>
+					<para>There is no concept of a default <function>filter</function>, which might be handy, although there is nothing to stop you defining a <function>filter</function> named <literal>default</literal> and specifying that.</para>
+					<para>Only one <function>filter</function> can be used at any time. So, in our example, if you wanted to filter by <literal>deptno</literal>, or <literal>lastname</literal> or (<literal>deptno</literal> and <literal>lastname</literal>) you would have to define three different filters. While this doesn't place any limits on what you can do, it might lead you to duplicating SQL which would otherwise not be required.</para>
+				</refsection>
+				<refsection>
+					<title>See Also</title>
+					<para><citerefentry><refentrytitle>project2-rdbmsdatasource</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
+				</refsection>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>filerows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-filerows</refname>
+					<refpurpose>Create a row set from a character separated local file.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>fsrows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-fsrows</refname>
+					<refpurpose>Create a row set from files and directories on the local filesystem.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>urlrows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-urlrows</refname>
+					<refpurpose>Create a row set from a character separated remote resource.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>procrows</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-procrows</refname>
+					<refpurpose>Create a row set from the character separated output of another program.</refpurpose>
+				</refnamediv>
+			</refentry>
 		</section>
 		<section>
 			<title>Tasks</title>
-			<section>
-				<title>sessionset</title>
-			</section>
-			<section>
-				<title>sessionclear</title>
-			</section>
-			<section>
-				<title>sqlmergetask</title>
-			</section>
-			<section>
-				<title>sqltask</title>
-			</section>
-			<section>
-				<title>sendmail</title>
-			</section>
+			<refentry>
+				<refmeta>
+					<refentrytitle>sessionset</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-sessionset</refname>
+					<refpurpose>Set a value in the current session.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>sessionclear</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-sessionclear</refname>
+					<refpurpose>Remove a value from the current session.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>sqlmergetask</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-sqlmergetask</refname>
+					<refpurpose>Merge row set data into an RDBMS table.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>sqltask</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-sqltask</refname>
+					<refpurpose>Execute an arbitory DML statement.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>sendmail</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-sendmail</refname>
+					<refpurpose>Send an email.</refpurpose>
+				</refnamediv>
+			</refentry>
 		</section>
 		<section>
 			<title>Variables</title>
-			<section>
-				<title>literal</title>
-			</section>
-			<section>
-				<title>config</title>
-			</section>
-			<section>
-				<title>parent</title>
-			</section>
-			<section>
-				<title>uri</title>
-			</section>
-			<section>
-				<title>param</title>
-			</section>
-			<section>
-				<title>session</title>
-			</section>
+			<refentry>
+				<refmeta>
+					<refentrytitle>literal</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-literal</refname>
+					<refpurpose>A literal value.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>config</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-config</refname>
+					<refpurpose>Retrieve a value from the platform configuration.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>parent</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-parent</refname>
+					<refpurpose>Retrieve a value from a current in execution row set field or attribute.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>uri</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-uri</refname>
+					<refpurpose>Retrieve a value from the URL of the original request.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>param</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-param</refname>
+					<refpurpose>Retrieve a value from the parameters of the original request.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>session</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-session</refname>
+					<refpurpose>Retrieve a value from the current session.</refpurpose>
+				</refnamediv>
+			</refentry>
 		</section>
 		<section>
 			<title>Checks</title>
-			<section>
-				<title>regexcheck</title>
-			</section>
-			<section>
-				<title>sqlcheck</title>
-			</section>
+			<refentry>
+				<refmeta>
+					<refentrytitle>regexcheck</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-regexcheck</refname>
+					<refpurpose>Check a value against a regular expression.</refpurpose>
+				</refnamediv>
+			</refentry>
+			<refentry>
+				<refmeta>
+					<refentrytitle>sqlcheck</refentrytitle>
+					<manvolnum>7</manvolnum>
+				</refmeta>
+				<refnamediv>
+					<refname>project2-sqlcheck</refname>
+					<refpurpose>Check a value against an RDBMS data source.</refpurpose>
+				</refnamediv>
+			</refentry>
 		</section>
 	</chapter>
 </book>