RubyGems - rake - Versions diffs - 0.4.11 → 0.8.7 - Mend

rake 0.4.11 → 0.8.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

data/CHANGES +288 -1
data/README +101 -114
data/Rakefile +269 -54
data/TODO +1 -0
data/bin/rake +26 -3
data/doc/command_line_usage.rdoc +102 -0
data/doc/jamis.rb +133 -106
data/doc/rake.1.gz +0 -0
data/doc/rakefile.rdoc +304 -4
data/doc/release_notes/rake-0.4.14.rdoc +23 -0
data/doc/release_notes/rake-0.4.15.rdoc +35 -0
data/doc/release_notes/rake-0.5.0.rdoc +53 -0
data/doc/release_notes/rake-0.5.3.rdoc +78 -0
data/doc/release_notes/rake-0.5.4.rdoc +46 -0
data/doc/release_notes/rake-0.6.0.rdoc +141 -0
data/doc/release_notes/rake-0.7.0.rdoc +119 -0
data/doc/release_notes/rake-0.7.1.rdoc +59 -0
data/doc/release_notes/rake-0.7.2.rdoc +121 -0
data/doc/release_notes/rake-0.7.3.rdoc +47 -0
data/doc/release_notes/rake-0.8.0.rdoc +114 -0
data/doc/release_notes/rake-0.8.2.rdoc +165 -0
data/doc/release_notes/rake-0.8.3.rdoc +112 -0
data/doc/release_notes/rake-0.8.4.rdoc +147 -0
data/doc/release_notes/rake-0.8.5.rdoc +53 -0
data/doc/release_notes/rake-0.8.6.rdoc +55 -0
data/doc/release_notes/rake-0.8.7.rdoc +55 -0
data/lib/rake/alt_system.rb +108 -0
data/lib/rake/classic_namespace.rb +8 -0
data/lib/rake/clean.rb +3 -1
data/lib/rake/contrib/ftptools.rb +40 -26
data/lib/rake/contrib/publisher.rb +1 -1
data/lib/rake/contrib/rubyforgepublisher.rb +3 -3
data/lib/rake/contrib/sshpublisher.rb +1 -1
data/lib/rake/contrib/sys.rb +25 -23
data/lib/rake/gempackagetask.rb +14 -15
data/lib/rake/loaders/makefile.rb +42 -0
data/lib/rake/packagetask.rb +65 -33
data/lib/rake/rake_test_loader.rb +5 -0
data/lib/rake/rdoctask.rb +112 -31
data/lib/rake/ruby182_test_unit_fix.rb +23 -0
data/lib/rake/runtest.rb +4 -4
data/lib/rake/tasklib.rb +11 -12
data/lib/rake/testtask.rb +67 -24
data/lib/rake/win32.rb +55 -0
data/lib/rake.rb +2087 -578
data/test/capture_stdout.rb +26 -0
data/test/check_expansion.rb +5 -0
data/test/check_no_expansion.rb +5 -0
data/test/data/chains/Rakefile +15 -0
data/test/data/default/Rakefile +19 -0
data/test/data/dryrun/Rakefile +22 -0
data/test/data/file_creation_task/Rakefile +33 -0
data/test/data/imports/Rakefile +19 -0
data/test/data/imports/deps.mf +1 -0
data/test/data/multidesc/Rakefile +17 -0
data/test/data/namespace/Rakefile +57 -0
data/test/data/rakelib/test1.rb +3 -0
data/test/data/sample.mf +14 -0
data/test/data/statusreturn/Rakefile +8 -0
data/test/data/unittest/Rakefile +1 -0
data/test/filecreation.rb +18 -12
data/test/functional.rb +6 -73
data/test/in_environment.rb +30 -0
data/test/rake_test_setup.rb +24 -0
data/test/reqfile.rb +3 -0
data/test/reqfile2.rb +3 -0
data/test/session_functional.rb +339 -0
data/test/shellcommand.rb +0 -0
data/test/test_application.rb +675 -0
data/test/{testclean.rb → test_clean.rb} +1 -0
data/test/test_definitions.rb +85 -0
data/test/test_earlytime.rb +35 -0
data/test/test_extension.rb +63 -0
data/test/test_file_creation_task.rb +62 -0
data/test/test_file_task.rb +143 -0
data/test/test_filelist.rb +623 -0
data/test/test_fileutils.rb +251 -0
data/test/{testftp.rb → test_ftp.rb} +5 -1
data/test/test_invocation_chain.rb +81 -0
data/test/test_makefile_loader.rb +26 -0
data/test/test_multitask.rb +45 -0
data/test/test_namespace.rb +55 -0
data/test/{testpackagetask.rb → test_package_task.rb} +49 -12
data/test/test_pathmap.rb +210 -0
data/test/test_pseudo_status.rb +26 -0
data/test/test_rake.rb +41 -0
data/test/test_rdoc_task.rb +88 -0
data/test/test_require.rb +35 -0
data/test/test_rules.rb +349 -0
data/test/test_task_arguments.rb +89 -0
data/test/test_task_manager.rb +173 -0
data/test/test_tasklib.rb +12 -0
data/test/test_tasks.rb +374 -0
data/test/{testtesttask.rb → test_test_task.rb} +8 -2
data/test/test_top_level_functions.rb +86 -0
data/test/test_win32.rb +72 -0
metadata +184 -84
data/test/testfilelist.rb +0 -255
data/test/testfileutils.rb +0 -83
data/test/testtasks.rb +0 -371
/data/test/contrib/{testsys.rb → test_sys.rb} +0 -0

