Log Message:
-----------
Plenty of minor corrections

Modified Files:
--------------
    slony1-engine/doc/howto:
        slonik_commands.html (r1.3 -> r1.4)

-------------- next part --------------
Index: slonik_commands.html
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/howto/slonik_commands.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -Ldoc/howto/slonik_commands.html -Ldoc/howto/slonik_commands.html -u -w -r1.3 -r1.4
--- doc/howto/slonik_commands.html
+++ doc/howto/slonik_commands.html
@@ -57,11 +57,12 @@
 </a>
 <div style="margin-left:40px; margin-right:80px;">
 <p>
-	Slonik is a commandline utility designed specifically to
-	setup and modify configurations of the Slony-I replication
-	system. 
-	This document is meant as a developer syntax-booklet, not
-	as a manual how to configure and setup a replication system.
+	Slonik is a commandline utility designed specifically to setup
+	and modify configurations of the Slony-I replication system.
+</p>
+
+<p> This document is meant as a developer syntax-booklet, not as a
+manual on how to configure and set up a replication system.
 </p>
 <p align="right">Back to <a href="#index">Index</a></p>
 </div>
@@ -72,16 +73,29 @@
 </a>
 <div style="margin-left:40px; margin-right:80px;">
 <p>
-	The slonik commandline utility is supposed to be embedded into
-	shell scripts and reads commands from files or stdin (via
-	here documents for example). Nearly all of the real configuration
-	work is done by calling stored procedures after loading the 
-	Slony-I support base into a database. Slonik was created because
-	these stored procedures have special requirements as to on which
-	particular node in the replication system they are called, the
-	lack of named parameters for stored procedures makes it rather
-	hard to do this from the psql prompt, and psql lacks the ability
-	to maintain multiple connections with open transactions.
+	The slonik commandline utility is supposed to be used embedded
+	into shell scripts and reads commands from files or stdin (via
+	here documents for example). Nearly all of the <i>real</i>
+	configuration work is done by calling stored procedures after
+	loading the Slony-I support base into a database.  You may
+	find documentation for those procedures in the <a
+	href="schemadoc.html"> Slony-I Schema Documentation </a>, as
+	well as in comments associated with them in the database.
+</p>
+      <p>
+	Slonik was created because:
+      <ul>
+
+	<li> The stored procedures have special requirements as to on
+	which particular node in the replication system they are
+	called,
+
+	<li> the lack of named parameters for stored procedures makes
+	it rather hard to do this from the psql prompt, and
+
+	<li> psql lacks the ability to maintain multiple connections
+	with open transactions.
+      </ul>
 </p>
 <p>
 	
@@ -95,10 +109,10 @@
 	parentheses. Each option consists of one or more keywords, followed
 	by an equal sign, followed by a value. Multiple options inside the
 	parentheses are separated by commas. All keywords are case
-	insensitive.
+	insensitive.  The language should remind the reader of SQL.
 </p>
 <p>
-	Option values are:
+	Option values may be:
 	<ul>
 		<li>integer values
 		<li>string literals enclosed in single quotes
@@ -135,9 +149,10 @@
 </a>
 <div style="margin-left:40px; margin-right:80px;">
 <p>
-	The following commands must appear at the very top of every slonik
-	command script. They do not cause any direct action on any of the
-	nodes in the replication system, but affect the entire script.
+	The following commands must appear at the very top of every
+	slonik command script. They do not cause any direct action on
+	any of the nodes in the replication system, but affect the
+	execution of the entire script.
 </p>
 
 <!-- **************************************** -->
@@ -149,14 +164,18 @@
 	CLUSTER NAME = &lt;string&gt;;
 <h3>Description:</h3>
 <p>
-	Must be the very first command in every slonik script. Defines the
-	namespace in which all Slony-I specific functions, procedures,
-	tables and sequences are defined. The namespace name is built by
-	prefixing the given string literal with an underscore. This
-	namespace will be identical in all databases that participate in
-	the same replication group. No user objects are supposed to live
-	in this namespace and the namespace is not allowed to exist prior
-	to adding a database to the replication system.
+	Must be the very first command in every slonik script. Defines
+	the namespace in which all Slony-I specific functions,
+	procedures, tables and sequences are defined. The namespace
+	name is built by prefixing the given string literal with an
+	underscore. This namespace will be identical in all databases
+	that participate in the same replication group. No user
+	objects are supposed to live in this namespace and the
+	namespace is not allowed to exist prior to adding a database
+	to the replication system.  Thus, if you add a new node using
+	<tt> pg_dump -s </tt> on a database that is already in the
+	cluster, you will need to drop the namespace via the SQL
+	command <tt> DROP SCHEMA _testcluster CASCADE; </tt>.
 </p>
 <h3>Example:</h3>
 <p>
