From 39e4c7c6fe3f733eac715db202a97d6c2c1e5d22 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Fri, 20 Jun 2014 11:59:49 -0400
Subject: [PATCH] doc: Update overview a bit

Link to docker, note in introductory paragraph the goal of package
composition on a server.
---
 doc/overview.xml | 44 ++++++++++++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/doc/overview.xml b/doc/overview.xml
index f2273068..94bf9c78 100644
--- a/doc/overview.xml
+++ b/doc/overview.xml
@@ -8,19 +8,27 @@
   <chapter id="ostree-intro">
     <title>Introduction</title>
     <para>
-      OSTree is best summarized in a single sentence as "git for
-      operating system binaries".  At its core architecture is a
-      userspace content-addressed filesystem, and layered on top of
-      that is an administrative layer that is designed to atomically
-      parallel install multiple bootable Unix-like operating systems.
+      OSTree an upgrade system for Linux-based operating systems that
+      performs atomic upgrades of complete filesystem trees.  It is
+      not a package system; rather, it is intended to complement them.
+      A primary model is composing packages on a server, and then
+      replicating them to clients.
+    </para>
+
+    <para>
+      The underlying architecture might be summarized as "git for
+      operating system binaries".  It operates in userspace, and will
+      work on top of any Linux filesystem.  At its core is a git-like
+      content-addressed object store, and layered on top of that is
+      bootloader configuration, management of
+      <filename>/etc</filename>, and other functions to perform an
+      upgrade beyond just replicating files.
     </para>
     
     <para>
-      While it takes over some of the roles of tradtional "package
-      managers" like dpkg and rpm, it is <emphasis>not</emphasis> a
-      package system; nor is it a tool for managing full disk
-      images. Instead, OSTree sits between those levels, offering a
-      blend of the advantages (and disadvantages) of both.
+      You can use OSTree standalone in the pure replication model,
+      but another approach is to add a package manager on top,
+      thus creating a hybrid tree/package system.
     </para>
 
   </chapter>
@@ -35,6 +43,7 @@
       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
@@ -48,24 +57,27 @@
       included in your tree, so you should support the equivalent of
       <command>rpm -q</command> or <command>dpkg -L</command>.
     </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.
+      application installation.  An example application mechanism is
+      <ulink url="http://docker.io/">Docker</ulink>.
     </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
+      For example, when installing a package, rather than changing 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.
+      a new filesystem tree that layers the new packages on top of a
+      base tree, 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>