Bug 1298836

Summary: improve help output
Product: [Community] Virtualization Tools Reporter: PetaMem R&D <info>
Component: libvirtAssignee: Libvirt Maintainers <libvirt-maint>
Status: CLOSED DEFERRED QA Contact:
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: unspecifiedCC: crobinso, rbalakri
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2016-04-10 23:05:30 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

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