buildr 1.3.2 → 1.3.3

data/doc/pages/contributing.textile

@@ -1,41 +1,28 @@
 h1. Contributing
 
-Buildr is a community effort, and we welcome all contributors.  Here's your
-chance to get involved and help your fellow developers.
+Buildr is a community effort, and we welcome all contributors.  Here's your chance to get involved and help your fellow developers.
 
+h2.  Getting involved
 
-h2.  Mailing Lists
+All our discussions are done in the open, over "email":mailing_lists.html, and that would be the first place to look for answers, raise ideas, etc.  For bug reports, issues and patches, "see below":#bugs_aka_issues.
 
-We run two mailing lists, the
-"buildr-user":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/
-mailing list for developers working with Buildr, that would be you if you're
-using Buildr or interested in using it.  There's the 
-"buildr-dev":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/
-mailing list for talking about development of Buildr itself, and 
-"commits":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/
-mailing list for following SVN commits and JIRA issues.
 
-Check the "mailing lists":mailing_lists.html page for more information on
-subscribing, searching and posting to the mailing list.
+h3.  Mailing Lists
 
+We run two mailing lists, the "buildr-user":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/ mailing list for developers working with Buildr, that would be you if you're using Buildr or interested in using it.  There's the  "buildr-dev":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/ mailing list for talking about development of Buildr itself, and  "commits":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/ mailing list for following SVN commits and JIRA issues.
 
-h2.  Bugs (aka Issues)
+Check the "mailing lists":mailing_lists.html page for more information on subscribing, searching and posting to the mailing list.
 
-We really do try to keep bugs to a minimum, and anticipate everything you'll
-ever want to do with Buildr.  We're also, not perfect.  So you may have found a
-bug, or have an enhancement in mind, or better yet, a patch to contribute.
-Here's what you can do.
 
-If it's a bug, enhancement or patch, add it to
-"JIRA":http://issues.apache.org/jira/browse/Buildr.  For trivial stuff, that's
-good enough.
+h3.  Bugs (aka Issues)
 
-If it needs more attention, start a discussion over on the mailing list.  We
-will still use JIRA to log the progress, but the mailing list is a better place
-for talking things through.
+We really do try to keep bugs to a minimum, and anticipate everything you'll ever want to do with Buildr.  We're also, not perfect.  So you may have found a bug, or have an enhancement in mind, or better yet, a patch to contribute. Here's what you can do.
 
-When reporting a bug, please tell us which version of Ruby, Buildr and Java you
-are using, and also which operating system you are on:
+If it's a bug, enhancement or patch, add it to "JIRA":http://issues.apache.org/jira/browse/Buildr.  For trivial stuff, that's good enough.
+
+If it needs more attention, start a discussion over on the mailing list.  We will still use JIRA to log the progress, but the mailing list is a better place for talking things through.
+
+When reporting a bug, please tell us which version of Ruby, Buildr and Java you are using, and also which operating system you are on:
 
 {{{!sh
 $ ruby --version
@@ -43,54 +30,65 @@ $ buildr --version
 $ java --version
 }}}
 
-If you have a patch to submit, do it through
-"JIRA":http://issues.apache.org/jira/browse/Buildr.  We want to make sure
-Apache gets the right to use your contribution, and the JIRA upload form
-includes a simple contribution agreement.  Lawyer not included.
 
+h3.  Community Wiki
+
+Our community Wiki is available at "http://cwiki.apache.org/confluence/display/BUILDR/Index":http://cwiki.apache.org/confluence/display/BUILDR/Index.
+
+
+h3.  Contributing Code
+
+Yes, please.
+
+If you have a patch to submit, do it through "JIRA":http://issues.apache.org/jira/browse/Buildr.  We want to make sure Apache gets the right to use your contribution, and the JIRA upload form includes a simple contribution agreement.  Lawyer not included.
+
+h4.  The Perfect Patch
+
+If you want to get your patch accepted quickly:
+
+#  Provide a good summary of the bug/fix.  We use that to decide which issue we can do quickly, and also copy and paste it into the changelog.
+#  Provide short explanation of what failed, under what conditions, why, and what else could be affected by the change (when relevant).  The helps us understand the problem and move on to the next step.
+#  Provide a patch with relevant specs, or a fix to incomplete/broken specs. First thing we have to do is replicate the problem, before applying the change, and then make sure the change fixes that problem.  And we need to have those specs in there, they make sure we don't accidentally break it again in the future.
+#  Provide a patch with the fix/change itself.  Keep it separate from the specs, so it's easy to apply them individually.
 
