# HG changeset patch
# User Pascal Volk <user@localhost.localdomain.org>
# Date 1346619700 0
# Node ID ab97727357a494240ae8b302cbd2481dccb86b11
# Parent  b994444f7dee8b1f31217aeadcd9c0e453ecceef
VMM/cli: Activated help subcommand.

Implemented Command.help_(), which reads the command's help message from
cli.clihelp.

diff -r b994444f7dee -r ab97727357a4 VirtualMailManager/cli/clihelp.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/VirtualMailManager/cli/clihelp.py	Sun Sep 02 21:01:40 2012 +0000
@@ -0,0 +1,222 @@
+# -*- coding: UTF-8 -*-
+# Copyright (c) 2012, Pascal Volk
+# See COPYING for distribution information.
+"""
+    VirtualMailManager.cli.vmmhelp
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Virtual Mail Manager's command line help.
+"""
+
+_ = lambda msg: msg
+
+
+help_msgs = {'configget': (_(u"""This subcommand is used to display the
+actual value of the given configuration <option>."""),),
+    # configset
+    'configset': (_(u"""Use this subcommand to set or update a single
+configuration option's value. <option> is the configuration option, <value>
+is the <option>'s new value."""),
+_(u"""Note: This subcommand will create a new vmm.cfg without any comments.
+Your current configuration file will be backed as vmm.cfg.bak."""),),
+    # configure
+    'configure': (_(u"""Starts the interactive configuration for all
+configuration sections."""),
+_(u"""In this process the currently set value of each option will be displayed
+in square brackets. If no value is configured, the default value of each
+option will be displayed in square brackets. Press the return key, to accept
+the displayed value."""),
+_(u"""If the optional argument <section> is given, only the configuration
+options from the given section will be displayed and will be configurable.
+The following sections are available:
+"""),
+"""    account, bin, database, domain, mailbox, misc""",
+_(u"""All configuration options are described in vmm.cfg(5)."""),
+_(u"""Note: This subcommand will create a new vmm.cfg without any comments.
+Your current configuration file will be backed as vmm.cfg.bak."""),),
+    # getuser
+    'getuser': (_(u"""If only the <uid> is available, for example from process
+list, the subcommand getuser will show the user's address."""),),
+    # listdomains
+    'listdomains': (_(u"""This subcommand lists all available domains. All
+domain names will be prefixed either with `[+]', if the domain is a primary
+domain, or with `[-]', if it is an alias domain name. The output can be
+limited with an optional <pattern>."""),
+_(u"""To perform a wild card search, the % character can be used at the start
+and/or the end of the <pattern>."""),),
+    # listpwschemes
+    'listpwschemes': (_(u"""This subcommand lists all password schemes which
+could be used in the vmm.cfg as value of the misc.password_scheme option.
+The output varies, depending on the used Dovecot version and the system's
+libc."""),
+_(u"""When your Dovecot installation isn't too old, you will see additionally
+a few usable encoding suffixes. One of them can be appended to the password
+scheme."""),),
+    # version
+    'version': (_(u"""Prints vmm's version and copyright information to stdout.
+After this vmm exits."""),),
+    # domainadd
+    'domainadd': (_(u"""Adds the new domain into the database and creates the
+domain directory."""),
+_(u"""If the optional argument <transport> is given, it will override the
+default transport (domain.transport) from vmm.cfg. The specified <transport>
+will be the default transport for all new accounts in this domain."""),
+_(u"""Configuration-related behavior:"""),
+u""" * domain.auto_postmaster""",
+_(u"""When that option is set to true (default) vmm will automatically create
+the postmaster account for the new domain and prompt for postmaster@<fqdn>'s
+password."""),
+u""" * account.random_password""",
+_(u"""When the value of that option is also set to true, vmm will automatically
+create the postmaster account for the new domain and print the generated
+postmaster password to stdout."""),),
+    # domaindelete
+    'domaindelete': (_(u"""This subcommand deletes the domain specified by
+<fqdn>."""),
+_(u"""If there are accounts, aliases and/or relocated users assigned to the
+given domain, vmm will abort the requested operation and show an error
+message. If you know, what you are doing, you can specify the optional keyword
+'force'."""),
+_(u"""If you really always know what you are doing, edit your vmm.cfg and set
+the option domain.force_deletion to true."""),),
+    # domaininfo
+    'domaininfo': (_(u"""This subcommand shows some information about the
+given domain."""),
+_(u"""For a more detailed information about the domain the optional argument
+<details> can be specified. A possible <details> value can be one of the
+following six keywords:"""),
+"""    accounts, aliasdomains, aliases, catchall, relocated, full""",),
+    # domainquota
+    'domainquota': (_(u"""This subcommand is used to configure a new quota
+limit for the accounts of the domain - not for the domain itself."""),
+_(u"""The default quota limit for accounts is defined in the vmm.cfg
+(domain.quota_bytes and domain.quota_messages)."""),
+_(u"""The new quota limit will affect only those accounts for which the limit
+has not been overridden. If you want to restore the default to all accounts,
+you may pass the keyword 'force'. When the argument <messages> was omitted the
+default number of messages 0 (zero) will be applied."""),),
+    # domainservices
+    'domainservices': (_(u"""To define which services could be used by the
+users of the domain — with the given <fqdn> — use this subcommand."""),
+_(u"""Each specified <service> will be enabled/usable. All other services
+will be deactivated/unusable. Possible <service> names are:"""),
+u"""    imap, pop3, sieve, smtp""",
+_(u"""The new service set will affect only those accounts for which the set has
+not been overridden. If you want to restore the default to all accounts, you
+may pass the keyword 'force'."""),),
+    # domaintransport
+    'domaintransport': (_(u"""A new transport for the indicated domain can be
+set with this subcommand."""),
+_(u"""The new transport will affect only those accounts for which the transport
+has not been overridden. If you want to restore the default to all accounts,
+you may pass the keyword 'force'."""),),
+    # domainnote
+    'domainnote': (_(u"""With this subcommand, it is possible to attach a
+note to the specified domain. Without an argument, an existing note is
+removed."""),),
+    # aliasdomainadd
+    'aliasdomainadd': (_(u"""This subcommand adds the new alias domain
+(<fqdn>) to the destination <domain> that should be aliased."""),),
+    # aliasdomaindelete
+    'aliasdomaindelete': (_(u"""Use this subcommand if the alias domain
+<fqdn> should be removed."""),),
+    # aliasdomaininfo
+    'aliasdomaininfo': (_(u"""This subcommand shows to which domain the alias
+domain <fqdn> is assigned to."""),),
+    # aliasdomainswitch
+    'aliasdomainswitch': (_(u"""If the destination of the existing alias
+domain <fqdn> should be switched to another <destination> use this
+subcommand."""),),
+    # useradd
+    'useradd': (_(u"""Use this subcommand to create a new e-mail account for
+the given <address>."""),
+_(u"""If the <password> is not provided, vmm will prompt for it interactively.
+When no <password> is provided and account.random_password is set to true, vmm
+will generate a random password and print it to stdout after the account has
+been created."""),),
+    # userdelete
+    'userdelete': (_(u"""Use this subcommand to delete the account with the
+given <address>."""),
+_(u"""If there are one or more aliases with an identical destination address,
+vmm will abort the requested operation and show an error message. To prevent
+this, specify the optional keyword 'force'."""),),
+    # userinfo
+    'userinfo': (_(u"""This subcommand displays some information about the
+account specified by <address>."""),
+_(u"""If the optional argument <details> is given some more information will be
+displayed. Possible values for <details> are:"""),
+u"""    aliases, du. full""",),
+    # username
+    'username': (_(u"""The user's real <name> can be set/updated with this
+subcommand."""),
+_(u"""If no <name> is given, the value stored for the account is erased."""),
+),
+    # userpassword
+    'userpassword': (_(u"""The password of an account can be updated with this
+subcommand."""),
+_(u"""If no <password> was provided, vmm will prompt for it interactively."""),
+),
+    # usernote
+    'usernote': (_(u"""With this subcommand, it is possible to attach a note
+to the specified account. Without an argument, an existing note is
+removed."""),),
+    # userquota
+    'userquota': (_(u"""This subcommand is used to set a new quota limit for
+the given account."""),
+_(u"""When the argument <messages> was omitted the default number of messages
+0 (zero) will be applied."""),
+_(u"""Instead of <storage> pass the keyword 'domain' to remove the
+account-specific override, causing the domain's value to be in effect."""),),
+    # userservices
+    'userservices': (_(u"""To grant a user access to the specified services,
+use this command."""),
+_(u"""All omitted services will be deactivated/unusable for the user with the
+given <address>."""),
+_(u"""Instead of <service> pass 'domain' to remove the account-specific
+override, causing the domain's value to be in effect."""),),
+    # usertransport
+    'usertransport': (_(u"""A different <transport> for an account can be
+specified with this subcommand."""),
+_(u"""Instead of <transport> pass 'domain' to remove the account-specific
+override, causing the domain's value to be in effect."""),),
+    # aliasadd
+    'aliasadd': (_(u"""This subcommand is used to create a new alias
+<address> with one or more <destination> addresses."""),
+_(u"""Within the destination address, the placeholders '%n', '%d', and '%='
+will be replaced by the local part, the domain, or the email address with '@'
+replaced by '=' respectively. In combination with alias domains, this enables
+domain-specific destinations."""),),
+    # aliasinfo
+    'aliasinfo': (_(u"""Information about the alias with the given <address>
+can be displayed with this subcommand."""),),
+    # relocatedadd
+    'relocatedadd': (_(u"""A new relocated user can be created with this
+subcommand."""),
+_(u"""<address> is the user's ex-email address, for example
+b.user@example.com, and <newaddress> points to the new email address where
+the user can be reached."""),),
+    # relocatedinfo
+    'relocatedinfo': (_(u"""This subcommand shows the new address of the
+relocated user with the given <address>."""),),
+    # relocateddelete
+    'relocateddelete': (_(u"""Use this subcommand in order to delete the
+relocated user with the given <address>."""),),
+    # catchalladd
+    'catchalladd': (_(u"""This subcommand allows to specify destination
+addresses for a domain, which shall receive mail addressed to unknown
+local-parts within that domain. Those catch-all aliases hence "catch all" mail
+to any address in the domain (unless a more specific alias, mailbox or
+relocated entry exists)."""),
+_(u"""WARNING: Catch-all addresses can cause mail server flooding because
+spammers like to deliver mail to all possible combinations of names, e.g.
+to all addresses between abba@example.org and zztop@example.org."""),),
+    # catchallinfo
+    'catchallinfo': (_(u"""This subcommand displays information about catch-all
+aliases defined for the domain <fqdn>."""),),
+    # catchalldelete
+    'catchalldelete': (_(u"""With this subcommand, catch-all aliases defined
+for a domain can be removed, either all of them, or a single one if specified
+explicitly."""),),
+}
+
+del _
diff -r b994444f7dee -r ab97727357a4 VirtualMailManager/cli/subcommands.py
--- a/VirtualMailManager/cli/subcommands.py	Sun Sep 02 20:18:16 2012 +0000
+++ b/VirtualMailManager/cli/subcommands.py	Sun Sep 02 21:01:40 2012 +0000
@@ -16,6 +16,7 @@
 
 from VirtualMailManager import ENCODING
 from VirtualMailManager.cli import get_winsize, prog, w_err, w_std
