README in reap-5.10.10 vs README in reap-6.0.0

@@ -1,125 +1,186 @@
-= Reap
+= Reap -- A Project Assistant for Ruby
 
-User Friendly Project Assitant for Ruby
+Reap is an easy to use project assistant for Ruby developers.
+Reap makes it easy to do the following tasks:
 
-== What's This?
-
-Reap is a user friendly project assistant for Ruby developers.
-By organizing your project in a conventional manner, 
-as promoted by setup.rb, Reap makes it easy to do the
-following tasks:
-
-* Generate RDocs.
-* Run unit tests.
-* Extract tests for scripts.
-* Create Ruby Gem packages.
-* Create standard .tgz, tbz (bzip2) and/or .zip packages.
+* Build new convention-based project folders.
+* Generate RDoc API documentation.
+* Run unit tests (each in it's ruby process).
+* Extract comment embedded tests from source code.
+* Run comment embedded unit test directly from source.
+* Create source tar.gz, tar.bz2 and zip packages.
+* Create RubyGem and Debian packages, plus pacman PKGBUILDs.
 * Publish documents to Rubyforge or other web sites.
-* Announce a release to Ruby-talk or other mailing list.
-* Prepare files for distribution (i.e. chmod, tag, etc.).
-* Upload packages (coming soon!).
+* Make announcement to ruby-talk or other mailing list.
+* Prepare files for distribution (i.e. chmod, tag, etc.)
+* Release distributions on Rubyforge or other such host.
+* Generate XML-format DOAP project file.
 
-If you have special needs that Reap doesn't accomodate,
-new task are farily easy to create. And I am always
-happy to hear suggestions.
+New features continue to be be developed. If you have special
+needs that Reap doesn't accomodate, new tasks are farily easy
+to create. And Reap's maintainers are always happy to engage
+suggestions.
 
+
 == Installation
 
+=== Requirements
+
+Reap requires Ruby Facets. If manually installing be sure to
+have the latest version of Facets installed too.
+
 === Gem Install
 
 Install the ruby gem as you would any other:
 
-  <tt>gem install reap</tt>
+    gem install reap
 
-Reap requires Ruby Facets.
+Gems still suffers from the datadir problem, so we've had
+to create some work arounds, for the template and scaffold
+tasks in particular. If you have any trouble with the Gem
+install please let us know so we can correct.
 
 === Manual Install
 
-To install manually follow the usual setup.eb steps:
+To install manually follow the usual setup.rb steps:
 
 1. Download the compressed package.
 2. Unpack it.
 3. Change into the unpacked directory.
-4. run <tt>sudo ruby setup.rb</tt>
+4. run 'sudo ruby setup.rb'
 
 You should be good to go.
 
+
 == Usage
 
 === Using a Reap Task
 
 Reap makes it pretty easy to use it's built-in tasks.
-Largely this is because it grabs common data from a ProjectInfo
-(or Reapfile) as available. Some Reap tasks are
-automatic b/c there are reasonable defaults, others
-_require_ entries in the ProjectInfo file.
+Largely this is because it utilizes a single data file,
+called the ProjectInfo file, to describe project procedures.
 
-For instance, to create a "package" target you generally do not need
-an entry in the ProjectInfo file. Reap will package up everything
-in the typical directories and makes compressed versions in the
-common formats. It will then place those in either ../leaf/
-(for those or you using trunk/ branches/ layouts) or pkg/ otherwise.
-The same holds for other tasks. Reap will do it's best to extrapolate
-the needed information from the ProjectInfo file.
+To use Reap the first thing your project will need is a
+ProjectInfo file in it's main directory. A template is provided
+and a task to copy it to your current directory. Simply type:
 
-Of course no matter the level of content, you will of course need to
-create this file in you projects main directory. A template is provided
-and a command line tool to copy it to your current directory. Simply type:
+    % reap template
 
-  > reap template
+Then edit the ProjectInfo file created. The fields are fairly self
+explanitiory. The template has a number of commented-out exmaples.
+Apart from utilization by Reap, such a file is even nice to have
+just on it's own informative merits too.
 
-Then edit the ProjectInfo file. The fields are fairly self
-explanitiory. Apart from Reap such a file is nice to have just on
-it's own merits too.
+Alternatively, Reap can build an entire new project directory with
+all the conventional components pre-arranged. Try it by creating
+a new empty directory, changing into it and then typing:
 
+    % reap scaffold
+
+The directory will be filled out with all the ususal directories,
+lib/, bin/, etc.  If you use subversion for version management,
+you can create a subversion layout instead.
+
+    % reap scaffold svn
+
+Filling out a ProjectInfo file is simply a matter adding entries
+for the primary information of you project and adding sections for
+the tasks you wish to use in for project. For example to use the
+RDoc task you could add:
+
+    document: !!rdoc
+      dir: rdoc
+
+By default Reap's Rdoc task will look in the bin/ lib/ and ext/
+directories for ruby scripts to document. Or you can specify
+exactly which files to include (See the Reap RDocs themselves
+for parameter details.) Some tasks can operate automatically
+based on reasonable defaults. Indeed in some cases all one might
+need is the one line:
+
+    name: !!task
+
+In others cases certain parameters are required for the task to function.
+But Reap will do it's best to extrapolate the needed information from
+what's available in the ProjectInfo file.
+
+Once you have some entries in your ProjectInfo file, enter:
+
+    % reap
+
+And you will see a list of executable tasks. To run a task enter:
+
+    % reap [task]
+
+For basic help try:
+
+    % reap help
+
+For a list of all avaialbe tasks or to get more detailed help on how to 
+use a particular task have a look at the RDoc API documentation.
+
+
 === Building a Reap Task
 
-Building a Reap task differs from building a Rake task
-by two important factors. First there is only one target
-per task (this may change) Second, task blocks are yeilded
-_prior_ to the #init routine being exectuted. So your #init
-routine should expect data to already be present in
-the tasks attribute and take that into account (usually that
-means using ++||=++)
+Building a Reap task is pretty easy too. In fact if you ever used Rake
+you already have a good idea about how to do it. 
 
-Here's an, oh so simple, example:
+First make sure your project has a task/ folder. Any file in that
+folder will be read by Reap and used to setup tasks. In a file with
+in that folder you can add a task or collection of tasks.
+Here's an "oh-so-simple" example:
 
-  class OhSoSimple < Reap::Task
+    module Tasks
 
-     task_desc 'This is a custom reap task'
+      def simple( name, data )
 
-     attr_accessor :message
+        desc 'This is a custom reap task class.'
 
-     def init
-       @message ||= master['default'] || 'None Found!'
-       @another ||= section['another'] || 'Again!'
-     end
+        task name do
+          data.message ||= master.message
+          puts data.message + "\n\n" + data.signed
+        end
 
-     # run the target task
-     def run
-       puts @message + "\n" + @another
-     end
+      end
 
-   end
+    end
 
-The corresponding settings in the ProjectInfo file (master) will then be:
+The corresponding settings in the ProjectInfo file will then be:
 
-   default: Default text, if any.
-   ohsosimple:
-     another: Your other message here.
+    message: Hi, how are you?
 
-And to use it
+    simple: !!simple
+      signed: Your friend, Tom.
 
-  > reap ohsosimple
+And to use it type:
 
+    % reap simple
+
+Notice the reference to 'master'. This is an OpenCascade interface
+(similar to OpenObject and OpenStruct) to the whole ProjectInfo dataset.
+
+You might recognize the core methods of creating a task, 'desc' and 'task'.
+These are used exactly as they are in Rake. We encapsulate them in a
+task-definition method (eg. simple) so the task can be generated dyanmically
+if such a section (!!simple) appears in the ProjectInfo file. Such 
+task-definition methods are recognized by reap b/c they are stored in the 
+special purpose Tasks module.
+
+
 == Status
 
-Reap is currently Usable Beta. Most of the tasks
-work very well. Refinements are still common though,
-and a few important tasks are still being planned.
+Reap is currently what one might call "usable beta". Most of the tasks
+work very well. Refinements are still common though.
 
+Also, Windows support is weak. Reap hasn't been fully tested in that
+environment so it is likely a few tasks will not yet work in this case.
+If you are Windows user and would like to use Reap, we would
+really appreciate someone working out the issues here.
+
+
 == Legal
 
-Reap
-Copyright(c)2004-2005 Thomas Sawyer
-Ruby License
+  Reap
+  Copyright (c) 2004-2006 Thomas Sawyer
+  Ruby License
+