-h2.  Source Code
+If you don't know how to fix it, but can at least write a spec for the correct behavior (which, obviously would fail), do just that.  A spec is preferred to a fix.
 
-Did we mention Buildr is an open source project?  In fact, when you install
-Buildr you get all the source code, documentation, test case and everything you
-need to use it, extend it and patch it.  Have a look in your Gem directory.
+h4.  Working on a new feature?
 
-h4. Using SVN
+If you want to work on a cool new feature, but not quite ready to submit a patch, there's still a way you can get the Buildr community involved.  We're experimenting with using Git for that.  You can use Git to maintain a fork of Buildr that can keep up with changes in the main branch (tip: use @git rebase@), while developing your own changes/features on it.
 
-But if you want to work with the latest and greatest, you'll want to check out
-"Buildr from SVN":http://svn.apache.org/repos/asf/incubator/buildr:
+That way you can get other people involved, checking out the code, and eventually merge it back with the main branch.  Check out the "Git section":#Git below and the post "Git forking for fun and profit":http://blog.labnotes.org/2008/04/30/git-forking-for-fun-and-profit/.
+
+
+h2.  Living on the edge
+
+Did we mention Buildr is an open source project?  In fact, when you install Buildr you get all the source code, documentation, test case and everything you need to use it, extend it and patch it.  Have a look in your Gem directory.
+
+h3.  SVN
+
+But if you want to work with the latest and greatest, you'll want to check out "Buildr from SVN":http://svn.apache.org/repos/asf/incubator/buildr:
 
 {{{!sh
 $ svn co http://svn.apache.org/repos/asf/incubator/buildr/trunk buildr
 }}}
 
-You can also browse the "Buildr
-repository":http://svn.apache.org/repos/asf/incubator/buildr.
+You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/incubator/buildr.
 
-h4. Using Git
+h3.  Git
 
-Not a fan SVN?  We understand.  You can also grab a copy of "Buildr from
-GitHub":http://github.com/vic/buildr/tree/master:
+Not a fan SVN?  We understand.  You can also grab a copy of "Buildr from GitHub":http://github.com/vic/buildr/tree/master:
 
 {{{!sh
 $ git clone git://github.com/vic/buildr.git
 }}}
 
-The GitHub repository is maintained by contributors to this project, but is
-*not* an official Apache repository.  To obtain Buildr from the official Apache
-repository, consider using @giv-svn@ instead.
+If you want to learn more about Git, you can start by watching Scott Chacon’s "Git presentation":http://en.oreilly.com/rails2008/public/asset/attachment/2816 (PDF), or any of the "Git screencasts":http://www.gitcasts.com/.  For more, there's also the "Git Internals book":http://peepcode.com/products/git-internals-pdf.
 
-If you want to learn more about Git, you can start by watching Scott Chacon’s
-"Git presentation":http://en.oreilly.com/rails2008/public/asset/attachment/2816
-(PDF), or any of the "Git screencasts":http://www.gitcasts.com/.  For more,
-there's also the "Git Internals
-book":http://peepcode.com/products/git-internals-pdf.
+And keep this "Git cheat sheet":http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png close at hand. Very useful.
 
-And keep this "Git cheat
-sheet":http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png handy at
-hand. Very useful.
+*Note:* The GitHub repository is maintained by contributors to this project, but is *not* an official Apache repository.  To obtain Buildr from the official Apache repository, consider using @git-svn@ instead.
 
-h4. Installing from Source
+h3. Working with Source Code
 
 To install Buildr from the source directory:
 
@@ -106,77 +104,86 @@ $ cd buildr
 $ jruby -S rake setup install
 }}}
 
