From 060f4c666e1b2fe81ec3e21ef28a262a290471f4 Mon Sep 17 00:00:00 2001
From: Deepak Shetty <dpkshetty@gmail.com>
Date: Wed, 18 Mar 2015 19:18:22 +0530
Subject: [PATCH] doc: Fix doc for backingStore

I spent quite some time figuring that backingStore info
isn't included in the dom xml, unless guest is up and
running. Hopefully putting that in the doc should help.

Also, several people have complained that libvirt reports
a backing file as raw, even though they expected it to be
qcow2; where the culprit is usually the user forgetting to
create the file with qemu-img create -o backing_fmt=qcow2.

This patch adds that info to the doc.

Signed-off-by: Deepak C Shetty <deepakcs@redhat.com>
Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/formatdomain.html.in | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index ab5198295..be35c82e7 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -2108,14 +2108,22 @@
         </dd>
       <dt><code>backingStore</code></dt>
       <dd>
-        This element describes the backing store used by the disk specified by
-        sibling <code>source</code> element. It is currently ignored on input
-        and only used for output to describe the detected backing chains.
-        <span class="since">Since 1.2.4</span>. An empty
-        <code>backingStore</code> element means the sibling source is
-        self-contained and is not based on any backing store. The following
-        attributes and sub-elements are supported in
-        <code>backingStore</code>:
+        This element describes the backing store used by the disk
+        specified by sibling <code>source</code> element. It is
+        currently ignored on input and only used for output to
+        describe the detected backing chains of running
+        domains <span class="since">since 1.2.4</span> (although a
+        future version of libvirt may start accepting chains on input,
+        or output information for offline domains). An
+        empty <code>backingStore</code> element means the sibling
+        source is self-contained and is not based on any backing
+        store. For backing chain information to be accurate, the
+        backing format must be correctly specified in the metadata of
+        each file of the chain (files created by libvirt satisfy this
+        property, but using existing external files for snapshot or
+        block copy operations requires the end user to pre-create the
+        file correctly). The following attributes and sub-elements are
+        supported in <code>backingStore</code>:
         <dl>
           <dt><code>type</code> attribute</dt>
           <dd>
-- 
2.39.5