changeset 3108:2572688e031a

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, 478 insertions(+), 179 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
-
-    @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.
+MoinMoin - check / process user accounts
 
-    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).
+@copyright: 2003-2006 MoinMoin:ThomasWaldmann
+@license: GNU GPL, see COPYING for details.
+"""
 
-    How to use this tool?
-    =====================
+# ----------------------------------------------------------------------------
+# if a user subscribes to magicpages, it means that he wants to keep
+# exactly THIS account - this will avoid deleting it.
+magicpages = [
+    "ThisAccountIsCorrect",
+    "DieserAccountIstRichtig",
+]
 
-    General syntax: moin [options] account check [check-options]
+# ----------------------------------------------------------------------------
 
-    [options] usually should be:
-        --config-dir=/path/to/my/cfg/ --wiki-url=wiki.example.org/
+import os, sys
 
-    [check-options] see below:
+from MoinMoin.script import MoinScript
+from MoinMoin import user, wikiutil
+
+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.
+
+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).
+
+Detailed Instructions:
+======================
+
+General syntax: moin [options] account check [check-options]
+
+[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
+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.
-
-    @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.
+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.
-
-    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