+The _setup_ task takes care of installing all the necessary dependencies used for building, testing and running Buildr. Once in a while we upgrade or add new dependencies, if you're experiencing a missing dependency, simply run @rake setup@ again.
+
+The _install_ task creates a Gem in your working directory (_pkg/_) and install it in your local repository. Since Ruby Gems uses version numbers to detect new releases, if you installed Buildr this way and want to upgrade to the latest official release, you need to use @gem install buildr@ rather than @gem upgrade@.
+
+Both _setup_ and _install_ tasks use the @sudo@ command on platforms that require it (i.e. not Windows), so there's no need to run @sudo rake@ when working with the Buildr source code.
+
+
+h3. Using development build
+
+Occasionally we'll make development builds from the current code in trunk/head. We appreciate if you can take the time to test those out and report any bugs. To install development builds, use the Gem repository at @people.apache.org/~assaf/buildr/snapshot@:
+
+{{{!sh
+gem source --add http://people.apache.org/~assaf/buildr/snapshot/
+}}}
+
+Since Ruby Gems uses version numbers to detect new releases, if you installed Buildr from a snapshot and want to upgrade to a newer snapshot or the latest official release, you need to use @gem install buildr@ rather than @gem upgrade@.
+
+If you want to go back to using the RubyForge releases:
+
+{{{!sh
+gem source --remove http://people.apache.org/~assaf/buildr/snapshot/
+gem install buildr
+}}}
+
+
+h2.  Tested and Documented
 
-h2.  Testing/Specs
+Two things we definitely encourage!
 
-Obviously we won't turn down patches, but we'll love you even more if you
-include a test case.  One that will fail without the patch, and run
-successfully with it.  If not for our love, then think of the benefit to you:
-once we add that test case, we won't accidentally break that feature in the
-next release.
+h3.  Testing/Specs
 
-We test using "RSpec":http://rspec.info/, a Behavior-Driven Development test
-framework.  The main difference between RSpec and xUnit is that RSpec helps you
-formulate test cases in terms of specifications: you describe how the code
-should behave, and run RSpec to make sure it matches that specification.
+Obviously we won't turn down patches, but we'll love you even more if you include a test case.  One that will fail without the patch, and run successfully with it.  If not for our love, then think of the benefit to you: once we add that test case, we won't accidentally break that feature in the next release.
+
+We test using "RSpec":http://rspec.info/, a Behavior-Driven Development test framework.  The main difference between RSpec and xUnit is that RSpec helps you formulate test cases in terms of specifications: you describe how the code should behave, and run RSpec to make sure it matches that specification.
 
 You can run an individual specifications using the @spec@ command, for example:
 
 {{{!sh
+$ spec spec/compiler_spec.rb
 $ spec spec/compiler_spec.rb -l 409
 }}}
 
-To make sure your change did not break anything else, you can run all the
-specifications (be patient, we have a lot of these):
+The first command will run all the specifications in @compiler_spec@, the second command will run only the specification identified by line 409 of that file. You can use line numbers to point at a particular specification (lines starting with @it@), or set of specifications (lines starting with @describe@). You can also use the @-e@ command line option to name a particular specification.
+
+To make sure your change did not break anything else, you can run all the specifications (be patient, we have a lot of these):
 
 {{{!sh
 $ rake spec
 }}}
 
+If you get any failures, you can use @rake failed@ to run only the failed specs, and repeat until there are no more failed specs to run. The list of failed specs is stored in the file _failed_.
+
 We always @rake spec@ before making a release.
 
-You can also check out the "RSpec report":report.html which provides the
-official specification against which we test each release.
+For full test coverage:
+
+{{{!sh
+$ rake coverage
+}}}
+
+Specification and coverage reports are HTML files you can view with a Web browser, look for them in the _reports_ directory. You can also check out the "RSpec report":specs.html and "test coverage":coverage/index.html we publish with each release.
 
 
-h2.  Documentation
+h3.  Documentation
 
-Yes, we do make typos, spelling errors and sometimes we write things that don't
-make sense, so if you find a documentation bug, or want to help make the
-documentation even better, here's the way to do it.
+Yes, we do make typos, spelling errors and sometimes we write things that don't make sense, so if you find a documentation bug, or want to help make the documentation even better, here's the way to do it.
 
-For simple typos and quick fixes, just send a message to the mailing list or
-log an issue in JIRA.
+For simple typos and quick fixes, just send a message to the mailing list or log an issue in JIRA.
 
-If you end up rewriting a significant piece of text, or add new documentation
-(your rock!), send a patch.  Making documentation patches is fairly easy.  All
-the documentation is generated from text files in the @doc/pages@ directory, so
-all you need to do is check it out from SVN, edit, and @svn diff@ to create a
-patch.
+If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch.  Making documentation patches is fairly easy.  All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from SVN, edit, and @svn diff@ to create a patch.
 
