Mercurial > moin > 1.9

changeset 3108:2572688e031a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
improved moin script's builtin help function, thanks to Federico Lorenzi (ported from 1.6)
author Thomas Waldmann <tw AT waldmann-edv DOT de>
date Sat, 23 Feb 2008 23:40:48 +0100
parents c6e39279f83b
children 4cd113328476
files MoinMoin/script/__init__.py MoinMoin/script/account/check.py MoinMoin/script/account/create.py MoinMoin/script/account/disable.py MoinMoin/script/cli/show.py MoinMoin/script/export/dump.py MoinMoin/script/export/package.py MoinMoin/script/import/irclog.py MoinMoin/script/index/build.py MoinMoin/script/maint/cleancache.py MoinMoin/script/maint/cleanpage.py MoinMoin/script/maint/globaledit.py MoinMoin/script/maint/mailtranslators.py MoinMoin/script/maint/mkpagepacks.py MoinMoin/script/maint/reducewiki.py MoinMoin/script/xmlrpc/mailimport.py MoinMoin/script/xmlrpc/remote.py MoinMoin/script/xmlrpc/retrieve.py MoinMoin/script/xmlrpc/write.py
diffstat 19 files changed, 477 insertions(+), 178 deletions(-) [+]
line wrap: on
line diff
--- a/MoinMoin/script/__init__.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/__init__.py	Sat Feb 23 23:40:48 2008 +0100
@@ -112,7 +112,7 @@
 
         self.parser = optparse.OptionParser(
             usage="%(cmd)s [command] %(usage)s" % {'cmd': os.path.basename(sys.argv[0]), 'usage': usage, },
-            version=rev)
+            version=rev, add_help_option=False)
         self.parser.allow_interspersed_args = False
         if def_values:
             self.parser.set_defaults(**def_values.__dict__)
@@ -231,11 +231,7 @@
 Specific options:
     Most commands need additional parameters after command subcommand.
 
-    Sorry, but there is not much docs about that stuff yet, you can check
-    docs/CHANGES and the MoinMoin wiki site for more infos (or just try to
-    invoke some command/subcommand to see if it emits more help).
-    The code you invoke is contained in MoinMoin/script/command/subcommand.py,
-    so just reading the comments / source there might help you, too.
+    To obtain additonal help on a command use 'moin module subcommand --help'
 """)
 
         cmd_module, cmd_name = args[:2]
@@ -244,5 +240,15 @@
             plugin_class = wikiutil.importBuiltinPlugin('script.%s' % cmd_module, cmd_name, 'PluginScript')
         except wikiutil.PluginMissingError:
             fatal("Command plugin %r, command %r was not found." % (cmd_module, cmd_name))
-        plugin_class(args[2:], self.options).run() # all starts again there
 
+        # We have to use the args list here instead of optparse, as optparse only
+        # deals with things coming before command subcommand.
+        if "--help" in args or "-h" in args:
+            print "MoinMoin Help - %s/ %s\n" % (cmd_module, cmd_name)
+            print plugin_class.__doc__
+            print "Command line reference:"
+            print "======================="
+            plugin_class(args[2:], self.options).parser.print_help()
+        else:
+            plugin_class(args[2:], self.options).run() # all starts again there
+
--- a/MoinMoin/script/account/check.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/account/check.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,31 +1,49 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - check / process user accounts
+MoinMoin - check / process user accounts
 
-    @copyright: 2003-2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2003-2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
+"""
 
-    Why is this needed?
-    ===================
-    When using ACLs, a wiki user name has to be unique, there must not be
-    multiple accounts having the same username. The problem is, that this
-    was possible before the introduction of ACLs and many users, who forgot
-    their ID, simply created a new ID using the same user name.
+# ----------------------------------------------------------------------------
+# if a user subscribes to magicpages, it means that he wants to keep
+# exactly THIS account - this will avoid deleting it.
+magicpages = [
+    "ThisAccountIsCorrect",
+    "DieserAccountIstRichtig",
+]
+
+# ----------------------------------------------------------------------------
+
+import os, sys
+
+from MoinMoin.script import MoinScript
+from MoinMoin import user, wikiutil
 
