some doc updatesplproxy_2_0

3 files changed, 47 insertions, 20 deletions

diff --git a/Makefile b/Makefile
index 65fdb05..303103a 100644
--- a/Makefile
+++ b/Makefile
@@ -17,9 +17,9 @@ PG_CPPFLAGS = -I$(PQINC)
 SHLIB_LINK = -L$(PQLIB) -lpq
 
 DIST_FILES = Makefile src/plproxy.h src/scanner.l src/parser.y \
-	     sql/*.sql expected/*.out db/*.sql doc/*.txt doc/Makefile \
+	     sql/*.sql expected/*.out config/*.sql doc/*.txt doc/Makefile \
 	     AUTHORS COPYRIGHT README
-DIST_DIRS = src sql expected db doc
+DIST_DIRS = src sql expected config doc
 TARNAME = plproxy-$(PLPROXY_VERSION)
 
 # regression testing setup
diff --git a/doc/overview.txt b/doc/overview.txt
index aad6c9d..729c822 100644
--- a/doc/overview.txt
+++ b/doc/overview.txt
@@ -4,18 +4,16 @@
 
 [[TableOfContents]]
 
-== What is pl/proxy - a short history ==
+== Overview ==
 
-Short version - pl/proxy is a proxy language used for remote database 
-procedure calls and data partitioning between databases based on hashing
-field values.
+PL/Proxy is a proxy language used for remote database procedure calls
+and data partitioning between databases based on hashing field values.
 
+Main idea is that proxy function will be created with same
+signature as remote function to be called, so only destination
+info needs to be specified inside proxy function body.
 
-Longer version - 
-
-== subpages ==
-
-Downloads: http://pgfoundry.org/projects/PlProxy
+Downloads: http://pgfoundry.org/projects/plproxy
 
 Detailed info: ./LanguageSyntax  ./ClusterConfig
 
diff --git a/doc/syntax.txt b/doc/syntax.txt
index ab493f5..48f6b7b 100644
--- a/doc/syntax.txt
+++ b/doc/syntax.txt
@@ -10,28 +10,57 @@ if it is missing, there will be default query generated based on proxy
 function signature.
 
 === CONNECT ===
-`CONNECT 'libpq connstr';`
+{{{
+CONNECT 'libpq connstr';
 }}}
 
+Specifies exact location where to connect and execute the query.
+If several functions have same connstr, they will use same connection.
+
 === CLUSTER ===
+{{{
+CLUSTER 'cluster_name';
+}}}
 
-`CLUSTER 'cluster_name' | cluster_func(..);`
+Specifies exact cluster name to be run on.  The cluster name will
+be passed to plproxy.get_cluster_* functions.
+
+{{{
+CLUSTER cluster_func(..);
+}}}
+Cluster name can be dynamically decided upon proxy function arguments.
+`cluster_func` should returns text value for final cluster name.
 
 === RUN ON ===
 {{{
+RUN ON ALL;
+}}}
+Query will be run on all partitions in cluster in parallel.
+
+{{{
+RUN ON ANY;
+}}}
+Query will be run on random partition.
 
-RUN ON (partition_func(..) | ALL | ANY | <NR>) ;
+{{{
+RUN ON <NR>;
+}}}
+Run on partition number `<NR>`.
 
+{{{
+RUN ON partition_func(..);
 }}}
- * Arguments for hashfunc and SELECT can be both $1 and full name.
- * Hashfunc can return "setof int4", several servers are tagged then.
- * If query is ran on several server, the execution will happen in parallel.
+Run partition_func() which should return one or more hash values.  (int4)
+Query will be run on tagged partitions.  If more than one partition was
+tagged, query will be sent in parallel to them.
+
 
 === SELECT ===
 {{{
 SELECT .... ;
 }}}
 
-By default runs SELECT * from funcname(..); on remote side
-where funcname is name of plproxy function.  
- * Result fields will be mapped on name.
+=== Argument substitution ===
+
+Proxy function arguments can be referenced using name or `$n` syntax.
+Everything that is not argument reference is just passed on.