Bug 1298836 - improve help output
improve help output
Product: Virtualization Tools
Classification: Community
Component: libvirt (Show other bugs)
Unspecified Unspecified
unspecified Severity unspecified
: ---
: ---
Assigned To: Libvirt Maintainers
Depends On:
  Show dependency treegraph
Reported: 2016-01-15 03:56 EST by PetaMem R&D
Modified: 2016-04-10 19:05 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2016-04-10 19:05:30 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description PetaMem R&D 2016-01-15 03:56:35 EST
Description of problem:

"virsh help" has several issues.

1) it emits all of the help in detail, which is a) different behaviour than e.g. git or subversion does and b) results in spilling out lots of text which scrolls through any terminal size. Overview is lost and grep is your friend again...

We would suggest to output only the help sections

domain      <short description>
monitor     <short description>
host        <short description>
interface   <short description>

and only upon "virsh help domain" to emit the domain commands overview.

As the domain names are different from the command names anyway, e.g. "virsh help create" would still work as is.

2) The sorting is inconsistent

Alphabetical sorting is ok, but please make sure it stays that way.

There is no reason to have "emulatorpin" between "vcpupin" and "vncdisplay"

    vcpupin                        control or query domain vcpu affinity
    emulatorpin                    control or query domain emulator affinity
    vncdisplay                     vnc display

also, there is no reason to have "connect" after "quit"

    quit                           quit this interactive terminal
    connect                        (re)connect to hypervisor

Version-Release number of selected component (if applicable):

happens in

# virsh version
Compiled against library: libvirt 1.2.9
Using library: libvirt 1.2.9
Using API: QEMU 1.2.9
Running hypervisor: QEMU 2.1.2

as well as in

# virsh version
Compiled against library: libvirt 1.3.0
Using library: libvirt 1.3.0
Using API: QEMU 1.3.0
Running hypervisor: QEMU 2.5.0

How reproducible:

Steps to Reproduce:
1. virsh help
2. observe

Actual results:

too much text, inconsistent output

Expected results:

toplevel overview;
consistent output in detail overview

Additional info:
Comment 1 Cole Robinson 2016-04-10 19:05:30 EDT
I strongly like the way the help output dumps every command: I like to be able to do 'virsh help | grep part-of-the-command-name-that-i-remember' or similar. The proposed subsection bit is more code and requires multiple commands if a user just wants to browse the whole help output.

Regarding the sorting... it seems like within disparate categories some of the commands are grouped logically rather than strictly alphabetically. Like the two pin commands above. They should have probably been named pin-vcpu and pin-emulator for better alphabetic consistency. I agree it's confusing but I wouldn't be surprised if a patch to the list generates some bike shedding :)

I think for these issues it's better to just say 'please send a patch to libvir-list' than track them here. Closing as DEFERRED

Note You need to log in before you can comment on or make changes to this bug.