@@ -184,7 +203,7 @@
 </p>
 <p>
 	The slonik utility will not try to connect to the databases
-	unless any subsequent command requires the connection. 
+	unless some subsequent command requires the connection.
 </p>
 <p>
 	Note: As mentioned in the original documents, Slony-I is designed as an
@@ -194,6 +213,16 @@
 	and configuration activities can use simple authentication schemes
 	like trust. 
 </p>
+
+<p>
+	Note: If you need to change the DSN information for a node, as
+	would happen if the IP address for a host were to change, you
+	may submit the new information using this command, and that
+	configuration will be propagated.  Existing <tt> slon </tt>
+	processes <i>may </i> need to be restarted in order for them
+	to become aware of the configuration change.
+
+</p>
 <h3>Example:</h3>
 <p>
 	NODE 1 ADMIN CONNINFO = 'dbname=testdb host=server1 user=slony';
@@ -306,6 +335,8 @@
 <p>
 	Initialize a new node and add it to the configuration of
 	an existing cluster.
+</p>
+<p>
 	The initialization process consists of creating the cluster
 	namespace in the new node (the database itself must already
 	exist), loading all the base tables, functions, procedures
@@ -431,7 +462,7 @@
 	Causes an eventually running replication daemon on the specified
 	node to shutdown and restart itself. Theoretically this command
 	should be obsolete. In practice, TCP timeouts can delay critical
-	configuration changes to actually happen in the case, a former
+	configuration changes to actually happen in the case where a former
 	forwarding node failed and needs to be bypassed by subscribers.
 </p>
 <h3>Example:</h3>
@@ -806,11 +837,16 @@
 	MERGE SET ( &lt;options&gt; );
 <h3>Description:</h3>
 <p>
-	Merge a set of tables and sequences into another one. This function
-	is a workaround for the problem that it is not possible to add
-	tables/sequences to subscribed sets. One can create a temporary set,
-	add the new objects to that, subscribe all nodes, currently subscribed
-	to the other set to this new one and then merge the two together.
+	Merge a set of tables and sequences into another one. This
+	function is a workaround for the problem that it is not
+	possible to add tables/sequences to already-subscribed
+	sets. One may create a temporary set, add the new objects to
+	that, subscribe all nodes currently subscribed to the other
+	set to this new one, and then merge the two together.
+</p>
+<p>
+	This request will fail if the two sets do not have exactly the
+	same set of subscribers.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -853,8 +889,8 @@
 <h3>Description:</h3>
 <p>
 	Add an existing user table to a replication set. The set
-	cannot currently be subscribed by any other node (this
-	functionality will soon be implemented with a MERGE SET command).
+	cannot currently be subscribed by any other node - that
+	functionality is supported by the<tt>MERGE SET</tt> command.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -932,8 +968,8 @@
 <h3>Description:</h3>
 <p>
 	Add an existing user sequence to a replication set. The set
-	cannot currently be subscribed by any other node (this
-	functionality will soon be implemented with a MERGE SET command).
+	cannot currently be subscribed by any other node - that
+	functionality is supported by the MERGE SET command.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -1084,18 +1120,19 @@
 <h3>Description:</h3>
 <p>
 	Causes a node (subscriber) to start replicating a set of
-	tables either from the origin or from another provider node, which
-	must be a currently forwarding subscriber itself.
+	tables either from the origin or from another provider node,
+	which must be a currently forwarding subscriber itself.
 </p>
 <p>
-	The application tables contained in the set must already exist and
-	should ideally be currently empty. The current version of Slony-I
-	will not attempt to copy the schema of the set. The replication daemon
-	will start copying the current content of the set from the given
-	provider and then try to catch up with any update activity that
-	happened during that copy process. After successfull subscription,
-	the tables are guarded on the subscriber against accidential updates
-	by the application.
+	The application tables contained in the set must already exist
+	and should ideally be currently empty. The current version of
+	Slony-I will not attempt to copy the schema of the set. The
+	replication daemon will start copying the current content of
+	the set from the given provider and then try to catch up with
+	any update activity that happened during that copy
+	process. After successful subscription, the tables are guarded
+	on the subscriber using triggers against accidental updates by
+	the application.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -1119,9 +1156,10 @@
 <tr>
 	<td align="left" valign="top" nowrap><b>FORWARD = &lt;boolean&gt;</b></td>
 	<td align="left" valign="top"><p>
-		Flag if the new subscriber should store the log information
-		during replication to become a possible candidate for the
-		provider role of future nodes.
+		Flag whether or not the new subscriber should store
+		the log information during replication to make it
+		possible candidate for the provider role for future
+		nodes.
 	</p></td>
 </tr>
 </table>
@@ -1153,9 +1191,10 @@
 	restored.
 </p>
 <p>
