doc: clean up files under doc/

- move extra.css, fixman.py and getattrs.py under misc/
- move .html, .xml, .1 files to subdir
- remove londiste.5
- standardise: pgq-admin->pgqadm, londiste.cmdline -> londiste

9 files changed, 193 insertions, 215 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 1cf9ec70..4cb3560b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -9,39 +9,47 @@ EPYDOC = epydoc
 EPYARGS = --no-private --url="http://pgfoundry.org/projects/skytools/" \
 	--name="Skytools" --html --no-private -v
 
-HTMLS = londiste.cmdline.html londiste.config.html README.html INSTALL.html \
-	londiste.ref.html TODO.html pgq-sql.html pgq-admin.html pgq-nodupes.html \
-	$(SCRIPT_HTMLS) faq.html set.notes.html qadmin.html skytools3.html devnotes.html
+HTMLS = README.html INSTALL.html \
+	londiste.ref.html TODO.html pgq-sql.html pgqadm.html pgq-nodupes.html \
+	$(SCRIPT_HTMLS) faq.html set.notes.html skytools3.html devnotes.html
 
-SCRIPT_TXTS = walmgr.txt queue_mover.txt queue_splitter.txt \
-	      scriptmgr.txt skytools_upgrade.txt
-SCRIPT_MANS = $(SCRIPT_TXTS:.txt=.1)
+SCRIPT_TXTS = walmgr.txt queue_mover.txt queue_splitter.txt qadmin.txt \
+	      scriptmgr.txt skytools_upgrade.txt londiste.txt pgqadm.txt
 SCRIPT_HTMLS = $(SCRIPT_TXTS:.txt=.html)
 
+MAN1 = $(SCRIPT_TXTS:.txt=.1)
+MAN5 = 
+
+FQHTML = $(addprefix html/, $(HTMLS))
+FQMAN1 = $(addprefix man/, $(MAN1))
+FQMAN5 = $(addprefix man/, $(MAN5))
+FQMAN = $(FQMAN1) $(FQMAN5)
+
 COMMON = common.switches.txt common.config.txt common.logutriga.txt
 
-GETATTRS = python ./getattrs.py
+GETATTRS = python ../misc/getattrs.py
+FIXMAN = python ../misc/fixman.py
 
 #AFLAGS = -a linkcss
 #AFLAGS = -a stylesheet=extra.css
 
-all: man $(HTMLS)
+all: $(FQMAN) $(FQHTML)
 
-man: londiste.1 londiste.5 pgqadm.1 $(SCRIPT_MANS)
+man: $(FQMAN)
 
-html: $(HTMLS)
+html: $(FQHTML)
 
-install: man $(HTMLS)
+install: $(FQMAN) $(FQHTML)
 	mkdir -p $(DESTDIR)/$(mandir)/man1
 	mkdir -p $(DESTDIR)/$(mandir)/man5
 	mkdir -p $(DESTDIR)/$(docdir)
-	install -m 644 londiste.1 $(DESTDIR)/$(mandir)/man1
-	install -m 644 londiste.5 $(DESTDIR)/$(mandir)/man5
-	install -m 644 pgqadm.1 $(DESTDIR)/$(mandir)/man1
-	for m in $(SCRIPT_MANS); do \
+	for m in $(FQMAN1); do \
 	  install -m 644 $$m $(DESTDIR)/$(mandir)/man1 ; \
 	done
-	for h in $(HTMLS); do \
+	for m in $(FQMAN5); do \
+	  install -m 644 $$m $(DESTDIR)/$(mandir)/man5 ; \
+	done
+	for h in $(FQHTML); do \
 	  install -m 644 $$h $(DESTDIR)/$(docdir) ; \
 	done
 
@@ -91,49 +99,42 @@ realclean: distclean
 
 ifneq ($(ASCIIDOC),no)
 ifneq ($(XMLTO),no)
-londiste.1: londiste.cmdline.xml
-	$(XMLTO) man $<
-
-londiste.5: londiste.config.xml
-	$(XMLTO) man $<
-
-pgqadm.1: pgq-admin.xml
-	$(XMLTO) man $<
-
-walmgr.1: walmgr.xml
-	$(XMLTO) man $<
-
-%.xml: %.txt $(COMMON)
+man/%.xml: %.txt $(COMMON)
+	@mkdir -p man
 	$(ASCIIDOC) -b docbook -d manpage `$(GETATTRS) $<` -o - $< \
-	| python fixman.py > $@
+	| $(FIXMAN) > $@
 
-%.1: %.xml
-	$(XMLTO) man $<
+man/%.1: man/%.xml
+	@mkdir -p man
+	$(XMLTO) -o man man $<
 endif
 