-    Because access rights (when using ACLs) depend on the NAME (not the ID),
-    this must be cleaned up before using ACLs or users will have difficulties
-    changing settings and saving their account data (system won't accept the
-    save, if the user name and email is not unique).
+class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+When using ACLs, a wiki user name has to be unique, there must not be
+multiple accounts having the same username. The problem is, that this
+was possible before the introduction of ACLs and many users, who forgot
+their ID, simply created a new ID using the same user name.
 
-    How to use this tool?
-    =====================
-
-    General syntax: moin [options] account check [check-options]
+Because access rights (when using ACLs) depend on the NAME (not the ID),
+this must be cleaned up before using ACLs or users will have difficulties
+changing settings and saving their account data (system won't accept the
+save, if the user name and email is not unique).
 
-    [options] usually should be:
-        --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+Detailed Instructions:
+======================
+
+General syntax: moin [options] account check [check-options]
 
-    [check-options] see below:
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[check-options] see below:
 
     0. Check the settings at top of the code!
        Making a backup of your wiki might be also a great idea.
@@ -51,25 +69,8 @@
     5. Optionally you may want to make wikinames out of the user names
        moin ... account check --wikinames
        moin ... account check --wikinames --save
-
 """
 
-# ----------------------------------------------------------------------------
-# if a user subsribes to magicpages, it means that he wants to keep
-# exactly THIS account - this will avoid deleting it.
-magicpages = [
-    "ThisAccountIsCorrect",
-    "DieserAccountIstRichtig",
-]
-
-# ----------------------------------------------------------------------------
-
-import os, sys
-
-from MoinMoin.script import MoinScript
-from MoinMoin import user, wikiutil
-
-class PluginScript(MoinScript):
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
         self._addFlag("usersunique",
--- a/MoinMoin/script/account/create.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/account/create.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,14 +1,38 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - create a user account
+MoinMoin - create a user account
 
-    @copyright: 2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool allows you to create user accounts via a command line interface.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] account create [create-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[create-options] see below:
+    0. Verify that the account does not exist.
+       Currently this script does not check if the user exists.
+
+    1. Verify that you have specified the right options.
+       This script does no verification of email addresses or the like.
+
+    2. To create a normal user 'JohnSmith' with an alias of 'JSmith' and an
+       email of 'john@smith.com'
+       moin ... account create --name JohnSmith --alias JSmith --email john@smith.com
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
         self.parser.add_option(
@@ -49,4 +73,3 @@
         print " %-20s %-25s %-35s" % (u.id, u.name, u.email),
         u.save()
         print "- created."
-
--- a/MoinMoin/script/account/disable.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/account/disable.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,14 +1,40 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - disable a user account
+MoinMoin - disable a user account
 
-    @copyright: 2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool allows you to disable user accounts via a command line interface.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] account disable [disable-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[disable-options] see below:
+    0. Verify that you really want to disable the account.
+       While there is a disable script, no such enable script exists.
+
+    1. If using usernames, verify that multiple usernames with the same
+       user ID do not exist.
+
+    2. To disable the user 'JohnSmith':
+       moin ... account disable --name JohnSmith
+
+    3. To disable the user 'JohnSmith', based on his UID '1198872910.78.56322':
+       moin ... account disable --uid 1198872910.78.56322
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
         self.parser.add_option(
@@ -50,4 +76,3 @@
             print "- disabled."
         else:
             print "- is already disabled."
-
--- a/MoinMoin/script/cli/show.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/cli/show.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,17 +1,26 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - cli show script
+MoinMoin - cli show script
 
-    Just run a CLI request and show the output.
-
-    @copyright: 2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
-    """ show page script class """
+    """\
+Purpose:
+========
+Just run a CLI request and show the output.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] cli show
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+"""
 
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
@@ -19,4 +28,3 @@
     def mainloop(self):
         self.init_request()
         self.request.run()
-
--- a/MoinMoin/script/export/dump.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/export/dump.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,14 +1,10 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - Dump a MoinMoin wiki to static pages
-
-    You must run this script as owner of the wiki files, usually this is the
-    web server user.
+MoinMoin - Dump a MoinMoin wiki to static pages
 
-    @copyright: 2002-2004 Juergen Hermann <jh@web.de>,
-                2005-2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
-
+@copyright: 2002-2004 Juergen Hermann <jh@web.de>,
+            2005-2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 import sys, os, time, codecs, shutil, re, errno
@@ -95,7 +91,29 @@
 
 
 class PluginScript(script.MoinScript):
-    """ Dump script class """
+    """\
+Purpose:
+========
+This tool allows you to dump MoinMoin wiki pages to static HTML files.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] export dump [dump-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[dump-options] see below:
+    0. You must run this script as owner of the wiki files, usually this is the
+       web server user.
+
+    1. To dump all the pages on the wiki to the directory '/mywiki'
+       moin ... export dump --target-dir=/mywiki
+
+    2. To dump all the pages readable by 'JohnSmith' on the wiki to the directory
+       '/mywiki'
+       moin ... export dump --target-dir=/mywiki --username JohnSmith
+"""
 
     def __init__(self, argv=None, def_values=None):
         script.MoinScript.__init__(self, argv, def_values)
--- a/MoinMoin/script/export/package.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/export/package.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,15 +1,11 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - Create a MoinMoin package from wiki pages specified.
-
-    You must run this script as owner of the wiki files, usually this is the
-    web server user.
+MoinMoin - Create a MoinMoin package from wiki pages specified.
 
-    @copyright: 2002-2004 Juergen Hermann <jh@web.de>,
-                2005-2006 MoinMoin:ThomasWaldmann,
-                2007 Federico Lorenzi
-    @license: GNU GPL, see COPYING for details.
-
+@copyright: 2002-2004 Juergen Hermann <jh@web.de>
+            2005-2006 MoinMoin:ThomasWaldmann,
+            2007 Federico Lorenzi
+@license: GNU GPL, see COPYING for details.
 """
 
 import codecs, errno, os, re, shutil, sys, time
@@ -19,7 +15,34 @@
 
 
 class PluginScript(script.MoinScript):
-    """ Create package class """
+    """\
+Purpose:
+========
+This tool allows you to create a package of certain wiki pages.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] export package [package-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[package-options] see below:
+    0. You must run this script as owner of the wiki files, usually this is the
+       web server user.
+
+    1. To package all non-system and non-underlay pages on a wiki to the file '~/mywiki.zip'
+       moin ... export package --output ~/mywiki.zip
+
+    2. To package the pages 'FooBar' and 'TestPage' on a wiki to the file '~/mywiki.zip'
+       moin ... export package --pages FooBar,TestPage --output ~/mywiki.zip
+
+    3. To package all pages matching the search term 'MoinMoin' on a wiki to the file '~/mywiki.zip'
+       moin ... export package --search MoinMoin --output ~/mywiki.zip
+
+    4. Optionally, the --user argument could be added to any of the above examples,
+       causing the script to respect ACLs.
+"""
 
     def __init__(self, argv=None, def_values=None):
         script.MoinScript.__init__(self, argv, def_values)
--- a/MoinMoin/script/import/irclog.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/import/irclog.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,18 +1,10 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - Push files into the wiki.
-
-    This script pushes files from a directory into the wiki (to be exact: it
-    pushes all except the last file, as this is maybe still written to in
-    case of irc logs).
-    One application is to use it to store IRC logs into the wiki.
+MoinMoin - Push files into the wiki.
 
-    Usage:
-    moin --config-dir=... --wiki-url=... import irclog --author=IrcLogImporter --file-dir=.
-
-    @copyright: 2005-2007 MoinMoin:AlexanderSchremmer
-                2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2005-2007 MoinMoin:AlexanderSchremmer
+            2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 # this function generates a pagename from the file name
@@ -43,7 +35,25 @@
 
 
 class PluginScript(MoinScript):
-    """ irclog importer script class """
+    """\
+Purpose:
+========
+This script pushes files from a directory into the wiki (to be exact: it
+pushes all except the last file, as this is maybe still written to in
+case of irc logs).
+One application is to use it to store IRC logs into the wiki.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] import irclog [irclog-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[irclog-options] see below:
+    0. To add all the files in the current directory to the wiki as the user 'JohnSmith'
+       moin ... import irclog --author=JohnSmirh --file-dir=.
+"""
 
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
--- a/MoinMoin/script/index/build.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/index/build.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,18 +1,39 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - build xapian search engine's index
+MoinMoin - build xapian search engine's index
 
-    You must run this script as owner of the wiki files, usually this is the
-    web server user.
-
-    @copyright: 2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 from MoinMoin.script import MoinScript
 
 class IndexScript(MoinScript):
-    """ Xapian general index script class """
+    """\
+Purpose:
+========
+This tool allows you to control xapian's index of Moin.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] index build [build-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[build-options] see below:
+    0. You must run this script as owner of the wiki files, usually this is the
+       web server user.
+
+    1. To add the files from '/files.lst' to the index
+       moin ... index build --files /files.lst --mode add
+
+    2. To update the index with the files from '/files.lst'
+       moin ... index build --files /files.lst --mode update
+
+    3. To rebuild the index with the files from '/files.lst'
+       moin ... index build --files /files.lst --mode rebuild
+"""
 
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
--- a/MoinMoin/script/maint/cleancache.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/maint/cleancache.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,21 +1,10 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - cleancache script
-
-    globally delete cache files in data/pages/PageName/cache/ and /data/cache directories
+MoinMoin - cleancache script
 
-    You will usually do this after changing MoinMoin code, by either upgrading
-    version, installing or removing macros or changing the regex expression for dicts.
-    This often makes the text_html and dict files invalid, so you have to remove them
-    (the wiki will recreate them automatically).
-
-    text_html is the name of the cache file used for compiled pages formatted
-    by the wiki text to html formatter, A dict file does cache the pages which
-    do fit to the page_group_regex variable.
-
-    @copyright: 2005-2007 MoinMoin:ThomasWaldmann,
-                2007 MoinMoin:ReimarBauer
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2005-2007 MoinMoin:ThomasWaldmann,
+            2007 MoinMoin:ReimarBauer
+@license: GNU GPL, see COPYING for details.
 """
 
 from MoinMoin import caching
@@ -23,6 +12,29 @@
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This script allows you to globally delete all the cache files in data/pages/PageName/cache/
+and /data/cache directories
+
+You will usually do this after changing MoinMoin code, by either upgrading
+version, installing or removing macros or changing the regex expression for dicts.
+This often makes the text_html and dict files invalid, so you have to remove them
+(the wiki will recreate them automatically).
+
+text_html is the name of the cache file used for compiled pages formatted
+by the wiki text to html formatter, A dict file does cache the pages which
+do fit to the page_group_regex variable.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] maint cleancache
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
 
--- a/MoinMoin/script/maint/cleanpage.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/maint/cleanpage.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,11 +1,9 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - display unused or trash page directories in data/pages
+MoinMoin - display unused or trash page directories in data/pages
 
-    Then please review the output before running it!
-
-    @copyright: 2005-2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2005-2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 import os
@@ -13,6 +11,25 @@
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool outputs a shell script which upon execution will remove unused or
+trashed pages from the wiki.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] maint cleanpage [cleanpage-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[cleanpage-options] see below:
+    0. Verify the outputted shell script before running it.
+
+    1. This script takes no command line arguments.
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
 
--- a/MoinMoin/script/maint/globaledit.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/maint/globaledit.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,20 +1,36 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - do global changes to all pages in a wiki.
+MoinMoin - do global changes to all pages in a wiki.
+  
+@copyright: 2004-2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
+"""
 
-    The changes being done are hardcoded in function do_edit.
-    As it is, this script is mostly useful for the MoinMoin release maintainer
-    using: moin ... --wiki-url=moinmaster.wikiwikiweb.de/ maint globaledit
-
-    @copyright: 2004-2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
-"""
 debug = False
 
 from MoinMoin import PageEditor
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool allows you to edit all the pages in a wiki.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] maint globaledit [globaledit-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[globaledit-options] see below:
+    0. The changes that will be performed are hardcoded in the function
+       do_edit.
+
+    1. This script takes no command line arguments.
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
 
--- a/MoinMoin/script/maint/mailtranslators.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/maint/mailtranslators.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,14 +1,9 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - mailtranslators script
-    
-    read mail text from standard input and send an email to all translators -
-    %(lang)s will be replaced by language.
+MoinMoin - mailtranslators script
 
-    Usage: moin ... maint mailtranslators
-    
-    @copyright: 2004-2007 MoinMoin:ThomasWaldmann
-    @license: GPL, see COPYING for details
+@copyright: 2004-2007 MoinMoin:ThomasWaldmann
+@license: GPL, see COPYING for details
 """
 
 import sys, os
@@ -18,6 +13,29 @@
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool allows you to have a message read in from standard input, and
+then sent to all translators via email. If you use %(lang)s in the mssage
+it will be replaced with the appropriate language code for the translater.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] maint mailtranslators [mailtranslators-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[mailtranslators-options] see below:
+    0. To send an email to all translaters, from john@smith.com, and with a subject
+       of 'Please update your translations!' and a body of 'Please update your language,
+       %(lang)s'
+       moin ... maint mailtranslators --from-address john@smith.com --subject 'Please update your translations!'
+       Please update your language, %(lang)s
+       ^D
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
         self.parser.add_option(
--- a/MoinMoin/script/maint/mkpagepacks.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/maint/mkpagepacks.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,10 +1,10 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - Package Generator
+MoinMoin - Package Generator
 
-    @copyright: 2005 Alexander Schremmer,
-                2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2005 Alexander Schremmer,
+            2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 import os
@@ -23,6 +23,24 @@
 COMPRESSION_LEVEL = zipfile.ZIP_STORED
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool generates a set of packages from all the pages in a wiki.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] maint mkpagepacks [mkpagepacks-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[mkpagepacks-options] see below:
+    0. THIS SCRIPT SHOULD NEVER BE RUN ON ANYTHING OTHER THAN A TEST WIKI!
+
+    1. This script takes no command line arguments.
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
 
--- a/MoinMoin/script/maint/reducewiki.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/maint/reducewiki.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,27 +1,9 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - reducewiki script
-
-    Use this script to reduce a data/ directory to the latest page revision of
-    each non-deleted page (plus all attachments).
-
-    This is used to make the distributed underlay directory, but can also be
-    used for other purposes.
-
-    Usage: moin ... maint reducewiki --target-dir=myunderlay
+MoinMoin - reducewiki script
 
-    So we change like this:
-        * data/pages/PageName/revisions/{1,2,3,4}
-          -> data/pages/revisions/1  (with content of 4)
-        * data/pages/PageName/current (pointing to e.g. 4)
-          -> same (pointing to 1)
-        * data/pages/PageName/edit-log and data/edit-log
-          -> do not copy
-        * data/pages/PageName/attachments/*
-          -> just copy
-
-    @copyright: 2005-2006 MoinMoin:ThomasWaldmann
-    @license: GPL, see COPYING for details
+@copyright: 2005-2006 MoinMoin:ThomasWaldmann
+@license: GPL, see COPYING for details
 """
 
 import os, shutil, codecs
@@ -33,6 +15,38 @@
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool allows you to reduce a data/ directory to just the latest page
+revision of each non-deleted page (plus all attachments).
+
+This is used to make the distributed underlay directory, but can also be
+used for other purposes.
+
+So we change like this:
+    * data/pages/PageName/revisions/{1,2,3,4}
+        -> data/pages/revisions/1  (with content of 4)
+    * data/pages/PageName/current (pointing to e.g. 4)
+        -> same (pointing to 1)
+    * data/pages/PageName/edit-log and data/edit-log
+        -> do not copy
+    * data/pages/PageName/attachments/*
+        -> just copy
+
+Detailed Instructions:
+======================
+General syntax: moin [options] maint reducewiki [reducewiki-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[reducewiki-options] see below:
+    0. To create a wiki data/ directory with just the latest revisions in the
+       directory '/mywiki'
+       moin ... maint reducewiki --target-dir=/mywiki
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
         self.parser.add_option(
@@ -76,4 +90,3 @@
         for pagename in pagelist:
             self.copypage(request, destdir, pagename)
 
-
--- a/MoinMoin/script/xmlrpc/mailimport.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/xmlrpc/mailimport.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,11 +1,9 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - MailImport script
+MoinMoin - MailImport script
 
-    Imports a mail into the wiki.
-
-    @copyright: 2006 MoinMoin:AlexanderSchremmer
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2006 MoinMoin:AlexanderSchremmer
+@license: GNU GPL, see COPYING for details.
 """
 
 import sys
@@ -16,7 +14,26 @@
 input = sys.stdin
 
 class PluginScript(MoinScript):
-    """ Mail Importer """
+    """\
+Purpose:
+========
+This tool allows you to import mail into the wiki.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] maint mailimport [mailimport-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[mailimport-options] see below:
+    0. Verify that you have a mailimportconf.py configuration file.
+
+    1. To import mail from the file '/mymail'
+       moin ... xmlrpc mailimport << /mymail
+       OR
+       cat /mymail | moin ... xmlrpc mailimport
+"""
 
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
--- a/MoinMoin/script/xmlrpc/remote.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/xmlrpc/remote.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,11 +1,9 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - remote command execution, client part
+MoinMoin - remote command execution, client part
 
-    This can be used as client to execute moin scripts remotely.
-
-    @copyright: 2006 MoinMoin:ThomasWaldmann
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 import sys
@@ -14,7 +12,24 @@
 from MoinMoin.script import MoinScript, fatal
 
 class PluginScript(MoinScript):
-    """ Remote Script Execution Client """
+    """\
+Purpose:
+========
+This tool allows you to execute moin scripts remotely.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] xmlrpc remote [remote-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[remote-options] see below:
+    0. Verify that you have a remotescriptconf.py configuration file.
+
+    1. To run the script 'account check' remotely.
+       moin ... xmlrpc remote account check
+"""
 
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
--- a/MoinMoin/script/xmlrpc/retrieve.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/xmlrpc/retrieve.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,9 +1,9 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - page contents retriever
+MoinMoin - page contents retriever
 
-    @copyright: 2007 MoinMoin:JohannesBerg
-    @license: GNU GPL, see COPYING for details.
+@copyright: 2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
 """
 
 import xmlrpclib
@@ -11,6 +11,24 @@
 from MoinMoin.script import MoinScript
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool allows you to print out the contents of a page via xmlrpc.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] xmlrpc retrieve [retrieve-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[retrieve-options] see below:
+    0. To retrieve the page 'FrontPage' from the wiki '192.168.0.1' which is
+       running xmlrpc
+       moin ... xmlrpc retrieve 192.168.0.1 FrontPage
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
         self.argv = argv
--- a/MoinMoin/script/xmlrpc/write.py	Sat Feb 23 22:59:30 2008 +0100
+++ b/MoinMoin/script/xmlrpc/write.py	Sat Feb 23 23:40:48 2008 +0100
@@ -1,8 +1,6 @@
 # -*- coding: iso-8859-1 -*-
 """
-    MoinMoin - page contents writer
-
-    Commented example of how to edit a page with xmlrpc.
+MoinMoin - page contents writer
 
     @copyright: 2007 MoinMoin:JohannesBerg
     @license: GNU GPL, see COPYING for details.
@@ -15,6 +13,28 @@
 from MoinMoin.support.multicall import MultiCall
 
 class PluginScript(MoinScript):
+    """\
+Purpose:
+========
+This tool allows you to edit a page with xmlrpc. It is more of a commented
+example than an actual script.
+
+Detailed Instructions:
+======================
+General syntax: moin [options] xmlrpc write [write-options]
+
+[options] usually should be:
+    --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+
+[write-options] see below:
+    0. To edit the page 'FrontPage' on '192.168.0.1' using the username
+       'JohnSmith' and the password 'MyPass', changing the page contents
+       to 'This will be the new contents of the page!'
+       moin ... xmlrpc write 192.168.0.1 JohnSmith MyPass FrontPage
+       This will be the new contents of the page!
+       ^D
+"""
+
     def __init__(self, argv, def_values):
         MoinScript.__init__(self, argv, def_values)
         self.argv = argv