-	<b>Warning!</b> Resubscribing an unsubscribed set requires a full
-	new copy from the provider to be transferred since the tables have
-	been subject to possible independant modifications.
+	<b>Warning!</b> Resubscribing an unsubscribed set requires a
+	<i>complete fresh copy</i> of data from the provider to be
+	transferred since the tables have been subject to possible
+	independent modifications.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -1195,12 +1234,13 @@
 	command.
 </p>
 <p>
-	This command must be the first in a possible statement group (try).
-	The reason for this is that it needs to commit the changes made
-	to the tables (adding a special trigger function) before it can
-	wait for every concurrent transaction to finish. At the same time
-	it cannot hold an open transaction to the same database itself since
-	this would result in blocking itself forever.
+	This command must be the first in a possible statement group
+	(<tt>try</tt>).  The reason for this is that it needs to
+	commit the changes made to the tables (adding a special
+	trigger function) before it can wait for every concurrent
+	transaction to finish. At the same time it cannot hold an open
+	transaction to the same database itself since this would
+	result in blocking itself forever.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -1275,17 +1315,19 @@
 	locked on the old origin. 
 </p>
 <p>
-	After this command, the set cannot be unlocked on the old origin
-	any more. The old origin will continue as a forwarding subscriber
-	of the set and the subscription chain from the old origin to the
-	new origin will get hop by hop reversed. As soon as the new origin
-	has finished processing the event (that includes any outstanding
-	sync events that happened before, i.e. fully catching up), the
-	new origin will take over and open all tables in the set for
-	client application update activity.
+	After this command, the set cannot be unlocked on the old
+	origin any more. The old origin will continue as a forwarding
+	subscriber of the set and the subscription chain from the old
+	origin to the new origin will be reversed, hop by hop. As soon
+	as the new origin has finished processing the event (that
+	includes any outstanding sync events that happened before,
+	<i>i.e.</i> fully catching up), the new origin will take over
+	and open all tables in the set for client application update
+	activity.
 </p>
 <p>
-	This is not failover, as it requires a fully functional old origin.
+	This is not failover, as it requires a fully functional old
+	origin node.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -1327,25 +1369,26 @@
 	FAILOVER ( &lt;options&gt; );
 <h3>Description:</h3>
 <p>
-	WARNING: This command will abandon the status of the failed node.
-	There is no other possibility to let the failed node join the
-	cluster again than rebuilding it from scratch as a slave.
-</p>
-<p>
-	The failover command causes the backup node to take over all sets
-	that currently originate on the failed node. Slonik will contact
-	all other direct subscribers of the failed node to determine which
-	node has the highest sync status for each set. If another node has
-	a higher sync status than the backup node, the replication will
-	first be redirected so that the backup node replicates against that
-	other node, before assuming the origin role and allowing update
-	activity.
-</p>
-<p>
-	After successfull failover, all former direct subscribers of the
-	failed node are direct subscribers of the backup node. The failed
-	node can and should be removed from the configuration with
-	DROP NODE.
+	WARNING: This command will abandon the status of the failed
+	node.  There is no possibility to let the failed node join the
+	cluster again without rebuilding it from scratch as a slave
+	slave.
+</p>
+<p>
+	The failover command causes the backup node to take over all
+	sets that currently originate on the failed node. Slonik will
+	contact all other direct subscribers of the failed node to
+	determine which node has the highest sync status for each
+	set. If another node has a higher sync status than the backup
+	node, the replication will first be redirected so that the
+	backup node replicates against that other node, before
+	assuming the origin role and allowing update activity.
+</p>
+<p>
+	After successful failover, all former direct subscribers of
+	the failed node become direct subscribers of the backup
+	node. The failed node can and should be removed from the
+	configuration with <tt>DROP NODE</tt>.
 </p>
 <table border="0" cellpadding="10">
 <tr>
@@ -1381,15 +1424,16 @@
 <h3>Description:</h3>
 <p>
 	Executes a script containing arbitrary SQL statements on all
-	nodes that are subscribed to a set at a controlled point within
-	the replication stream.
+	nodes that are subscribed to a set at a common controlled
+	point within the replication transaction stream.
 </p>
 <p>
 	The specified event origin must be the origin of the set. The
 	script file must not contain any START or COMMIT TRANSACTION
-	calls. Also any non-deterministic DML statements (like updating
-	a field with CURRENT_TIMESTAMP) must be avoided, since the
-	data changes done by the script are explicitly not replicated. 
+	calls. In addition, non-deterministic DML statements (like
+	updating a field with CURRENT_TIMESTAMP) must be avoided,
+	since the data changes done by the script are explicitly not
+	replicated.
 </p>
 <table border="0" cellpadding="10">
 <tr>