-%.html: %.txt $(COMMON)
+html/%.html: %.txt $(COMMON)
+	@mkdir -p html
 	LANG=C cat $< \
 	| sed -e '/^include/b;s,\([A-Za-z.0-9]*\)[.]txt,link:\1.html[],g' \
 	| $(ASCIIDOC) $(AFLAGS) -a toc `$(GETATTRS) $<` -o - - \
-	| sed -e "/^[/][*] Workarounds/r extra.css" \
+	| sed -e "/^[/][*] Workarounds/r ../misc/extra.css" \
 	> $@
 
-README.html: ../README
+html/README.html: ../README
+	@mkdir -p html
 	cat $< \
 	| sed -e 's,doc/\([!-~]*\)[.]txt,link:\1.html[],g' \
 	      -e 's,http:[!-~]*,&[],g' \
 	| $(ASCIIDOC) $(AFLAGS) -o - - \
-	| sed -e "/^[/][*] Workarounds/r extra.css" \
+	| sed -e "/^[/][*] Workarounds/r ../misc/extra.css" \
 	> $@
 
-INSTALL.html: ../INSTALL
+html/INSTALL.html: ../INSTALL
+	@mkdir -p html
 	$(ASCIIDOC) $(AFLAGS) -o - $< \
-	| sed -e "/^[/][*] Workarounds/r extra.css" \
+	| sed -e "/^[/][*] Workarounds/r ../misc/extra.css" \
 	> $@
 endif
 
 web: $(HTMLS)
-	rsync -avz $(HTMLS) $(web)/doc/
+	rsync -avz $(FQHTML) $(web)/doc/
 
 
 
diff --git a/doc/TODO.txt b/doc/TODO.txt
index 583cd2d7..d01da41c 100644
--- a/doc/TODO.txt
+++ b/doc/TODO.txt
@@ -151,3 +151,137 @@ who already is handling it.
 * skytools: config-less operation?
 * londiste: somehow automatic sync of table structure/functions/...?
 