-We use "Textile":http://www.textism.com/tools/textile/ as the markup language,
-it takes all of a few minutes to learn, it's intuitive to use, and produces
-clean HTML.  Also check out the "Textile Quick
-Reference":http://hobix.com/textile/quick.html.
+We use "Textile":http://www.textism.com/tools/textile/ as the markup language, it takes all of a few minutes to learn, it's intuitive to use, and produces clean HTML.  You can learn it all in a few minutes from the "Textile Reference Manual":http://redcloth.org/textile.  Also check out the "Textile Quick Reference":http://hobix.com/textile/quick.html.
 
-You can always check the documentation to see which conventions we use, and
-also a couple of extensions we have for styling source code (with syntax
-highlighting!) and handling footnotes.  The table of contents is auto-generated
-form H1/H2 headers.
+You can always check the documentation to see which conventions we use, and also a couple of extensions we have for styling source code (with syntax highlighting!) and handling footnotes.  The table of contents is auto-generated form H1/H2 headers.
 
-The tool we use for this is called Docter, which we developed specifically for
-Buildr, and use to create the Web site and printable PDF.  If you want to try
-it out you'll need to first @gem install docter@.  To generate a copy of the
-Web site, simple run @rake html@ .
+The tool we use for this is called Docter, which we developed specifically for Buildr, and use to create the Web site and printable PDF.  If you want to try it out you'll need to first @gem install docter@.  To generate a copy of the Web site, simple run @rake html@ .
 
-If you're thinking of editing the docs, and using @rake html@ to see what the
-HTML looks like, you may want to try something simpler.  Start by running the
-Docter Web server with @rake docter@ and then point your browser at
-@http://localhost:3000@.  To see your edits, simply refresh the page.
+If you're thinking of editing the docs, and using @rake html@ to see what the HTML looks like, you may want to try something simpler.  Start by running the Docter Web server with @rake docter@ and then point your browser at @http://localhost:3000@.  To see your edits, simply refresh the page.
 
-Generating the PDF is a bit more tricky, we use the HTML in combination with
-print media CSS stylesheets and run them through the wonderful
-"PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML
+Generating the PDF is a bit more tricky, we use the HTML in combination with print media CSS stylesheets and run them through the wonderful "PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML
 first before you can @rake pdf@.
 
 
@@ -188,11 +195,14 @@ Here is the list of people who are actively working and committing on Buildr:
 
 *Alex Boisvert*
 
+Came to Buildr as a refuge from the Maven Uncertainty Principle.  Alex has been working mostly on the Scala integration and believes Ruby scripting is a great complement to statically typed languages. 
+
 *"Matthieu Riou":http://offthelip.org*
 
 *Victor Hugo Borja* (vborja at apache.org)
 
-Currently a Java Developer at
-"http://jwmsolutions.com":http://jwmsolutions.com, Victor has been enjoying and
-using Apache's software since 1999 when he started with Java, now he prefers
-programming Ruby and is happy to help on Apache's first ruby project. 
+Currently a Java Developer at "http://jwmsolutions.com":http://jwmsolutions.com, Victor has been enjoying and using Apache's software since 1999 when he started with Java, now he prefers programming Ruby and is happy to help on Apache's first ruby project. 
+
+*Lacton* (lacton at apache.org)
+
+A test-infected developer since 2001, Lacton yearns for a development infrastructure that would shorten feedback loops so much that testing, building, refactoring and committing would feel as easy and natural as breathing air.

data/doc/pages/download.textile

@@ -3,28 +3,28 @@ h1. Download
 
 h2.  Installing Buildr
 