data/doc/jamis.rb CHANGED Viewed

@@ -182,30 +182,39 @@ h3, h4, h5, h6 {
 CSS
-BODY = <<HTML
+XHTML_PREAMBLE = %{<?xml version="1.0" encoding="%charset%"?>
+<!DOCTYPE html
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+}
+HEADER = XHTML_PREAMBLE + <<ENDHEADER
 <html>
   <head>
     <title>%title%</title>
     <meta http-equiv="Content-Type" content="text/html; charset=%charset%" />
     <link rel="stylesheet" href="%style_url%" type="text/css" media="screen" />
-    <script type="text/javascript" language="JavaScript">
-      <!--
+    <script language="JavaScript" type="text/javascript">
+    // <![CDATA[
         function toggleSource( id )
         {
           var elem
           var link
-          if( document.all )
+          if( document.getElementById )
+          {
+            elem = document.getElementById( id )
+            link = document.getElementById( "l_" + id )
+          }
+          else if ( document.all )
           {
             elem = eval( "document.all." + id )
             link = eval( "document.all.l_" + id )
           }
           else
-          {
-            elem = document.getElementById( id )
-            link = document.getElementById( "l_" + id )
-          }
+            return false;
           if( elem.style.display == "block" )
           {
@@ -223,89 +232,12 @@ BODY = <<HTML
         {
           window.open( url, "SOURCE_CODE", "width=400,height=400,scrollbars=yes" )
         }
-      //-->
+      // ]]>
     </script>
   </head>
   <body>
-!INCLUDE! <!-- banner header -->
-  <div id="content">
-IF:diagram
-  <table cellpadding='0' cellspacing='0' border='0' width="100%"><tr><td align="center">
-    %diagram%
-  </td></tr></table>
-ENDIF:diagram
-IF:description
-  <div class="description">%description%</div>
-ENDIF:description
-IF:requires
-  <div class="sectiontitle">Required Files</div>
-  <ul>
-START:requires
-  <li>HREF:aref:name:</li>
-END:requires
-  </ul>
-ENDIF:requires
-IF:methods
-  <div class="sectiontitle">Methods</div>
-  <ul>
-START:methods
-  <li>HREF:aref:name:</li>
-END:methods
-  </ul>
-ENDIF:methods
-IF:constants
-  <div class="sectiontitle">Constants</div>
-  <table border='0' cellpadding='5'>
-START:constants
-  <tr valign='top'>
-    <td class="attr-name">%name%</td>
-    <td>=</td>
-    <td class="attr-value">%value%</td>
-  </tr>
-IF:desc
-  <tr valign='top'>
-    <td>&nbsp;</td>
-    <td colspan="2" class="attr-desc">%desc%</td>
-  </tr>
-ENDIF:desc
-END:constants
-  </table>
-ENDIF:constants
-IF:attributes
-  <div class="sectiontitle">Attributes</div>
-  <table border='0' cellpadding='5'>
-START:attributes
-  <tr valign='top'>
-    <td class='attr-rw'>
-IF:rw
-[%rw%]
-ENDIF:rw
-    </td>
-    <td class='attr-name'>%name%</td>
-    <td class='attr-desc'>%a_desc%</td>
-  </tr>
-END:attributes
-  </table>
-ENDIF:attributes
-IF:classlist
-  <div class="sectiontitle">Classes and Modules</div>
-  %classlist%
-ENDIF:classlist
-!INCLUDE! <!-- method descriptions -->
-    </div>
-  </body>
-</html>
-HTML
+ENDHEADER
 FILE_PAGE = <<HTML
 <table border='0' cellpadding='0' cellspacing='0' width="100%" class='banner'>
@@ -318,7 +250,7 @@ FILE_PAGE = <<HTML
             <td>Path:</td>
             <td>%full_path%
 IF:cvsurl
-				&nbsp;(<a href="%cvsurl%">CVS</a>)
+              &nbsp;(<a href="%cvsurl%">CVS</a>)
 ENDIF:cvsurl
             </td>
           </tr>
@@ -374,6 +306,44 @@ HTML
 ###################################################################
 METHOD_LIST = <<HTML
+  <div id="content">
+IF:diagram
+  <table cellpadding='0' cellspacing='0' border='0' width="100%"><tr><td align="center">
+    %diagram%
+  </td></tr></table>
+ENDIF:diagram
+IF:description
+  <div class="description">%description%</div>
+ENDIF:description
+IF:requires
+  <div class="sectiontitle">Required Files</div>
+  <ul>
+START:requires
+  <li>HREF:aref:name:</li>
+END:requires
+  </ul>
+ENDIF:requires
+IF:toc
+  <div class="sectiontitle">Contents</div>
+  <ul>
+START:toc
+  <li><a href="#%href%">%secname%</a></li>
+END:toc
+  </ul>
+ENDIF:toc
+IF:methods
+  <div class="sectiontitle">Methods</div>
+  <ul>
+START:methods
+  <li>HREF:aref:name:</li>
+END:methods
+  </ul>
+ENDIF:methods
 IF:includes
 <div class="sectiontitle">Included Modules</div>
 <ul>
@@ -383,6 +353,57 @@ END:includes
 </ul>
 ENDIF:includes
+START:sections
+IF:sectitle
+<div class="sectiontitle"><a nem="%secsequence%">%sectitle%</a></div>
+IF:seccomment
+<div class="description">
+%seccomment%
+</div>
+ENDIF:seccomment
+ENDIF:sectitle
+IF:classlist
+  <div class="sectiontitle">Classes and Modules</div>
+  %classlist%
+ENDIF:classlist
+IF:constants
+  <div class="sectiontitle">Constants</div>
+  <table border='0' cellpadding='5'>
+START:constants
+  <tr valign='top'>
+    <td class="attr-name">%name%</td>
+    <td>=</td>
+    <td class="attr-value">%value%</td>
+  </tr>
+IF:desc
+  <tr valign='top'>
+    <td>&nbsp;</td>
+    <td colspan="2" class="attr-desc">%desc%</td>
+  </tr>
+ENDIF:desc
+END:constants
+  </table>
+ENDIF:constants
+IF:attributes
+  <div class="sectiontitle">Attributes</div>
+  <table border='0' cellpadding='5'>
+START:attributes
+  <tr valign='top'>
+    <td class='attr-rw'>
+IF:rw
+[%rw%]
+ENDIF:rw
+    </td>
+    <td class='attr-name'>%name%</td>
+    <td class='attr-desc'>%a_desc%</td>
+  </tr>
+END:attributes
+  </table>
+ENDIF:attributes
 IF:method_list
 START:method_list
 IF:methods
@@ -415,8 +436,8 @@ END:aka
 ENDIF:aka
 IF:sourcecode
 <div class="sourcecode">
-  <p class="source-link">[ <a href="javascript:toggleSource('%aref%-source')" id="l_%aref%-source">show source</a> ]</p>
-  <div id="%aref%-source" class="dyn-source">
+  <p class="source-link">[ <a href="javascript:toggleSource('%aref%_source')" id="l_%aref%_source">show source</a> ]</p>
+  <div id="%aref%_source" class="dyn-source">
 <pre>
 %sourcecode%
 </pre>
@@ -428,14 +449,28 @@ END:methods
 ENDIF:methods
 END:method_list
 ENDIF:method_list
+END:sections
+</div>
 HTML
-=begin
-=end
+FOOTER = <<ENDFOOTER
+  </body>
+</html>
+ENDFOOTER
+BODY = HEADER + <<ENDBODY
+  !INCLUDE! <!-- banner header -->
+  <div id="bodyContent">
+    #{METHOD_LIST}
+  </div>
+  #{FOOTER}
+ENDBODY
 ########################## Source code ##########################
-SRC_PAGE = <<HTML
+SRC_PAGE = XHTML_PREAMBLE + <<HTML
 <html>
 <head><title>%title%</title>
 <meta http-equiv="Content-Type" content="text/html; charset=%charset%">
@@ -467,7 +502,7 @@ FR_INDEX_BODY = <<HTML
 !INCLUDE!
 HTML
-FILE_INDEX = <<HTML
+FILE_INDEX = XHTML_PREAMBLE + <<HTML
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=%charset%">
@@ -494,6 +529,7 @@ FILE_INDEX = <<HTML
   a {
     color: #00F;
     text-decoration: none;
+    white-space: nowrap;
   }
   a:hover {
     color: #77F;
@@ -516,8 +552,8 @@ HTML
 CLASS_INDEX = FILE_INDEX
 METHOD_INDEX = FILE_INDEX
-INDEX = <<HTML
-<html>
+INDEX = XHTML_PREAMBLE + <<HTML
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
   <title>%title%</title>
   <meta http-equiv="Content-Type" content="text/html; charset=%charset%">
@@ -549,16 +585,7 @@ ENDIF:inline_source
 </html>
 HTML
-# and a blank page to use as a target
-BLANK = %{
-<html><body bgcolor="white"></body></html>
-}
-def write_extra_pages
-  template = TemplatePage.new(BLANK)
-  File.open("blank.html", "w") { |f| template.write_html_on(f, {}) }
-end
 end
 end

data/doc/rake.1.gz ADDED Viewed

Binary file

data/doc/rakefile.rdoc CHANGED Viewed

@@ -1,4 +1,4 @@
-= Rakefile Format
+= Rakefile Format (as of version 0.8.3)
 First of all, there is no special format for a Rakefile.  A Rakefile
 contains executable Ruby code.  Anything legal in a ruby script is
@@ -110,6 +110,171 @@ both prerequisites and actions can be added later.  For example ...
     cp Dir["standard_data/*.data"], "testdata"
   end
+== Tasks with Parallel Prerequisites
+Rake allows parallel execution of prerequisites using the following syntax:
+  multitask :copy_files => [:copy_src, :copy_doc, :copy_bin] do
+    puts "All Copies Complete"
+  end
+In this example, +copy_files+ is a normal rake task.  Its actions are
+executed whereever all of its prerequisites are done.  The big
+difference is that the prerequisites (+copy_src+, +copy_bin+ and
++copy_doc+) are executed in parallel.  Each of the prerequisites are
+run in their own Ruby thread, possibly allowing faster overall runtime.
+=== Secondary Prerequisites
+If any of the primary prerequites of a multitask have common secondary
+prerequisites, all of the primary/parallel prerequisites will wait
+until the common prerequisites have been run.
+For example, if the <tt>copy_<em>xxx</em></tt> tasks have the
+following prerequisites:
+  task :copy_src => [:prep_for_copy]
+  task :copy_bin => [:prep_for_copy]
+  task :copy_doc => [:prep_for_copy]
+Then the +prep_for_copy+ task is run before starting all the copies in
+parallel.  Once +prep_for_copy+ is complete, +copy_src+, +copy_bin+,
+and +copy_doc+ are all run in parallel.  Note that +prep_for_copy+ is
+run only once, even though it is referenced in multiple threads.
+=== Thread Safety
+The Rake internal data structures are thread-safe with respect
+to the multitask parallel execution, so there is no need for the user
+to do extra synchronization for Rake's benefit.  However, if there are
+user data structures shared between the parallel prerequisites, the
+user must do whatever is necessary to prevent race conditions.
+== Tasks with Arguments
+Prior to version 0.8.0, rake was only able to handle command line
+arguments of the form NAME=VALUE that were passed into Rake via the
+ENV hash.  Many folks had asked for some kind of simple command line
+arguments, perhaps using "--" to separate regular task names from
+argument values on the command line.  The problem is that there was no
+easy way to associate positional arguments on the command line with
+different tasks.  Suppose both tasks :a and :b expect a command line
+argument: does the first value go with :a?  What if :b is run first?
+Should it then get the first command line argument.
+Rake 0.8.0 solves this problem by explicitly passing values directly
+to the tasks that need them.  For example, if I had a release task
+that required a version number, I could say:
+   rake release[0.8.2]
+And the string "0.8.2" will be passed to the :release task.  Multiple
+arguments can be passed by separating them with a comma, for example:
+   rake name[john,doe]
+Just a few words of caution.  The rake task name and its arguments
+need to be a single command line argument to rake.  This generally
+means no spaces.  If spaces are needed, then the entire rake +
+argument string should be quoted.  Something like this:
+   rake "name[billy bob, smith]"
+(Quoting rules vary between operating systems and shells, so make sure
+you consult the proper docs for your OS/shell).
+=== Tasks that Expect Parameters
+Parameters are only given to tasks that are setup to expect them.  In
+order to handle named parameters, the task declaration syntax for
+tasks has been extended slightly.
+For example, a task that needs a first name and last name might be
+declared as:
+   task :name, [:first_name, :last_name]
+The first argument is still the name of the task (:name in this case).
+The next to argumements are the names of the parameters expected by
+:name in an array (:first_name and :last_name in the example).
+To access the values of the paramters, the block defining the task
+behaviour can now accept a second parameter:
+   task :name, [:first_name, :last_name] do |t, args|
+     puts "First name is #{args.first_name}"
+     puts "Last  name is #{args.last_name}"
+   end
+The first argument of the block "t" is always bound to the current
+task object.  The second argument "args" is an open-struct like object
+that allows access to the task arguments.  Extra command line
+arguments to a task are ignored.  Missing command line arguments are
+given the nil value.
+If you wish to specify default values for the arguments, you can use
+the with_defaults method in the task body.  Here is the above example
+where we specify default values for the first and last names:
+   task :name, [:first_name, :last_name] do |t, args|
+     args.with_defaults(:first_name => "John", :last_name => "Dough")
+     puts "First name is #{args.first_name}"
+     puts "Last  name is #{args.last_name}"
+   end
+=== Tasks that Expect Parameters and Have Prerequisites
+Tasks that use parameters have a slightly different format for
+prerequisites.  Use the arrow notation to indicate the prerequisites
+for tasks with arguments.  For example:
+   task :name, [:first_name, :last_name] => [:pre_name] do |t, args|
+     args.with_defaults(:first_name => "John", :last_name => "Dough")
+     puts "First name is #{args.first_name}"
+     puts "Last  name is #{args.last_name}"
+   end
+=== Deprecated Task Parameters Format
+There is an older format for declaring task parameters that omitted
+the task argument array and used the :needs keyword to introduce the
+dependencies.  That format is still supported for compatibility, but
+is not recommended for use.
+== Accessing Task Programatically
+Sometimes it is useful to manipulate tasks programatically in a
+Rakefile. To find a task object, use the <tt>:[]</tt> operator on the
+<tt>Rake::Task</tt>.
+=== Programmatic Task Example
+For example, the following Rakefile defines two tasks.  The :doit task
+simply prints a simple "DONE" message.  The :dont class will lookup
+the doit class and remove (clear) all of its prerequisites and
+actions.
+   task :doit do
+     puts "DONE"
+   end
+   task :dont do
+     Rake::Task[:doit].clear
+   end
+Running this example:
+  $ rake doit
+  (in /Users/jim/working/git/rake/x)
+  DONE
+  $ rake dont doit
+  (in /Users/jim/working/git/rake/x)
+  $
+The ability to programmatically manipulate tasks gives rake very
+powerful meta-programming capabilities w.r.t. task execution, but
+should be used with cation.
 == Rules
 When a file is named as a prerequisite, but does not have a file task
@@ -128,8 +293,8 @@ prerequisite a source file with an extension of ".c" must exist.  If
 Rake is able to find a file named "mycode.c", it will automatically
 create a task that builds "mycode.o" from "mycode.c".
-Notice that the source file "mycode.c" must exist.  Rake does not
-(currently) try to do multi-level task synthesis.
+If the file "mycode.c" does not exist, rake will attempt
+to recursively synthesize a rule for it.
 When a task is synthesized from a rule, the +source+ attribute of the
 task is set to the matching source file.  This allows us to write
@@ -163,6 +328,39 @@ The following rule might be used for Java files ...
 <b>NOTE:</b> +java_compile+ is a hypothetical method that invokes the
 java compiler.
+== Importing Dependencies
+Any ruby file (including other rakefiles) can be included with a
+standard Ruby +require+ command.  The rules and declarations in the
+required file are just added to the definitions already accumulated.
+Because the files are loaded _before_ the rake targets are evaluated,
+the loaded files must be "ready to go" when the rake command is
+invoked.  This make generated dependency files difficult to use.  By
+the time rake gets around to updating the dependencies file, it is too
+late to load it.
+The +import+ command addresses this by specifying a file to be loaded
+_after_ the main rakefile is loaded, but _before_ any targets on the
+command line are specified.  In addition, if the file name matches an
+explicit task, that task is invoked before loading the file.  This
+allows dependency files to be generated and used in a single rake
+command invocation.
+=== Example:
+  require 'rake/loaders/makefile'
+  file ".depends.mf" => [SRC_LIST] do |t|
+    sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}"
+  end
+  import ".depends.mf"
+If ".depends" does not exist, or is out of date w.r.t. the source
+files, a new ".depends" file is generated using +makedepend+ before
+loading.
 == Comments
 Standard Ruby comments (beginning with "#") can be used anywhere it is
@@ -170,7 +368,7 @@ legal in Ruby source code, including comments for tasks and rules.
 However, if you wish a task to be described using the "-T" switch,
 then you need to use the +desc+ command to describe the task.
-Example:
+=== Example:
   desc "Create a distribution package"
   task :package => [ ... ] do ... end
@@ -198,6 +396,107 @@ Only tasks with descriptions will be displayed with the "-T" switch.
 Use "-P" (or "--prereqs") to get a list of all tasks and their
 prerequisites.
+== Namespaces
+As projects grow (and along with it, the number of tasks), it is
+common for task names to begin to clash.  For example, if you might
+have a main program and a set of sample programs built by a single
+Rakefile.  By placing the tasks related to the main program in one
+namespace, and the tasks for building the sample programs in a
+different namespace, the task names will not will not interfer with
+each other.
+For example:
+  namespace "main"
+    task :build do
+      # Build the main program
+    end
+  end
+  namespace "samples" do
+    task :build do
+      # Build the sample programs
+    end
+  end
+  task :build => ["main:build", "samples:build"]
+Referencing a task in a separate namespace can be achieved by
+prefixing the task name with the namespace and a colon
+(e.g. "main:build" refers to the :build task in the +main+ namespace).
+Nested namespaces are supported, so
+Note that the name given in the +task+ command is always the unadorned
+task name without any namespace prefixes.  The +task+ command always
+defines a task in the current namespace.
+=== FileTasks
+File task names are not scoped by the namespace command.  Since the
+name of a file task is the name of an actual file in the file system,
+it makes little sense to include file task names in name space.
+Directory tasks (created by the +directory+ command) are a type of
+file task and are also not affected by namespaces.
+=== Name Resolution
+When looking up a task name, rake will start with the current
+namespace and attempt to find the name there.  If it fails to find a
+name in the current namespace, it will search the parent namespaces
+until a match is found (or an error occurs if there is no match).
+The "rake" namespace is a special implicit namespace that refers to
+the toplevel names.
+If a task name begins with a "^" character, the name resolution will
+start in the parent namespace.  Multiple "^" characters are allowed.
+Here is an example file with multiple :run tasks and how various names
+resolve in different locations.
+  task :run
+  namespace "one" do
+    task :run
+    namespace "two" do
+      task :run
+      # :run            => "one:two:run"
+      # "two:run"       => "one:two:run"
+      # "one:two:run"   => "one:two:run"
+      # "one:run"       => "one:run"
+      # "^run"          => "one:run"
+      # "^^run"         => "rake:run" (the top level task)
+      # "rake:run"      => "rake:run" (the top level task)
+    end
+    # :run       => "one:run"
+    # "two:run"  => "one:two:run"
+    # "^run"     => "rake:run"
+  end
+  # :run           => "rake:run"
+  # "one:run"      => "one:run"
+  # "one:two:run"  => "one:two:run"
+== FileLists
+FileLists are the way Rake manages lists of files.  You can treat a
+FileList as an array of strings for the most part, but FileLists
+support some additional operations.
+=== Creating a FileList
+Creating a file list is easy.  Just give it the list of file names:
+   fl = FileList['file1.rb', file2.rb']
+Or give it a glob pattern:
+   fl = FileList['*.rb']
 == Odds and Ends
 === do/end verses { }
@@ -229,6 +528,7 @@ This is the proper way to specify the task ...
   end
 ----
 == See
 * README -- Main documentation for Rake.