Bringing README up to date and filling in some ...

Bringing README up to date and filling in some of the info gaps. Review
by cunei.

1 files changed, 25 insertions, 18 deletions

diff --git a/README b/README
index 5bf8d51e0c..9a39a8a8fe 100644
--- a/README
+++ b/README
@@ -12,9 +12,10 @@ Part I. The repository layout
 
 Follows the file layout of the Scala repository. Files marked with a † are not
 part of the Subversion repository but are either automatically generated by the
-build script or user-created if needed.
+build script or user-created if needed.  This is not a complete listing.
 
 scala/
+      bin/                      Developer utilities.
       build/ †                  Temporary staging area for build products.
       build.excludes †          An optional build configuration file.
       build.number              The version number of the current distribution.
@@ -23,24 +24,24 @@ scala/
       dist/ †                   The destination folder of Scala distributions.
       docs/                     Documentation of Scala. More in its own module.
            development/         Developer documentation.
-           examples/            Scala example files.
-           man/                 UNIX manual files.
+           examples/            Scala source code examples.
       lib/                      Pre-compiled libraries for the build.
           fjbg.jar              The Java byte-code generation library.
-          scala-compiler.jar    The last stable version of the Scala compiler.
-          scala-library.jar     The last stable version of the Scala library.
+          scala-compiler.jar    The stable reference version (aka 'starr') of the Scala compiler
+          scala-library.jar     The stable reference version (aka 'starr') of the Scala library.
+          scala-library-src.jar A snapshot of the source code which was used to build starr.
           ant/                  Support libraries for the build tool.
               ant-contrib.jar   Provides additional features for Ant
               vizant.jar        Provides DOT graph generation for Ant
       README                    The file you are currently reading.
       sandbox/ †                A folder to test code etc.
       src/                      All the source files of Scala.
+          actors/               The sources of the Actor library.
           compiler/             The sources of the Scala compiler.
-          library/              The sources of the Scala library.
+          library/              The sources of the core Scala library.
+          swing/                The sources of the Swing library.
       test/                     The Scala test suite.
 
-Any change to this structure requires a modification of the 'build.xml' file.
-
 Part IV. Building Scala with SABBUS
 --------------------------------------------------------------------------------
 
@@ -50,7 +51,7 @@ LAYERS:
 
 In order to guarantee the bootstrapping of the Scala compiler, SABBUS builds Scala in layers. Each layer is a complete compiled Scala compiler and library. A superior layer is always compiled by the layer just below it. Here is a short description of the four layers that SABBUS uses, from bottom to top:
 
-'starr': the stable reference Scala release which is shared by all the developers. It is found in the repository as 'lib/scala.compiler.jar' and 'lib/scala-library.jar'. Any committable source code must be compiled directly by starr to guarantee the bootstrapping of the compiler.
+'starr': the stable reference Scala release which is shared by all the developers. It is found in the repository as 'lib/scala-compiler.jar' and 'lib/scala-library.jar'. Any committable source code must be compiled directly by starr to guarantee the bootstrapping of the compiler.
 
 'locker': the local reference which is compiled by starr and is the work compiler in a typical development cycle. When it has been built once, it is “frozen” in this state. Updating it to fit the current source code must be explicitly required (see below).
 
@@ -60,7 +61,7 @@ In order to guarantee the bootstrapping of the Scala compiler, SABBUS builds Sca
 
 DEPENDANT CHANGES:
 
-SABBUS compiles, for each layer, the Scala library first and the compiler next. That means that any changes in the library can immediately be used in the compiler without an intermediate build. On the other hand, if building the library requires changes in the compiler a new starr (or in some case only locker if bootstrapping is still possible) compiler must be built in-between.
+SABBUS compiles, for each layer, the Scala library first and the compiler next. That means that any changes in the library can immediately be used in the compiler without an intermediate build. On the other hand, if building the library requires changes in the compiler, a new locker must be built if bootstrapping is still possible, or a new starr if it is not.
 
 Part III. Requirements for SABBUS
 --------------------------------------------------------------------------------
@@ -73,30 +74,34 @@ Part IV. Common use-cases
 --------------------------------------------------------------------------------
 
 'ant -p'
-  Prints-out information about all available targets in the build script.
+  Prints out information about the commonly used ant targets.  The interested developer can find the rest in the xml files.
 
 'ant' or 'ant build'
   A quick compilation (to quick) of your changes using the locker compiler.
     - This will rebuild all quick if locker changed.
     - This will also rebuild locker if starr changed.
 
-'ln -s build/quick/bin bin' (once)
-'ant && bin/scalac -d sandbox sandbox/test.scala && bin/scala -cp sandbox Test'
+'ln -s build/quick/bin qbin' (once)
+'ant && qbin/scalac -d sandbox sandbox/test.scala && qbin/scala -cp sandbox Test'
   Incrementally builds quick, and then uses it to compile and run the file
   'sandbox/test.scala'. This is a typical debug cycle.
 
-'ant newlocker'
+'ant replacelocker'
   "unfreezes" locker by updating it to match the current source code.
     - This will delete quick so as not to mix classes compiled with different
       versions of locker.
 
 'ant test'
   Tests that your code is working and fit to be committed.
-    - Runs the test suite on quick.
+    - Runs the test suite and bootstrapping test on quick.
+    - You can run the suite only (skipping strap) with 'ant test.suite'.
 
 'ant docs'
   Generates the HTML documentation for the library from the sources using the
-  scaladoc tool in quick.
+  scaladoc tool in quick.  Note: on most machines this requires more heap than
+  is allocate by default.  You can adjust the parameters with ANT_OPTS.
+  Example command line:
+    ANT_OPTS="-Xms512M -Xmx2048M -Xss1M -XX:MaxPermSize=128M" ant docs
 
 'ant dist'
   Builds a distribution.
@@ -115,7 +120,9 @@ Part IV. Common use-cases
 'ant all.clean'
   Removes all build files (including locker) and all distributions.
 
-Additional ant targets can be seen via 'ant -p'.
+Many of these targets offer a variant which runs with -optimise enabled.
+Optimized targets include build-opt, test-opt, dist-opt, fastdist-opt,
+replacestarr-opt, replacelocker-opt, and distpack-opt.
 
 Part V. Contributing to Scala
 --------------------------------------------------------------------------------
@@ -124,7 +131,7 @@ If you wish to contribute, you can find all of the necessary information on
 the official Scala website: www.scala-lang.org.
 
 Specifically, you can subscribe to the Scala mailing lists, read all of the
-available documentation, and browse the live SVN repository. You can contact
+available documentation, and browse the live SVN repository.  You can contact
 the Scala team by sending us a message on one of the mailing lists, or by using
 the available contact form.