Created attachment 1367496 [details]
'vdo --help' in previous version

The display is the default behavior of the python argparse module following its 'command' structure paradigm where the high-level commands are only named when run as 'vdo --help'.

Help for individual commands is available via 'vdo <command> --help'.  This provides the same level of detail as previous vdo implementations but displays only those options and arguments applicable to the specified command; an improvement in not cluttering the help with non-applicable options.

If there is a particular format desired for the high-level 'vdo --help' please let us know.  We can certainly look into providing such.

Hi Joe,
I agree with just listing the commands with 'vdo --help' and providing help to individual commands on demand by 'vdo /command/ --help'. The issue here is with the listing itself, as it is quite hard to read. Much better approach is for example what lvm does. Plus it not only lists the commands but also ads short description to each of them:

$ lvm --help
  Available lvm commands:
  Use 'lvm help <command>' for more information

  config          Display and manipulate configuration information
  devtypes        Display recognised built-in block device types
  dumpconfig      Display and manipulate configuration information
  formats         List available metadata formats
  help            Display help for commands
  fullreport      Display full report
  lastlog         Display last command's log report
  lvchange        Change the attributes of logical volume(s)
  lvconvert       Change logical volume layout
  lvcreate        Create a logical volume
  lvdisplay       Display information about a logical volume
  lvextend        Add space to a logical volume
  lvmchange       With the device mapper, this is obsolete and does nothing.
  lvmconfig       Display and manipulate configuration information
  lvmdiskscan     List devices that may be used as physical volumes
  lvmsadc         Collect activity data
  lvmsar          Create activity report
  lvreduce        Reduce the size of a logical volume
  lvremove        Remove logical volume(s) from the system
  lvrename        Rename a logical volume
  lvresize        Resize a logical volume
  lvs             Display information about logical volumes
  lvscan          List all logical volumes in all volume groups
  pvchange        Change attributes of physical volume(s)
  pvresize        Resize physical volume(s)
  pvck            Check the consistency of physical volume(s)
  pvcreate        Initialize physical volume(s) for use by LVM
  pvdata          Display the on-disk metadata for physical volume(s)
  pvdisplay       Display various attributes of physical volume(s)
  pvmove          Move extents from one physical volume to another
  lvpoll          Continue already initiated poll operation on a logical volume
  pvremove        Remove LVM label(s) from physical volume(s)
  pvs             Display information about physical volumes
  pvscan          List all physical volumes
  segtypes        List available segment types
  systemid        Display the system ID, if any, currently set on this host
  tags            List tags defined on this host
  vgcfgbackup     Backup volume group configuration(s)
  vgcfgrestore    Restore volume group configuration
  vgchange        Change volume group attributes
  vgck            Check the consistency of volume group(s)
  vgconvert       Change volume group metadata format
  vgcreate        Create a volume group
  vgdisplay       Display volume group information
  vgexport        Unregister volume group(s) from the system
  vgextend        Add physical volumes to a volume group
  vgimport        Register exported volume group with system
  vgimportclone   Import a VG from cloned PVs
  vgmerge         Merge volume groups
  vgmknodes       Create the special files for volume group devices in /dev
  vgreduce        Remove physical volume(s) from a volume group
  vgremove        Remove volume group(s)
  vgrename        Rename a volume group
  vgs             Display information about volume groups
  vgscan          Search for all volume groups
  vgsplit         Move physical volumes into a new or existing volume group
  version         Display software and driver version information

Another example is libstoragemgmts cli 'lsmcli', attaching it as it is quite long. lsmcli has some common optional arguments and common command formatting so it is listing that too.
AFAIK vdo has some common options applicable to all vdo commands, so it might be a good idea to list that too at this point. 
Also the common formatting listed here makes it more clear that user should use style 'vdo /command/ /option(s)/' as this change was introduced very recently.

Created attachment 1367864 [details]
lsmcli --help

The first part of vdo --help messega as it is now appears when using wrong option:

# vdo create --name vdo --device /dev/sdd --wrongOption
usage: vdo [-h]

           {activate,changeWritePolicy,create,deactivate,disableCompression,disableDeduplication,enableCompression,enableDeduplication,growLogical,growPhysical,list,modify,printConfigFile,remove,start,status,stop}
           ...
vdo: error: unrecognized arguments: --wrongOption

With a bit of massaging I've gotten argparse to produce the output detailed below.
Please comment on any issues with this output.