-The easiest way to install Buildr is using the fabulous RubyGems package
-manager.  Of course, you will need either Ruby or JRuby, and we recommend
-upgrading to the most recent version of RubyGems.  If this sounds foreign to
-you, don't worry.  We'll show you how to install Buildr on Linux, OS/X, Windows
-and JRuby in the "Getting Started guide":getting_started.html, we even provide
-automated installation scripts.
-
-The *official Apache distribution* consists of the digitally signed binaries
-(gems) and source packages "available below":#binaries_and_source_code.  To
-install these binaries, you must first download them to disk and then install
-them using the @gem install@ command (or @rake install@ for a source
-distribution).
-
-In addition, contributors to this project maintain a separate distribution over
-on "RubyForge":http://rubyforge.org/projects/buildr.  Using this distribution,
-you're able to install Buildr directly from the remote gem repository and to
-automatically upgrade when a new release comes out.  The RubyForge distribution
-is *not* an official Apache distribution.
+The easiest way to install Buildr is using the fabulous RubyGems package manager.  Of course, you will need either Ruby or JRuby, and we recommend upgrading to the most recent version of RubyGems.  If this sounds foreign to you, don't worry.  We'll show you how to install Buildr on Linux, OS X, Windows and JRuby in the "Getting Started guide":getting_started.html, we even provide automated installation scripts.
+
+The *official Apache distribution* consists of the digitally signed binaries (gems) and source packages "available below":#binaries_and_source_code.  To install these binaries, you must first download them to disk and then install them using the @gem install@ command (or @rake install@ for a source distribution).
+
+In addition, contributors to this project maintain a separate distribution over on "RubyForge":http://rubyforge.org/projects/buildr.  Using this distribution, you're able to install Buildr directly from the remote gem repository and to automatically upgrade when a new release comes out.  The RubyForge distribution is *not* an official Apache distribution.
+
+The source code is included in both source and binary distribution, the Gem distribution expands the source code into your local Gem repository. That's in addition to getting the source code directly from "SVN":http://svn.apache.org/repos/asf/incubator/buildr or "GitHub":http://github.com/vic/buildr/tree/master. Learn more about working with source code and "living on the edge":contributing.html#living_on_the_edge.
 
 
 h2.  Binaries and Source Code
 
+h3. buildr 1.3.2-incubating (2008-07-18)
+
+|_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.2-incubating.gem":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.gem | "225504bc195334c4eb9d6dec814d9db1":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.gem.md5 | "Sig":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.gem.asc |
+| "buildr-1.3.2-java-incubating.gem":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-java-incubating.gem | "d7d8394c7aed887987be0e813e1e4cee":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-java-incubating.gem.md5 | "Sig":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-java-incubating.gem.asc |
+| "buildr-1.3.2-incubating.tgz":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.tgz | "611e97df1bc76382ecbe6b60e9340f2b":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.tgz.md5 | "Sig":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.tgz.asc |
+| "buildr-1.3.2-incubating.zip":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.zip | "d65d20005f603338c0aedd4f17d0bc90":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.zip.md5 | "Sig":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/buildr-1.3.2-incubating.zip.asc |
+
+p>. ("Release signing keys":http://www.apache.org/dist/incubator/buildr/1.3.2-incubating/KEYS)
+
+
 
 h3. buildr 1.3.1-incubating (2008-05-19)
 
@@ -48,12 +48,4 @@ h3. buildr 1.3.0-incubating (2008-05-01)
 p>. ("Release signing keys":http://www.apache.org/dist/incubator/buildr/1.3.0-incubating/KEYS)
 
 
-p(note). When downloading from files please check the
-"md5sum":http://www.apache.org/dev/release-signing#md5 and verify the
-"OpenPGP":http://www.apache.org/dev/release-signing#openpgp compatible
-signature from the main Apache site. This
-"KEYS":http://www.apache.org/dist/incubator/buildr/KEYS file contains the
-public keys used for signing releases. It is recommended that (when possible) a
-web of trust is used to confirm the identity of these keys. For more
-information, please see the "Apache Release
-FAQ":http://www.apache.org/dev/release.html.
+p(note). When downloading from files please check the "md5sum":http://www.apache.org/dev/release-signing#md5 and verify the "OpenPGP":http://www.apache.org/dev/release-signing#openpgp compatible signature from the main Apache site. This "KEYS":http://www.apache.org/dist/incubator/buildr/KEYS file contains the public keys used for signing releases. It is recommended that (when possible) a web of trust is used to confirm the identity of these keys. For more information, please see the "Apache Release FAQ":http://www.apache.org/dev/release.html.

data/doc/pages/extending.textile

@@ -2,16 +2,9 @@ h1. Extending Buildr
 
 h2. Organizing Tasks
 
-A couple of things we learned while working on Buildr.  Being able to write
-your own Rake tasks is a very powerful feature.  But if you find yourself
-doing the same thing over and over, you might also want to consider functions.
-They give you a lot more power and easy abstractions.
+A couple of things we learned while working on Buildr.  Being able to write your own Rake tasks is a very powerful feature.  But if you find yourself doing the same thing over and over, you might also want to consider functions. They give you a lot more power and easy abstractions.
 
-For example, we use OpenJPA in several projects.  It's a very short task, but
-each time I have to go back to the OpenJPA documentation to figure out how to
-set the Ant MappingTool task, tell Ant how to define it.  After the second
-time, you're recognizing a pattern and it's just easier to write a function
-that does all that for you.
+For example, we use OpenJPA in several projects.  It's a very short task, but each time I have to go back to the OpenJPA documentation to figure out how to set the Ant MappingTool task, tell Ant how to define it.  After the second time, you're recognizing a pattern and it's just easier to write a function that does all that for you.
 
 Compare this:
 
@@ -46,36 +39,20 @@ file('derby.sql') do
 end
 }}}
 
