docs: Emphasize that devices have to be inside the <devices> element

Also cleanup indentation of domain XML examples.

docs/formatdomain.html.in

@@ -412,6 +412,7 @@
   ...
   <devices>
     <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
+  </devices>
   ...</pre>
 
     <dl>
@@ -435,6 +436,7 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;disk type='file'&gt;
       &lt;driver name="tap" type="aio" cache="default"&gt;
       &lt;source file='/var/lib/xen/images/fv0'/&gt;
@@ -444,6 +446,7 @@
       &lt;/encryption&gt;
       &lt;shareable/&gt;
     &lt;/disk&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -502,21 +505,27 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;hostdev mode='subsystem' type='usb'&gt;
       &lt;source&gt;
         &lt;vendor id='0x1234'/&gt;
         &lt;product id='0xbeef'/&gt;
       &lt;/source&gt;
     &lt;/hostdev&gt;
+  &lt;/devices&gt;
   ...</pre>
+
     <p>or:</p>
+
 <pre>
   ...
+  &lt;devices&gt;
     &lt;hostdev mode='subsystem' type='pci'&gt;
       &lt;source&gt;
         &lt;address bus='0x06' slot='0x02' function='0x0'/&gt;
       &lt;/source&gt;
     &lt;/hostdev&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -558,11 +567,13 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='bridge'&gt;
       &lt;source bridge='xenbr0'/&gt;
       &lt;mac address='00:16:3e:5d:c7:9e'/&gt;
       &lt;script path='vif-bridge'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSVirtual">Virtual network</a></h5>
@@ -591,6 +602,7 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='network'&gt;
       &lt;source network='default'/&gt;
     &lt;/interface&gt;
@@ -600,6 +612,7 @@
       &lt;target dev='vnet7'/&gt;
       &lt;mac address="11:22:33:44:55:66"/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSBridge">Bridge to LAN</a></h5>
@@ -625,15 +638,17 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='bridge'&gt;
       &lt;source bridge='br0'/&gt;
     &lt;/interface&gt;
-
+    ...
     &lt;interface type='bridge'&gt;
       &lt;source bridge='br0'/&gt;
       &lt;target dev='vnet7'/&gt;
       &lt;mac address="11:22:33:44:55:66"/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSSlirp">Userspace SLIRP stack</a></h5>
@@ -649,11 +664,13 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='user'/&gt;
     ...
     &lt;interface type='user'&gt;
       &lt;mac address="11:22:33:44:55:66"/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
 
@@ -671,12 +688,14 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='ethernet'/&gt;
     ...
     &lt;interface type='ethernet'&gt;
       &lt;target dev='vnet7'/&gt;
       &lt;script path='/etc/qemu-ifup-mynet'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSMulticast">Multicast tunnel</a></h5>
@@ -695,9 +714,11 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='mcast'&gt;
       &lt;source address='230.0.0.1' port='5558'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSTCP">TCP tunnel</a></h5>
@@ -713,6 +734,7 @@
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='server'&gt;
       &lt;source address='192.168.0.1' port='5558'/&gt;
     &lt;/interface&gt;
@@ -720,17 +742,20 @@
     &lt;interface type='client'&gt;
     &lt;source address='192.168.0.1' port='5558'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSModel">Setting the NIC model</a></h5>
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='network'&gt;
       &lt;source network='default'/&gt;
       &lt;target dev='vnet1'/&gt;
       <b>&lt;model type='ne2k_pci'/&gt;</b>
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -759,10 +784,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='network'&gt;
       &lt;source network='default'/&gt;
       <b>&lt;target dev='vnet1'/&gt;</b>
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -785,7 +812,9 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;input type='mouse' bus='usb'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -809,10 +838,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;graphics type='sdl' display=':0.0'/&gt;
     &lt;graphics type='vnc' port='5904'/&gt;
     &lt;graphics type='rdp' autoport='yes' multiUser='yes' /&gt;
     &lt;graphics type='desktop' fullscreen='yes'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -869,11 +900,13 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;video&gt;
       &lt;model type='vga' vram='8192' heads='1'&gt;
         &lt;acceleration accel3d='yes' accel3d='yes'/&gt;
       &lt;/model&gt;
     &lt;/video&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -909,6 +942,7 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;parallel type='pty'&gt;
       &lt;source path='/dev/pts/2'/&gt;
       &lt;target port='0'/&gt;