+
+== qadmin todo list ==
+
+== Goal ==
+
+Easy to use admin console to examine and administer PgQ queues.
+Main feature is psql like tab-completion for everything (queue/consumer names).
+
+== Current direction ==
+
+* Cmdline switches similar to psql.
+* No config file. (?)
+* SQL-like syntax (potential to accept full SQL).
+* Target is console usage, not scripts.
+* Info about both plain and cascaded queues.
+* Administer only plain queues.
+
+== Potential future directions ==
+
+ * SQL Scripts.
+  - Full SQL
+  - Variables?
+  - Logic?
+ * Admin scripts for cascaded queues.  Eg. implement current "switchover", "change-provider"
+   commands with it.
+  - Needs variables and multi-node support (execute on this node).
+    Maybe look at the paralled exec features of psql.
+ * Admin scripts for something else.
+  - data maintainer?
+  - release_script?
+
+== Command line ==
+
+
+  -Q:: queue name
+  -U:: username
+  -h:: host
+  -p:: port
+  -d:: database
+ 
+  --help:: help
+  --version:: version
+
+== Internal language ==
+
+All the commands assume they are connected to a database.
+
+Raw connect, maybe set default queue:
+
+  CONNECT dbname=.. host=.. port=.. user=.. password=.. queue=..;
+
+Set default queue:
+
+  CONNECT queue=..;
+
+Connect to node on default queue:
+
+  CONNECT node=..;
+
+Plain queue modification:
+
+  CREATE QUEUE <qname> [params?];
+  REGISTER CONSUMER <cons>;
+  UNREGISTER CONSUMER <cons>;
+  DROP QUEUE <qname>;
+
+  ALTER QUEUE <qname> SET ..;
+
+Install code:
+
+  INSTALL pgq;      -- txid, pgq, pgq_ext, pgq_node
+  INSTALL londiste; -- all of above + londiste
+
+Information:
+
+  SHOW QUEUE (<qname> | *);
+  SHOW CONSUMER (<cons> | *) [ ON <qname | * ];
+  SHOW BATCH INFO (<id> | <consumer>) [ON <queue>?];
+  SHOW BATCH EVENTS (<id> | <consumer>) [ON <queue>?];
+
+== Smaller Open Questions ==
+
+* What arguments should qadmin accept from command line?
+
+  psql-style: qadmin [switches] [dbname [username]]
+  ssh-style:  qadmin [switches] [command [args]]
+
+* Command style and syntax.
+
+* Multi-word vs. long words:
+ - SHOW BATCH EVENTS <id>;
+ - SHOW_BATCH_EVENTS <id>;
+
+* Default queue vs. queue name in commands.
+
+== ToDo ==
+
+* General:
+  - Lots of useful commands.
+
+* Parsing:
+
+  - Node naming is not consistent, as it has grown, not designed.
+    Suggestions: (Word -> Ident, WList->TokenList?/NodeList?,
+    DynList->DynIdent?, SWord->Param?) Also: get_next() -> parse()
+  - Quoted idents/strings not supported.  Fix: nodes should unquote early.
+    IIRC libpq connect string generation in "connect" code assumes already
+    quoted values, quoting needs to be added there.
+  - Tab-completion of uppercase keywords.
+  - Disable lowercasing of quoted indents. (?)
+  - Tab-completion of quoted idents. (?)
+  - Multi-line commands. (?)
+
+* Cascading: It would be useful to also have cascading commands available in qadmin.
+   ( SWITCHOVER / CREATE NODE / PAUSE NODE / CHANGE PROVIDER ).
+   But currently they are implemented using DBScript framework.  And
+   we don't want to have several implementations of the commands.
+   There seems to be 2 ways forward:
+   - Convert qadmin to DBScript.  It is possible to make config-less DBScript.
+   - Implement command under qadmin in non-DBScript way and make
+     CascadeAdmin call qadmin implementation.
+
+* Londiste: It seems to be good idea to make Londiste management also available in qadmin.
+  - LONDISTE ADD|REMOVE TABLE <tbl>
+  - LONDISTE ADD|REMOVE SEQUENCE <seq>
+  - LONDISTE SHOW TABLES / SHOW LONDISTE TABLES / SHOW TABLES ?
+  - SHOW MISSING TABLES?
+
+* random other ideas:
+  - queue rename.  (on remote side too?)
+  - copy consumer pos
+  - rename consumer
+  - event del?
+
diff --git a/doc/londiste.config.txt b/doc/londiste.config.txt
deleted file mode 100644
index 7d2144d6..00000000
--- a/doc/londiste.config.txt
+++ /dev/null
@@ -1,63 +0,0 @@
-= londiste(5) =
-
-== NAME ==
-
-londiste - PostgreSQL replication engine written in python
-
-== SYNOPSIS ==
-
-	[londiste]
-	job_name = asd
-
-== DESCRIPTION == 
-
-The londiste configuration file follow the famous .INI syntax. It
-contains only one section named londiste.
-
-Most defaults values are reasonable ones. That means you can only edit
-provider_db, subscriber_db and pgq_queue_name and be done with
-londiste configuration.
-
-== OPTIONS ==
-
-You can configure the following options into the londiste section.
-
-job_name::
-  Each running londiste replay process has a unique job name.
-
-provider_db::
-  Provider database connection string (DSN).
-
-subscriber_db::
-  Subscriber database connection string (DSN).
-
-pgq_queue_name::
-  Name of the PgQ to use. Must match the PgQ ticker configuration.
-
-logfile::
-  Where to log londiste activity.
-
-pidfile::
-  Where to store the pid of the main londiste process, the replay one.
-
-== EXAMPLE ==
-
-  [londiste]
-  job_name = test_to_subcriber
-  
-  provider_db = dbname=provider port=6000 host=127.0.0.1
-  subscriber_db = dbname=subscriber port=6000 host=127.0.0.1
-  
-  # it will be used as sql ident so no dots/spaces
-  pgq_queue_name = londiste.replika
-  
-  logfile = /tmp/%(job_name)s.log
-  pidfile = /tmp/%(job_name)s.pid
-  
-  # both events and ticks will be copied there
-  #mirror_queue = replika_mirror
-  
-
-== SEE ALSO ==
-
-londiste(1)
diff --git a/doc/londiste.cmdline.txt b/doc/londiste.txt
index a6665927..a6665927 100644
--- a/doc/londiste.cmdline.txt
+++ b/doc/londiste.txt
diff --git a/doc/pgq-admin.txt b/doc/pgqadm.txt
index 7c6df5c7..7c6df5c7 100644
--- a/doc/pgq-admin.txt
+++ b/doc/pgqadm.txt
diff --git a/doc/qadmin.txt b/doc/qadmin.txt
index 95761bbd..0c0b1d04 100644
--- a/doc/qadmin.txt
+++ b/doc/qadmin.txt
@@ -1,133 +1,39 @@
-= qadmin =
 
-== Goal ==
+= qadmin(1) =
 
-Easy to use admin console to examine and administer PgQ queues.
-Main feature is psql like tab-completion for everything (queue/consumer names).
+== NAME ==
 
-== Current direction ==
+qadmin - Easy to use admin console to examine and administer PgQ queues.
 
-* Cmdline switches similar to psql.
-* No config file. (?)
-* SQL-like syntax (potential to accept full SQL).
-* Target is console usage, not scripts.
-* Info about both plain and cascaded queues.
-* Administer only plain queues.
+== SYNOPSIS ==
 
-== Potential future directions ==
+  qadmin.py [ options ... ]
 
