Added autogenerated TOC for network and storage XML reference docs

docs/formatnetwork.html

@@ -114,17 +114,41 @@
       </div>
       <div id="content">
         <h1>Network XML format</h1>
+        <ul><li>
+            <a href="#elements">Element and attribute overview</a>
+            <ul><li>
+                <a href="#elementsMetadata">General metadata</a>
+              </li><li>
+                <a href="#elementsConnect">Connectivity</a>
+              </li><li>
+                <a href="#elementsAddress">Addressing</a>
+              </li></ul>
+          </li><li>
+            <a href="#examples">Example configuration</a>
+            <ul><li>
+                <a href="#examplesNAT">NAT based network</a>
+              </li><li>
+                <a href="#examplesRoute">Routed network config</a>
+              </li><li>
+                <a href="#examplesPrivate">Isolated network config</a>
+              </li></ul>
+          </li></ul>
         <p>
       This page provides an introduction to the network XML format. For background
       information on the concepts referred to here, consult the <a href="archnetwork.html">network driver architecture</a>
       page.
     </p>
-        <h2>Element and attribute overview</h2>
+        <h2>
+          <a name="elements" id="elements">Element and attribute overview</a>
+        </h2>
         <p>
       The root element required for all virtual networks is
       named <code>network</code> and has no attributes.
+      The network XML format is available <span class="since">since 0.3.0</span>
     </p>
-        <h3>General metadata</h3>
+        <h3>
+          <a name="elementsMetadata" id="elementsMetadata">General metadata</a>
+        </h3>
         <p>
       The first elements provide basic metadata about the virtual
       network.
@@ -139,12 +163,14 @@
 	consist only of alpha-numeric characters and is required
 	to be unique within the scope of a single host. It is
 	used to form the filename for storing the persistent
-	configuration file.</dd><dt><code>uuid</code></dt><dd>The content of the <code>uuid</code> element provides
+	configuration file. <span class="since">Since 0.3.0</span></dd><dt><code>uuid</code></dt><dd>The content of the <code>uuid</code> element provides
 	a globally unique identifier for the virtual network.
 	The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
 	If omitted when defining/creating a new network, a random
-	UUID is generated.</dd></dl>
-        <h3>Connectivity</h3>
+	UUID is generated. <span class="since">Since 0.3.0</span></dd></dl>
+        <h3>
+          <a name="elementsConnect" id="elementsConnect">Connectivity</a>
+        </h3>
         <p>
       The next set of elements control how a virtual network is
       provided connectivity to the physical LAN (if at all).
@@ -152,7 +178,7 @@
         <pre>
         ...
         &lt;bridge name="virbr0" /&gt;
-	&lt;forward type="nat"/&gt;
+	&lt;forward mode="nat" dev="eth0"/&gt;
 	...</pre>
         <dl><dt><code>bridge</code></dt><dd>The <code>name</code> attribute on the <code>bridge</code> element
 	defines the name of a bridge device which will be used to construct
@@ -161,18 +187,22 @@
 	may also be connected to the LAN. It is recommended that bridge
 	device names started with the prefix <code>vir</code>, but the name
 	<code>virbr0</code> is reserved for the "default" virtual network.
-	This element should always be provided when defining a new network
+	This element should always be provided when defining a new network.
+	<span class="since">Since 0.3.0</span>
       </dd><dt><code>forward</code></dt><dd>Inclusion of the <code>forward</code> element indicates that
 	the virtual network is to be connected to the physical LAN. If
 	no attributes are set, NAT forwarding will be used for connectivity.
 	Firewall rules will allow forwarding to any other network device whether
 	ethernet, wireless, dialup, or VPN. If the <code>dev</code> attribute
 	is set, the firewall rules will restrict forwarding to the named
-	device only. If the <code>type</code> attribute is set to <code>route</code>
+	device only. If the <code>mode</code> attribute is set to <code>route</code>
 	then the traffic will not have NAT applied. This presumes that the
 	local LAN router has suitable routing table entries to return traffic
-	to this host.</dd></dl>
-        <h3>Addressing</h3>
+	to this host. <span class="since">Since 0.3.0; 'mode' attribute since
+        0.4.2</span></dd></dl>
+        <h3>
+          <a name="elementsAddress" id="elementsAddress">Addressing</a>
+        </h3>
         <p>
       The final set of elements define the IPv4 address range available,
       and optionally enable DHCP sevices.
@@ -190,19 +220,24 @@
 	device associated with the virtual network. To the guests this
 	address will be their default route. The <code>netmask</code>
 	attribute defines the significant bits of the network address,
-	again specified in dotted-decimal format.
+	again specified in dotted-decimal format.  <span class="since">Since 0.3.0</span>
       </dd><dt><code>dhcp</code></dt><dd>Immediately within the <code>ip</code> element there is an
 	optional <code>dhcp</code> element. The presence of this element
 	enables DHCP services on the virtual network. It will further
 	contain one or more <code>range</code> elements.
