[libvirt] Fixing the output of "virsh help"

[Justin Clift]

Hi all,

The output of virsh --help has become pretty unwieldy for people,
so I'd like to adjust it to display things in a fashion that's
easier to locate things in.

Below is my first mock up of what the new output should look like,
with it broken into functional categories.

Does this seem like the best approach?  Open to completely
different ideas, different layout approaches, etc. :)

Notes:

 + In a final (working) solution, each of the commands would be
   alphabetically sorted in its category.  Only roughly manually
   sorted them below, to show the general effect.

 + Some of the lines below looked like they might wrap in email,
   so I manually cut them off with "...".  Not thinking of doing
   that in a coded up version.  We'd just let them wrap. ;)

 + Pretty sure we'd need to adjust the test suite components that
   leverage from virsh --help, but I don't think it can be avoided.

**********************************************************************

virsh # help
Commands:

    CPU Management
    **************
    cpu-baseline    compute baseline CPU
    cpu-compare     compare host CPU with a CPU described by an ...
    maxvcpus        connection vcpu maximum
    setvcpus        change number of virtual CPUs
    vcpucount       domain vcpu counts
    vcpuinfo        detailed domain vcpu information
    vcpupin         control domain vcpu affinity

    Device Management
    *****************
    attach-device   attach device from an XML file
    attach-disk     attach disk device
    detach-device   detach device from an XML file
    detach-disk     detach disk device
    update-device   update device from an XML file

    Domain Management
    *****************
    autostart       autostart a domain
    create          create a domain from an XML file
    destroy         destroy a domain
    define          define (but don't start) a domain from an XML...
    domid           convert a domain name or UUID to domain id
    domuuid         convert a domain name or id to domain UUID
    dominfo         domain information
    domjobinfo      domain job information
    domjobabort     abort active domain job
    domname         convert a domain id or UUID to domain name
    domstate        domain state
    domblkstat      get device block stats for a domain
    domifstat       get network interface stats for a domain
    dommemstat      get memory statistics for a domain
    domblkinfo      domain block device size information
    domxml-from-native Convert native config to domain XML
    domxml-to-native Convert domain XML to native config
    dump            dump the core of a domain to a file for anal...
    dumpxml         domain information in XML
    edit            edit XML configuration for a domain
    list            list domains
    managedsave     managed save of a domain state
    managedsave-remove Remove managed save of a domain
    memtune         Get/Set memory paramters
    migrate         migrate domain to another host
    migrate-setmaxdowntime set maximum tolerable downtime
    reboot          reboot a domain
    restore         restore a domain from a saved state in a file
    resume          resume a domain
    save            save a domain state to a file
    setmem          change memory allocation
    setmaxmem       change maximum memory limit
    shutdown        gracefully shutdown a domain
    start           start a (previously defined) inactive domain
    suspend         suspend a domain
    undefine        undefine an inactive domain

    Management of Secrets
    *********************
    secret-define   define or modify a secret from an XML file
    secret-dumpxml  secret attributes in XML
    secret-set-value set a secret value
    secret-get-value Output a secret value
    secret-undefine undefine a secret
    secret-list     list secrets

    Networking
    **********
    net-autostart   autostart a network
    net-create      create a network from an XML file
    net-define      define (but don't start) a network from...
    net-destroy     destroy a network
    net-dumpxml     network information in XML
    net-edit        edit XML configuration for a network
    net-list        list networks
    net-name        convert a network UUID to network name
    net-start       start a (previously defined) inactive network
    net-undefine    undefine an inactive network
    net-uuid        convert a network name to network UUID

    Network Interfaces
    ******************
    attach-interface attach network interface
    detach-interface detach network interface
    iface-list      list physical host interfaces
    iface-name      convert an interface MAC address to inte...
    iface-mac       convert an interface name to interface M...
    iface-dumpxml   interface information in XML
    iface-define    define (but don't start) a physical host...
    iface-undefine  undefine a physical host interface (remo...
    iface-edit      edit XML configuration for a physical ho...
    iface-start     start a physical host interface (enable ...
    iface-destroy   destroy a physical host interface (disab...

    Nodes
    *****
    nodeinfo        node information
    nodedev-list    enumerate devices on this host
    nodedev-dumpxml node device details in XML
    nodedev-dettach dettach node device from its device driver
    nodedev-reattach reattach node device to its device driver
    nodedev-reset   reset node device
    nodedev-create  create a device defined by an XML file o...
    nodedev-destroy destroy a device on the node

    NWfilter
    ********
    nwfilter-define define or update a network filter from a...
    nwfilter-undefine undefine a network filter
    nwfilter-dumpxml network filter information in XML
    nwfilter-list   list network filters
    nwfilter-edit   edit XML configuration for a network filter

    Snapshots
    *********
    snapshot-create Create a snapshot
    snapshot-current Get the current snapshot
    snapshot-delete Delete a domain snapshot
    snapshot-dumpxml Dump XML for a domain snapshot
    snapshot-list   List snapshots for a domain
    snapshot-revert Revert a domain to a snapshot

    Storage Pools
    *************
    find-storage-pool-sources discover potential storage poo...
    find-storage-pool-sources-as find potential storage pool...
    pool-autostart  autostart a pool
    pool-build      build a pool
    pool-create     create a pool from an XML file
    pool-create-as  create a pool from a set of args
    pool-define     define (but don't start) a pool from an ...
    pool-define-as  define a pool from a set of args
    pool-destroy    destroy a pool
    pool-delete     delete a pool
    pool-dumpxml    pool information in XML
    pool-edit       edit XML configuration for a storage pool
    pool-info       storage pool information
    pool-list       list pools
    pool-name       convert a pool UUID to pool name
    pool-refresh    refresh a pool
    pool-start      start a (previously defined) inactive pool
    pool-undefine   undefine an inactive pool
    pool-uuid       convert a pool name to pool UUID

    Storage Volumes
    ***************
    vol-create      create a vol from an XML file
    vol-create-from create a vol, using another volume as input
    vol-create-as   create a volume from a set of args
    vol-clone       clone a volume.
    vol-delete      delete a vol
    vol-wipe        wipe a vol
    vol-dumpxml     vol information in XML
    vol-info        storage vol information
    vol-list        list vols
    vol-pool        returns the storage pool for a given ...
    vol-path        returns the volume path for a given ...
    vol-name        returns the volume name for a given ...
    vol-key         returns the volume key for a given ...

    Virsh itself
    **************
    cd              change the current directory
    connect         (re)connect to hypervisor
    console         connect to the guest console
    echo            echo arguments
    exit            quit this interactive terminal
    help            print help
    pwd             print the current directory
    quit            quit this interactive terminal
    uri             print the hypervisor canonical URI
    version         show version
    vncdisplay      vnc display

    Not sure (need suggestions) :>
    ******************************
    capabilities    capabilities
    freecell        NUMA free memory
    hostname        print the hypervisor hostname
    schedinfo       show/set scheduler parameters
    ttyconsole      tty console

virsh #

**********************************************************************