[ostree] docs: Add an overview section, migrate some content from the wiki

[Colin Walters <walters src gnome org>]

commit 75cd17d9d9e75f06e67788c0db9315a353c0e913
Author: Colin Walters <walters verbum org>
Date:   Sat Aug 17 09:22:08 2013 -0400

    docs: Add an overview section, migrate some content from the wiki

 doc/Makefile.am                                    |    8 +-
 doc/{libostree-docs.xml => ostree-docs.xml}        |    4 +-
 ...{libostree-sections.txt => ostree-sections.txt} |    0
 doc/overview.xml                                   |  131 ++++++++++++++++++++
 4 files changed, 139 insertions(+), 4 deletions(-)
---
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 38bc5de..b5acad6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -25,7 +25,7 @@ NULL =
 AUTOMAKE_OPTIONS = 1.6
 
 # The name of the module, e.g. 'glib'.
-DOC_MODULE=libostree
+DOC_MODULE=ostree
 
 # The top-level SGML file. You can change this if you want to.
 DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
@@ -73,7 +73,9 @@ HTML_IMAGES=
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=$(NULL)
+content_files= \
+       overview.xml \
+       $(NULL)
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -90,7 +92,7 @@ expand_content_files= \
 GTKDOC_LIBS=
 
 # Hacks around gtk-doc brokenness for out of tree builds
-libostree-sections.txt: $(srcdir)/libostree-sections.txt
+ostree-sections.txt: $(srcdir)/ostree-sections.txt
        cp $< $@
 
 version.xml:
diff --git a/doc/libostree-docs.xml b/doc/ostree-docs.xml
similarity index 90%
rename from doc/libostree-docs.xml
rename to doc/ostree-docs.xml
index 5fdd3d8..71561ac 100644
--- a/doc/libostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -7,10 +7,12 @@
 ]>
 <book id="index">
        <bookinfo>
-               <title>libostree</title>
+               <title>OSTree Manual</title>
                <releaseinfo>for OSTree &version;</releaseinfo>
        </bookinfo>
 
+       <xi:include href="overview.xml"/>
+
        <chapter xml:id="reference">
                <title>API Reference</title>
                <xi:include href="xml/libostree-core.xml"/>
diff --git a/doc/libostree-sections.txt b/doc/ostree-sections.txt
similarity index 100%
rename from doc/libostree-sections.txt
rename to doc/ostree-sections.txt
diff --git a/doc/overview.xml b/doc/overview.xml
new file mode 100644
index 0000000..2c8e957
--- /dev/null
+++ b/doc/overview.xml
@@ -0,0 +1,131 @@
+<?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"; [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="overview">
+  <title>OSTree Overview</title>
+  <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.
+    </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.
+    </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>
+
+    <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>
+</part>