xml: Add element <title> to allow short description of domains

This patch adds a new element <title> to the domain XML. This attribute
can hold a short title defined by the user to ease the identification of
domains. The title may not contain newlines and should be reasonably short.

 *docs/formatdomain.html.in
 *docs/schemas/domaincommon.rng
        - add schema grammar for the new element and documentation
  *src/conf/domain_conf.c
  *src/conf/domain_conf.h
        - add field to hold the new attribute
        - add code to parse and create XML with the new attribute

docs/formatdomain.html.in

@@ -32,6 +32,7 @@
 <domain type='xen' id='3'>
   <name>fv0</name>
   <uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
+  <title>A short description - title - of the domain</title>
   <description>Some human readable description</description>
   <metadata>
     <app1:foo xmlns:app1="http://app1.org/app1/">..</app1:foo>
@@ -58,6 +59,11 @@
         specification. <span class="since">Since 0.0.1, sysinfo
         since 0.8.7</span></dd>
 
+      <dt><code>title</code></dt>
+      <dd>The optional element <code>title</code> provides space for a
+        short description of the domain. The title should not contain
+        any newlines. <span class="since">Since 0.9.10</span>.</dd>
+
       <dt><code>description</code></dt>
       <dd>The content of the <code>description</code> element provides a
         human readable description of the virtual machine. This data is not
@@ -72,7 +78,7 @@
         (if the application needs structure, they should have
         sub-elements to their namespace
         element). <span class="since">Since 0.9.10</span></dd>
-    </dl>
+   </dl>
 
     <h3><a name="elementsOS">Operating system booting</a></h3>
 

docs/schemas/domaincommon.rng

@@ -6,7 +6,7 @@
   <include href='networkcommon.rng'/>
 
   <!--
-    description element, may be placed anywhere under the root
+    description and title element, may be placed anywhere under the root
     -->
   <define name="description">
     <element name="description">
@@ -14,6 +14,16 @@
     </element>
   </define>
 
+  <define name="title">
+    <element name="title">
+      <data type="string">
+        <!-- Use literal newline instead of \n for bug in libxml2 2.7.6 -->
+        <param name="pattern">[^
+]+</param>
+      </data>
+    </element>
+  </define>
+
   <!--
       We handle only document defining a domain
     -->
@@ -22,6 +32,9 @@
       <ref name="hvs"/>
       <ref name="ids"/>
       <interleave>
+        <optional>
+          <ref name="title"/>
+        </optional>
         <optional>
           <ref name="description"/>
         </optional>

src/conf/domain_conf.c

@@ -1481,6 +1481,7 @@ void virDomainDefFree(virDomainDefPtr def)
     VIR_FREE(def->cpumask);
     VIR_FREE(def->emulator);
     VIR_FREE(def->description);
+    VIR_FREE(def->title);
 
     virBlkioDeviceWeightArrayClear(def->blkio.devices,
                                    def->blkio.ndevices);
@@ -7158,6 +7159,14 @@ static virDomainDefPtr virDomainDefParseXML(virCapsPtr caps,
         VIR_FREE(tmp);
     }
 
+    /* Extract short description of domain (title) */
+    def->title = virXPathString("string(./title[1])", ctxt);
+    if (def->title && strchr(def->title, '\n')) {
+        virDomainReportError(VIR_ERR_XML_ERROR, "%s",
+                             _("Domain title can't contain newlines"));
+        goto error;
+    }
+
     /* Extract documentation if present */
     def->description = virXPathString("string(./description[1])", ctxt);
 
@@ -11487,6 +11496,8 @@ virDomainDefFormatInternal(virDomainDefPtr def,
     virUUIDFormat(uuid, uuidstr);
     virBufferAsprintf(buf, "  <uuid>%s</uuid>\n", uuidstr);
 
+    virBufferEscapeString(buf, "  <title>%s</title>\n", def->title);
+
     virBufferEscapeString(buf, "  <description>%s</description>\n",
                           def->description);
 

src/conf/domain_conf.h

@@ -1425,6 +1425,7 @@ struct _virDomainDef {
     int id;
     unsigned char uuid[VIR_UUID_BUFLEN];
     char *name;
+    char *title;
     char *description;
 
     struct {

tests/domainschemadata/qemu-simple-description-title.xml

@@ -0,0 +1,27 @@
+<domain type='qemu'>
+  <name>qemu-demo</name>
+  <uuid>603cc28c-9841-864e-0949-8cc7d3bae9f8</uuid>
+  <memory>65536</memory>
+  <currentMemory>65536</currentMemory>
+  <title>A short description of this domain</title>
+  <description>
+      A longer explanation that this domain is a test domain
+      for validating domain schemas.
+  </description>
+  <vcpu>1</vcpu>
+  <os>
+    <type arch='x86_64' machine='pc-0.14'>hvm</type>
+  </os>
+  <features>
+    <acpi/>
+    <apic/>
+    <pae/>
+  </features>
+  <clock offset='utc'/>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>restart</on_crash>
+  <devices>
+    <emulator>/usr/bin/qemu-kvm</emulator>
+  </devices>
+</domain>

tests/qemuxml2argvdata/qemuxml2argv-minimal.xml

@@ -1,6 +1,11 @@
 <domain type='qemu'>
   <name>QEMUGuest1</name>
   <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+  <title>A description of the test machine.</title>
+  <description>
+      A test of qemu&apos;s minimal configuration.
+      This test also tests the description and title elements.
+  </description>
   <memory>219100</memory>
   <currentMemory>219100</currentMemory>
   <vcpu cpuset='1-4,8-20,525'>1</vcpu>