-I prefer the second.  It's easier to look at the Buildfile and understand what
-it does.  It's easier to maintain when you only have to look at the important
-information.
+I prefer the second.  It's easier to look at the Buildfile and understand what it does.  It's easier to maintain when you only have to look at the important information.
 
-But just using functions is not always enough.  You end up with a Buildfile
-containing a lot of code that clearly doesn't belong there.  For starters, I
-recommend putting it in the @tasks@ directory.  Write it into a file with a
-@.rake@ extension and place that in the @tasks@ directory next to the
-Buildfile.  Buildr will automatically pick it up and load it for you.
+But just using functions is not always enough.  You end up with a Buildfile containing a lot of code that clearly doesn't belong there.  For starters, I recommend putting it in the @tasks@ directory.  Write it into a file with a @.rake@ extension and place that in the @tasks@ directory next to the Buildfile.  Buildr will automatically pick it up and load it for you.
 
-If you want to share these pre-canned definitions between projects, you have a
-few more options.  You can share the @tasks@ directory using SVN externals.
-Another mechanism with better version control is to package all these tasks,
-functions and modules into a "Gem":http://rubygems.org/ and require it from
-your Buildfile.  You can run your own internal Gem server for that.
+If you want to share these pre-canned definitions between projects, you have a few more options.  You can share the @tasks@ directory using SVN externals. Another mechanism with better version control is to package all these tasks, functions and modules into a "Gem":http://rubygems.org/ and require it from your Buildfile.  You can run your own internal Gem server for that.
 
-For individual task files, you can also use
-"Sake":http://errtheblog.com/post/6069 for system-wide Rake tasks deployment.
+For individual task files, you can also use "Sake":http://errtheblog.com/post/6069 for system-wide Rake tasks deployment.
 
 
 h2.  Creating Extensions
 
-The basic mechanism for extending projects in Buildr are Ruby modules.  In
-fact, base features like compiling and testing are all developed in the form
-of modules, and then added to the core Project class.
+The basic mechanism for extending projects in Buildr are Ruby modules.  In fact, base features like compiling and testing are all developed in the form of modules, and then added to the core Project class.
   
-A module defines instance methods that are then mixed into the project and
-become instance methods of the project.  There are two general ways for
-extending projects.  You can extend all projects by including the module in
-Project:
+A module defines instance methods that are then mixed into the project and become instance methods of the project.  There are two general ways for extending projects.  You can extend all projects by including the module in Project:
 
 {{{!ruby
 class Project
@@ -83,8 +60,7 @@ class Project
 end
 }}}
 
-You can also extend a given project instance and only that instance by
-extending it with the module:
+You can also extend a given project instance and only that instance by extending it with the module:
 
 {{{!ruby
 define 'foo' do
@@ -92,23 +68,14 @@ define 'foo' do
 end
 }}}
 
-Some extensions require tighter integration with the project, specifically for
-setting up tasks and properties, or for configuring tasks based on the project
-definition.  You can do that by adding callbacks to the process.
+Some extensions require tighter integration with the project, specifically for setting up tasks and properties, or for configuring tasks based on the project definition.  You can do that by adding callbacks to the process.
 
-The easiest way to add callbacks is by incorporating the Extension module in
-your own extension, and using the various class methods to define callback
-behavior.
+The easiest way to add callbacks is by incorporating the Extension module in your own extension, and using the various class methods to define callback behavior.
 
 |_. Method        |_. Usage |
-| @first_time@    | This block will be called once for any particular
-extension.  You can use this to setup top-level and local tasks. |
-| @before_define@ | This block is called once for the project with the project
-instance, right before running the project definition.  You can use this to add
-tasks and set properties that will be used in the project definition. |
-| @after_define@  | This block is called once for the project with the project
-instance, right after running the project definition.  You can use this to do
-any post-processing that depends on the project definition. |
+| @first_time@    | This block will be called once for any particular extension.  You can use this to setup top-level and local tasks. |
+| @before_define@ | This block is called once for the project with the project instance, right before running the project definition.  You can use this to add tasks and set properties that will be used in the project definition. |
+| @after_define@  | This block is called once for the project with the project instance, right after running the project definition.  You can use this to do any post-processing that depends on the project definition. |
 
 This example illustrates how to write a simple extension:
 
