Bug 738411 - doc: typo errors on virsh help snapshot-create-as
Summary: doc: typo errors on virsh help snapshot-create-as
Keywords:
Status: CLOSED ERRATA
Alias: None
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: libvirt
Version: 6.2
Hardware: Unspecified
OS: Linux
medium
medium
Target Milestone: rc
: ---
Assignee: Eric Blake
QA Contact: Virtualization Bugs
URL:
Whiteboard:
Depends On: 638510
Blocks: 740168 743047
TreeView+ depends on / blocked
 
Reported: 2011-09-14 18:06 UTC by Nan Zhang
Modified: 2011-12-06 11:29 UTC (History)
9 users (show)

Fixed In Version: libvirt-0.9.4-12.el6
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2011-12-06 11:29:22 UTC


Attachments (Terms of Use)


Links
System ID Priority Status Summary Last Updated
Red Hat Product Errata RHBA-2011:1513 normal SHIPPED_LIVE libvirt bug fix and enhancement update 2011-12-06 01:23:30 UTC

Description Nan Zhang 2011-09-14 18:06:41 UTC
Description of problem:
That's doc issue, snapshot-create-as should be followed by --diskspec to introduce the arguments, rather than follow <diskspec> directly.

Version-Release number of selected component (if applicable):
libvirt-0.9.4-11.el6.x86_64

How reproducible:
always

Steps to Reproduce:
# virsh help snapshot-create-as
  NAME
    snapshot-create-as - Create a snapshot from a set of args

  SYNOPSIS
    snapshot-create-as <domain> [<name>] [<description>] [--print-xml] [--no-metadata] [--halt] [--disk-only] [<diskspec>]...

  DESCRIPTION
    Create a snapshot (disk and RAM) from arguments

  OPTIONS
    [--domain] <string>  domain name, id or uuid
    [--name] <string>  name of snapshot
    [--description] <string>  description of snapshot
    --print-xml      print XML document rather than create
    --no-metadata    take snapshot but create no metadata
    --halt           halt domain after snapshot is created
    --disk-only      capture disk state but not vm state
    <diskspec>       disk attributes: disk[,snapshot=type][,driver=type][,file=name]
  
Actual results:
  SYNOPSIS
    snapshot-create-as <domain> [<name>] [<description>] [--print-xml] [--no-metadata] [--halt] [--disk-only] [<diskspec>]...

  OPTIONS
    <diskspec>       disk attributes: disk[,snapshot=type][,driver=type][,file=name]

Expected results:
  SYNOPSIS
    snapshot-create-as <domain> [<name>] [<description>] [--print-xml] [--no-metadata] [--halt] [--disk-only] [--diskspec]...

  OPTIONS
    --diskspec <string>       disk attributes: disk[,snapshot=type][,driver=type][,file=name]

Additional info:

Comment 2 Eric Blake 2011-09-14 18:24:06 UTC
(In reply to comment #0)
> Description of problem:
> That's doc issue, snapshot-create-as should be followed by --diskspec to
> introduce the arguments, rather than follow <diskspec> directly.

Not quite true.  The '--diskspec' option is mandatory if you do not have all three of domain, name, and description already provided, but if all three are present, then you can skip the option name for diskspec as well.

$ tools/virsh -c test:///default snapshot-create-as --print-xml test name desc vda
<domainsnapshot>
  <name>name</name>
  <description>desc</description>
  <disks>
    <disk name='vda'/>
  </disks>
</domainsnapshot>

> 
>   OPTIONS
>     [--domain] <string>  domain name, id or uuid
>     [--name] <string>  name of snapshot
>     [--description] <string>  description of snapshot
>     --print-xml      print XML document rather than create
>     --no-metadata    take snapshot but create no metadata
>     --halt           halt domain after snapshot is created
>     --disk-only      capture disk state but not vm state
>     <diskspec>       disk attributes:

However, I agree that this is a bit confusing, and might look better as [--diskspec] <diskspec> in the 'virsh help' output, and as '[[/--diskspec/] *diskspec*]...' (with // for italic and ** for bold) in the 'man virsh' section.

I'll reply more to your proposed upstream patch with my counter proposals:
https://www.redhat.com/archives/libvir-list/2011-September/msg00543.html

Comment 6 Vivian Bian 2011-09-21 10:06:14 UTC
tested with 
libvirt-0.9.4-12.el6.x86_64

Steps:
# virsh help snapshot-create-as
  SYNOPSIS
    snapshot-create-as <domain> [<name>] [<description>] [--print-xml]
[--no-metadata] [--halt] [--disk-only] [--diskspec]...

  OPTIONS
    --diskspec <string>       disk attributes:
disk[,snapshot=type][,driver=type][,file=name]

Get expected result, so set bug status to VERIFIED

Comment 7 Eric Blake 2011-09-21 14:49:18 UTC
however, this patch broke virsh qemu-monitor-command and virsh send-key; see bug 740168

Comment 8 errata-xmlrpc 2011-12-06 11:29:22 UTC
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2011-1513.html


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