From 7ece6ad8c6132ca26ee6bb5532bcc1b9a9fe98c6 Mon Sep 17 00:00:00 2001
From: David Zeuthen <davidz@redhat.com>
Date: Fri, 24 Feb 2012 09:20:12 -0500
Subject: [PATCH] Reword the section about block device objects a little bit

Signed-off-by: David Zeuthen <davidz@redhat.com>
---
 doc/udisks2-docs.xml | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/udisks2-docs.xml b/doc/udisks2-docs.xml
index e5e9c0c..28d8fce 100644
--- a/doc/udisks2-docs.xml
+++ b/doc/udisks2-docs.xml
@@ -59,9 +59,10 @@
       <sect1 id="ref-dbus-block-devices">
         <title>The /org/freedesktop/UDisks2/block_devices/* objects</title>
         <para>
-          Objects with an object path starting with
+          Objects with object paths starting with
           <literal>/org/freedesktop/UDisks2/block_devices/</literal>
-          implement the
+          all represent <ulink url="http://en.wikipedia.org/wiki/Block_device#Block_devices">block devices</ulink>.
+          Such objects implement the
           <link linkend="gdbus-interface-org-freedesktop-UDisks2-Block.top_of_page">org.freedesktop.UDisks2.Block</link>
           D-Bus interface and may optionally implement other D-Bus interfaces such as
           <link linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link>,
@@ -69,9 +70,13 @@
           <link linkend="gdbus-interface-org-freedesktop-UDisks2-Loop.top_of_page">org.freedesktop.UDisks2.Loop</link> depending on the block device in question.
         </para>
         <para>
-          Note that interfaces may be added and removed at run-time. For example, if a block device is full of zeroes, it will not intially implement the
-          <link linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link>
-          interface; however, if a filesystem is written to disk (using, say, the
+          Note that interfaces may be added and removed at
+          run-time. For example, if a block device is full of zeroes
+          (or, at least, have zeroes in the known metadata areas), it
+          will not intially implement the <link
+          linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link>
+          interface; however, if a filesystem is later created on the device
+          (using, say, the
           <citerefentry>
             <refentrytitle>mkfs</refentrytitle><manvolnum>8</manvolnum>
           </citerefentry>
-- 
2.7.4