[ostree] doc: Split overview into chapters, expand a bit

[Colin Walters <walters src gnome org>]

commit 032f1316ad19bc8c5ba7156302a77efb4a376ff9
Author: Colin Walters <walters verbum org>
Date:   Thu Aug 22 09:17:08 2013 -0400

    doc: Split overview into chapters, expand a bit

 doc/overview.xml |  213 ++++++++++++++++++++++++++++--------------------------
 1 files changed, 109 insertions(+), 104 deletions(-)
---
diff --git a/doc/overview.xml b/doc/overview.xml
index 2c8e957..7e53530 100644
--- a/doc/overview.xml
+++ b/doc/overview.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
 <!ENTITY version SYSTEM "../version.xml">
 ]>
 <part id="overview">
@@ -22,110 +22,115 @@
       images. Instead, OSTree sits between those levels, offering a
       blend of the advantages (and disadvantages) of both.
     </para>
-    
-    <simplesect id="ostree-package-comparison">
-      <title>Comparison with "package managers"</title>
-      <para>
-       Because OSTree is designed for deploying core operating
-       systems, a comparison with traditional "package managers" such
-       as dpkg and rpm is illustrative.  Packages are traditionally
-       composed of partial filesystem trees with metadata and scripts
-       attached, and these are dynamically assembled on the client
-       machine, after a process of dependency resolution.
-      </para>
-      <para>
-       In contrast, OSTree only supports recording and deploying
-       <emphasis>complete</emphasis> (bootable) filesystem trees.  It
-       has no built-in knowledge of how a given filesystem tree was
-       generated or the origin of individual files, or dependencies,
-       descriptions of individual components.
-      </para>
-      <para>
-       The OSTree core emphasizes replicating read-only trees via
-       HTTP.  It is designed for the model where a build server
-       assembles one or more trees, and these are replicated to
-       clients, which can choose between fully assembled (and
-       hopefully tested) trees.
-      </para>
-      <para>
-       However, it is entirely possible to use OSTree underneath a
-       package system; For example, when installing a package, rather
-       than mutating the currently running filesystem, the package
-       manager could assemble a new filesystem tree that includes the
-       new package, record it in the local OSTree repository, and
-       then set it up for the next boot.  To support this model,
-       OSTree provides an (introspectable) C shared library.
-      </para>
-    </simplesect>
 
-    <simplesect id="ostree-block-comparison">
-      <title>Comparison with block/image replication</title>
-      <para>
-       OSTree shares some similarity with "dumb" replication and
-       stateless deployments, such as the model common in "cloud"
-       deployments where nodes are booted from an (effectively)
-       readonly disk, and user data is kept on a different volumes.
-       The advantage of "dumb" replication, shared by both OSTree and
-       the cloud model, is that it's <emphasis>reliable</emphasis>
-       and <emphasis>predictable</emphasis>.
-      </para>
-      <para>
-       But unlike many default image-based deployments, OSTree
-       supports a persistent, writable <literal>/etc</literal> that
-       is preserved across upgrades.
-      </para>
-      <para>
-       Because OSTree operates at the Unix filesystem layer, it works
-       on top of any filesystem or block storage layout; it's
-       possible to replicate a given filesystem tree from an OSTree
-       repository into both a BTRFS disk and an XFS-on-LVM
-       deployment.  Note: OSTree will transparently take advantage of
-       some BTRFS features if deployed on it.
-      </para>
-    </simplesect>
+  </chapter>
+  
+  <chapter id="ostree-package-comparison">
+    <title>Comparison with "package managers"</title>
+    <para>
+      Because OSTree is designed for deploying core operating
+      systems, a comparison with traditional "package managers" such
+      as dpkg and rpm is illustrative.  Packages are traditionally
+      composed of partial filesystem trees with metadata and scripts
+      attached, and these are dynamically assembled on the client
+      machine, after a process of dependency resolution.
+    </para>
+    <para>
+      In contrast, OSTree only supports recording and deploying
+      <emphasis>complete</emphasis> (bootable) filesystem trees.  It
+      has no built-in knowledge of how a given filesystem tree was
+      generated or the origin of individual files, or dependencies,
+      descriptions of individual components.
+    </para>
+    <para>
+      The OSTree core emphasizes replicating read-only OS trees via
+      HTTP, and where the OS includes (if desired) an entirely
+      separate mechanism to install applications, stored in <filename
+      class='directory'>/var</filename> if they're system global, or
+      <filename class='directory'>/home</filename> for per-user
+      application installation.
+    </para>
+    <para>
+      However, it is entirely possible to use OSTree underneath a
+      package system, where the contents of <filename
+      class='directory'>/usr</filename> are computed on the client.
+      For example, when installing a package, rather than mutating the
+      currently running filesystem, the package manager could assemble
+      a new filesystem tree that includes the new package, record it
+      in the local OSTree repository, and then set it up for the next
+      boot.  To support this model, OSTree provides an
+      (introspectable) C shared library.
+    </para>
+  </chapter>
 