@@ -926,7 +960,7 @@ qemu-kvm -net nic,model=? /dev/null
       &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
     &lt;/channel&gt;
   &lt;/devices&gt;
-      &lt;/domain&gt;</pre>
+  ...</pre>
 
     <p>
       In each of these directives, the top-level element name (parallel, serial,
@@ -951,10 +985,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;parallel type='pty'&gt;
       &lt;source path='/dev/pts/2'/&gt;
       &lt;target port='0'/&gt;
     &lt;/parallel&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -967,10 +1003,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type='pty'&gt;
       &lt;source path='/dev/pts/3'/&gt;
       &lt;target port='0'/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -989,10 +1027,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;console type='pty'&gt;
       &lt;source path='/dev/pts/4'/&gt;
       &lt;target port='0'/&gt;
     &lt;/console&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -1010,10 +1050,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;channel type='unix'&gt;
       &lt;source mode='bind' path='/tmp/guestfwd'/&gt;
       &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
     &lt;/channel&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -1047,9 +1089,11 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;console type='stdio'&gt;
       &lt;target port='1'&gt;
     &lt;/console&gt;
+  &lt;/devices&gt;
   ...</pre>
 
 
@@ -1062,10 +1106,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="file"&gt;
       &lt;source path="/var/log/vm/vm-serial.log"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharVC">Virtual console</a></h6>
@@ -1078,9 +1124,11 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type='vc'&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharNull">Null device</a></h6>
@@ -1092,9 +1140,11 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type='null'&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharPTY">Pseudo TTY</a></h6>
@@ -1107,10 +1157,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="pty"&gt;
       &lt;source path="/dev/pts/3"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -1132,10 +1184,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="dev"&gt;
       &lt;source path="/dev/ttyS0"/&gt;
       &lt;target port="1"/&gt;
   &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharPipe">Named pipe</a></h6>
@@ -1147,10 +1201,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="pipe"&gt;
       &lt;source path="/tmp/mypipe"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharTCP">TCP client/server</a></h6>
@@ -1162,11 +1218,13 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="tcp"&gt;
       &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
       &lt;protocol type="raw"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
    ...</pre>
 
     <p>
@@ -1175,11 +1233,13 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="tcp"&gt;
       &lt;source mode="bind" host="127.0.0.1" service="2445"/&gt;
       &lt;protocol type="raw"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -1188,6 +1248,7 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="tcp"&gt;
       &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
       &lt;protocol type="telnet"/&gt;
@@ -1199,6 +1260,7 @@ qemu-kvm -net nic,model=? /dev/null
       &lt;protocol type="telnet"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharUDP">UDP network console</a></h6>
@@ -1210,11 +1272,13 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="udp"&gt;
       &lt;source mode="bind" host="0.0.0.0" service="2445"/&gt;
       &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharUNIX">UNIX domain socket client/server</a></h6>
@@ -1226,10 +1290,12 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="unix"&gt;
       &lt;source mode="bind" path="/tmp/foo"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
 
@@ -1242,7 +1308,9 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;sound model='es1370'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -1278,13 +1346,17 @@ qemu-kvm -net nic,model=? /dev/null
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;watchdog model='i6300esb'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
 <pre>
   ...
+  &lt;devices&gt;
     &lt;watchdog model='i6300esb' action='poweroff'/&gt;
-      ...</pre>
+  &lt;/devices&gt;
+&lt;/domain&gt;</pre>
 
     <dl>
       <dt><code>model</code></dt>