- * SQL Scripts.
-  - Full SQL
-  - Variables?
-  - Logic?
- * Admin scripts for cascaded queues.  Eg. implement current "switchover", "change-provider"
-   commands with it.
-  - Needs variables and multi-node support (execute on this node).
-    Maybe look at the paralled exec features of psql.
- * Admin scripts for something else.
-  - data maintainer?
-  - release_script?
+== DESCRIPTION ==
 
-== Command line ==
+The goal is to be psql-like console for queue administration.
 
+== GENERAL OPTIONS ==
 
-  -Q:: queue name
-  -U:: username
-  -h:: host
-  -p:: port
-  -d:: database
- 
-  --help:: help
-  --version:: version
+Initial connection options (for libpq):
 
-== Internal language ==
+ -h host:: specify host to connect to (default: localhost via unix socket)
 
-All the commands assume they are connected to a database.
+ -p port:: specify port
 
-Raw connect, maybe set default queue:
+ -U user:: specify user name
 
-  CONNECT dbname=.. host=.. port=.. user=.. password=.. queue=..;
+ -d dbname:: database name
 
-Set default queue:
+Options for qadmin:
 
-  CONNECT queue=..;
+ -Q queuename:: queue name
 
-Connect to node on default queue:
+ -c cmd_string:: execute command
 
-  CONNECT node=..;
+ -f execfile:: execute file containing commands
 
-Plain queue modification:
+ --help:: help screen
 
-  CREATE QUEUE <qname> [params?];
-  REGISTER CONSUMER <cons>;
-  UNREGISTER CONSUMER <cons>;
-  DROP QUEUE <qname>;
-
-  ALTER QUEUE <qname> SET ..;
-
-Install code:
-
-  INSTALL pgq;      -- txid, pgq, pgq_ext, pgq_node
-  INSTALL londiste; -- all of above + londiste
-
-Information:
-
-  SHOW QUEUE (<qname> | *);
-  SHOW CONSUMER (<cons> | *) [ ON <qname | * ];
-  SHOW BATCH INFO (<id> | <consumer>) [ON <queue>?];
-  SHOW BATCH EVENTS (<id> | <consumer>) [ON <queue>?];
-
-== Smaller Open Questions ==
-
-* What arguments should qadmin accept from command line?
-
-  psql-style: qadmin [switches] [dbname [username]]
-  ssh-style:  qadmin [switches] [command [args]]
-
-* Command style and syntax.
-
-* Multi-word vs. long words:
- - SHOW BATCH EVENTS <id>;
- - SHOW_BATCH_EVENTS <id>;
-
-* Default queue vs. queue name in commands.
-
-== ToDo ==
-
-* General:
-  - Lots of useful commands.
-
-* Parsing:
-
-  - Node naming is not consistent, as it has grown, not designed.
-    Suggestions: (Word -> Ident, WList->TokenList?/NodeList?,
-    DynList->DynIdent?, SWord->Param?) Also: get_next() -> parse()
-  - Quoted idents/strings not supported.  Fix: nodes should unquote early.
-    IIRC libpq connect string generation in "connect" code assumes already
-    quoted values, quoting needs to be added there.
-  - Tab-completion of uppercase keywords.
-  - Disable lowercasing of quoted indents. (?)
-  - Tab-completion of quoted idents. (?)
-  - Multi-line commands. (?)
-
-* Cascading: It would be useful to also have cascading commands available in qadmin.
-   ( SWITCHOVER / CREATE NODE / PAUSE NODE / CHANGE PROVIDER ).
-   But currently they are implemented using DBScript framework.  And
-   we don't want to have several implementations of the commands.
-   There seems to be 2 ways forward:
-   - Convert qadmin to DBScript.  It is possible to make config-less DBScript.
-   - Implement command under qadmin in non-DBScript way and make
-     CascadeAdmin call qadmin implementation.
-
-* Londiste: It seems to be good idea to make Londiste management also available in qadmin.
-  - LONDISTE ADD|REMOVE TABLE <tbl>
-  - LONDISTE ADD|REMOVE SEQUENCE <seq>
-  - LONDISTE SHOW TABLES / SHOW LONDISTE TABLES / SHOW TABLES ?
-  - SHOW MISSING TABLES?
-
-* random other ideas:
-  - queue rename.  (on remote side too?)
-  - copy consumer pos
-  - rename consumer
-  - event del?
+ --version:: print version
 
diff --git a/doc/extra.css b/misc/extra.css
index eb44f103..eb44f103 100644
--- a/doc/extra.css
+++ b/misc/extra.css
diff --git a/doc/fixman.py b/misc/fixman.py
index 55f930bc..55f930bc 100755
--- a/doc/fixman.py
+++ b/misc/fixman.py
diff --git a/doc/getattrs.py b/misc/getattrs.py
index e538b033..e538b033 100755
--- a/doc/getattrs.py
+++ b/misc/getattrs.py