-    <simplesect id="ostree-atomic-parallel-installation">
-      <title>Atomic transitions between parallel-installable read-only filesystem trees</title>
-      <para>
-       Another deeply fundamental difference between both package
-       managers and image-based replication is that OSTree is
-       designed to parallel-install <emphasis>multiple
-       versions</emphasis> of multiple
-       <emphasis>independent</emphasis> operating systems.  OSTree
-       relies on a new toplevel <filename
-       class='directory'>ostree</filename> directory; it can in fact
-       parallel install inside an existing OS or distribution
-       occupying the physical <filename
-       class='directory'>/</filename> root.
-      </para>
-      <para>
-       On each client machine, there is an OSTree repository stored
-       in <filename class='directory'>/ostree/repo</filename>, and a
-       set of "deployments" stored in <filename
-       
class='directory'>/ostree/deploy/<replaceable>OSNAME</replaceable>/<replaceable>CHECKSUM</replaceable></filename>.
-       Each deployment is primarily composed of a set of hardlinks
-       into the repository.  This means each version is deduplicated;
-       an upgrade process only costs disk space proportional to the
-       new files, plus some constant overhead.
-      </para>
-      <para>
-       The model OSTree emphasizes is that the OS read-only content
-       is kept in the classic Unix <filename
-       class='directory'>/usr</filename>; it comes with code to
-       create a Linux read-only bind mount to prevent inadvertent
-       corruption.  There is exactly one <filename
-       class='directory'>/var</filename> writable directory shared
-       between each deployment for a given OS.  The OSTree core code
-       does not touch content in this directory; it is up to the code
-       in each operating system for how to manage and upgrade state.
-      </para>
-      <para>
-       Finally, each deployment has its own writable copy of the
-       configuration store <filename
-       class='directory'>/etc</filename>.  On upgrade, OSTree will
-       perform a basic 3-way diff, and apply any local changes to the
-       new copy, while leaving the old untouched.
-      </para>
-    </simplesect>
+  <chapter id="ostree-block-comparison">
+    <title>Comparison with block/image replication</title>
+    <para>
+      OSTree shares some similarity with "dumb" replication and
+      stateless deployments, such as the model common in "cloud"
+      deployments where nodes are booted from an (effectively)
+      readonly disk, and user data is kept on a different volumes.
+      The advantage of "dumb" replication, shared by both OSTree and
+      the cloud model, is that it's <emphasis>reliable</emphasis>
+      and <emphasis>predictable</emphasis>.
+    </para>
+    <para>
+      But unlike many default image-based deployments, OSTree
+      supports a persistent, writable <literal>/etc</literal> that
+      is preserved across upgrades.
+    </para>
+    <para>
+      Because OSTree operates at the Unix filesystem layer, it works
+      on top of any filesystem or block storage layout; it's possible
+      to replicate a given filesystem tree from an OSTree repository
+      into plain ext4, BTRFS, XFS, or in general any Unix-compatible
+      filesystem that supports hard links.  Note: OSTree will
+      transparently take advantage of some BTRFS features if deployed
+      on it.
+    </para>
+  </chapter>
+
+  <chapter id="ostree-atomic-parallel-installation">
+    <title>Atomic transitions between parallel-installable read-only filesystem trees</title>
+    <para>
+      Another deeply fundamental difference between both package
+      managers and image-based replication is that OSTree is
+      designed to parallel-install <emphasis>multiple
+      versions</emphasis> of multiple
+      <emphasis>independent</emphasis> operating systems.  OSTree
+      relies on a new toplevel <filename
+      class='directory'>ostree</filename> directory; it can in fact
+      parallel install inside an existing OS or distribution
+      occupying the physical <filename
+      class='directory'>/</filename> root.
+    </para>
+    <para>
+      On each client machine, there is an OSTree repository stored
+      in <filename class='directory'>/ostree/repo</filename>, and a
+      set of "deployments" stored in <filename
+      
class='directory'>/ostree/deploy/<replaceable>OSNAME</replaceable>/<replaceable>CHECKSUM</replaceable></filename>.
+      Each deployment is primarily composed of a set of hardlinks
+      into the repository.  This means each version is deduplicated;
+      an upgrade process only costs disk space proportional to the
+      new files, plus some constant overhead.
+    </para>
+    <para>
+      The model OSTree emphasizes is that the OS read-only content
+      is kept in the classic Unix <filename
+      class='directory'>/usr</filename>; it comes with code to
+      create a Linux read-only bind mount to prevent inadvertent
+      corruption.  There is exactly one <filename
+      class='directory'>/var</filename> writable directory shared
+      between each deployment for a given OS.  The OSTree core code
+      does not touch content in this directory; it is up to the code
+      in each operating system for how to manage and upgrade state.
+    </para>
+    <para>
+      Finally, each deployment has its own writable copy of the
+      configuration store <filename
+      class='directory'>/etc</filename>.  On upgrade, OSTree will
+      perform a basic 3-way diff, and apply any local changes to the
+      new copy, while leaving the old untouched.
+    </para>
   </chapter>
 </part>