--- a/__init__.py
+++ b/__init__.py
@@ -1,3 +1,17 @@
+'''integration with Subversion repositories
+
+This extension allows Mercurial to act as a Subversion client, for
+fast incremental, bidirectional updates.
+
+It is *not* ready yet for production use. You should only be using
+this if you're ready to hack on it, and go diving into the internals
+of Mercurial and/or Subversion.
+
+Before using hgsubversion, it is *strongly* encouraged to run the
+automated tests. See `README' in the hgsubversion directory for
+details.
+'''
+
 import os
 
 from mercurial import commands
@@ -16,10 +30,12 @@ def reposetup(ui, repo):
 
 
 def svn(ui, repo, subcommand, *args, **opts):
+    '''see detailed help for list of subcommands'''
+
     return svncommand.svncmd(ui, repo, subcommand, *args, **opts)
 
 def svn_fetch(ui, svn_url, hg_repo_path=None, **opts):
-    '''Clone Subversion repository to local Mercurial repository.
+    '''clone Subversion repository to a local Mercurial repository.
 
     If no destination directory name is specified, it defaults to the
     basename of the source plus "-hg".
@@ -42,20 +58,22 @@ commands.norepo += " svnclone"
 cmdtable = {
     "svn":
         (svn,
-         [('u', 'svn-url', '', 'Path to the Subversion server.'),
-          ('', 'stupid', False, 'Be stupid and use diffy replay.'),
+         [('u', 'svn-url', '', 'path to the Subversion server.'),
+          ('', 'stupid', False, 'be stupid and use diffy replay.'),
           ('A', 'authors', '', 'username mapping filename'),
-          ('', 'filemap', '', 'remap file to exclude paths or include only certain paths'),
+          ('', 'filemap', '',
+           'remap file to exclude paths or include only certain paths'),
           ],
          svncommand.generate_help(),
          ),
     "svnclone":
         (svn_fetch,
-         [('S', 'skipto-rev', '0', 'Skip commits before this revision.'),
-          ('', 'stupid', False, 'Be stupid and use diffy replay.'),
+         [('S', 'skipto-rev', '0', 'skip commits before this revision.'),
+          ('', 'stupid', False, 'be stupid and use diffy replay.'),
           ('T', 'tag-locations', 'tags', 'Relative path to Subversion tags.'),
           ('A', 'authors', '', 'username mapping filename'),
-          ('', 'filemap', '', 'remap file to exclude paths or include only certain paths'),
+          ('', 'filemap', '',
+           'remap file to exclude paths or include only certain paths'),
          ],
          'hg svnclone source [dest]'),
 }

--- a/diff_cmd.py
+++ b/diff_cmd.py
@@ -25,7 +25,7 @@ def filterdiff(diff, base_revision):
 
 
 def diff_command(ui, repo, hg_repo_path, **opts):
-    """Show a diff of the most recent revision against its parent from svn.
+    """show a diff of the most recent revision against its parent from svn
     """
     hge = hg_delta_editor.HgChangeReceiver(hg_repo_path,
                                            ui_=ui)

--- a/fetch_command.py
+++ b/fetch_command.py
@@ -26,7 +26,7 @@ def fetch_revisions(ui, svn_url, hg_repo
                     authors=None,
                     filemap=None,
                     **opts):
-    """Pull new revisions from Subversion.
+    """pull new revisions from Subversion
     """
     svn_url = util.normalize_url(svn_url)
     old_encoding = merc_util._encoding

--- a/push_cmd.py
+++ b/push_cmd.py
@@ -13,7 +13,7 @@ import utility_commands
 
 def push_revisions_to_subversion(ui, repo, hg_repo_path, svn_url,
                                  stupid=False, **opts):
-    """Push revisions starting at a specified head back to Subversion.
+    """push revisions starting at a specified head back to Subversion.
     """
     oldencoding = merc_util._encoding
     merc_util._encoding = 'UTF-8'

--- a/rebuildmeta.py
+++ b/rebuildmeta.py
@@ -7,7 +7,7 @@ import svnwrap
 import util
 
 def rebuildmeta(ui, repo, hg_repo_path, args, **opts):
-    """Rebuild hgsubversion metadata using values stored in revisions.
+    """rebuild hgsubversion metadata using values stored in revisions
     """
     assert len(args) == 1, 'You must pass the svn URI used to create this repo.'
     uuid = None

--- a/svncommand.py
+++ b/svncommand.py
@@ -55,7 +55,7 @@ def svncmd(ui, repo, subcommand, *args, 
 
 
 def help_command(ui, args=None, **opts):
-    """Get help on the subsubcommands.
+    """show help for a given subcommands or a help overview
     """
     if args:
         subcommand = args[0]
@@ -79,7 +79,7 @@ def help_command(ui, args=None, **opts):
 help_command = register_subcommand('help')(help_command)
 
 def update(ui, args, repo, clean=False, **opts):
-    """Update to a specified Subversion revision number.
+    """update to a specified Subversion revision number
     """
     assert len(args) == 1
     rev = int(args[0])
@@ -104,7 +104,7 @@ update = register_subcommand('up')(updat
 
 
 def verify_revision(ui, args, repo, force=False, **opts):
-    """Verify a single converted revision.
+    """verify a single converted revision
     Note: This wipes your working copy and then exports the corresponding
     Subversion into your working copy to verify. Use with caution.
     """
@@ -141,8 +141,7 @@ def verify_revision(ui, args, repo, forc
 verify_revision = register_subcommand('verify_revision')(verify_revision)
 
 def verify_all_revisions(ui, args, repo, **opts):
-    """Verify all the converted revisions
-    optionally starting at a revision.
+    """verify converted revisions; all or starting at a revision
 
     Note: This is *extremely* abusive of the Subversion server. It exports every
     revision of the code one revision at a time.

--- a/util.py
+++ b/util.py
@@ -14,10 +14,12 @@ def register_subcommand(name):
 
 
 def generate_help():
-    ret = ['', 'hg svn subcommand\n', 'Subcommands:\n']
+    ret = ['hg svn ...', '',
+           'subcommands for Subversion integration', '',
+           'list of subcommands:', '']
 
     for name, func in sorted(svn_subcommands.items()):
-        short_description = (func.__doc__ or '').split('\n')[0]
+        short_description = (func.__doc__ or '').splitlines()[0]
         ret.append(" %-10s  %s" % (name, short_description))
 
     return "\n".join(ret) + '\n'

--- a/utility_commands.py
+++ b/utility_commands.py
@@ -7,7 +7,7 @@ import util
 import hg_delta_editor
 
 def print_wc_url(ui, repo, hg_repo_path, **opts):
-    """Url of Subversion repository.
+    """show the location (URL) of the Subversion repository
     """
     hge = hg_delta_editor.HgChangeReceiver(hg_repo_path,
                                            ui_=ui)
@@ -16,7 +16,7 @@ print_wc_url = util.register_subcommand(
 
 
 def run_svn_info(ui, repo, hg_repo_path, **opts):
-    """Like svn info details.
+    """show Subversion details similar to `svn info'
     """
     hge = hg_delta_editor.HgChangeReceiver(hg_repo_path,
                                            ui_=ui)
@@ -60,7 +60,7 @@ run_svn_info = util.register_subcommand(
 
 
 def print_parent_revision(ui, repo, hg_repo_path, **opts):
-    """Display hg hash and svn revision of nearest svn parent.
+    """show Mercurial & Subversion parents of the working dir or revision
     """
     hge = hg_delta_editor.HgChangeReceiver(hg_repo_path,
                                            ui_=ui)
@@ -81,7 +81,7 @@ print_parent_revision = util.register_su
 
 
 def rebase_commits(ui, repo, hg_repo_path, extrafn=None, sourcerev=None, **opts):
-    """Rebases current unpushed revisions onto Subversion head.
+    """rebase current unpushed revisions onto the Subversion head
 
     This moves a line of development from making its own head to the top of
     Subversion development, linearizing the changes. In order to make sure you
@@ -131,7 +131,7 @@ rebase_commits = util.register_subcomman
 
 
 def show_outgoing_to_svn(ui, repo, hg_repo_path, **opts):
-    """Show changesets not yet pushed to SVN.
+    """show changesets not found in the Subversion repository
     """
     hge = hg_delta_editor.HgChangeReceiver(hg_repo_path,
                                            ui_=ui)