[libvirt] [PATCH] man pages: update the description for the virsh help command
Now includes information on keyword usage, and provides examples. --- tools/virsh.pod | 37 ++++++++++++++++++++++++++++++++++--- 1 files changed, 34 insertions(+), 3 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index c97786a..66654a7 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -115,10 +115,41 @@ The following commands are generic i.e. not specific to a domain. =over 4 -=item B<help> optional I<command> +=item B<help> optional I<--command> I<command> | I<group-keyword> -This prints a small synopsis about all commands available for B<virsh> -B<help> I<command> will print out a detailed help message on that command. +This lists each of the virsh commands. When used without options, all +commands are listed, one per line, grouped into related categories, +displaying the keyword for each group. + +To display only commands for a specific group, give the keyword for that +group as an option. For example: + + virsh # help host + + Host and Hypervisor (help keyword 'host'): + capabilities capabilities + connect (re)connect to hypervisor + freecell NUMA free memory + hostname print the hypervisor hostname + qemu-monitor-command Qemu Monitor Command + uri print the hypervisor canonical URI + +To display detailed information for a specific command, give its name as the +option instead. For example: + + virsh # help list + NAME + list - list domains + + SYNOPSIS + list [--inactive] [--all] + + DESCRIPTION + Returns list of domains. + + OPTIONS + --inactive list inactive domains + --all list inactive & active domains =item B<quit>, B<exit> -- 1.7.3.2
On 12/02/2010 06:04 AM, Justin Clift wrote:
Now includes information on keyword usage, and provides examples. --- tools/virsh.pod | 37 ++++++++++++++++++++++++++++++++++--- 1 files changed, 34 insertions(+), 3 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index c97786a..66654a7 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -115,10 +115,41 @@ The following commands are generic i.e. not specific to a domain.
=over 4
-=item B<help> optional I<command> +=item B<help> optional I<--command> I<command> | I<group-keyword>
Hmm, this doesn't quite match 'virsh help help', which if used literally would translate to: =item B<help> optional I<command> I<group> On the other hand, I'm thinking we implemented the help command slightly wrong by specifying that it takes two optional strings. Really, it only takes one optional string, which is a command-or-group. For instance, with the current code, 'virsh help --group help' lists a command help, rather than a group help, and 'virsh help --command virsh' lists the group help, rather than a command help. Meanwhile, 'virsh help help virsh' is accepted by the parser, but silently ignores the virsh group argument. So I'm thinking we need yet another patch to virsh.c that reduces opts_help to just one VSH_OT_DATA flag name (whether we keep it named --command, or rename it to --command-or-group, is another question, which is also impacted by whether we decide to implement unambiguous prefix parsing like getopt_long). In the meantime, how about we list this line as: =item B<help> optional I<command-or-group> ACK with that one-line change; the rest of the patch is uncontroversial, and the virsh.c cleanup can be a separate patch. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 03/12/2010, at 4:47 AM, Eric Blake wrote:
On the other hand, I'm thinking we implemented the help command slightly wrong by specifying that it takes two optional strings. Really, it only takes one optional string, which is a command-or-group. For instance, with the current code, 'virsh help --group help' lists a command help, rather than a group help, and 'virsh help --command virsh' lists the group help, rather than a command help. Meanwhile, 'virsh help help virsh' is accepted by the parser, but silently ignores the virsh group argument.
Yeah, the current approach is a bit wrong. It can take either the string "--command" or "--group", both of which do exactly the same thing rather than making a distinction.
So I'm thinking we need yet another patch to virsh.c that reduces opts_help to just one VSH_OT_DATA flag name (whether we keep it named --command, or rename it to --command-or-group, is another question, which is also impacted by whether we decide to implement unambiguous prefix parsing like getopt_long).
Good point. With the naming of the new option, I'm not sure how much stock we should put in maintaining backwards compatibility in this instance. With a new patch we could probably drop the "--group" keyword, plus make the "--command" keyword a null operation (ie ignore it). Then, if a command or group has been given on the line, display that as is presently being done.
In the meantime, how about we list this line as:
=item B<help> optional I<command-or-group>
ACK with that one-line change; the rest of the patch is uncontroversial, and the virsh.c cleanup can be a separate patch.
That's better wording, thanks Eric. I'll make that tweak and push it.
于 2010年12月03日 14:50, Justin Clift 写道:
On 03/12/2010, at 4:47 AM, Eric Blake wrote:
On the other hand, I'm thinking we implemented the help command slightly wrong by specifying that it takes two optional strings. Really, it only takes one optional string, which is a command-or-group. For instance, with the current code, 'virsh help --group help' lists a command help, rather than a group help, and 'virsh help --command virsh' lists the group help, rather than a command help. Meanwhile, 'virsh help help virsh' is accepted by the parser, but silently ignores the virsh group argument.
Yeah, the current approach is a bit wrong. It can take either the string "--command" or "--group", both of which do exactly the same thing rather than making a distinction.
So I'm thinking we need yet another patch to virsh.c that reduces opts_help to just one VSH_OT_DATA flag name (whether we keep it named --command, or rename it to --command-or-group, is another question, which is also impacted by whether we decide to implement unambiguous prefix parsing like getopt_long).
Good point. With the naming of the new option, I'm not sure how much stock we should put in maintaining backwards compatibility in this instance.
With a new patch we could probably drop the "--group" keyword, plus make the "--command" keyword a null operation (ie ignore it). Then, if a command or group has been given on the line, display that as is presently being done.
In the meantime, how about we list this line as:
=item B<help> optional I<command-or-group>
ACK with that one-line change; the rest of the patch is uncontroversial, and the virsh.c cleanup can be a separate patch.
That's better wording, thanks Eric. I'll make that tweak and push it.
great, I just sent patches with consistent changes. - Osier
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
于 2010年12月03日 01:47, Eric Blake 写道:
On 12/02/2010 06:04 AM, Justin Clift wrote:
Now includes information on keyword usage, and provides examples. --- tools/virsh.pod | 37 ++++++++++++++++++++++++++++++++++--- 1 files changed, 34 insertions(+), 3 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index c97786a..66654a7 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -115,10 +115,41 @@ The following commands are generic i.e. not specific to a domain.
=over 4
-=item B<help> optional I<command> +=item B<help> optional I<--command> I<command> | I<group-keyword>
Hmm, this doesn't quite match 'virsh help help', which if used literally would translate to:
=item B<help> optional I<command> I<group>
On the other hand, I'm thinking we implemented the help command slightly wrong by specifying that it takes two optional strings. Really, it only takes one optional string, which is a command-or-group. For instance, with the current code, 'virsh help --group help' lists a command help, rather than a group help, and 'virsh help --command virsh' lists the group help, rather than a command help. Meanwhile, 'virsh help help virsh' is accepted by the parser, but silently ignores the virsh group argument.
So I'm thinking we need yet another patch to virsh.c that reduces opts_help to just one VSH_OT_DATA flag name (whether we keep it named --command, or rename it to --command-or-group, is another question, which is also impacted by whether we decide to implement unambiguous prefix parsing like getopt_long). In the meantime, how about we list this line as:
=item B<help> optional I<command-or-group>
ACK with that one-line change; the rest of the patch is uncontroversial, and the virsh.c cleanup can be a separate patch.
I thought "<command-or-group>" is too long before, so didn't use it, now I change the mind, as think user nearly won't use it, they could directly get the help by "# virsh help $word", where it's long or short doesn't matter much then. so I will make patch to use <command-or-group> Thanks - Osier
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
participants (3)
-
Eric Blake -
Justin Clift -
Osier Yang