diff options
author | Marko Kreen | 2009-06-05 10:32:09 +0000 |
---|---|---|
committer | Marko Kreen | 2009-06-07 15:19:39 +0000 |
commit | 37cd5f3e1252c052fc6dfdd53e4f01f8d1e757b6 (patch) | |
tree | 56c130c6baa130f1b996c03d3ca6333998aae74b | |
parent | 49e87a1c2e41ab613f0c383c8749066be92e14d2 (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/Makefile | 79 | ||||
-rw-r--r-- | doc/TODO.txt | 134 | ||||
-rw-r--r-- | doc/londiste.config.txt | 63 | ||||
-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.txt | 132 | ||||
-rw-r--r-- | misc/extra.css (renamed from doc/extra.css) | 0 | ||||
-rwxr-xr-x | misc/fixman.py (renamed from doc/fixman.py) | 0 | ||||
-rwxr-xr-x | misc/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 |