summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarko Kreen2009-06-05 10:32:09 +0000
committerMarko Kreen2009-06-07 15:19:39 +0000
commit37cd5f3e1252c052fc6dfdd53e4f01f8d1e757b6 (patch)
tree56c130c6baa130f1b996c03d3ca6333998aae74b
parent49e87a1c2e41ab613f0c383c8749066be92e14d2 (diff)
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
-rw-r--r--doc/Makefile79
-rw-r--r--doc/TODO.txt134
-rw-r--r--doc/londiste.config.txt63
-rw-r--r--doc/londiste.txt (renamed from doc/londiste.cmdline.txt)0
-rw-r--r--doc/pgqadm.txt (renamed from doc/pgq-admin.txt)0
-rw-r--r--doc/qadmin.txt132
-rw-r--r--misc/extra.css (renamed from doc/extra.css)0
-rwxr-xr-xmisc/fixman.py (renamed from doc/fixman.py)0
-rwxr-xr-xmisc/getattrs.py (renamed from doc/getattrs.py)0
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