As to the display of the usage for the particular command which detects an incorrect 
option (e.g., create --wrongOption), debugging argparse's behavior in the command subparser paradigm doesn't generate the error condition in the parser that detects the error (if it did, we'd be all set).  Rather, it returns an indication to its parent that it found incorrect option(s) and the parent generates the error condition.  Thus the command-specific state information is lost.  I have some ideas on how to get it to do what we want, but nothing definite yet.

-----------------------
> ./vdo --help
usage: vdo [-h] command ...

Manage kernel VDO devices and related configuration information. For help on
individual commands specify the command followed by --help.

optional arguments:
  -h, --help            show this help message and exit

management commands:
  command               description
    activate            Activates one or more VDO volumes. Activated volumes
                        can be started using the 'start' command. This command
                        must be run with root privileges.
    changeWritePolicy   Modifies the write policy of one or all running VDO
                        volumes. This command must be run with root
                        privileges.
    create              Creates a VDO volume and its associated index and
                        makes it available unless --activate=disabled is
                        specified. Will not overwrite an existing file system
                        or formatted VDO volume unless --force is given. This
                        command must be run with root privileges.
    deactivate          Deactivates one or more VDO volumes. Deactivated
                        volumes cannot be started by the 'start' command.
                        Deactivating a currently running volume does not stop
                        it, but once stopped it must be activated before it
                        can be started again. This command must be run with
                        root privileges.
    disableCompression  Disables compression on one or more VDO volumes. If
                        the VDO volume is running, takes effect immediately;
                        otherwise compression will be disabled the next time
                        the VDO volume is started. This command must be run
                        with root privileges.
    disableDeduplication
                        Disables deduplication on one more VDO volumes. If the
                        VDO volume is running, deduplication will be stopped
                        as well; otherwise, deduplication will be disabled the
                        next time the VDO volume is started. This command must
                        be run with root privileges.
    enableCompression   Enables compression on one or more VDO volumes. If the
                        VDO volume is running, takes effect immediately;
                        otherwise compression will be enabled the next time
                        the VDO volume is started. This command must be run
                        with root privileges.
    enableDeduplication
                        Enables deduplication on one or more VDO volumes. If
                        the VDO volume is running, deduplication will be
                        started as well; otherwise, deduplication will be
                        enabled the next time the VDO volume is started. This
                        command must be run with root privileges.
    growLogical         Grows the logical size of a VDO volume. The volume
                        must exist and must be running. This command must be
                        run with root privileges.
    growPhysical        Grows the physical size of a VDO volume. The volume
                        must exist and must be running. This command must be
                        run with root privileges.
    list                Displays a list of started VDO volumes. If --all is
                        specified it displays both started and non-started
                        volumes.
    modify              Modifies configuration parameters of one or all VDO
                        volumes. Changes take effect the next time the VDO
                        device is started; already-running devices are not
                        affected.
    printConfigFile     Prints the configuration file to stdout.
    remove              Removes one or more stopped VDO volumes and associated
                        indexes. This command must be run with root
                        privileges.
    start               Starts one or more stopped, activated VDO volumes and
                        associated services. This command must be run with
                        root privileges.
    status              Reports VDO system and volume status in YAML format.
                        Status information will be incomplete if the command
                        is not run with root privileges.
    stop                Stops one or more running VDO volumes and associated
                        services. This command must be run with root
                        privileges.

High-level help is now as below (less voluble than previously described):

-----------------------
> ./vdo --help
usage: vdo [-h] command ...

Manage kernel VDO devices and related configuration information. For help on
individual commands specify the command followed by --help. Unless otherwise
noted all commands must be run with root privileges.

optional arguments:
  -h, --help            show this help message and exit

management commands:
  command               description
    activate            Activates one or more VDO volumes. Activated volumes
                        can be started using the 'start' command.
    changeWritePolicy   Modifies the write policy of one or all running VDO
                        volumes.
    create              Creates a VDO volume and its associated index and
                        makes it available.
    deactivate          Deactivates one or more VDO volumes. Deactivated
                        volumes cannot be started by the 'start' command.
                        Deactivating a currently running volume does not stop
                        it.
    disableCompression  Disables compression on one or more VDO volumes. If
                        the VDO volume is running, takes effect immediately.
    disableDeduplication
                        Disables deduplication on one more VDO volumes. If the
                        VDO volume is running, takes effect immediately.
    enableCompression   Enables compression on one or more VDO volumes. If the
                        VDO volume is running, takes effect immediately.
    enableDeduplication
                        Enables deduplication on one or more VDO volumes. If
                        the VDO volume is running, takes effect immediately.
    growLogical         Grows the logical size of a VDO volume. The volume
                        must exist and must be running.
    growPhysical        Grows the physical size of a VDO volume. The volume
                        must exist and must be running.
    list                Displays a list of started VDO volumes. If --all is
                        specified it displays both started and non-started
                        volumes.
    modify              Modifies configuration parameters of one or all VDO
                        volumes. Changes take effect the next time the VDO
                        device is started; already-running devices are not
                        affected.
    printConfigFile     Prints the configuration file to stdout. This command
                        does not require root privileges.
    remove              Removes one or more stopped VDO volumes and associated
                        indexes.
    start               Starts one or more stopped, activated VDO volumes and
                        associated services.
    status              Reports VDO system and volume status in YAML format.
                        This command does not require root privileges though
                        information will be incomplete if run without.
    stop                Stops one or more running VDO volumes and associated
                        services.

Error reporting of unrecognized arguments is now command-specific.  As an example...

-----------------------
> ./vdo activate --all --unknown
usage: vdo activate [-h] (-a | -n <volume>) [-f <file>] [--logfile <pathname>]
                    [--verbose]
vdo activate: error: unrecognized arguments: --unknown

Great job!

# vdo --help
usage: vdo [-h] command ...

Manage kernel VDO devices and related configuration information. For help on
individual commands specify the command followed by --help. Unless otherwise
noted all commands must be run with root privileges.

optional arguments:
  -h, --help            show this help message and exit

management commands:
  command               description
    activate            Activates one or more VDO volumes. Activated volumes
                        can be started using the 'start' command.
    changeWritePolicy   Modifies the write policy of one or all running VDO
                        volumes.
    create              Creates a VDO volume and its associated index and
                        makes it available.
    deactivate          Deactivates one or more VDO volumes. Deactivated
                        volumes cannot be started by the 'start' command.
                        Deactivating a currently running volume does not stop
                        it.
    disableCompression  Disables compression on one or more VDO volumes. If
                        the VDO volume is running, takes effect immediately.
    disableDeduplication
                        Disables deduplication on one more VDO volumes. If the
                        VDO volume is running, takes effect immediately.
    enableCompression   Enables compression on one or more VDO volumes. If the
                        VDO volume is running, takes effect immediately.
    enableDeduplication
                        Enables deduplication on one or more VDO volumes. If
                        the VDO volume is running, takes effect immediately.
    growLogical         Grows the logical size of a VDO volume. The volume
                        must exist and must be running.
    growPhysical        Grows the physical size of a VDO volume. The volume
                        must exist and must be running.
    list                Displays a list of started VDO volumes. If --all is
                        specified it displays both started and non-started
                        volumes.
    modify              Modifies configuration parameters of one or all VDO
                        volumes. Changes take effect the next time the VDO
                        device is started; already-running devices are not
                        affected.
    printConfigFile     Prints the configuration file to stdout. This command
                        does not require root privileges.
    remove              Removes one or more stopped VDO volumes and associated
                        indexes.
    start               Starts one or more stopped, activated VDO volumes and
                        associated services.
    status              Reports VDO system and volume status in YAML format.
                        This command does not require root privileges though
                        information will be incomplete if run without.
    stop                Stops one or more running VDO volumes and associated
                        services.

# vdo unknown --help
usage: vdo [-h] command ...
vdo: error: argument command: invalid choice: 'unknown' (choose from 'activate', 'changeWritePolicy', 'create', 'deactivate', 'disableCompression', 'disableDeduplication', 'enableCompression', 'enableDeduplication', 'growLogical', 'growPhysical', 'list', 'modify', 'printConfigFile', 'remove', 'start', 'status', 'stop')

# vdo create --name vdo --device /dev/sde --unknown
usage: vdo create [-h] -n <volume> --device <devicepath>
                  [--activate {disabled,enabled}]
                  [--blockMapCacheSize <megabytes>]
                  [--blockMapPeriod <period>]
                  [--compression {disabled,enabled}]
                  [--deduplication {disabled,enabled}]
                  [--emulate512 {disabled,enabled}] [--force]
                  [--indexMem <gigabytes>] [--readCache {disabled,enabled}]
                  [--readCacheSize <megabytes>]
                  [--sparseIndex {disabled,enabled}]
                  [--vdoAckThreads <threadCount>]
                  [--vdoBioRotationInterval <ioCount>]
                  [--vdoBioThreads <threadCount>]
                  [--vdoCpuThreads <threadCount>]
                  [--vdoHashZoneThreads <threadCount>]
                  [--vdoLogicalSize <megabytes>]
                  [--vdoLogicalThreads <threadCount>]
                  [--vdoLogLevel {critical,error,warning,notice,info,debug}]
                  [--vdoPhysicalThreads <threadCount>]
                  [--vdoSlabSize <megabytes>] [--writePolicy {async,sync}]
                  [-f <file>] [--logfile <pathname>] [--verbose]
vdo create: error: unrecognized arguments: --unknown

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHEA-2018:0871