@@ -152,16 +119,9 @@ end
 
 h2.  Using Alternative Layouts
 
-Buildr follows a common convention for project layouts: Java source files
-appear in @src/main/java@ and compile to @target/classes@, resources are
-copied over from @src/main/resources@ and so forth.  Not all projects follow
-this convention, so it's now possible to specify an alternative project
-layout.
+Buildr follows a common convention for project layouts: Java source files appear in @src/main/java@ and compile to @target/classes@, resources are copied over from @src/main/resources@ and so forth.  Not all projects follow this convention, so it's now possible to specify an alternative project layout.
 
-The default layout is available in @Layout.default@, and all projects inherit
-it.  You can set @Layout.default@ to your own layout, or define a project with
-a given layout (recommended) by setting the @:layout@ property.  Projects
-inherit the layout from their parent projects.  For example:
+The default layout is available in @Layout.default@, and all projects inherit it.  You can set @Layout.default@ to your own layout, or define a project with a given layout (recommended) by setting the @:layout@ property.  Projects inherit the layout from their parent projects.  For example:
 
 {{{!ruby
 define 'foo', :layout=>my_layout do
@@ -169,10 +129,7 @@ define 'foo', :layout=>my_layout do
 end
 }}}
 
-A layout is an object that implements the @expand@ method.  The easiest way to
-define a custom layout is to create a new @Layout@ object and specify mapping
-between names used by Buildr and actual paths within the project.  For
-example:
+A layout is an object that implements the @expand@ method.  The easiest way to define a custom layout is to create a new @Layout@ object and specify mapping between names used by Buildr and actual paths within the project.  For example:
 
 {{{!ruby
 my_layout = Layout.new
@@ -187,30 +144,19 @@ my_layout = Layout.new
 my_layout[:source, :main] = ''
 }}}
 
-If you need anything more complex, you can always subclass @Layout@ and add
-special handling in the @expand@ method, you'll find one such example in the
-API documentation.
+If you need anything more complex, you can always subclass @Layout@ and add special handling in the @expand@ method, you'll find one such example in the API documentation.
 
-The built-in tasks expand lists of symbols into relative paths, using the
-following convention:
+The built-in tasks expand lists of symbols into relative paths, using the following convention:
 
 |_. Path                          |_. Expands to |
-| @:source, :main, <lang/usage>@  |  Directory containing source files for a
-given language or usage, for example, @:java@, @:resources@, @:webapp@. |
-| @:source, :test, <lang/usage>@  | Directory containing test files for a given
-language or usage, for example, @:java@, @:resources@. |
-| @:target, :generated@           | Target directory for generated code
-(typically source code). |
-| @:target, :main, <lang/usage>@  | Target directory for compiled code, for
-example, @:classes@, @:resources@. |
-| @:target, :test, <lang/usage>@  | Target directory for compile test cases,
-for example, @:classes@, @:resources@. |
-| @:reports, <framework/usage>@   | Target directory for generated reports, for
-example, @:junit@, @:coverage@. |
-
-All tasks are encouraged to use the same convention, and whenever possible, we
-recommend using the project's @path_to@ method to expand a list of symbols
-into a path, or use the appropriate path when available.  For example:
+| @:source, :main, <lang/usage>@  |  Directory containing source files for a given language or usage, for example, @:java@, @:resources@, @:webapp@. |
+| @:source, :test, <lang/usage>@  | Directory containing test files for a given language or usage, for example, @:java@, @:resources@. |
+| @:target, :generated@           | Target directory for generated code (typically source code). |
+| @:target, :main, <lang/usage>@  | Target directory for compiled code, for example, @:classes@, @:resources@. |
+| @:target, :test, <lang/usage>@  | Target directory for compile test cases, for example, @:classes@, @:resources@. |
+| @:reports, <framework/usage>@   | Target directory for generated reports, for example, @:junit@, @:coverage@. |
+
+All tasks are encouraged to use the same convention, and whenever possible, we recommend using the project's @path_to@ method to expand a list of symbols into a path, or use the appropriate path when available.  For example:
 
 {{{!ruby
 define 'bad' do