+	<span class="since">Since 0.3.0</span>
       </dd><dt><code>range</code></dt><dd>The <code>start</code> and <code>end</code> attributes on the
 	<code>range</code> element specify the boundaries of a pool of
 	IPv4 addresses to be provided to DHCP clients. These two addresses
 	must lie within the scope of the network defined on the parent
-	<code>ip</code> element.
+	<code>ip</code> element.  <span class="since">Since 0.3.0</span>
       </dd></dl>
-        <h2>Example configuration</h2>
-        <h3>NAT based network</h3>
+        <h2>
+          <a name="examples" id="examples">Example configuration</a>
+        </h2>
+        <h3>
+          <a name="examplesNAT" id="examplesNAT">NAT based network</a>
+        </h3>
         <p>
       This example is the so called "default" virtual network. It is
       provided and enabled out-of-the-box for all libvirt installations.
@@ -223,7 +258,9 @@
 	  &lt;/dhcp&gt;
 	&lt;/ip&gt;
       &lt;/network&gt;</pre>
-        <h3>Routed network config</h3>
+        <h3>
+          <a name="examplesRoute" id="examplesRoute">Routed network config</a>
+        </h3>
         <p>
       This is a variant on the default network which routes traffic
       from the virtual network to the LAN without applying any NAT.
@@ -243,7 +280,9 @@
 	  &lt;/dhcp&gt;
 	&lt;/ip&gt;
       &lt;/network&gt;</pre>
-        <h3>Isolated network config</h3>
+        <h3>
+          <a name="examplesPrivate" id="examplesPrivate">Isolated network config</a>
+        </h3>
         <p>
       This variant provides a completely isolated private network
       for guests. The guests can talk to each other, and the host

docs/formatnetwork.html.in

@@ -2,20 +2,24 @@
   <body>
     <h1>Network XML format</h1>
 
+    <ul id="toc">
+    </ul>
+
     <p>
       This page provides an introduction to the network XML format. For background
       information on the concepts referred to here, consult the <a href="archnetwork.html">network driver architecture</a>
       page.
     </p>
 
-    <h2>Element and attribute overview</h2>
+    <h2><a name="elements">Element and attribute overview</a></h2>
 
     <p>
       The root element required for all virtual networks is
       named <code>network</code> and has no attributes.
+      The network XML format is available <span class="since">since 0.3.0</span>
     </p>
 
-    <h3>General metadata</h3>
+    <h3><a name="elementsMetadata">General metadata</a></h3>
 
     <p>
       The first elements provide basic metadata about the virtual
@@ -35,16 +39,16 @@
 	consist only of alpha-numeric characters and is required
 	to be unique within the scope of a single host. It is
 	used to form the filename for storing the persistent
-	configuration file.</dd>
+	configuration file. <span class="since">Since 0.3.0</span></dd>
       <dt><code>uuid</code></dt>
       <dd>The content of the <code>uuid</code> element provides
 	a globally unique identifier for the virtual network.
 	The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
 	If omitted when defining/creating a new network, a random
-	UUID is generated.</dd>
+	UUID is generated. <span class="since">Since 0.3.0</span></dd>
     </dl>
 
-    <h3>Connectivity</h3>
+    <h3><a name="elementsConnect">Connectivity</a></h3>
 
     <p>
       The next set of elements control how a virtual network is
@@ -54,7 +58,7 @@
     <pre>
         ...
         &lt;bridge name="virbr0" /&gt;
-	&lt;forward type="nat"/&gt;
+	&lt;forward mode="nat" dev="eth0"/&gt;
 	...</pre>
 
     <dl>
@@ -66,7 +70,8 @@
 	may also be connected to the LAN. It is recommended that bridge
 	device names started with the prefix <code>vir</code>, but the name
 	<code>virbr0</code> is reserved for the "default" virtual network.
-	This element should always be provided when defining a new network
+	This element should always be provided when defining a new network.
+	<span class="since">Since 0.3.0</span>
       </dd>
       <dt><code>forward</code></dt>
       <dd>Inclusion of the <code>forward</code> element indicates that
@@ -75,13 +80,14 @@
 	Firewall rules will allow forwarding to any other network device whether
 	ethernet, wireless, dialup, or VPN. If the <code>dev</code> attribute
 	is set, the firewall rules will restrict forwarding to the named
-	device only. If the <code>type</code> attribute is set to <code>route</code>
+	device only. If the <code>mode</code> attribute is set to <code>route</code>
 	then the traffic will not have NAT applied. This presumes that the
 	local LAN router has suitable routing table entries to return traffic
-	to this host.</dd>
+	to this host. <span class="since">Since 0.3.0; 'mode' attribute since
+        0.4.2</span></dd>
     </dl>
 
-    <h3>Addressing</h3>
+    <h3><a name="elementsAddress">Addressing</a></h3>
 
     <p>
       The final set of elements define the IPv4 address range available,
@@ -104,26 +110,27 @@
 	device associated with the virtual network. To the guests this
 	address will be their default route. The <code>netmask</code>
 	attribute defines the significant bits of the network address,