+from VirtualMailManager.cli.clihelp import help_msgs
 from VirtualMailManager.common import human_size, size_in_bytes, \
      version_str, format_domain_default
 from VirtualMailManager.constants import __copyright__, __date__, \
@@ -48,6 +49,10 @@
 class Command(object):
     """Container class for command information."""
     __slots__ = ('name', 'alias', 'func', 'args', 'descr')
+    FMT_HLP_USAGE = """
+usage: %(prog)s %(name)s %(args)s
+       %(prog)s %(alias)s %(args)s
+"""
 
     def __init__(self, name, alias, func, args, descr):
         """Create a new Command instance.
@@ -76,6 +81,26 @@
         """the command's usage info."""
         return u'%s %s %s' % (prog, self.name, self.args)
 
+    def help_(self):
+        """Print the Command's help message to stdout."""
+        old_ii = txt_wrpr.initial_indent
+        old_si = txt_wrpr.subsequent_indent
+
+        txt_wrpr.subsequent_indent = (len(self.name) + 2) * ' '
+        w_std(txt_wrpr.fill('%s: %s' % (self.name, self.descr)))
+
+        info = Command.FMT_HLP_USAGE % dict(alias=self.alias, args=self.args,
+                                            name=self.name, prog=prog)
+        w_std(info)
+
+        txt_wrpr.initial_indent = txt_wrpr.subsequent_indent = ' '
+        try:
+            [w_std(txt_wrpr.fill(_(para)) + '\n') for para
+                    in help_msgs[self.name]]
+        except KeyError:
+            w_err(1, _(u"Subcommand '%s' is not yet documented." % self.name),
+                  'see also: vmm(1)')
+
 
 class RunContext(object):
     """Contains all information necessary to run a subcommand."""
@@ -445,8 +470,8 @@
             else:
                 usage(INVALID_ARGUMENT, _(u"Unknown help topic: '%s'") %
                       ctx.args[2], ctx.scmd)
-        # FIXME
-        w_err(1, "'help %s' not yet implemented." % topic, 'see also: vmm(1)')
+        if topic != u'help':
+            return cmd_map[topic].help_()
 
     old_ii = txt_wrpr.initial_indent
     old_si = txt_wrpr.subsequent_indent