--- a/README	Wed Dec 07 16:09:12 2011 -0800
+++ b/README	Wed Dec 07 16:11:42 2011 -0800
@@ -24,14 +24,15 @@
 will be contributed by the community in an open collaboration
 process.
 
-Contributing to the ns-3 project is still a very informal
-process because that process depends heavily on the background
-of the people involved, the amount of time they can invest
-and the type of model they want to work on.  
+The process of contributing to the ns-3 project varies with
+the people involved, the amount of time they can invest
+and the type of model they want to work on, but the current
+process that the project tries to follow is described here:
+http://www.nsnam.org/developers/contributing-code/
 
-Despite this lack of a formal process, there are a number of 
-steps which naturally stem from the open-source roots of the
-project.  These steps are described in doc/contributing.txt
+This README excerpts some details from a more extensive
+tutorial that is maintained at:
+http://www.nsnam.org/documentation/latest/
 
 2) Building ns-3
 ----------------
@@ -47,9 +48,13 @@
 included in the file doc/build.txt
 
 However, the real quick and dirty way to get started is to
-type the command "./waf configure; ./waf" the the directory which contains
+type the command
+  ./waf configure --enable-examples
+followed by
+  ./waf 
+in the the directory which contains
 this README file. The files built will be copied in the
-build/debug or build/optimized.
+build/ directory.
 
 The current codebase is expected to build and run on the
 set of platforms listed in the RELEASE_NOTES file.
@@ -60,15 +65,16 @@
 3) Running ns-3
 ---------------
 
-On recent Linux systems, once you have built ns-3, it 
-should be easy to run the sample programs with the
-following command:
+On recent Linux systems, once you have built ns-3 (with examples
+enabled), it should be easy to run the sample programs with the
+following command, such as:
 
-./waf --run simple-global-routing
+  ./waf --run simple-global-routing
 
 That program should generate a simple-global-routing.tr text 
 trace file and a set of simple-global-routing-xx-xx.pcap binary
 pcap trace files, which can be read by tcpdump -tt -r filename.pcap
+The program source can be found in the examples/routing directory.
 
 4) Getting access to the ns-3 documentation
 -------------------------------------------
@@ -79,18 +85,19 @@
 some ns-3 documentation. 
 
 All of that documentation should always be available from
-the ns-3 website: http:://www.nsnam.org/ but we
-include some of it in this release for ease of use.
+the ns-3 website: http:://www.nsnam.org/documentation/.
 
 This documentation includes:
 
   - a tutorial
  
-  - a manual
+  - a reference manual
+
+  - models in the ns-3 model library
 
   - a wiki for user-contributed tips: http://www.nsnam.org/wiki/
 
-  - an API documentation generated using doxygen: this is
+  - API documentation generated using doxygen: this is
     a reference manual, most likely not very well suited 
     as introductory text:
     http://www.nsnam.org/doxygen/index.html

--- a/doc/build.txt	Wed Dec 07 16:09:12 2011 -0800
+++ b/doc/build.txt	Wed Dec 07 16:11:42 2011 -0800
@@ -23,28 +23,28 @@
 
 To see valid configure options, type ./waf --help.  The most important
 option is -d <debug level>.  Valid debug levels (which are listed in
-waf --help) are: "debug" or "optimized".  It is
+waf --help) are: "debug" or "optimized", with debug being default.  It is
 also possible to change the flags used for compilation with (e.g.):
-CXXFLAGS="-O3" ./waf configure.
+CXXFLAGS="-O3" ./waf configure.  By default, ns-3 is built as debug code, 
+with examples and tests disabled, and with python bindings enabled.  
 
 [ Note:  Unlike some other build tools, to change the build target,
 the option must be supplied during the configure stage rather than
 the build stage (i.e., "./waf -d optimized" will not work; instead, do
 "./waf -d optimized configure; ./waf" ]
 
-The resulting binaries are placed in build/<debuglevel>/srcpath.
+The resulting executables and libraries are placed in build/.
 
 Other waf usages include:
 
  1. ./waf configure --enable-examples --enable-tests
     Turn on examples and tests.
 
- 2. ./waf --doxygen
-    Run doxygen to generate documentation
+ 2. ./waf configure --disable-python
+    Disable python bindings.
 
- 3. ./waf --lcov-report
-    Run code coverage analysis (assuming the project was configured
-with --enable-gcov)
+ 3. ./waf --doxygen
+    Run doxygen to generate documentation
 
  4. ./waf --run "program [args]"
     Run a ns3 program, given its target name, with the given
@@ -79,29 +79,29 @@
   1. Create the module directory under src;
   2. Add the source files to it;
   3. Add a 'wscript' describing it;
-  4. Add the module subdirectory name to the all_modules list in src/wscript.
+
+A convenience program to auto-generate the template of a new module can
+be found in src/create-module.py.
 
 A module's wscript file is basically a regular Waf script.  A ns-3
 module is created as a cpp/shlib object, like this:
 
 def build(bld):
-    obj = bld.create_obj('cpp', 'shlib')
-
-    ## set module name; by convention it starts with ns3-
-    obj.name = 'ns3-mymodule'
-    obj.target = obj.name 
-
-    ## list dependencies to other modules
-    obj.uselib_local = ['ns3-core'] 
+    module = bld.create_ns3_module('ns3-mymodule', ['core'])
+    module.source = [
+        'model/ns3-mymodule.cc',
+        'helper/ns3-mymodule-helper.cc',
+        ]
 
-    ## list source files (private or public header files excluded)
-    obj.source = [
-        'mymodule.cc',
-    ]
+    headers = bld.new_task_gen(features=['ns3header'])
+    headers.module = 'ns3-mymodule'
+    headers.source = [
+        'model/ns3-mymodule.h',
+        'helper/ns3-mymodule-helper.h',
+        ]
 
-    ## list module public header files
-    headers = bld.create_obj('ns3header')
-    headers.source = [
-        'mymodule-header.h',
-    ]
+    if bld.env.ENABLE_EXAMPLES:
+        bld.add_subdirs('examples')
 
+    # bld.ns3_python_bindings()
+