-	again specified in dotted-decimal format.
+	again specified in dotted-decimal format.  <span class="since">Since 0.3.0</span>
       </dd>
       <dt><code>dhcp</code></dt>
       <dd>Immediately within the <code>ip</code> element there is an
 	optional <code>dhcp</code> element. The presence of this element
 	enables DHCP services on the virtual network. It will further
 	contain one or more <code>range</code> elements.
+	<span class="since">Since 0.3.0</span>
       </dd>
       <dt><code>range</code></dt>
       <dd>The <code>start</code> and <code>end</code> attributes on the
 	<code>range</code> element specify the boundaries of a pool of
 	IPv4 addresses to be provided to DHCP clients. These two addresses
 	must lie within the scope of the network defined on the parent
-	<code>ip</code> element.
+	<code>ip</code> element.  <span class="since">Since 0.3.0</span>
       </dd>
     </dl>
 
-    <h2>Example configuration</h2>
+    <h2><a name="examples">Example configuration</a></h2>
 
-    <h3>NAT based network</h3>
+    <h3><a name="examplesNAT">NAT based network</a></h3>
 
     <p>
       This example is the so called "default" virtual network. It is
@@ -147,7 +154,7 @@
 	&lt;/ip&gt;
       &lt;/network&gt;</pre>
 
-    <h3>Routed network config</h3>
+    <h3><a name="examplesRoute">Routed network config</a></h3>
 
     <p>
       This is a variant on the default network which routes traffic
@@ -170,7 +177,7 @@
 	&lt;/ip&gt;
       &lt;/network&gt;</pre>
 
-    <h3>Isolated network config</h3>
+    <h3><a name="examplesPrivate">Isolated network config</a></h3>
 
     <p>
       This variant provides a completely isolated private network

docs/libvirt.css

@@ -348,3 +348,9 @@ head:first-child+body #projects dl {
     text-decoration: inherit;
     font-size: 1.2em;
 }
+
+span.since {
+    color: #3c857c;
+    font-style: italic;
+    font-weight: bold;
+}

docs/page.xsl

@@ -59,6 +59,54 @@
     </ul>
   </xsl:template>
 
+  <xsl:template name="toc">
+    <ul>
+      <xsl:for-each select="/html/body/h2[count(a) = 1]">
+        <xsl:variable name="thishead" select="."/>
+        <li>
+          <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
+          <xsl:if test="count(./following-sibling::h3[preceding-sibling::h2[1] = $thishead and count(a) = 1]) > 0">
+            <ul>
+              <xsl:for-each select="./following-sibling::h3[preceding-sibling::h2[1] = $thishead and count(a) = 1]">
+                <xsl:variable name="thissubhead" select="."/>
+                <li>
+                  <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
+                  <xsl:if test="count(./following-sibling::h4[preceding-sibling::h3[1] = $thissubhead and count(a) = 1]) > 0">
+                    <ul>
+                      <xsl:for-each select="./following-sibling::h4[preceding-sibling::h3[1] = $thissubhead and count(a) = 1]">
+                        <li>
+                          <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
+                          <xsl:if test="count(./following-sibling::h5[preceding-sibling::h4[1] = $thissubhead and count(a) = 1]) > 0">
+                            <ul>
+                              <xsl:for-each select="./following-sibling::h5[preceding-sibling::h4[1] = $thissubhead and count(a) = 1]">
+                                <li>
+                                  <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
+                                  <xsl:if test="count(./following-sibling::h6[preceding-sibling::h5[1] = $thissubhead and count(a) = 1]) > 0">
+                                    <ul>
+                                      <xsl:for-each select="./following-sibling::h6[preceding-sibling::h5[1] = $thissubhead and count(a) = 1]">
+                                        <li>
+                                          <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
+                                        </li>
+                                      </xsl:for-each>
+                                    </ul>
+                                  </xsl:if>
+                                </li>
+                              </xsl:for-each>
+                            </ul>
+                          </xsl:if>
+                        </li>
+                      </xsl:for-each>
+                    </ul>
+                  </xsl:if>
+                </li>
+              </xsl:for-each>
+            </ul>
+          </xsl:if>
+        </li>
+      </xsl:for-each>
+    </ul>
+  </xsl:template>
+
   <!-- This is the master page structure -->
   <xsl:template match="/" mode="page">
     <xsl:param name="pagename"/>
@@ -93,7 +141,16 @@
             </xsl:apply-templates>
           </div>
           <div id="content">
-            <xsl:copy-of select="html/body/*"/>
+            <xsl:for-each select="html/body/*">
+              <xsl:choose>
+                <xsl:when test="name() = 'ul' and @id = 'toc'">
+                  <xsl:call-template name="toc"/>
+                </xsl:when>
+                <xsl:otherwise>
+                  <xsl:copy-of select="."/>
+                </xsl:otherwise>
+              </xsl:choose>
+            </xsl:for-each>
           </div>
         </div>
         <div id="footer">