diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
index a9c86f9fc709e42f8c3e4a5fe8cb10b3369f58ee..e28af4e737d621d189f8f0810ca21786eb38c51f 100644
--- a/docs/drvnodedev.html.in
+++ b/docs/drvnodedev.html.in
@@ -28,60 +28,12 @@
     </p>
 
     <p>
-      The generic format of a host device XML can be seen below.
-      To identify a device both within the host and the device tree hierarchy,
-      the following elements are used:
+      Details of the XML format of a host device can be found <a
+      href="formatnode.html">here</a>. Of particular interest is the
+      <code>capability</code> element, which describes features supported by
+      the device. Some specific device types are addressed in more detail
+      below.
     </p>
-      <dl>
-        <dt><code>name</code></dt>
-        <dd>
-          The device's name will be generated by libvirt using the subsystem,
-          like pci and the device's sysfs basename.
-        </dd>
-        <dt><code>path</code></dt>
-        <dd>
-          Fully qualified sysfs path to the device.
-        </dd>
-        <dt><code>parent</code></dt>
-        <dd>
-          This element identifies the parent node in the device hierarchy. The
-          value of the element will correspond with the device parent's
-          <code>name</code> element or <code>computer</code> if the device does
-          not have any parent.
-        </dd>
-        <dt><code>driver</code></dt>
-        <dd>
-          This elements reports the driver in use for this device. The presence
-          of this element in the output XML depends on whether the underlying
-          device manager (most likely udev) exposes information about the
-          driver.
-        </dd>
-        <dt><code>capability</code></dt>
-        <dd>
-          Describes the device in terms of feature support. The element has one
-          mandatory attribute <code>type</code> the value of which determines
-          the type of the device. Currently recognized values for the attribute
-          are:
-          <code>system</code>,
-          <code>pci</code>,
-          <code>usb</code>,
-          <code>usb_device</code>,
-          <code>net</code>,
-          <code>scsi</code>,
-          <code>scsi_host</code> (<span class="since">Since 0.4.7</span>),
-          <code>fc_host</code>,
-          <code>vports</code>,
-          <code>scsi_target</code> (<span class="since">Since 0.7.3</span>),
-          <code>storage</code> (<span class="since">Since 1.0.4</span>),
-          <code>scsi_generic</code> (<span class="since">Since 1.0.7</span>),
-          <code>drm</code> (<span class="since">Since 3.1.0</span>), and
-          <code>mdev</code> (<span class="since">Since 3.4.0</span>).
-          This element can be nested in which case it further specifies a
-          device's capability. Refer to specific device types to see more values
-          for the <code>type</code> attribute which are exclusive.
-        </dd>
-      </dl>
-
     <h2>Basic structure of a node device</h2>
     <pre>
 &lt;device&gt;
@@ -191,45 +143,14 @@
       A PCI device capable of creating mediated devices will include a nested
       capability <code>mdev_types</code> which enumerates all supported mdev
       types on the physical device, along with the type attributes available
-      through sysfs:
+      through sysfs. A detailed description of the XML format for the
+      <code>mdev_types</code> capability can be found
+      <a href="formatnode.html#MDEVCap">here</a>.
     </p>
-
-    <dl>
-      <dt><code>type</code></dt>
-      <dd>
-        This element describes a mediated device type which acts as an
-        abstract template defining a resource allocation for instances of this
-        device type. The element has one attribute <code>id</code> which holds
-        an official vendor-supplied identifier for the type.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>name</code></dt>
-      <dd>
-        The <code>name</code> element holds a vendor-supplied code name for
-        the given mediated device type. This is an optional element.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>deviceAPI</code></dt>
-      <dd>
-        The value of this element describes how an instance of the given type
-        will be presented to the guest by the VFIO framework.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>availableInstances</code></dt>
-      <dd>
-        This element reports the current state of resource allocation. In other
-        words, how many instances of the given type can still be successfully
-        created on the physical device.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-    </dl>
-
     <p>
-      For a more info about mediated devices, refer to the
-      <a href="#MDEV">paragraph below</a>.
+      The following example shows how we might represent an NVIDIA GPU device
+      that supports mediated devices. See below for <a href="#MDEV">more
+      information about mediated devices</a>.
     </p>
 
 <pre>
@@ -262,32 +183,11 @@
       as multiple separate PCIe devices on the host's PCI bus, mediated devices
       only appear on the mdev virtual bus. Therefore, no detach/reattach
       procedure from/to the host driver procedure is involved even though
