--- a/README	Fri Oct 15 16:14:01 2010 -0500
+++ b/README	Fri Oct 15 16:15:38 2010 -0500
@@ -2,46 +2,97 @@
 	    Getting started with the Userland Consolidation
 
 
-Building the bits
+Getting Started
+
+    This README provides a very brief overview of the gate, how to retrieve
+    a copy, and how to build it.  Detailed documentation about the Userland
+    gate can be found in the 'doc' directory.  Questions or comments about
+    the gate can be addressed to [email protected].
+
+Overview
 
     The Userland consolidation maintains a Mercurial gate at
-    
+
         ssh://[email protected]//hg/userland/gate
-        
+
     This gate contains build recipies, patches, IPS manifests, etc. necessary
     to download, prep, build, test, package and publish open source software.
-    In order to build the contents of the Userland gate, you need to clone it.
-    Since you are reading this, you probably already have, but in any event
-    you can do so with the following command
-    
-    $ hg clone ssh://[email protected]//hg/userland/gate /scratch/clone
-    
-    In order to build the bits either individually or collectively, you must
-    set the WS_TOP environment variable to point to the top of your workspace.
-    
-    $ export WS_TOP=/scratch/clone
-    
-    To build and publish the entire contents of the gate, you can use
-    
-    $ cd /scratch/clone
-    $ gmake publish
+    The build infrastructure is similiar to that of the SFW consolidation in
+    that it makes use of herarchical Makefiles which provide dependency and
+    recipe information for building the components.  In order to build the
+    contents of the Userland gate, you need to clone it.  Since you are
+    reading this, you probably already have.
+
+Getting the Bits
+
+    As mentioned, the gate is stored in a Mercurial repository.  In order to
+    build or develop in the gate, you will need to clone it.  You can do so
+    with the following command
     
-    To build and publish a specific component you need to initialize the
-    workspace by building the tools and creating a repository to publish
-    your results in.  The easiest way to do this is to
-    
-    $ cd /scratch/clone
-    $ gmake setup
-    
-    Once you have initialize the the workspace, you can build individual
-    components by
-    
-    $ cd /scratch/clone/components/(component)
-    $ gmake publish
-    
-    All of the bits are are built will be published to the repository created
-    by the setup step (file:///scratch/clone/repo/)  If you build the entire
-    contents of the gate, individual build logs for each component will be
-    located at /scratch/clone/logs/(target):(component).log
+      $ hg clone ssh://[email protected]//hg/userland/gate /scratch/clone
+
+    This will create a replica of the various pieces that are checked into the
+    source code management system, but it does not retrieve the community
+    source archives associated with the gate content.  To download the
+    community source associated with your cloned workspace, you will need to
+    execute the following:
+
+      $ export WS_TOP=/scratch/clone
+      $ cd /scratch/clone/components
+      $ gmake download
+
+    This will use GNU make and the downloading tool in the gate to walk through
+    all of the component directories downloading and validating the community
+    source archives from the gate machine or their canonical source repository.
+
+    There are two variation to this that you may find interesting.  First, you
+    can cause gmake(1) to perform it's work in parallel by adding '-j (jobs)'
+    to the command line.  Second, if you are only interested in working on a
+    particular component, you can change directories to that component's
+    directory and use 'gmake download' from that to only get it's source
+    archive.
+
+Building the Bits.
+
+    You can build individual components or the contents of the entire gate.
+    Regardless of how you build the gate, you must set WS_TOP in the calling
+    environment to point to the top of your workspace. Ex:
+
+      $ export WS_TOP=/scratch/clone
+
+  Component build
 
+    If you are only working on a single component, you can just build it using
+    following:
 
+      setup the workspace for building components
+
+        $ cd ${WS_TOP}/components ; gmake setup
+
+      build the individual component
+
+        $ cd (component-dir) ; gmake publish
+
+  Complete Top Down build  
+
+    Complete top down builds are also possible by simply running
+
+      $ cd ${WS_TOP}/components
+      $ gmake package-install
+
+    The 'package-install' target will build each component, publish it to the
+    workspace IPS repo and install it in the running environment.  As a result,
+    it is strongly recommended that you only perform complete top down builds
+    in a zone.  Tools to help facilitate build zone creation will be integrated
+    shortly.  If the zone you create to build your workspace in does not have
+    networking enabled, you can pre-download any community source archives into
+    your workspace from the global with:
+
+      $ cd ${WS_TOP}/components
+      $ gmake download
+
+  You can add parallelism to your builds by adding '-j (jobs)' to your gmake
+  command line arguments.
+
+  The gate should only incrementally build what it needs to based on what has
+  changed since you last built it.