Bug 713922

Summary: virsh man page refers to unspecified "documentation"
Product: Red Hat Enterprise Linux 6 Reporter: Dave Allan <dallan>
Component: libvirtAssignee: Dave Allan <dallan>
Status: CLOSED ERRATA QA Contact: Virtualization Bugs <virt-bugs>
Severity: medium Docs Contact:
Priority: low    
Version: 6.2CC: dyuan, mzhan, pschiffe, rwu, yupzhang
Target Milestone: rcKeywords: ManPageChange
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: libvirt-0.9.13-3.el6 Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-02-21 02:06:38 EST Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---
Bug Depends On:    
Bug Blocks: 747667, 756082    

Description Dave Allan 2011-06-16 15:11:45 EDT
In many places the virsh man page refers the user to "the documentation" but does not provide any guidance as to where that documentation might be found, which is especially puzzling since the man page is itself documentation.  For example:

"See the documentation to learn about libvirt XML format for a device."

In other places, the man page refers the user to a specific webpage:

"To better understand the values allowed as options for the command reading the documentation at <http://libvirt.org/formatdomain.html> on the format of the device sections to get the most accurate set of accepted values."

The man page should specify the webpage in each instance.
Comment 5 Dave Allan 2012-02-27 17:58:56 EST
Sent patch upstream.
Comment 6 Dave Allan 2012-03-21 22:16:00 EDT
Sent v2 upstream:

http://www.redhat.com/archives/libvir-list/2012-March/msg00907.html
Comment 9 Dave Allan 2012-05-10 12:34:34 EDT
Upstream commit:

commit ceb1d36b94be1de7264f86d1490450237238dc30
Author: Dave Allan <dallan@redhat.com>
Date:   Wed Mar 21 22:07:51 2012 -0400

    Clarify what documentation is being referenced
    
    virsh.pod had several instances in which it referred to "the
    documentation" which was a little puzzling to me since it is
    documentation.  Reading the document from end to end makes it clear
    that it means a specific URI which was noted previously in the text,
    but I had never noticed those URIs in several years of referring to
    the man page.  This patch adds those URIs to several additional places
    in the text.
Comment 13 yuping zhang 2012-07-24 07:27:41 EDT
Verified this issue with libvirt-0.9.13-3.el6.x86_64.

#man virsh
-d, --debug LEVEL
           Enable debug messages at integer LEVEL and above.  LEVEL can range from 0 to 4 (default).  See the documentation of VIRSH_DEBUG environment variable below for the description of each LEVEL. #########updated to "below"

connect URI [--readonly]
	...
	For remote access see the documentation page at <http://libvirt.org/uri.html> on how to make URIs.  The --readonly option allows for read-only connection   ##########link was added

attach-device domain-id FILE [--config]
           Attach a device to the domain, using a device definition in an XML file using a device definition element such as <disk> or <interface> as the top-level element.  See the documentation at <http://libvirt.org/formatdomain.html#elementsDevices> to learn about libvirt XML format for a device. ###############link was added

update-device domain-id file [--config] [--force]
           Update the characteristics of a device associated with domain-id, based on the device definition in an XML file.  If the --config option is used, the changes will take affect the next time libvirt starts the domain.  For compatibility purposes, --persistent is alias of --config.  The --force option can be used to force device update, e.g., to eject a CD-ROM even if it is locked/mounted in the domain. See the documentation at <http://libvirt.org/formatdomain.html#elementsDevices> to learn about libvirt XML format for a device.              ##################link was added

 net-create file
           Create a virtual network from an XML file, see the documentation at
 <http://libvirt.org/formatnetwork.html> to get a description of the XML network format used by libvirt. ##############link was added.

So change the bug status to VERIFEID.
Comment 14 errata-xmlrpc 2013-02-21 02:06:38 EST
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/RHSA-2013-0276.html