docs: Enhance documentation of the old-style boot configuration

Also encourages people to use per-device boot elements for better
control.

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 284e780e2f8f8e155e1d93f204a5626b069d6477..29497a059e04937b623cdc92095ba33764077884 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -131,12 +131,24 @@
       <dd>The <code>dev</code> attribute takes one of the values "fd", "hd",
         "cdrom" or "network" and is used to specify the next boot device
         to consider. The <code>boot</code> element can be repeated multiple
-        times to setup a priority list of boot devices to try in turn. The
-        <code>boot</code> element cannot be used if per-device boot elements
-        are used (see <a href="#elementsDisks">disks</a>,
+        times to setup a priority list of boot devices to try in turn.
+        Multiple devices of the same type are sorted according to their
+        targets while preserving the order of buses. After defining the
+        domain, its XML configuration returned by libvirt (through
+        virDomainGetXMLDesc) lists devices in the sorted order. Once sorted,
+        the first device is marked as bootable. Thus, e.g., a domain
+        configured to boot from "hd" with vdb, hda, vda, and hdc disks
+        assigned to it will boot from vda (the sorted list is vda, vdb, hda,
+        hdc). Similar domain with hdc, vda, vdb, and hda disks will boot from
+        hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to
+        configure in the desired way, which is why per-device boot elements
+        (see <a href="#elementsDisks">disks</a>,
         <a href="#elementsNICS">network interfaces</a>, and
-        <a href="#elementsUSB">USB and PCI devices</a> sections below).
-        <span class="since">Since 0.1.3, per-device boot since 0.8.8</span>
+        <a href="#elementsUSB">USB and PCI devices</a> sections below) were
+        introduced and they are the preferred way providing full control over
+        booting order. The <code>boot</code> element and per-device boot
+        elements are mutually exclusive. <span class="since">Since 0.1.3,
+        per-device boot since 0.8.8</span>
       </dd>
       <dt><code>bootmenu</code></dt>
       <dd> Whether or not to enable an interactive boot menu prompt on guest