-      mediated devices are used in a direct device assignment manner.
+      mediated devices are used in a direct device assignment manner.  A
+      detailed description of the XML format for the <code>mdev</code>
+      capability can be found <a href="formatnode.html#mdev">here</a>.
     </p>
 
-    <p>
-      The following sub-elements and attributes are exposed within the
-      <code>capability</code> element:
-    </p>
-
-    <dl>
-      <dt><code>type</code></dt>
-      <dd>
-        This element describes a mediated device type which acts as an
-        abstract template defining a resource allocation for instances of this
-        device type. The element has one attribute <code>id</code> which holds
-        an official vendor-supplied identifier for the type.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-
-      <dt><code>iommuGroup</code></dt>
-      <dd>
-        This element supports a single attribute <code>number</code> which holds
-        the IOMMU group number the mediated device belongs to.
-        <span class="since">Since 3.4.0</span>
-      </dd>
-    </dl>
-
     <h3>Example of a mediated device</h3>
     <pre>
 &lt;device&gt;
diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in
index 7dcd3638ffb2d8aa72f309b60a492fa45bbad9b3..76eae928dea597ea2ccbc884239e11fa231fe751 100644
--- a/docs/formatnode.html.in
+++ b/docs/formatnode.html.in
@@ -33,9 +33,23 @@
         to provide more specific names, such as
         "net_eth1_00_27_13_6a_fe_00".
       </dd>
+      <dt><code>path</code></dt>
+      <dd>
+        Fully qualified sysfs path to the device.
+      </dd>
       <dt><code>parent</code></dt>
-      <dd>If this element is present, it names the parent device (that
-        is, a controller to which this node belongs).
+      <dd>
+        This element identifies the parent node in the device hierarchy. The
+        value of the element will correspond with the device parent's
+        <code>name</code> element or <code>computer</code> if the device does
+        not have any parent.
+      </dd>
+      <dt><code>driver</code></dt>
+      <dd>
+        This elements reports the driver in use for this device. The presence
+        of this element in the output XML depends on whether the underlying
+        device manager (most likely udev) exposes information about the
+        driver.
       </dd>
       <dt><code>devnode</code></dt>
       <dd>This node appears for each associated <code>/dev</code>
@@ -138,8 +152,40 @@
                     means such device cannot be used for PCI passthrough.
                     <span class="since">Since 1.3.3</span>
                   </dd>
+                  <dt><code><a id="MDEVCap">mdev_types</a></code></dt>
+                  <dd>
+                    This device is capable of creating mediated devices, and
+                    the capability will contain a list of <code>type</code>
+                    elements, which list all mdev types supported on the
+                    physical device. <span class="since">Since 3.4.0</span>
+                    Each <code>type</code> element has a single <code>id</code>
+                    attribute that holds an official vendor-supplied identifier
+                    for the type. It supports the following sub-elements:
+                      <dl>
+                        <dt><code>name</code></dt>
+                        <dd>
+                          The <code>name</code> element holds a vendor-supplied
+                          code name for the given mediated device type. This is
+                          an optional element.
+                      </dd>
+                      <dt><code>deviceAPI</code></dt>
+                      <dd>
+                        The value of this element describes how an instance of
+                        the given type will be presented to the guest by the
+                        VFIO framework.
+                      </dd>
+                      <dt><code>availableInstances</code></dt>
+                      <dd>
+                        This element reports the current state of resource
+                        allocation. In other words, how many instances of the
+                        given type can still be successfully created on the
+                        physical device.
+                    </dd>
+                  </dl>
+                </dd>
                 </dl>
               </dd>
+
               <dt><code>numa</code></dt>
               <dd>
                 This optional element contains information on the PCI device
@@ -329,6 +375,26 @@
               <code>render</code>.</dd>
             </dl>
           </dd>
+          <dt><a id="mdev"><code>mdev</code></a></dt>
+          <dd>Describes a mediated device.  <span class="since">Since
+            3.4.0</span> Sub-elements include:
+            <dl>
+              <dt><code>type</code></dt>
+              <dd>
+                Describes a mediated device type which acts as an abstract
+                template defining a resource allocation for instances
+                of this device type. The element has one attribute
+                <code>id</code> which holds an official vendor-supplied
+                identifier for the type.
+              </dd>
+              <dt><code>iommuGroup</code></dt>
+              <dd>
+                This element supports a single attribute <code>number</code>
+                which holds the IOMMU group number the mediated device belongs
+                  to.
+              </dd>
+            </dl>
+          </dd>
           <dt><code>ccw</code></dt>
           <dd>Describes a Command Channel Word (CCW) device commonly found on
           the S390 architecture. Sub-elements include: