[libvirt] [PATCH 1/1] 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 URI in several years of referring to the man page. This patch adds those URIs to several additional places in the text. --- tools/virsh.pod | 38 ++++++++++++++++++++++---------------- 1 files changed, 22 insertions(+), 16 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index cb0d9b9..6040d40 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -73,7 +73,7 @@ instead of the default connection. Enable debug messages at integer I<LEVEL> and above. I<LEVEL> can range from 0 to 4 (default). See the documentation of B<VIRSH_DEBUG> -environment variable for the description of each I<LEVEL>. +environment variable below for the description of each I<LEVEL>. =item B<-l>, B<--log> I<FILE> @@ -224,7 +224,8 @@ connect to a local linux container =back -For remote access see the documentation page on how to make URIs. +For remote access see the documentation page at +L<http://libvirt.org/uri.html> list on how to make URIs. The I<--readonly> option allows for read-only connection =item B<uri> @@ -1433,12 +1434,14 @@ format of the device sections to get the most accurate set of accepted values. =item B<attach-device> I<domain-id> I<FILE> -Attach a device to the domain, using a device definition in an XML file. -See the documentation to learn about libvirt XML format for a device. -For cdrom and floppy devices, this command only replaces the media within -the single existing device; consider using B<update-device> for this usage. -For passthrough host devices, see also B<nodedev-dettach>, needed if -the device does not use managed mode. +Attach a device to the domain, using a device definition in an XML +file. See the documentation at +L<http://libvirt.org/formatdomain.html> to learn about libvirt XML +format for a device. For cdrom and floppy devices, this command only +replaces the media within the single existing device; consider using +B<update-device> for this usage. For passthrough host devices, see +also B<nodedev-dettach>, needed if the device does not use managed +mode. =item B<attach-disk> I<domain-id> I<source> I<target> [I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>] @@ -1508,12 +1511,14 @@ if more than one are present on the domain. =item B<update-device> I<domain-id> I<file> [I<--persistent>] [I<--force>] -Update the characteristics of a device associated with I<domain-id>, based on -the device definition in an XML I<file>. If the I<--persistent> option is -used, the changes will affect the next boot of the domain. The I<--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 to learn about libvirt -XML format for a device. +Update the characteristics of a device associated with I<domain-id>, +based on the device definition in an XML I<file>. If the +I<--persistent> option is used, the changes will affect the next boot +of the domain. The I<--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 +L<http://libvirt.org/formatdomain.html> to learn about libvirt XML +format for a device. =back @@ -1617,8 +1622,9 @@ The I<--disable> option disable autostarting. =item B<net-create> I<file> -Create a virtual network from an XML I<file>, see the documentation to get -a description of the XML network format used by libvirt. +Create a virtual network from an XML I<file>, see the documentation at +L<http://libvirt.org/formatnetwork.html> to get a description of the +XML network format used by libvirt. =item B<net-define> I<file> -- 1.7.7.6
On 02/27/2012 03:51 PM, Dave Allan wrote:
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 URI in several years of referring to the man page. This patch adds those URIs to several additional places in the text. --- tools/virsh.pod | 38 ++++++++++++++++++++++---------------- 1 files changed, 22 insertions(+), 16 deletions(-)
Much nicer. ACK with one nit.
=item B<attach-device> I<domain-id> I<FILE>
-Attach a device to the domain, using a device definition in an XML file. -See the documentation to learn about libvirt XML format for a device. -For cdrom and floppy devices, this command only replaces the media within -the single existing device; consider using B<update-device> for this usage. -For passthrough host devices, see also B<nodedev-dettach>, needed if -the device does not use managed mode. +Attach a device to the domain, using a device definition in an XML +file. See the documentation at +L<http://libvirt.org/formatdomain.html> to learn about libvirt XML
Here, I'd link to formatdomain.html#elementsDevices, as well as specifically mention an example or two of the valid top-level elements we are looking for. Maybe: ...using a device definition (such as <disk> or <interface>) as the top-level element in an XML file. See the documentation... -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On Mon, Feb 27, 2012 at 04:02:44PM -0700, Eric Blake wrote:
On 02/27/2012 03:51 PM, Dave Allan wrote:
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 URI in several years of referring to the man page. This patch adds those URIs to several additional places in the text. --- tools/virsh.pod | 38 ++++++++++++++++++++++---------------- 1 files changed, 22 insertions(+), 16 deletions(-)
Much nicer. ACK with one nit.
=item B<attach-device> I<domain-id> I<FILE>
-Attach a device to the domain, using a device definition in an XML file. -See the documentation to learn about libvirt XML format for a device. -For cdrom and floppy devices, this command only replaces the media within -the single existing device; consider using B<update-device> for this usage. -For passthrough host devices, see also B<nodedev-dettach>, needed if -the device does not use managed mode. +Attach a device to the domain, using a device definition in an XML +file. See the documentation at +L<http://libvirt.org/formatdomain.html> to learn about libvirt XML
Here, I'd link to formatdomain.html#elementsDevices, as well as specifically mention an example or two of the valid top-level elements we are looking for. Maybe:
...using a device definition (such as <disk> or <interface>) as the top-level element in an XML file. See the documentation...
Good point; I'll send a v2 shortly. Dave
-- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
participants (2)
-
Dave Allan -
Eric Blake