| Summary: | Should correct some info in virt-v2v manual and help | ||
|---|---|---|---|
| Product: | Red Hat Enterprise Linux 7 | Reporter: | mxie <mxie> |
| Component: | libguestfs | Assignee: | Richard W.M. Jones <rjones> |
| Status: | CLOSED NOTABUG | QA Contact: | Virtualization Bugs <virt-bugs> |
| Severity: | low | Docs Contact: | |
| Priority: | low | ||
| Version: | 7.3 | CC: | juzhou, keanli, mzhan, ptoscano, tzheng, xiaodwan |
| Target Milestone: | rc | ||
| Target Release: | --- | ||
| Hardware: | x86_64 | ||
| OS: | Unspecified | ||
| Whiteboard: | V2V | ||
| Fixed In Version: | Doc Type: | Bug Fix | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2016-04-21 09:27:38 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: | |
(In reply to mxie from comment #0) > Scenario1: > 1.Check virt-v2v help about --long-options and --short-options > > --long-options List long options > --short-options List short options > > 2.Check --long-options and --short-options in virt-v2v manual page, but > there is no info about them Every libguestfs tool has these options: they are internal, used mostly for bash completion. There is no way to hide them from --help of OCaml-based programs, such as virt-v2v, so most probably we can just append "(internal)". > Scenario2: > 1.Check virt-v2v manual page about --compressed option > --compressed > Write a compressed output file. This is only allowed if the output > format is qcow2 (see -of > below), and is equivalent to the -c option of qemu-img(1). > > 2.Check virt-v2v help about --compressed option > --compressed Compress output file > > Result now: > the reference info about --compressed option in virt-v2v help is not > clearly pointed out the option is only allowed when the output format is > qcow2 There is limited space in the output of --help, that's why all the options have much longer documentation in the man page. > Scenario3: > Some minor issue as below: > 1. -help option only shows in virt-v2v help, but not shows in manual page -help is added automatically by OCaml -- I will add them in the man pages. > 4.I think should adjust format about --verbose/-v and --version/-V from > part1 to part2 which will be more clearer in virt-v2v help > > Part1 {-V Display version and exit > -v Enable libguestfs > debugging messages > --vdsm-image-uuid uuid Output image UUID(s) > --vdsm-ovf-output Output OVF file > --vdsm-vm-uuid uuid Output VM UUID > --vdsm-vol-uuid uuid Output vol UUID(s) > --verbose Enable libguestfs > debugging messages > --version Display version and exit > } > > > > Part2 { > --vdsm-image-uuid uuid Output image UUID(s) > --vdsm-ovf-output Output OVF file > --vdsm-vm-uuid uuid Output VM UUID > --vdsm-vol-uuid uuid Output vol UUID(s) > -V Display version and exit > --version -"- > -v Enable libguestfs > debugging messages > --verbose -"- > > } The --help listing of options in OCaml-based programs (such as virt-v2v) now sorts the options automatically, which is much better than the manual ordering as done before. (In reply to mxie from comment #0) > Description of problem: > Should correct some info in virt-v2v manual and help > > Version-Release number of selected component (if applicable): > virt-v2v-1.32.4-1.el7.x86_64 > libguestfs-1.32.4-1.el7.x86_64 > > > How reproducible: > 100% > > Steps to Reproduce: > > Scenario1: > 1.Check virt-v2v help about --long-options and --short-options > > --long-options List long options > --short-options List short options > > 2.Check --long-options and --short-options in virt-v2v manual page, but > there is no info about them These are internal options that we don't document in the main page. They are used for bash tab completion. They have to appear in the --help output because that is automatically generated & we don't control it. > Scenario2: > 1.Check virt-v2v manual page about --compressed option > --compressed > Write a compressed output file. This is only allowed if the output > format is qcow2 (see -of > below), and is equivalent to the -c option of qemu-img(1). > > 2.Check virt-v2v help about --compressed option > --compressed Compress output file > > Result now: > the reference info about --compressed option in virt-v2v help is not > clearly pointed out the option is only allowed when the output format is > qcow2 The --help output is intentionally brief. It does say "A short summary of the options is given below. For detailed help please read the man page virt-v2v(1)." so I don't consider this is a bug. > Scenario3: > Some minor issue as below: > 1. -help option only shows in virt-v2v help, but not shows in manual page The -help option (added automatically by the OCaml Arg module) is intentionally undocumented. This is because we intend in future to switch to using GNU getopt for option parsing, and getopt won't understand the -help option as it will consider it to be equivalent to -h -e -l -p. > 2. --debug-overlay only shows in virt-v2v help, but not shows in manual page This is a debug option used for testing, so we don't document it in the main manual. > 3. I think there is a little repetitive info about -b/--bridge option in v2v > manual page, so the part1 could be removed > > part1 { -b ... > --bridge ... > See --network below. > } > > part2 { -b in:out > -b out > --bridge in:out > --bridge out > Map network (or bridge) called "in" to network (or bridge) > called "out". If no "in:" prefix is > given, all other networks (or bridges) are mapped to "out". > > See "NETWORKS AND BRIDGES" below. > } I don't think this is a problem. > 4.I think should adjust format about --verbose/-v and --version/-V from > part1 to part2 which will be more clearer in virt-v2v help > > Part1 {-V Display version and exit > -v Enable libguestfs > debugging messages > --vdsm-image-uuid uuid Output image UUID(s) > --vdsm-ovf-output Output OVF file > --vdsm-vm-uuid uuid Output VM UUID > --vdsm-vol-uuid uuid Output vol UUID(s) > --verbose Enable libguestfs > debugging messages > --version Display version and exit > } > > > > Part2 { > --vdsm-image-uuid uuid Output image UUID(s) > --vdsm-ovf-output Output OVF file > --vdsm-vm-uuid uuid Output VM UUID > --vdsm-vol-uuid uuid Output vol UUID(s) > -V Display version and exit > --version -"- > -v Enable libguestfs > debugging messages > --verbose -"- > > } The --help output ordering is determined using the 'sort' function, so we can't individually control the order in which options appear. I'm afraid I don't regard any of these as bugs or as things we can fix. |
Description of problem: Should correct some info in virt-v2v manual and help Version-Release number of selected component (if applicable): virt-v2v-1.32.4-1.el7.x86_64 libguestfs-1.32.4-1.el7.x86_64 How reproducible: 100% Steps to Reproduce: Scenario1: 1.Check virt-v2v help about --long-options and --short-options --long-options List long options --short-options List short options 2.Check --long-options and --short-options in virt-v2v manual page, but there is no info about them Scenario2: 1.Check virt-v2v manual page about --compressed option --compressed Write a compressed output file. This is only allowed if the output format is qcow2 (see -of below), and is equivalent to the -c option of qemu-img(1). 2.Check virt-v2v help about --compressed option --compressed Compress output file Result now: the reference info about --compressed option in virt-v2v help is not clearly pointed out the option is only allowed when the output format is qcow2 Scenario3: Some minor issue as below: 1. -help option only shows in virt-v2v help, but not shows in manual page 2. --debug-overlay only shows in virt-v2v help, but not shows in manual page 3. I think there is a little repetitive info about -b/--bridge option in v2v manual page, so the part1 could be removed part1 { -b ... --bridge ... See --network below. } part2 { -b in:out -b out --bridge in:out --bridge out Map network (or bridge) called "in" to network (or bridge) called "out". If no "in:" prefix is given, all other networks (or bridges) are mapped to "out". See "NETWORKS AND BRIDGES" below. } 4.I think should adjust format about --verbose/-v and --version/-V from part1 to part2 which will be more clearer in virt-v2v help Part1 {-V Display version and exit -v Enable libguestfs debugging messages --vdsm-image-uuid uuid Output image UUID(s) --vdsm-ovf-output Output OVF file --vdsm-vm-uuid uuid Output VM UUID --vdsm-vol-uuid uuid Output vol UUID(s) --verbose Enable libguestfs debugging messages --version Display version and exit } Part2 { --vdsm-image-uuid uuid Output image UUID(s) --vdsm-ovf-output Output OVF file --vdsm-vm-uuid uuid Output VM UUID --vdsm-vol-uuid uuid Output vol UUID(s) -V Display version and exit --version -"- -v Enable libguestfs debugging messages --verbose -"- } Actual results: As above description Expected results: Should correct some info in virt-v2v manual and help