0001-Documentation-patch.patch

From 59c9acddfa87a5391f088153994f607208be57c1 Mon Sep 17 00:00:00 2001
From: Will Leinweber <will@bitfission.com>
Date: Mon, 16 Nov 2009 00:25:27 -0600
Subject: [PATCH] Documentation patch
  * remove compiler from bootstrapping guide
  * add more detailed information on some of the bootstrapping stages
  * rename subtend to capi in most of the docs
  ** except the example in rubinius_spec.txt

---
 doc/bootstrapping.txt              |   37 +++++++++++++++++++++++++++++------
 doc/foreign_function_interface.txt |    2 +-
 doc/manifest.txt                   |    2 +-
 doc/rubinius_specs.txt             |    3 +-
 doc/vm/vm_interfaces.txt           |   14 +++++-------
 spec/README                        |    2 +-
 6 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/doc/bootstrapping.txt b/doc/bootstrapping.txt
index cae67ba..9ff51c4 100644
--- a/doc/bootstrapping.txt
+++ b/doc/bootstrapping.txt
@@ -1,9 +1,23 @@
 Bootstrapping is the process of building up functionality of the system until
-all Ruby code can be executed. There are eight stages to the bootstrap process:
+all Ruby code can be executed. There are seven stages to the bootstrap process:
 
 1.  VM: The virtual machine is able to load and execute bytecode, send messages
     (i.e. look up and execute methods), and all primitive functions are
     available, but not yet hooked up as Ruby methods.
+    
+    The Class class has to be manually set up this early in the process by
+    setting its class to be itself and its superclass to be Module. In
+    addition to Class and Module, a couple of other base classes are created
+    here including Object, Tuple, LookupTable, and MethodTable.
+    
+    Now that classes can be defined, 35 or so built in classes are told to
+    initialize themselves, symbols for top level methods (:object_id, :call,
+    :protected, etc) are created, basic exceptions are defined, and primitives
+    are registered. Finally IO gets hooked up.
+    
+    At this point there is enough defined behavior to begin to load up the
+    rest of the runtime kernel which is all defined in ruby. This has to be
+    done in several passes as the language grows.
 
 2.  alpha: This starts the loading of Ruby code. The ability to open classes
     and modules and define methods exists. The minimum functionality to
@@ -25,7 +39,9 @@ all Ruby code can be executed. There are eight stages to the bootstrap process:
     most of the kernel classes.
 
 4.  platform: The FFI (foreign function interface) system is implemented and
-    Ruby method interfaces to platform-specific functions are created
+    Ruby method interfaces to platform-specific functions are created.  Once
+    this is set up, platform specific things such as pointers, file access,
+    math, and POSIX commands are attached.
 
 5.  common: The vast majority of the Ruby core library classes are
     implemented. The Ruby core classes are kept as implementation-neutral as
@@ -36,12 +52,19 @@ all Ruby code can be executed. There are eight stages to the bootstrap process:
     implementation-specific versions of methods that override the versions
     provided in common are added.
 
-7.  compiler: The compiler files are loaded.
-
-8.  loader: The compiled version of kernel/loader.rb is run.
-
-The files in the kernel directories bootstrap, platform, common, delta, and
-compiler implement the respective bootstrapping stages above. The order in
+7.  loader: The compiled version of kernel/loader.rb is run.
+    
+    The final stage setups the life cycle of a ruby process. It starts by
+    connecting the VM to the system, sets up load paths, and reads
+    customization scripts from the home directory. It traps signals, and
+    processes command line arguments.
+    
+    After that, it either runs the script passed to it from the command line
+    or boots up the interactive ruby shell. When that finishes, it runs any
+    at_exit blocks that had been registered, finalizes all objects, and exits.
+
+The files in the kernel directories bootstrap, platform, common, and delta, 
+implement the respective bootstrapping stages above. The order in
 which these directories are loaded is specified in runtime/index.
 
 When an rbc file is loaded, code at the script level and in class or module
diff --git a/doc/foreign_function_interface.txt b/doc/foreign_function_interface.txt
index 85c7e5c..4c056e6 100644
--- a/doc/foreign_function_interface.txt
+++ b/doc/foreign_function_interface.txt
@@ -16,7 +16,7 @@ that it is not necessary to have anything compiled beforehand. FFI should be
 used to access the code outside of Rubinius, whether it is system libraries or
 some type of extension code, for example.
 
-There is also a specific Rubinius extension layer called Subtend.  It emulates
+There is also a specific Rubinius extension layer called Capi.  It emulates
 the extension interface of Ruby to allow old Ruby extensions to work with
 Rubinius.
 
diff --git a/doc/manifest.txt b/doc/manifest.txt
index d4f2880..34cc3aa 100644
--- a/doc/manifest.txt
+++ b/doc/manifest.txt
@@ -76,7 +76,7 @@ with a brief description of the contents of each.
 
 *   lib/ext/
 
-    C extensions that use Subtend (Ruby C-API).
+    C extensions that use Capi (Ruby C-API).
 
 *   mspec/
 
diff --git a/doc/rubinius_specs.txt b/doc/rubinius_specs.txt
index 81cf9c6..dc3c827 100644
--- a/doc/rubinius_specs.txt
+++ b/doc/rubinius_specs.txt
@@ -102,7 +102,8 @@ This directory contains Rubinius specific standard library classes (e.g.
 Actor, VMActor) and Rubinius specific behavior of methods of MatzRuby standard
 library classes.
 
-## Subtend
+## Capi
+(_Capi was formally called subtend_)
 
 Subtend is the Rubinius component that provides a C API compatible with MRI.
 Writing specs for the subtend functions involves writing a C extension. Review
diff --git a/doc/vm/vm_interfaces.txt b/doc/vm/vm_interfaces.txt
index 34a5c5a..637d2cb 100644
--- a/doc/vm/vm_interfaces.txt
+++ b/doc/vm/vm_interfaces.txt
@@ -3,7 +3,7 @@
 Rubinius provides three different mechanisms for interfacing with the VM:
 * Primitives
 * Foregin Function Interface (FFI)
-* Subtend
+* Capi
 
 === Primitives
 
@@ -36,18 +36,16 @@ additional details on how to use FFI.
 FFI should be used whenever access to an external library is required from
 Ruby.
 
-=== Subtend
+=== Capi
 
-Subtend is the MRI-compatible C interface that allows external code to call
+Capi is the MRI-compatible C interface that allows external code to call
 Ruby code running on Rubinius. It is provided so that external libraries
 written to the MRI C-interface can work with Rubinius, with only a re-compile
-required. See
-here[http://blog.fallingsnow.net/2007/03/06/subtend-version-1-is-in/] for more
-information.
+required.
 
 ==== When to Use
 
-Subtend should be used when external code needs to interact with Ruby code.
-Unlike the other two interfaces, Subtend is an inbound interface to
+Capi should be used when external code needs to interact with Ruby code.
+Unlike the other two interfaces, Capi is an inbound interface to
 Ruby/Rubinius.
 
diff --git a/spec/README b/spec/README
index 82b78a2..4780a79 100644
--- a/spec/README
+++ b/spec/README
@@ -39,7 +39,7 @@ spec
  |                + -- ...
  |                + -- time
  |                + -- yaml
- |-- subtend
+ |-- capi
  |     +-- ext
  +-- tags
 
-- 
1.6.4