Bug 1298836 - improve help output
Summary: improve help output
Keywords:
Status: CLOSED DEFERRED
Alias: None
Product: Virtualization Tools
Classification: Community
Component: libvirt
Version: unspecified
Hardware: Unspecified
OS: Unspecified
unspecified
unspecified
Target Milestone: ---
Assignee: Libvirt Maintainers
QA Contact:
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2016-01-15 08:56 UTC by PetaMem R&D
Modified: 2016-04-10 23:05 UTC (History)
2 users (show)

Fixed In Version:
Clone Of:
Environment:
Last Closed: 2016-04-10 23:05:30 UTC
Embargoed:


Attachments (Terms of Use)

Description PetaMem R&D 2016-01-15 08:56:35 UTC
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 23:05:30 UTC
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.